Docs: cacheless single-file access names WriteDocument and DecodeDocument; CultElementIds is not public

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-23 00:15:28 +02:00
commit bf01212f9a
2 changed files with 14 additions and 10 deletions

View file

@ -349,24 +349,28 @@ no serialization; a CultMath encoding, if added, uses this shape.
## Cacheless single-file access
A single-file store file can be read and written without a cache, through two public members of `SingleFileBackingStore` (for
example `SingleFileMessagePackBackingStore`): `ReadStoreSnapshot()` and `WriteRecord(record, catalogEntry, holdsIds, registry)`.
A single-file store file can be read and written without a cache, through public members of `SingleFileBackingStore` (for
example `SingleFileMessagePackBackingStore`): `ReadStoreSnapshot()`, `WriteRecord(record, catalogEntry, holdsIds, registry)`,
`WriteDocument<T>(key, document, storedAt, registry)` and `DecodeDocument<T>(key, payload, registry)`.
- `ReadStoreSnapshot()` reads the file once, under the store's gate, and returns the durable snapshot (records, schema catalog,
format stamp), or null when nothing is at the path. It throws `CultStoreUnreadableException` for a file the reader refuses.
- `WriteRecord` writes one record under the store's lock: the record replaces the one at its key, every other record and catalog
entry is copied forward as stored, and the file is replaced atomically.
entry is copied forward as stored, and the file is replaced atomically. It takes a payload the caller already encoded, so a
payload it cannot read leaves the header as the file has it (`holdsIds` null).
- `WriteDocument<T>` writes one typed document as a cache write does: it plans element ids, encodes the document with the
registry, and stores it through `WriteRecord`. A failed write gives the minted ids back.
- `DecodeDocument<T>` decodes a payload read from the store as a cache load does: it mints the ids a load mints and refuses what
a cache load refuses.
They share everything with a cache's store and nothing is re-implemented beside it: one reader (the stamp is judged before the
body, and a file the reader refuses is refused by a read and by a write alike), the store's lock, the atomic replace, and the
header rule (`holdsIds` true marks a v3 store; false leaves it as the rule decides; null, for a payload the caller cannot read,
keeps whatever the file already says). Ownership by declaration binds a cacheless write too: a record at the key under a schema id
the written catalog entry does not own or list as compatible is refused with `CultSchemaConflictException`, and the file is left as
it was. A typed writer plans element ids with `CultElementIds.Plan` before it serializes and passes `CultElementIds.Holds` as
`holdsIds`.
A store attached to a cache refuses `WriteRecord` with `InvalidOperationException`: write through the cache, whose staged writes
land through the same private write. CultMesh's single-file document helpers (`CultMesh.WriteSingleFileDocument`,
it was. Element-id planning (`CultElementIds`) is internal to the library: a caller never plans or marks ids, the store does. A store
attached to a cache refuses `WriteRecord` and `WriteDocument` (write through the cache, whose staged writes land through the
same private write) and `DecodeDocument` (read through the cache) with `InvalidOperationException`. CultMesh's single-file document helpers (`CultMesh.WriteSingleFileDocument`,
`ReadSingleFileDocument` and their payload forms) are built on these members and nothing else of the store.
## Runtime status