From 309dab9a64f3a93864b05af7464103ddd0f70eb7 Mon Sep 17 00:00:00 2001 From: Libby Date: Thu, 12 Nov 2026 08:24:27 +0000 Subject: [PATCH] TypeScript: a flush persists the image as the stores hold it (legacy-key globals) Soul finding on #136: merging pushAll left a legacy-key global under two keys, a store that does not reopen. storedSnapshot hands the global out under its stored key until its first write retires it; the readability walk now asserts nothing else is removed. Co-Authored-By: Claude Sonnet 5.5 --- packages/cultcache-ts/CHANGELOG.md | 2 +- packages/cultcache-ts/README.md | 2 +- packages/cultcache-ts/src/cult-cache.ts | 7 ++++++ packages/cultcache-ts/test/cult-cache.test.ts | 22 ++++++++++++++++++- packages/cultmesh-ts/src/index.ts | 2 +- packages/cultmesh-ts/test/cultmesh.test.ts | 17 +++++++++++++- 6 files changed, 47 insertions(+), 5 deletions(-) diff --git a/packages/cultcache-ts/CHANGELOG.md b/packages/cultcache-ts/CHANGELOG.md index 2b226954..dcbfd12e 100644 --- a/packages/cultcache-ts/CHANGELOG.md +++ b/packages/cultcache-ts/CHANGELOG.md @@ -7,7 +7,7 @@ All notable changes to `@gamecult/cultcache-ts` are recorded here, following ### Breaking -- `SingleFileMessagePackBackingStore.pushAll` writes the given entries onto the store as it is under the lock, as `push` does: a record under the same key is replaced and no other is removed. It used to replace the whole file with the entries, so `CultMesh.flush()` from a cache that held less than the store (a node created with `pullOnStart: false`, or one whose image was stale) wiped the records it never read. A caller that relied on `pushAll` to reset a store removes the file first. A soft flush and the dangling-link case are unchanged. +- `SingleFileMessagePackBackingStore.pushAll` writes the given entries onto the store as it is under the lock, as `push` does: a record under the same key is replaced and no other is removed. It used to replace the whole file with the entries, so `CultMesh.flush()` from a cache that held less than the store (a node created with `pullOnStart: false`, or one whose image was stale) wiped the records it never read. A caller that relied on `pushAll` to reset a store removes the file first. A soft flush and the dangling-link case are unchanged. `CultCache.storedSnapshot()` is the image as the stores hold it (a global loaded from a legacy key under that key) and is what `CultMesh.flush` persists, so a flush no longer leaves such a global under two keys; `snapshot()` is unchanged. - A single-file store marked `cultcache.store.v3` (it holds an element id, written by the C# runtime) is read, and a rewrite keeps the mark and the ids; this runtime does not decide when a document carries ids. A runtime from before this change refuses a v3 store by name, so rolling back to an older release after a store has been written as v3 is one-way: there is no carry-back, so restore from a copy taken before upgrading. - `indexes` are unique, as C# `[CultIndex]`: a write or a load that leaves two records of a type holding one non-blank value under one alias is refused naming both keys and the alias, and writes nothing. Index text is the C# canonical diff --git a/packages/cultcache-ts/README.md b/packages/cultcache-ts/README.md index a081cd92..625d28dd 100644 --- a/packages/cultcache-ts/README.md +++ b/packages/cultcache-ts/README.md @@ -174,7 +174,7 @@ const settings = cache.getRequiredGlobal(settingsDocument); - `updateGlobal(...)` - `delete(...)` - `deleteGlobal(...)` -- `snapshot()` +- `snapshot()` (the logical image) and `storedSnapshot()` (the image as the stores hold it, for a whole flush) - `getEnvelope(...)` - `getRequiredEnvelope(...)` - `getGlobalEnvelope(...)` diff --git a/packages/cultcache-ts/src/cult-cache.ts b/packages/cultcache-ts/src/cult-cache.ts index 6cf7a8cb..a88bd66d 100644 --- a/packages/cultcache-ts/src/cult-cache.ts +++ b/packages/cultcache-ts/src/cult-cache.ts @@ -636,6 +636,13 @@ export class CultCache { return [...this.#hydrated.entries.values()].map((entry) => this.#toEnvelope(entry)); } + // The image as the stores hold it, for persisting it whole (a flush): a global loaded from a legacy key is handed out under + // that key until its first write retires it, so a flush cannot leave the store holding it under two keys. `snapshot` is the + // logical image and always names a global by CultCache.GLOBAL_KEY. + storedSnapshot(): CultCacheEnvelope[] { + return [...this.#hydrated.entries.values()].map((entry) => this.#hydrated.legacyGlobals.get(entry.type) ?? this.#toEnvelope(entry)); + } + #registerNow(definition: AnyCultCacheDocumentDefinition): void { // Every registration refusal is a SchemaConflictError naming the new definition's schema id and both schema names. const refuse = (holder: RegisteredDefinition, claimed: CultCacheSchemaCatalogEntry, what: string) => diff --git a/packages/cultcache-ts/test/cult-cache.test.ts b/packages/cultcache-ts/test/cult-cache.test.ts index d2b515c9..2636a9d3 100644 --- a/packages/cultcache-ts/test/cult-cache.test.ts +++ b/packages/cultcache-ts/test/cult-cache.test.ts @@ -1032,6 +1032,25 @@ test("legacyKeyGlobalLoadsWithoutWritingAndFirstWriteLeavesOneGlobal", async () await assert.rejects(build().pullAllBackingStores(), /has multiple persisted entries/u); }); +test("a flush of a cache that loaded a legacy-key global leaves the store reopenable", async () => { + const settingsDocument = defineDocumentType({ type: "settings", schema: z.object({ t: z.string() }), global: true }); + const storePath = join(await mkdtemp(join(tmpdir(), "cultcache-legacy-flush-")), "generic.cc"); + const store = new SingleFileMessagePackBackingStore(storePath); + const build = () => CultCache.builder().withRegistry(defineDocumentRegistry(settingsDocument)).withGenericStore(store).build(); + const seed = CultCache.builder().withRegistry(defineDocumentRegistry(settingsDocument)).build(); + await seed.putGlobal(settingsDocument, { t: "old" }); + await store.push({ ...seed.getRequiredEnvelope(settingsDocument, CultCache.GLOBAL_KEY), key: "legacy" }); + + const cache = build(); + await cache.pullAllBackingStores(); + assert.equal(cache.snapshot()[0]!.key, CultCache.GLOBAL_KEY, "the logical image names the global by the global key"); + await store.pushAll(cache.storedSnapshot()); + assert.deepEqual((await store.pullAll()).map((entry) => entry.key), ["legacy"], "the flush wrote the record under the key the store holds it"); + const reopened = build(); + await reopened.pullAllBackingStores(); + assert.deepEqual(reopened.getRequiredGlobal(settingsDocument), { t: "old" }); +}); + test("concurrentPutAndAttachCannotLandRecordInNonHomeStore", async () => { const settingsDocument = defineDocumentType({ type: "settings", schema: z.object({ t: z.string() }) }); const tempDir = await mkdtemp(join(tmpdir(), "cultcache-put-attach-race-")); @@ -2614,6 +2633,7 @@ test("SingleFileMessagePackBackingStore rewrites a file exactly when it reads", ? store.push(envelopes[0]!) : store.delete(envelopes[0]!); if (reads) { + const heldBefore = operation === "pushAll" ? (await new SingleFileMessagePackBackingStore(file).pullAll()).map((entry) => entry.key) : []; await run(); if (operation === "pullAll") { continue; @@ -2631,7 +2651,7 @@ test("SingleFileMessagePackBackingStore rewrites a file exactly when it reads", const keys = (await new SingleFileMessagePackBackingStore(file).pullAll()).map((entry) => entry.key); if (operation === "pushAll") { assert.deepEqual(envelopes.map((entry) => entry.key).filter((key) => !keys.includes(key)), [], `${vector} ${operation}: every written key is held`); - assert.ok(keys.length >= envelopes.length, `${vector} ${operation}: nothing else is removed`); + assert.deepEqual(heldBefore.filter((key) => !keys.includes(key)), [], `${vector} ${operation}: nothing else is removed`); } else if (operation === "push") { assert.ok(keys.includes(envelopes[0]!.key), `${vector} ${operation}`); } else { diff --git a/packages/cultmesh-ts/src/index.ts b/packages/cultmesh-ts/src/index.ts index 2f734cfd..e6f71e21 100644 --- a/packages/cultmesh-ts/src/index.ts +++ b/packages/cultmesh-ts/src/index.ts @@ -3933,7 +3933,7 @@ export class CultMeshNode { } public async flush(soft = false): Promise { - await this.store.pushAll?.(this.cache.snapshot(), { soft }); + await this.store.pushAll?.(this.cache.storedSnapshot(), { soft }); } } diff --git a/packages/cultmesh-ts/test/cultmesh.test.ts b/packages/cultmesh-ts/test/cultmesh.test.ts index b22d5d65..341a35b3 100644 --- a/packages/cultmesh-ts/test/cultmesh.test.ts +++ b/packages/cultmesh-ts/test/cultmesh.test.ts @@ -6,7 +6,7 @@ import test from "node:test"; import assert from "node:assert/strict"; import { decodeWireValue, encodeWireValue } from "@gamecult/cultnet-ts/wire"; import { z } from "zod"; -import { SchemaConflictError, defineDocumentType, documentPayloadBytes, documentPayloadFromBytes } from "@gamecult/cultcache-ts"; +import { SchemaConflictError, SingleFileMessagePackBackingStore, defineDocumentType, documentPayloadBytes, documentPayloadFromBytes } from "@gamecult/cultcache-ts"; import { CultNetDocumentRegistry, CultNetPeer, @@ -122,6 +122,21 @@ test("CultMesh TS flush from a node that never pulled leaves the records the sto assert.equal(reopened.getRequired(noteDocument, "note:held").body, "already in the store"); }); +test("CultMesh TS flush of a node that loaded a legacy-key global leaves the store reopenable", async () => { + const settings = defineDocumentType({ type: "cultmesh.settings", schema: z.object({ theme: z.string() }), global: true }); + const filePath = join(await mkdtemp(join(tmpdir(), "cultmesh-ts-legacy-flush-")), "node.ccmp"); + const seed = await CultMesh.startNode(join(await mkdtemp(join(tmpdir(), "cultmesh-ts-seed-")), "seed.ccmp"), { documents: [settings] }); + await seed.cache.putGlobal(settings, { theme: "iron" }); + const legacy = { ...seed.cache.getRequiredEnvelope(settings, "__global__"), key: "legacy" }; + await new SingleFileMessagePackBackingStore(filePath).push(legacy); + + const node = await CultMesh.startNode(filePath, { documents: [settings] }); + await node.flush(); + + const reopened = await CultMesh.startNode(filePath, { documents: [settings] }); + assert.deepEqual(reopened.cache.getRequiredGlobal(settings), { theme: "iron" }); +}); + test("CultMesh TS document handles hide local cache plumbing behind typed reactive reads", async () => { const filePath = join(await mkdtemp(join(tmpdir(), "cultmesh-ts-doc-")), "node.ccmp"); const node = await CultMesh.startNode(filePath, {