diff --git a/src/GameCult.Caching/Contracts/cultcache-persistence-format.md b/src/GameCult.Caching/Contracts/cultcache-persistence-format.md index 9cb79fa8..bfa9c5dc 100644 --- a/src/GameCult.Caching/Contracts/cultcache-persistence-format.md +++ b/src/GameCult.Caching/Contracts/cultcache-persistence-format.md @@ -306,6 +306,95 @@ The lower-level API should still expose: That is the cache's responsibility, not the domain model's. +## Concurrent Store Policy + +CultCache files are expected to become shared state, not private save blobs. +Once multiple runtimes can read and write the same `.cc` file, the persistence +contract must protect both durability and observation. + +The store header should declare the write policy a runtime must obey before it +mutates the file: + +- `generation`: monotonic store generation, incremented on each committed + snapshot +- `contentHash`: hash of the committed snapshot body +- `concurrency.policy`: stable policy id, such as + `cultcache.concurrent.snapshot-lock.v1` +- `concurrency.lockName`: how to derive the sidecar lock path +- `concurrency.commit`: commit primitive, such as `atomic-replace` + +The header negotiates the protocol. It does not enforce the protocol by magic. +Writers still need an external coordination primitive because replacing the +main file also replaces whatever identity a platform may attach to that file +handle. + +The v1 concurrent single-file policy is: + +1. Readers may read lock-free when they can tolerate a stale-but-complete + snapshot. Readers that need a stable read boundary take a shared sidecar + lock. +2. Writers take an exclusive sidecar lock derived from the `.cc` path. +3. Writers re-read the current snapshot after taking the lock. +4. Writers merge or reject local staged changes against the latest generation. +5. Writers write a temp file, flush it, atomically replace the `.cc` file, and + release the lock. + +This preserves the key invariant: every reader sees a complete snapshot, and no +writer commits over unseen data without passing through the merge/reject point. + +## Live Change Observation + +A shared CultCache file is also a low-ceremony realtime database for local +applications. The filesystem is the transport. CultCache is the typed database +surface. The cache should therefore expose domain-level change streams, not +force applications to subscribe to raw storage envelopes. + +Recommended C# surface: + +```csharp +Observable> Watch(); +Observable WatchRecord(CultRecordKey key); +Observable WatchGlobal(); +Observable WatchByName(string name); +``` + +Change events should be emitted after a pulled or locally committed snapshot has +been reconciled into the in-memory cache. Subscribers should see domain objects +and cache-owned handles, not raw `schemaId`, `storedAt`, or MessagePack payload +bytes unless they explicitly subscribe to the raw persistence lane. + +The event model should distinguish at least: + +- `added` +- `updated` +- `removed` +- `schema_migrated` +- `rejected` + +Local and remote-looking writes use the same reconciliation path. A write from +another process is just a new committed generation discovered through file +watching or polling, pulled into the cache, diffed against the current domain +view, and published. + +### R3 Alignment + +The C# reactive surface should align with R3, Cysharp/neuecc's modern +Reactive Extensions implementation and successor line to UniRx. CultCache +should not invent a bespoke observer API when the .NET ecosystem already has a +well-understood shape for composable streams. + +R3 should own the C# subscription ergonomics: + +- `Observable` for public domain streams +- `Subject` or internal equivalents only at ownership boundaries +- disposable subscriptions for lifecycle control +- debounce/throttle operators for bursty filesystem notifications +- scheduler hooks where Unity, desktop UI, or server callers need thread + affinity + +The invariant is simple: the persistence layer owns bytes and generations; the +cache owns domain identity and diffing; R3 owns composition of observed changes. + ## CultNet Alignment CultCache and CultNet should not grow rival schema religions.