From 6c4d9f81d1792bf48492a19f9bc6eed90bbbf959 Mon Sep 17 00:00:00 2001 From: Libby Date: Wed, 11 Nov 2026 14:46:24 +0000 Subject: [PATCH] cultcache-ts: refuse a duplicate key in a legacy envelope array; refuse a second type under a stored key on push and pushAll Co-Authored-By: Claude Sonnet 5.5 --- .../single-file-messagepack-backing-store.ts | 36 +++++++++-- packages/cultcache-ts/test/cult-cache.test.ts | 36 +++++++++-- packages/cultcache-ts/test/store-file.test.ts | 59 ++++++++++++++++++- 3 files changed, 121 insertions(+), 10 deletions(-) diff --git a/packages/cultcache-ts/src/single-file-messagepack-backing-store.ts b/packages/cultcache-ts/src/single-file-messagepack-backing-store.ts index 9bf63932..b4984913 100644 --- a/packages/cultcache-ts/src/single-file-messagepack-backing-store.ts +++ b/packages/cultcache-ts/src/single-file-messagepack-backing-store.ts @@ -60,9 +60,8 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore { const disk = this.#readDisk(); this.#format = disk.format; const existing = disk.envelopes; - const filtered = existing.filter( - (candidate) => !(candidate.type === entry.type && candidate.key === entry.key), - ); + requireOneTypePerKey(this.filePath, [entry], existing); + const filtered = existing.filter((candidate) => candidate.key !== entry.key); await this.#writeAll([entry], filtered); }); } @@ -103,6 +102,7 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore { this.#format = STORE_FORMAT_VERSION; } + requireOneTypePerKey(this.filePath, entries, []); await this.#writeAll(entries, []); }); } @@ -137,6 +137,28 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore { } } +// A store holds a key once, and the reader refuses a file that holds it twice, so a write that would put a second type under a +// key (against a record on disk, or within its own batch) is refused before anything is written. Retyping a record is a delete +// of the old type followed by a put of the new one. +function requireOneTypePerKey(path: string, supplied: CultCacheEnvelope[], held: CultCacheEnvelope[]): void { + const typeByKey = new Map(); + for (const entry of held) { + typeByKey.set(entry.key, entry); + } + for (const entry of supplied) { + const prior = typeByKey.get(entry.key); + if (prior !== undefined && prior.type !== entry.type) { + throw new SchemaConflictError( + schemaIdForEnvelope(entry), + [prior.type, entry.type], + entry.key, + `CultCache store ${path} holds record "${entry.key}" as type "${prior.type}", so type "${entry.type}" cannot be written under the same key; remove the record first.`, + ); + } + typeByKey.set(entry.key, entry); + } +} + /** * The one reader of a CultCache single-file store, for this package's store and for any consumer that must read a * store file (an authority bundle, say) rather than decode it itself. A path with nothing at it is an absent, empty, @@ -417,6 +439,7 @@ function decodeStoreFile(data: Uint8Array): Omit throw new Error("CultCache file is not a recognized CultCache MessagePack store."); } + requireUniqueKeys(legacy); const normalized = legacy.map((entry) => ({ ...entry, payload: normalizePayload(entry.payload) })); return { format: STORE_FORMAT_VERSION, envelopes: envelopeArraySchema.parse(normalized).map((entry) => ({ ...entry, payload: documentPayloadFromBytes(entry.payload) })) as CultCacheEnvelope[] }; } @@ -450,6 +473,12 @@ function decodeSnapshot(decoded: unknown): DecodedSnapshot | undefined { } const records = recordsRaw.map(decodeRecord); + requireUniqueKeys(records); + return { format: decoded[0], catalogBySchemaId, records }; +} + +// A store holds a key once, whatever the type: a repeat is refused in a v1 snapshot and in a legacy envelope array alike. +function requireUniqueKeys(records: Array<{ key: string }>): void { const seen = new Set(); for (const { key } of records) { if (seen.has(key)) { @@ -457,7 +486,6 @@ function decodeSnapshot(decoded: unknown): DecodedSnapshot | undefined { } seen.add(key); } - return { format: decoded[0], catalogBySchemaId, records }; } function decodeCatalogEntry(value: unknown): CultCacheSchemaCatalogEntry { diff --git a/packages/cultcache-ts/test/cult-cache.test.ts b/packages/cultcache-ts/test/cult-cache.test.ts index dba79eff..d7780482 100644 --- a/packages/cultcache-ts/test/cult-cache.test.ts +++ b/packages/cultcache-ts/test/cult-cache.test.ts @@ -143,6 +143,33 @@ test("CultCache supports registry bootstrap, global documents, and lookup by nam }); }); +test("a put that would land a second type under a persisted key is refused, the cache and the file are unchanged, and the store reloads", async () => { + const alpha = defineDocumentType({ type: "alpha", schema: z.object({ v: z.number() }) }); + const beta = defineDocumentType({ type: "beta", schema: z.object({ v: z.number() }) }); + const storePath = join(await mkdtemp(join(tmpdir(), "cultcache-ts-")), "cache.msgpack"); + const registry = defineDocumentRegistry(alpha, beta); + const open = () => CultCache.builder().withRegistry(registry).withGenericStore(new SingleFileMessagePackBackingStore(storePath)).build(); + + const cache = open(); + await cache.put(alpha, "shared", { v: 1 }); + const before = [...(await readFile(storePath))]; + await assert.rejects(() => cache.put(beta, "shared", { v: 2 }), SchemaConflictError); + assert.deepEqual([...(await readFile(storePath))], before); + assert.deepEqual(cache.get(alpha, "shared"), { v: 1 }); + assert.equal(cache.get(beta, "shared"), undefined); + + const reloaded = open(); + await reloaded.pullAllBackingStores(); + assert.deepEqual(reloaded.get(alpha, "shared"), { v: 1 }); + + assert.equal(await cache.delete(alpha, "shared"), true); + await cache.put(beta, "shared", { v: 2 }); + const retyped = open(); + await retyped.pullAllBackingStores(); + assert.equal(retyped.get(alpha, "shared"), undefined); + assert.deepEqual(retyped.get(beta, "shared"), { v: 2 }); +}); + test("CultCache can register name and index lookups after entries already exist", async () => { const noteDocument = defineDocumentType({ type: "note", @@ -2582,18 +2609,17 @@ test("SingleFileMessagePackBackingStore replaces a file exactly when it reads", } }); -// One key is held once: a record pushed under a key replaces the stored record under that key, whatever its type, so the writer cannot -// emit a store its own reader refuses. -test("SingleFileMessagePackBackingStore push replaces the stored record under a key whatever the type", async () => { +// One key is held once: a push of a second type under a stored key is refused, so the writer cannot emit a store its own reader refuses. +test("SingleFileMessagePackBackingStore push refuses a second type under a stored key", async () => { const seed = CultCache.builder().withDocumentType(ownsId).withDocumentType(listsId).build(); await seed.put(ownsId, "k", { name: "owner" }); await seed.put(listsId, "k", { name: "lister" }); const file = join(await mkdtemp(join(tmpdir(), "cultcache-push-key-")), "store.msgpack"); const store = new SingleFileMessagePackBackingStore(file); await store.push(seed.getRequiredEnvelope(ownsId, "k")); - await store.push(seed.getRequiredEnvelope(listsId, "k")); + await assert.rejects(() => store.push(seed.getRequiredEnvelope(listsId, "k")), SchemaConflictError); const records = (decode(await readFile(file)) as unknown[][])[2] as unknown[][]; - assert.deepEqual(records.map((record) => [record[0], record[1]]), [["k", "id.lister"]]); + assert.deepEqual(records.map((record) => [record[0], record[1]]), [["k", "id.owned"]]); assert.equal((await store.pullAll()).length, 1); }); diff --git a/packages/cultcache-ts/test/store-file.test.ts b/packages/cultcache-ts/test/store-file.test.ts index ed2c469c..1ff23320 100644 --- a/packages/cultcache-ts/test/store-file.test.ts +++ b/packages/cultcache-ts/test/store-file.test.ts @@ -12,6 +12,7 @@ import { decode, encode } from "@msgpack/msgpack"; import { documentPayloadBytes, documentPayloadFromBytes } from "../src/document"; import { SingleFileMessagePackBackingStore } from "../src/single-file-messagepack-backing-store"; +import { SchemaConflictError, StoreUnreadableError } from "../src/store-format"; import type { CultCacheEnvelope } from "../src/types"; import { @@ -571,7 +572,7 @@ const snapshotOf = async (store: SingleFileMessagePackBackingStore): Promise `${entry.type}/${entry.key}:${[...documentPayloadBytes(entry.payload)].at(-1)}`) .sort(); -test("push replaces the record under the same key whatever its type and keeps every other", async () => { +test("push replaces the record under the same key and type and keeps every other; retyping is delete then push", async () => { const directory = await scratch(); try { const store = new SingleFileMessagePackBackingStore(join(directory, "store.cc")); @@ -580,6 +581,7 @@ test("push replaces the record under the same key whatever its type and keeps ev assert.deepEqual(await snapshotOf(store), ["t/a:9", "t/b:2", "u/c:3"]); await store.push(entryOf("d", "t", 4)); assert.deepEqual(await snapshotOf(store), ["t/a:9", "t/b:2", "t/d:4", "u/c:3"]); + await store.delete(entryOf("a", "t")); await store.push(entryOf("a", "u", 5)); assert.deepEqual(await snapshotOf(store), ["t/b:2", "t/d:4", "u/a:5", "u/c:3"]); } finally { @@ -587,6 +589,61 @@ test("push replaces the record under the same key whatever its type and keeps ev } }); +test("a push that would land a second type under an existing key is refused and the file is byte for byte unchanged", async () => { + const directory = await scratch(); + try { + const path = join(directory, "store.cc"); + const store = new SingleFileMessagePackBackingStore(path); + await store.pushAll([entryOf("k", "t", 1), entryOf("m", "t", 2)]); + const before = [...(await readFile(path))]; + await assert.rejects( + () => store.push(entryOf("k", "u", 9)), + (error: unknown) => error instanceof SchemaConflictError && error.recordKey === "k" && /holds record "k" as type "t"/u.test(error.message), + ); + assert.deepEqual([...(await readFile(path))], before); + assert.deepEqual(await snapshotOf(new SingleFileMessagePackBackingStore(path)), ["t/k:1", "t/m:2"]); + } finally { + await rm(directory, { recursive: true, force: true }); + } +}); + +test("a pushAll batch that carries one key under two types is refused and writes nothing", async () => { + const directory = await scratch(); + try { + const path = join(directory, "store.cc"); + const store = new SingleFileMessagePackBackingStore(path); + await assert.rejects(() => store.pushAll([entryOf("k", "t", 1), entryOf("k", "u", 2)]), SchemaConflictError); + assert.equal((await readdir(directory)).includes("store.cc"), false); + await store.pushAll([entryOf("a", "t", 1)]); + const before = [...(await readFile(path))]; + await assert.rejects(() => store.pushAll([entryOf("k", "t", 1), entryOf("k", "u", 2)]), SchemaConflictError); + assert.deepEqual([...(await readFile(path))], before); + } finally { + await rm(directory, { recursive: true, force: true }); + } +}); + +test("a legacy envelope array that holds a key under two types is refused on open, as a v1 store is", async () => { + const directory = await scratch(); + try { + const path = join(directory, "legacy.cc"); + const bytes = encode([ + { key: "a", type: "t", payload: { n: 1 }, storedAt: "2026-10-20T00:00:00Z" }, + { key: "a", type: "u", payload: { n: 2 }, storedAt: "2026-10-20T00:00:00Z" }, + ]); + await writeFile(path, bytes); + const store = new SingleFileMessagePackBackingStore(path); + await assert.rejects( + () => store.pullAll(), + (error: unknown) => error instanceof StoreUnreadableError && /"a" appears more than once/u.test(error.message), + ); + await assert.rejects(() => store.push(entryOf("b")), StoreUnreadableError); + assert.deepEqual([...(await readFile(path))], [...bytes]); + } finally { + await rm(directory, { recursive: true, force: true }); + } +}); + test("delete removes only the record at that type and key", async () => { const directory = await scratch(); try {