Contracts, CHANGELOG, vector README: written-count slots, consent cap, flatten refusal, IsWritable is the write's answer

CHANGELOG Unreleased (org.gamecult.cultlib): Breaking gains the flatten-through-an-unowned-base
refusal, MintElementIds refusing a store holding a marked memory-only record, and the
written-count rule with the [MessagePackFormatter] and unmeasurable-type exclusions; Added
corrects IsWritable. The vector README says what a runtime walks for extra-slot-consent.cc,
the unit-arm record and slot-outcomes.msgpack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Libby 2026-11-12 00:33:08 +00:00
commit bbfe335388
4 changed files with 68 additions and 16 deletions

View file

@ -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

View file

@ -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:

View file

@ -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`)

View file

@ -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