diff --git a/src/GameCult.Caching/Contracts/cultcache-persistence-format.md b/src/GameCult.Caching/Contracts/cultcache-persistence-format.md index 851d261e..65e3a5af 100644 --- a/src/GameCult.Caching/Contracts/cultcache-persistence-format.md +++ b/src/GameCult.Caching/Contracts/cultcache-persistence-format.md @@ -205,8 +205,14 @@ the next write stores it under the writing type's own id and sheds the slots. A record whose payload carries a slot past the slots its reader declares, at any depth (nested object, list element, union arm, unit arm), is read-only the same way, whatever id it is stored under. The one consent is the declaration above, and it reaches only depth-0 slots the schema comparison reports ignored under a -listed compatible id: a mark anywhere else, or at depth 0 under the reader's own id, is not consented to. -`CultCache.IsWritable(key)` answers the same question the staging refusal asks. +listed compatible id, up to the highest slot it reports: a mark anywhere else, past that slot, or at depth 0 +under the reader's own id, is not consented to. Declared slots are what the type's own formatter writes; a +type with its own `[MessagePackFormatter]`, or one no instance of which can be written, is not checked. +A flatten of a variant whose base chain holds a record that is not owned is refused with that record's +refusal, because it would write the base's decoded view; the variant's own writes persist only its delta and +stay allowed. A plain write to another key of a value read from a read-only record is a copy this rule does +not police. `CultCache.IsWritable(key)` answers what the staging refusal answers for a removal or a write of +the record's type, read-only and missing home stores included; it does not predict that flatten. The rule is checked again where the write lands, under the store's lock: a write or removal at a key whose durable record is not owned, because another writer rewrote it after this cache diff --git a/src/GameCult.Caching/Contracts/cultcache-schema-compatibility.md b/src/GameCult.Caching/Contracts/cultcache-schema-compatibility.md index c638050e..894865c9 100644 --- a/src/GameCult.Caching/Contracts/cultcache-schema-compatibility.md +++ b/src/GameCult.Caching/Contracts/cultcache-schema-compatibility.md @@ -119,8 +119,23 @@ served, `CultStoredDocument.UnreadSlots` names the first type read with extra sl `CultSchemaConflictException` (`UnreadSlots` set; the message names the type and the counts, never a slot value). A missing trailing slot keeps its default and stays writable; a non-nil value in a retired gap below the highest key is not extra. Declaring an id compatible consents only to depth-0 slots the schema comparison -reports ignored under that id; any other mark (nested, list element, arm, unit arm, or depth 0 under the -reader's own id) keeps the record read-only whatever is declared. +reports ignored under that id, and only up to the highest slot it reports: a payload carrying a slot past that +one is not consented to. Any other mark (nested, list element, arm, unit arm, or depth 0 under the reader's +own id) keeps the record read-only whatever is declared. + +A type's declared slots are the array its own formatter writes for one instance (an uninitialized instance, +else one from a parameterless constructor), never a reflected member list, so a non-public `[Key]` member of +an `AllowPrivate` type counts. Only concrete int-keyed `[MessagePackObject]` types are checked. A type that +names its own `[MessagePackFormatter]` owns its layout and its tolerance and is not checked, and neither is a +type no instance of which can be written (no parameterless constructor and a `[Key]` getter that throws on an +uninitialized one): extra slots in such a type are read past and dropped on the next write, as before. + +`Flatten` of a variant writes its base chain's decoded view into a plain record, so it is refused when any +record on that chain is not owned by its home store (a mark nothing explains, or undeclared drift that drops +slots), with that record's own refusal naming its key. Writing or removing the variant itself stays allowed: +it persists only its delta. `CultCache.IsWritable(key)` is the write's own answer for a removal or a write of +the record's type: it is also false when the record's home store is read-only or no attached store is home to +its type. The one write it does not predict is that flatten. The cache emits a typed migration report with: diff --git a/tests/vectors/union-parity/README.md b/tests/vectors/union-parity/README.md index 618562f1..9ecf47f5 100644 --- a/tests/vectors/union-parity/README.md +++ b/tests/vectors/union-parity/README.md @@ -55,7 +55,9 @@ string `"extra-slot"` appended as one more slot of one object; a reader decodes from each. The fifth is a bare arm of union `UnitOutcome` (0 Waiting `[Message]`; 2 Denied2, -2147483648 Floor2 and 2147483647 Ceiling2, each `[]`), the union of the `unit-arm-*` files; a reader decodes Denied2 from it. -An object's declared slots are its highest key plus one. Only an array longer than that marks: a short array +An object's declared slots are the slots its type's own formatter writes for one instance (for these fixtures, +the highest key plus one); a reader derives them from the layout it writes, never from a list of public members. +Only an array longer than that marks: a short array (missing trailing slots) keeps the defaults and is writable, and a non-nil value in a retired slot below the highest key (Image's slot 2) does not mark. A union adds no depth: an arm's array is counted against the arm's own slots. @@ -81,21 +83,47 @@ Load it as a store record under the reader's own schema id (the C# reference put 2. the record reports the mark as in the table: the first type read with extra slots, the slots it carried and the slots the reader declares, and the count of objects that carried extra slots (1 here); 3. the record is not writable (C#: `CultCache.IsWritable(key)` false), and a key no store holds is writable; -4. a replacing write, a variant write and a removal of the key (and a flatten, when the marked record is a variant) - are refused before anything is staged, +4. a replacing write, a variant write and a removal of the key, and a flatten of a variant whose base chain holds + the marked record, are refused before anything is staged, with the runtime's schema conflict refusal carrying the mark; its message names the type and both counts and never contains `extra-slot`, the slot's value; 5. a write to another key of the same store succeeds. Consent: a mark is explained only when it is at depth 0 and the schema comparison of the record's stored id against -the reader reported ignored extra slots, i.e. the record is stored under an id the reader lists compatible and the -catalog entry for that id has more members. Declaring that id consents to an explained mark only. Every mark in the -table is unexplained (stored under the reader's own id), so each record stays read-only whatever is declared. +the reader reported ignored extra slots covering it: the record is stored under an id the reader lists compatible, +that id's catalog entry has more members, and the mark's slot count is at most the highest reported slot plus one. +Declaring that id consents to an explained mark only. Every mark in the table above is unexplained (stored under +the reader's own id), so each record stays read-only whatever is declared. -`extra-slot-store.cc` is a single-file store of two `tests.union_surface` records, the store's clock pinned to -2026-01-01T00:00:00Z as `union-surface.cc`'s: `marked`, whose payload is `extra-slot-nested-record.msgpack`, and -`clean`, the value of `union-surface.msgpack`. Open it, assert `marked` read-only and `clean` writable, write `clean` -and flush: `marked`'s payload bytes, schema id and stored-at, and every catalog entry's bytes, equal the originals. +## Slot stores (`slot-outcomes.msgpack`) + +Two single-file stores, each record written as a value and its payload then replaced, the store's clock pinned to +2026-01-01T00:00:00Z as `union-surface.cc`'s: + +- `extra-slot-store.cc`, read with `tests.union_surface` (schema `tests.union_surface.v1`) and `tests.slot_unit` + (schema `tests.slot_unit.v1`, a document `[Name, Outcome: UnitOutcome]`). `marked` is + `extra-slot-nested-record.msgpack`; `clean` is `union-surface.msgpack`; `unit-arm` is the `tests.slot_unit` + document `["unit-arm", [2, ["extra-slot"]]]`, whose Denied2 arm sits at depth 1 (the document is depth 0; a union + adds none). +- `extra-slot-consent.cc`: every record is stored under `tests.union_surface.wide`, whose catalog entry is + `tests.union_surface`'s seven members plus slot 7 (`Wider`). Read it with a `tests.union_surface` type of schema + `tests.union_surface.v2` (the reference names it `SurfaceDeclaring`) that lists `tests.union_surface.wide` + compatible, so the comparison reports slot 7 ignored. `consented` is `union-surface.msgpack` plus one root slot + (slot 7); `over-consent` plus two (slots 7 and 8, past the highest reported); `nested` is + `extra-slot-nested-record.msgpack` plus one root slot; `clean` is `union-surface.msgpack`. + +`slot-outcomes.msgpack` is a second outcomes file, as `bounds-outcomes.msgpack` is, so readers of `outcomes.msgpack` +stay green. It is an array of rows `[store, key, writable, explained, type, slots, declared, occurrences]`, one +per record of both stores: `writable` is what `IsWritable` answers; for an unmarked record the last five are nil, +otherwise they are the mark: whether it is explained, the first type read with extra slots, the slots it carried, +the slots the reader declares, and how many objects carried extra slots. A depth-0 type is the reader's document +type (the reference's names: `SurfaceDeclaring` for the consent store). For each row, open a copy of the store, +assert the mark and `IsWritable`, then remove the key: refused (with the mark, the file unchanged) exactly where +`writable` is false. In the consent store a write of `consented` lands and a write of `over-consent` is refused. + +The carried-verbatim check: open `extra-slot-store.cc`, assert `marked` read-only and `clean` writable, write +`clean` and flush: `marked`'s payload bytes, schema id and stored-at, and every catalog entry's bytes, equal the +originals. ## Bounds (`bounds-outcomes.msgpack`) diff --git a/unity/org.gamecult.cultlib/CHANGELOG.md b/unity/org.gamecult.cultlib/CHANGELOG.md index c2fc2a1f..49fcc5ec 100644 --- a/unity/org.gamecult.cultlib/CHANGELOG.md +++ b/unity/org.gamecult.cultlib/CHANGELOG.md @@ -8,10 +8,13 @@ All notable changes to this package are documented in this file. - A single-file store holding two records under one key is unreadable: the reader refuses it with `CultStoreUnreadableException` naming the key (keys compare by ordinal code units, no case folding or normalisation), so a cache, `ReadStoreSnapshot` and a flush refuse the file and leave it as it is. Before, the later record silently replaced the earlier. A directory store reads its manifest through the same reader and refuses a duplicate key the same way. Repair the duplicate with the runtime that wrote it before reading the store here. - A record whose payload carries a slot past the slots its reading type declares, at any depth (the record, a nested object, a list element, a union arm or a unit arm), is loaded read-only: it is served, and every staged write or removal of its key (`Upsert`, `UpsertVariant`, `Remove`, a batch, and `Flatten` of a variant) is refused with `CultSchemaConflictException` before anything is staged, and the store keeps the record byte for byte. Before, the extra slots were skipped on read and dropped on the next write. Declaring an id compatible consents only to depth-0 slots the schema comparison reports ignored under that id; any other extra slot keeps the record read-only whatever is declared, including under the reader's own id. A variant overriding a slot its type does not have is read-only too (it used to be shed on flush). Write such a record from the build that declares those slots. Missing trailing slots still default and stay writable. +- `Flatten` (and `FlattenAsync`) of a variant whose base chain holds a record its store does not own (a record held read-only for extra slots, or undeclared drift that drops slots) is refused with `CultSchemaConflictException` naming that base record, and the store is left as it was. Before, the flatten wrote the base's decoded view into a plain record and the base's unread data was lost for that variant. Writing and removing the variant itself are still accepted: they persist only its delta. +- `MintElementIds` refuses a home store's commit while that store holds a record read-only for extra slots whose element ids exist only in memory, until the build that declares those slots rewrites it; commits to earlier stores stand. +- A type's declared slots are the array its own formatter writes for one instance, not its public `[Key]` members, so a non-public `[Key]` of an `AllowPrivate` type counts. A type carrying `[MessagePackFormatter]` is not checked for extra slots (it owns its layout), and neither is a type no instance of which can be written (no parameterless constructor and a `[Key]` getter that throws on an uninitialized instance); extra slots in those are read past and dropped on the next write, as before. ### Added -- `CultCache.IsWritable(CultRecordKey)`: whether a write or removal of the key would be let through, answered by the same predicate the write uses (false for a foreign record, undeclared drift that drops slots, or unread slots; true for a key no store holds). Live and advisory: the write still decides. +- `CultCache.IsWritable(CultRecordKey)`: whether a removal of the key, or a write of the record's own type, would be let through, answered by the write's own decision: false for a foreign record, undeclared drift that drops slots, unread slots, a read-only home store, or a record no attached store is home to; true for a key the cache does not hold unless a store lists it foreign. It does not predict a `Flatten` refused for its base chain. Live and advisory: the write still decides. - `CultUnreadSlots` (`TypeName`, `SlotCount`, `DeclaredCount`, `Occurrences`, `Explained`), `CultStoredDocument.UnreadSlots`, and `CultSchemaConflictException.UnreadSlots` with its constructor overload: what a load found past the reader's slots, holding no slot value. The refusal message names the type and both counts, never a value. ## [3.0.0] - 2026-11-11