From e34f351b95c627499da0a9c81016e99fa91c8269 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 3 Oct 2026 12:35:56 +0200 Subject: [PATCH] Contract and comments: a cache owns exactly the ids its types register or declare compatible The persistence contract's relabel paragraph is replaced by ownership by declaration: a record read through the catalog's schema name or a persisted entry's list is read-only, and declaring its id claims it. CultForeignRecord says no type can read it; the write APIs and MintElementIds name the refusal. Co-Authored-By: Claude Opus 5.5 --- .../Contracts/cultcache-persistence-format.md | 24 ++++++++++--------- src/GameCult.Caching/CultCache.cs | 16 +++++++++---- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/src/GameCult.Caching/Contracts/cultcache-persistence-format.md b/src/GameCult.Caching/Contracts/cultcache-persistence-format.md index 9065a377..49e0ea3a 100644 --- a/src/GameCult.Caching/Contracts/cultcache-persistence-format.md +++ b/src/GameCult.Caching/Contracts/cultcache-persistence-format.md @@ -178,23 +178,25 @@ A schema type declares the older ids its records may sit under: `CultDocumentAtt (C#), `compatibleSchemaIds` (TypeScript, Python). The registered catalog entry lists them after its own id, and the cache restamps a record loaded under one to the type's own id, so the next write of that record carries the registered id. A record another writer left under a declared id, and that a commit does not rewrite, stays under it -and the registered entry publishes it. Without the declaration, a C# commit onto a file that holds a record under an -id only the file's entry lists is refused, typed, and the file is left as it was. Rust has no such declaration. +and the registered entry publishes it. Without the declaration such a record is read-only to the cache (see +ownership by declaration, below). Rust has no such declaration. A cache resolves a record to a local type by the record's schema id: the registered type that owns the id, else one that lists it as compatible. The name the catalog entry carries is metadata. It -names a local type only when no local type has the id, for a store written by a runtime whose -schema ids this one cannot know (a Rust type's schema id is its entry type). A schema renamed under -a stable id therefore opens in every runtime that holds the id. +names a local type only when no local type has the id, and then only to read with: a record so +resolved is read-only (below). That serves a store written by a runtime whose schema ids this one +cannot know (a Rust type's schema id is its entry type). A schema renamed under a stable id +therefore opens in every runtime that holds the id. -A write copies forward what it did not stage. A record a cache resolved through the catalog's schema -name, or through an entry pointing at a local id, is readable, but its id is not one its type owns -or declares compatible: a write of another record copies it with its id, storedAt, bytes and -catalog entry exactly as they were stored. Only a write of that record itself stores it under the -type's own id. +**A cache owns exactly the schema ids its types register or declare compatible.** A record stored +under any other id that a type can read, through the catalog's schema name or an entry listing a +local id, is loaded read-only: Get and queries serve it, a write of another record copies it as +stored, and a staged write or removal of it (upsert, variant upsert, flatten, remove, commit) is +refused with the typed schema conflict before anything is staged. Declaring its id compatible on a +type claims it: the next write stores it under that type's own id. A record that resolves to no local type is a foreign record, for example one of a type this build does not -have, or one renamed without declaring its old id. A store never destroys or relabels it: the store carries it +have, or one renamed under a new schema name without declaring its old id. A store never destroys or relabels it: the store carries it byte for byte under its own id and its own catalog entry, lists it as foreign (`CacheBackingStore.ForeignRecords` in C#), and the cache never holds it. Writes of other records proceed and copy it forward as the file holds it. A write that would replace or remove it is refused with the typed schema conflict naming its key and id, and nothing is written. The refused keys are reloaded as the store holds them (a foreign record is not held), and their staged changes are forgotten. A write that carries a record forward keeps a marked header marked. Declaring its id on a type claims it at the next load. diff --git a/src/GameCult.Caching/CultCache.cs b/src/GameCult.Caching/CultCache.cs index 34103eaf..e0f4912d 100644 --- a/src/GameCult.Caching/CultCache.cs +++ b/src/GameCult.Caching/CultCache.cs @@ -154,10 +154,12 @@ namespace GameCult.Caching } /// - /// A record a store carries untouched because no registered type owns its schema id or lists it as compatible, for example a - /// record of a type this build does not have, or one renamed without declaring its old id. The store keeps its bytes as the - /// file holds them, a write of another record keeps it, and a write that would replace or remove it is refused with a + /// A record a store carries untouched because no registered type can read it, for example a record of a type this build does + /// not have, or one renamed under a new schema name without declaring its old id. The store keeps its bytes as the file holds + /// them, a write of another record keeps it, and a write that would replace or remove it is refused with a /// . The cache never holds it. Declaring its schema id on a type claims it at the next load. + /// A record a type can read (through the catalog's schema name) but no type owns or declares is not foreign: the cache holds it + /// read-only, and the same refusal applies to a write or removal of it. /// public sealed class CultForeignRecord { @@ -2060,7 +2062,8 @@ namespace GameCult.Caching // The one-shot rewrite for stores written before element ids existed: upserts every record whose ids exist only in // memory (minted when it loaded), through the normal write path, one commit per home store. Returns how many records - // it rewrote; a second call finds none. + // it rewrote; a second call finds none. A selected record stored under an id no registered type declares is read-only, + // so its home store's commit is refused with CultSchemaConflictException; commits to earlier stores stand. public int MintElementIds() { var groups = Held(() => _entries.Values @@ -2302,12 +2305,14 @@ namespace GameCult.Caching return UpsertAsync(document, handle); } + // Refused with CultSchemaConflictException when the key holds a record stored under an id no registered type declares. public Task> UpsertAsync(T document, CultRecordHandle? handle = null) { if (document == null) throw new ArgumentNullException(nameof(document)); return Task.FromResult(new CultRecordHandle(Write(document, handle?.Key))); } + // Refused with CultSchemaConflictException when the key holds a record stored under an id no registered type declares. public Task UpsertAsync(Type documentType, object document, CultRecordKey? key = null) { RequireInstanceOf(documentType, document); @@ -2315,6 +2320,7 @@ namespace GameCult.Caching } // A single-call variant write; a batch stages the same thing with CultCacheBatch.UpsertVariant. + // Refused with CultSchemaConflictException when the key holds a record stored under an id no registered type declares. public Task UpsertVariantAsync(CultRecordKey key, CultRecordKey baseKey, IEnumerable? overrides = null) { var delta = new CultVariantDelta(baseKey.Value, (overrides ?? Array.Empty()).ToArray()); @@ -2331,6 +2337,7 @@ namespace GameCult.Caching } // Replaces a variant with a plain record holding its resolved document (Q1a's explicit operation). + // Refused with CultSchemaConflictException when the key holds a record stored under an id no registered type declares. public Task FlattenAsync(CultRecordKey key) => Task.FromResult(Held(() => { var stored = StampFlatten(key); @@ -2342,6 +2349,7 @@ namespace GameCult.Caching return key; })); + // Refused with CultSchemaConflictException when the key holds a record stored under an id no registered type declares. public bool Remove(CultRecordKey key) => Held(() => { if (!_entries.TryGetValue(key.Value, out var existing))