cultcache-ts: retype refusal asks whether the written type owns the stored schema id; changelog records the duplicate-key refusals

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

packages/cultcache-ts/CHANGELOG.md

@@ -14,6 +14,10 @@ All notable changes to `@gamecult/cultcache-ts` are recorded here, following
   an empty string is no longer a value. `registerIndex` over held duplicates installs nothing. A new `roles` map names
   the many-row selection aliases (never indexed for lookup, same catalog `indexAlias`). The per-key migration rule is
   in the README; classify every key before the CultLib your tools load is updated. The refusal verdict is the contract, its text is informational.
+- The single-file reader (v1 and the legacy envelope array) refuses a store that holds two records under one key as `StoreUnreadableError`; a store that opened before may now be refused. Repair it by removing the extra record with the runtime that wrote it.
+- A `put`, `push` or `pushAll` that would land a second type under a held key (against the file, or within one batch) is refused with `SchemaConflictError`, and nothing is written. The written type may replace the record when its catalog entry carries the stored schema id as its own or lists it compatible (a type renamed under a stable id restamps the record, as C# does); otherwise retyping a key is a delete, then a put. The C# allowance for an undeclared older id of the same schema name that reads whole is not ported: a same-named type keeps passing.
+- Same-type writes replace by key; in one `pushAll` batch the last entry for a key wins.
+- A store whose canonical-schema catalog slot is not a string is refused as `StoreUnreadableError`.
 
 ### Changed
 

packages/cultcache-ts/src/single-file-messagepack-backing-store.ts

@@ -138,6 +138,14 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
   }
 }
 
+// As C# WrittenOwns' declared half: the written type owns the stored schema id when its catalog entry carries that id as its own
+// or lists it compatible, so a type renamed under a stable id restamps the record it already holds. (The C# half that lets an
+// undeclared older id of the same schema name through when it reads whole is not ported; a same-named type keeps passing.)
+function writtenOwns(written: CultCacheEnvelope, storedId: string): boolean {
+  const entry = written.catalogEntry;
+  return entry !== undefined && (entry.schemaId === storedId || (entry.compatibleSchemaIds ?? []).includes(storedId));
+}
+
 // 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.
@@ -148,7 +156,7 @@ function requireOneTypePerKey(path: string, supplied: CultCacheEnvelope[], held:
   }
   for (const entry of supplied) {
     const prior = typeByKey.get(entry.key);
-    if (prior !== undefined && prior.type !== entry.type) {
+    if (prior !== undefined && prior.type !== entry.type && !writtenOwns(entry, schemaIdForEnvelope(prior))) {
       throw new SchemaConflictError(
         schemaIdForEnvelope(entry),
         [prior.type, entry.type],

packages/cultcache-ts/test/cult-cache.test.ts

@@ -14,7 +14,7 @@ import { z } from "zod";
 import { CultCache } from "../src/cult-cache";
 import { inspectCultCacheBytes } from "../src/cult-cache-inspector";
 import { defineDocumentRegistry, defineDocumentType, documentPayloadBytes, documentPayloadFromBytes } from "../src/document";
-import { SingleFileMessagePackBackingStore, readStoreBytes } from "../src/single-file-messagepack-backing-store";
+import { SingleFileMessagePackBackingStore, readSingleFileStore, readStoreBytes } from "../src/single-file-messagepack-backing-store";
 import { SchemaConflictError, StoreUnreadableError, refuseUnreadStoreBytes } from "../src/store-format";
 import type { AnyCultCacheDocumentDefinition, CacheBackingStore, CultCacheEnvelope, CultCacheSchema } from "../src/types";
 
@@ -170,6 +170,36 @@ test("a put that would land a second type under a persisted key is refused, the
   assert.deepEqual(retyped.get(beta, "shared"), { v: 2 });
 });
 
+test("a put by a type renamed under the stored id, which lists that id compatible, restamps the record; an unrelated type is refused", async () => {
+  const old = defineDocumentType({ type: "ren.old", schema: z.object({ v: z.number() }), schemaId: "ren.id.v1", schemaName: "ren.old" });
+  const renamed = defineDocumentType({
+    type: "ren.new",
+    schema: z.object({ v: z.number() }),
+    schemaId: "ren.id.v2",
+    schemaName: "ren.new",
+    compatibleSchemaIds: ["ren.id.v2", "ren.id.v1"],
+  });
+  const other = defineDocumentType({ type: "ren.other", schema: z.object({ v: z.number() }), schemaId: "ren.id.other", schemaName: "ren.other" });
+  const storePath = join(await mkdtemp(join(tmpdir(), "cultcache-ts-")), "cache.msgpack");
+  const open = (...types: (typeof old)[]) =>
+    types
+      .reduce((builder, type) => builder.withDocumentType(type), CultCache.builder())
+      .withGenericStore(new SingleFileMessagePackBackingStore(storePath))
+      .build();
+
+  await open(old).put(old, "k", { v: 1 });
+  const cache = open(renamed, other as unknown as typeof old);
+  await cache.pullAllBackingStores();
+  assert.deepEqual(cache.get(renamed, "k"), { v: 1 });
+  await assert.rejects(() => cache.put(other, "k", { v: 9 }), SchemaConflictError);
+  await cache.put(renamed, "k", { v: 2 });
+
+  const reloaded = open(renamed);
+  await reloaded.pullAllBackingStores();
+  assert.deepEqual(reloaded.get(renamed, "k"), { v: 2 });
+  assert.equal(readSingleFileStore(storePath).envelopes.filter((envelope) => envelope.key === "k").length, 1);
+});
+
 test("CultCache can register name and index lookups after entries already exist", async () => {
   const noteDocument = defineDocumentType({
     type: "note",
@@ -2609,17 +2639,22 @@ test("SingleFileMessagePackBackingStore replaces a file exactly when it reads",
   }
 });
 
-// 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 () => {
+// One key is held once: a push whose type does not own the stored schema id is refused, so the writer cannot emit a store its own
+// reader refuses; one whose type owns it (its own id, or one it lists compatible, as C# WrittenOwns) restamps the record in place.
+test("SingleFileMessagePackBackingStore push asks whether the written type owns the stored id, not what the types are called", 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 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.owned"]]);
+  const idsOf = async () => ((decode(await readFile(file)) as unknown[][])[2] as unknown[][]).map((record) => [record[0], record[1]]);
+
+  await store.push(seed.getRequiredEnvelope(listsId, "k"));
+  await assert.rejects(() => store.push(seed.getRequiredEnvelope(ownsId, "k")), SchemaConflictError);
+  assert.deepEqual(await idsOf(), [["k", "id.lister"]]);
+
+  await store.pushAll([seed.getRequiredEnvelope(listsId, "k")]);
+  await store.push(seed.getRequiredEnvelope(listsId, "k"));
   assert.equal((await store.pullAll()).length, 1);
 });