@alma-harness/testing 0.1.0

package/dist/index.js

@@ -0,0 +1,1510 @@
+// src/session-store-contract.ts
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { toWellFormedDeep } from "@alma-harness/core";
+var ALICE = { org: "org-a", uid: "user-alice" };
+var BOB = { org: "org-a", uid: "user-bob" };
+var OTHER_ORG = { org: "org-b", uid: "user-alice" };
+function text(role, body) {
+  return {
+    role,
+    blocks: [{ type: "text", text: body }],
+    meta: { at: "2026-01-01T00:00:00.000Z" }
+  };
+}
+function withTools(at) {
+  return [
+    { role: "user", blocks: [{ type: "text", text: "check my notes" }], meta: { at } },
+    {
+      role: "assistant",
+      blocks: [
+        { type: "text", text: "one moment" },
+        { type: "tool_call", id: "c1", name: "listNotes", input: {} }
+      ],
+      meta: { at }
+    },
+    {
+      role: "tool",
+      blocks: [{ type: "tool_result", callId: "c1", output: "two notes" }],
+      meta: { at }
+    },
+    { role: "assistant", blocks: [{ type: "text", text: "you have two" }], meta: { at } }
+  ];
+}
+var kinds = (history) => history.map((m) => m.blocks.map((b) => b.type));
+function bodies(history) {
+  return history.map((m) => m.blocks[0]?.type === "text" ? m.blocks[0].text : m.blocks[0]);
+}
+function describeSessionStoreContract(name, factory) {
+  describe(`SessionStore contract: ${name}`, () => {
+    let store;
+    beforeEach(async () => {
+      store = await factory.create();
+    });
+    afterEach(async () => {
+      await factory.destroy?.(store);
+    });
+    it("round-trips appended messages, preserving content and order", async () => {
+      const entries = [text("user", "hello"), text("assistant", "hi there")];
+      await store.append(ALICE, "s1", entries);
+      const history = await store.load(ALICE, "s1");
+      expect(history).toEqual(entries);
+    });
+    it("round-trips astral-plane text unchanged \u2014 emoji and CJK, not just ASCII", async () => {
+      const entries = [
+        text("user", "n\xE3o aguento mais \u{1F642}\u{1F1E7}\u{1F1F7} \u2014 \u5BB6\u65CF\u3068\u8A71\u3057\u307E\u3057\u305F"),
+        text("assistant", "\u{1D518}\u{1D52B}\u{1D526}\u{1D520}\u{1D52C}\u{1D521}\u{1D522} \u2705")
+      ];
+      await store.append(ALICE, "s1", entries);
+      const history = await store.load(ALICE, "s1");
+      expect(history).toEqual(entries);
+      for (const body of bodies(history)) expect(String(body).isWellFormed()).toBe(true);
+    });
+    it("preserves order across sequential appends (transactional seq)", async () => {
+      await store.append(ALICE, "s1", [text("user", "1")]);
+      await store.append(ALICE, "s1", [text("assistant", "2"), text("user", "3")]);
+      await store.append(ALICE, "s1", [text("assistant", "4")]);
+      expect(bodies(await store.load(ALICE, "s1"))).toEqual(["1", "2", "3", "4"]);
+    });
+    it("resolves an unknown session to an empty history", async () => {
+      await expect(store.load(ALICE, "never-created")).resolves.toEqual([]);
+    });
+    it("isolates sessions by sessionId", async () => {
+      await store.append(ALICE, "s1", [text("user", "in s1")]);
+      await store.append(ALICE, "s2", [text("user", "in s2")]);
+      expect(bodies(await store.load(ALICE, "s1"))).toEqual(["in s1"]);
+      expect(bodies(await store.load(ALICE, "s2"))).toEqual(["in s2"]);
+    });
+    it("isolates scopes by uid and by org, even for identical session ids", async () => {
+      await store.append(ALICE, "shared-id", [text("user", "alice's")]);
+      await expect(store.load(BOB, "shared-id")).resolves.toEqual([]);
+      await expect(store.load(OTHER_ORG, "shared-id")).resolves.toEqual([]);
+    });
+    it("load with limit returns the most recent messages, still in order", async () => {
+      await store.append(ALICE, "s1", [
+        text("user", "1"),
+        text("assistant", "2"),
+        text("user", "3"),
+        text("assistant", "4")
+      ]);
+      expect(bodies(await store.load(ALICE, "s1", { limit: 2 }))).toEqual(["3", "4"]);
+    });
+    it("erase(scope, sessionId) removes only that session", async () => {
+      await store.append(ALICE, "doomed", [text("user", "bye")]);
+      await store.append(ALICE, "kept", [text("user", "stay")]);
+      await store.erase(ALICE, "doomed");
+      await expect(store.load(ALICE, "doomed")).resolves.toEqual([]);
+      expect(bodies(await store.load(ALICE, "kept"))).toEqual(["stay"]);
+    });
+    it("erase(scope) purges every session in the scope and nothing outside it", async () => {
+      await store.append(ALICE, "s1", [text("user", "a1")]);
+      await store.append(ALICE, "s2", [text("user", "a2")]);
+      await store.append(BOB, "s1", [text("user", "b1")]);
+      await store.erase(ALICE);
+      await expect(store.load(ALICE, "s1")).resolves.toEqual([]);
+      await expect(store.load(ALICE, "s2")).resolves.toEqual([]);
+      expect(bodies(await store.load(BOB, "s1"))).toEqual(["b1"]);
+    });
+    it("rejects an invalid scope even on no-op calls (empty append, non-positive limit)", async () => {
+      const bad = { org: "../evil", uid: "user-1" };
+      await expect(store.append(bad, "s1", [])).rejects.toThrow();
+      await expect(store.load(bad, "s1", { limit: 0 })).rejects.toThrow();
+      await expect(store.erase(bad)).rejects.toThrow();
+    });
+    it("expires a stale session's tool traffic and keeps everything the person saw", async () => {
+      await store.append(ALICE, "s1", withTools("2026-01-01T00:00:00.000Z"));
+      const report = await store.expireToolTraffic(ALICE, "s1", {
+        inactiveSince: "2026-06-01T00:00:00.000Z"
+      });
+      expect(report).toEqual({ blocks: 2, messages: 1, expired: true });
+      expect(kinds(await store.load(ALICE, "s1"))).toEqual([["text"], ["text"], ["text"]]);
+      expect(bodies(await store.load(ALICE, "s1"))).toEqual([
+        "check my notes",
+        "one moment",
+        "you have two"
+      ]);
+    });
+    it("refuses an ACTIVE session and touches nothing \u2014 a live prefix must not be rewritten", async () => {
+      const entries = withTools("2026-07-01T00:00:00.000Z");
+      await store.append(ALICE, "s1", entries);
+      const report = await store.expireToolTraffic(ALICE, "s1", {
+        inactiveSince: "2026-06-01T00:00:00.000Z"
+      });
+      expect(report).toEqual({ blocks: 0, messages: 0, expired: false });
+      expect(await store.load(ALICE, "s1")).toEqual(entries);
+    });
+    it("never leaves a tool_call without its tool_result \u2014 the pairing a provider enforces with a 400", async () => {
+      await store.append(ALICE, "s1", withTools("2026-01-01T00:00:00.000Z"));
+      await store.expireToolTraffic(ALICE, "s1", {
+        inactiveSince: "2026-06-01T00:00:00.000Z"
+      });
+      const flat = (await store.load(ALICE, "s1")).flatMap((m) => m.blocks.map((b) => b.type));
+      expect(flat).not.toContain("tool_call");
+      expect(flat).not.toContain("tool_result");
+    });
+    it("keeps media blocks \u2014 a pointer the user saw, not tool traffic", async () => {
+      await store.append(ALICE, "s1", [
+        {
+          role: "user",
+          blocks: [
+            { type: "media", kind: "image", ref: { uri: "gs://bucket/x.png" } },
+            { type: "tool_call", id: "c1", name: "describe", input: {} }
+          ],
+          meta: { at: "2026-01-01T00:00:00.000Z" }
+        }
+      ]);
+      await store.expireToolTraffic(ALICE, "s1", {
+        inactiveSince: "2026-06-01T00:00:00.000Z"
+      });
+      expect(kinds(await store.load(ALICE, "s1"))).toEqual([["media"]]);
+    });
+    it("expires only the named session, and validates the scope", async () => {
+      await store.append(ALICE, "s1", withTools("2026-01-01T00:00:00.000Z"));
+      await store.append(ALICE, "s2", withTools("2026-01-01T00:00:00.000Z"));
+      await store.expireToolTraffic(ALICE, "s1", {
+        inactiveSince: "2026-06-01T00:00:00.000Z"
+      });
+      expect(kinds(await store.load(ALICE, "s2"))).toEqual([
+        ["text"],
+        ["text", "tool_call"],
+        ["tool_result"],
+        ["text"]
+      ]);
+      await expect(
+        store.expireToolTraffic({ org: "../evil", uid: "u" }, "s1", {
+          inactiveSince: "2026-06-01T00:00:00.000Z"
+        })
+      ).rejects.toThrow();
+    });
+    it("round-trips a MediaRef whole, filename included", async () => {
+      const ref = {
+        uri: "gs://bucket/laudo.pdf",
+        contentType: "application/pdf",
+        bytes: 20480,
+        filename: "laudo \u2014 2026.pdf"
+      };
+      await store.append(ALICE, "s1", [
+        {
+          role: "user",
+          blocks: [{ type: "media", kind: "document", ref }],
+          meta: { at: "2026-01-01T00:00:00.000Z" }
+        }
+      ]);
+      const block = (await store.load(ALICE, "s1"))[0]?.blocks[0];
+      expect(block?.type === "media" ? block.ref : null).toEqual(ref);
+    });
+    it("round-trips a MediaRef with no filename \u2014 the field is optional", async () => {
+      const ref = { uri: "gs://bucket/x.png" };
+      await store.append(ALICE, "s1", [
+        {
+          role: "user",
+          blocks: [{ type: "media", kind: "image", ref }],
+          meta: { at: "2026-01-01T00:00:00.000Z" }
+        }
+      ]);
+      const block = (await store.load(ALICE, "s1"))[0]?.blocks[0];
+      expect(block?.type === "media" ? block.ref : null).toEqual(ref);
+      expect(block?.type === "media" ? "filename" in block.ref : true).toBe(false);
+    });
+    it("expires by the message's own meta.at, not by when the row was written", async () => {
+      await store.append(ALICE, "s1", withTools("2025-01-01T00:00:00.000Z"));
+      const report = await store.expireToolTraffic(ALICE, "s1", {
+        inactiveSince: "2025-06-01T00:00:00.000Z"
+      });
+      expect(report).toEqual({ blocks: 2, messages: 1, expired: true });
+    });
+    it("treats a message with no meta.at as ACTIVE \u2014 an age that cannot be established is not old", async () => {
+      const undated = {
+        role: "assistant",
+        blocks: [{ type: "tool_call", id: "c1", name: "x", input: {} }]
+      };
+      await store.append(ALICE, "s1", [...withTools("2025-01-01T00:00:00.000Z"), undated]);
+      const report = await store.expireToolTraffic(ALICE, "s1", {
+        inactiveSince: "2025-06-01T00:00:00.000Z"
+      });
+      expect(report).toEqual({ blocks: 0, messages: 0, expired: false });
+    });
+    it("refuses malformed UTF-16 identically on every adapter, naming the entry", async () => {
+      const lone = `broken \uD83D end`;
+      expect(lone.isWellFormed()).toBe(false);
+      await expect(
+        store.append(ALICE, "s1", [text("user", "fine"), text("assistant", lone)])
+      ).rejects.toThrow(/entries\[1\]/);
+      await expect(store.load(ALICE, "s1")).resolves.toEqual([]);
+    });
+    it("accepts the same value once toWellFormedDeep has run \u2014 the documented remedy works", async () => {
+      const repaired = toWellFormedDeep(text("assistant", `broken \uD83D end`));
+      await store.append(ALICE, "s1", [repaired]);
+      const [loaded] = await store.load(ALICE, "s1");
+      expect(loaded).toEqual(repaired);
+      expect(String(bodies([loaded])[0]).isWellFormed()).toBe(true);
+    });
+    it("returns defensive copies \u2014 mutating a loaded history never corrupts the store", async () => {
+      await store.append(ALICE, "s1", [text("user", "original")]);
+      const first = await store.load(ALICE, "s1");
+      first.pop();
+      const block = (await store.load(ALICE, "s1"))[0]?.blocks[0];
+      if (block?.type === "text") block.text = "mutated";
+      expect(bodies(await store.load(ALICE, "s1"))).toEqual(["original"]);
+    });
+  });
+}
+
+// src/episode-store-contract.ts
+import { afterEach as afterEach2, beforeEach as beforeEach2, describe as describe2, expect as expect2, it as it2 } from "vitest";
+import { deriveEpisodeId, isRecallable } from "@alma-harness/memory";
+var ALICE2 = { org: "org-a", uid: "user-alice" };
+var BOB2 = { org: "org-a", uid: "user-bob" };
+var OTHER_ORG2 = { org: "org-b", uid: "user-alice" };
+var T = {
+  old: "2026-01-01T00:00:00.000Z",
+  mid: "2026-06-01T00:00:00.000Z",
+  recent: "2026-08-01T00:00:00.000Z"
+};
+function summaries(episodes) {
+  return episodes.map((e) => e.summary);
+}
+function describeEpisodeStoreContract(name, factory) {
+  describe2(`EpisodeStore contract: ${name}`, () => {
+    let store;
+    beforeEach2(async () => {
+      store = await factory.create();
+    });
+    afterEach2(async () => {
+      await factory.destroy?.(store);
+    });
+    it2("round-trips an appended episode, defaulting importance and state", async () => {
+      const stored = await store.append(ALICE2, {
+        kind: "conversation",
+        summary: "prefers morning appointments",
+        at: T.recent,
+        source: { sessionId: "s1", turnId: "t1" }
+      });
+      expect2(stored).toMatchObject({
+        kind: "conversation",
+        summary: "prefers morning appointments",
+        at: T.recent,
+        importance: 0.5,
+        state: "active",
+        source: { sessionId: "s1", turnId: "t1" }
+      });
+      expect2(isRecallable(stored)).toBe(true);
+      const found = await store.get(ALICE2, [stored.id]);
+      expect2(found).toEqual([stored]);
+    });
+    it2("addresses episodes by a deterministic id, so re-extraction overwrites and never duplicates", async () => {
+      const input = {
+        kind: "note",
+        summary: "runs 5k on saturdays",
+        source: { sessionId: "s1", turnId: "t1" }
+      };
+      const first = await store.append(ALICE2, { ...input, at: T.old });
+      const second = await store.append(ALICE2, { ...input, at: T.recent });
+      expect2(second.id).toBe(first.id);
+      expect2(second.id).toBe(deriveEpisodeId(ALICE2, input));
+      const { episodes } = await store.query(ALICE2, {});
+      expect2(episodes).toHaveLength(1);
+    });
+    it2("derives different ids for the same content in different scopes", async () => {
+      const input = { kind: "note", summary: "same words" };
+      const mine = await store.append(ALICE2, input);
+      const theirs = await store.append(BOB2, input);
+      expect2(mine.id).not.toBe(theirs.id);
+    });
+    it2("dedupeKey separates two genuinely distinct episodes with identical content", async () => {
+      const input = { kind: "note", summary: "checked in", source: { turnId: "t1" } };
+      await store.append(ALICE2, { ...input, dedupeKey: "a" });
+      await store.append(ALICE2, { ...input, dedupeKey: "b" });
+      const { episodes } = await store.query(ALICE2, {});
+      expect2(episodes).toHaveLength(2);
+    });
+    it2("keeps a dedupeKey scoped to its content: reuse in a later turn never overwrites", async () => {
+      const first = await store.append(ALICE2, {
+        kind: "note",
+        summary: "chose the morning slot",
+        source: { turnId: "t1" },
+        dedupeKey: "choice"
+      });
+      const second = await store.append(ALICE2, {
+        kind: "note",
+        summary: "chose the evening slot",
+        source: { turnId: "t2" },
+        dedupeKey: "choice"
+      });
+      expect2(second.id).not.toBe(first.id);
+      expect2((await store.get(ALICE2, [first.id]))[0]).toMatchObject({
+        summary: "chose the morning slot"
+      });
+    });
+    it2("normalizes timestamps to canonical UTC, so backends never disagree", async () => {
+      const stored = await store.append(ALICE2, {
+        kind: "note",
+        summary: "written with an offset",
+        at: "2026-08-01T02:00:00+02:00"
+      });
+      expect2(stored.at).toBe("2026-08-01T00:00:00.000Z");
+      expect2((await store.get(ALICE2, [stored.id]))[0]?.at).toBe("2026-08-01T00:00:00.000Z");
+    });
+    it2("isolates scopes by uid and by org", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "alice's memory" });
+      await expect2(store.query(BOB2, {})).resolves.toMatchObject({ episodes: [] });
+      await expect2(store.query(OTHER_ORG2, {})).resolves.toMatchObject({ episodes: [] });
+    });
+    it2("filters by kind and by time range", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "note one", at: T.old });
+      await store.append(ALICE2, { kind: "observation", summary: "observed thing", at: T.mid });
+      await store.append(ALICE2, { kind: "note", summary: "note two", at: T.recent });
+      const byKind = await store.query(ALICE2, { kinds: ["observation"] });
+      expect2(summaries(byKind.episodes)).toEqual(["observed thing"]);
+      const byRange = await store.query(ALICE2, { since: T.mid, until: T.recent });
+      expect2(summaries(byRange.episodes).sort()).toEqual(["note two", "observed thing"]);
+    });
+    it2("ranks a term match above a non-match, and excludes non-matches entirely", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "loves kayaking", at: T.old });
+      await store.append(ALICE2, { kind: "note", summary: "dislikes crowds", at: T.recent });
+      const { episodes } = await store.query(ALICE2, { text: "kayaking" });
+      expect2(summaries(episodes)).toEqual(["loves kayaking"]);
+    });
+    it2("finds a term deep in a long summary, past the query tokenizer's cap", async () => {
+      const filler = Array.from({ length: 40 }, (_, i) => `filler${i}`).join(" ");
+      await store.append(ALICE2, { kind: "note", summary: `${filler} chocolate` });
+      const { episodes } = await store.query(ALICE2, { text: "chocolate" });
+      expect2(episodes).toHaveLength(1);
+    });
+    it2("matches case-insensitively beyond ASCII, whatever locale the backend runs under", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "Adora CAF\xC9 da manh\xE3" });
+      const { episodes } = await store.query(ALICE2, { text: "caf\xE9" });
+      expect2(summaries(episodes)).toEqual(["Adora CAF\xC9 da manh\xE3"]);
+    });
+    it2("breaks a ranking tie toward the more recent episode", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "coffee order", at: T.old });
+      await store.append(ALICE2, { kind: "note", summary: "coffee order", dedupeKey: "b", at: T.recent });
+      const { episodes } = await store.query(ALICE2, { text: "coffee" });
+      expect2(episodes.map((e) => e.at)).toEqual([T.recent, T.old]);
+    });
+    it2("ranks higher importance above lower at equal overlap and age", async () => {
+      await store.append(ALICE2, {
+        kind: "note",
+        summary: "allergy penicillin",
+        dedupeKey: "low",
+        at: T.mid,
+        importance: 0.1
+      });
+      await store.append(ALICE2, {
+        kind: "note",
+        summary: "allergy penicillin",
+        dedupeKey: "high",
+        at: T.mid,
+        importance: 0.9
+      });
+      const { episodes } = await store.query(ALICE2, { text: "allergy" });
+      expect2(episodes.map((e) => e.importance)).toEqual([0.9, 0.1]);
+    });
+    it2("caps the read at the budget and says it truncated", async () => {
+      for (const n of ["one", "two", "three"]) {
+        await store.append(ALICE2, { kind: "note", summary: `budget ${n}`, dedupeKey: n, at: T.mid });
+      }
+      const capped = await store.query(ALICE2, { text: "budget", budget: { maxItems: 1 } });
+      expect2(capped.episodes).toHaveLength(1);
+      expect2(capped.truncated).toBe(true);
+      const uncapped = await store.query(ALICE2, { text: "budget" });
+      expect2(uncapped.episodes).toHaveLength(3);
+      expect2(uncapped.truncated).toBe(false);
+    });
+    it2("drops whole items rather than overflowing a character budget", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "x".repeat(30), dedupeKey: "big", at: T.mid });
+      const result = await store.query(ALICE2, { budget: { maxChars: 10 } });
+      expect2(result.episodes).toEqual([]);
+      expect2(result.truncated).toBe(true);
+    });
+    it2("resolves a non-positive limit to an empty result", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "present" });
+      await expect2(store.query(ALICE2, { limit: 0 })).resolves.toMatchObject({ episodes: [] });
+    });
+    it2("archives an episode out of hot recall while keeping its content intact", async () => {
+      const ep = await store.append(ALICE2, { kind: "note", summary: "seasonal detail", at: T.mid });
+      await expect2(store.archive(ALICE2, [ep.id])).resolves.toBe(1);
+      const hot = await store.query(ALICE2, { text: "seasonal" });
+      expect2(hot.episodes).toEqual([]);
+      const cold = await store.query(ALICE2, { text: "seasonal", includeArchived: true });
+      expect2(summaries(cold.episodes)).toEqual(["seasonal detail"]);
+      expect2(isRecallable(cold.episodes[0])).toBe(false);
+    });
+    it2("keeps an archived episode archived when it is re-appended", async () => {
+      const input = { kind: "note", summary: "seasonal detail", source: { turnId: "t1" } };
+      const ep = await store.append(ALICE2, input);
+      await store.archive(ALICE2, [ep.id]);
+      const reappended = await store.append(ALICE2, input);
+      expect2(reappended.state).toBe("archived");
+    });
+    it2("tombstones an episode: content gone, position kept, never recalled again", async () => {
+      const ep = await store.append(ALICE2, {
+        kind: "note",
+        summary: "sensitive detail",
+        at: T.mid,
+        source: { sessionId: "s1" }
+      });
+      const result = await store.tombstone(ALICE2, { kind: "episodes", episodeIds: [ep.id] }, T.recent);
+      expect2(result.episodeIds).toEqual([ep.id]);
+      const [stored] = await store.get(ALICE2, [ep.id]);
+      expect2(stored).toMatchObject({
+        id: ep.id,
+        kind: "",
+        // the label goes too — nothing enforces that it is not content
+        summary: "",
+        state: "tombstoned",
+        erasedAt: T.recent
+      });
+      expect2(isRecallable(stored)).toBe(false);
+      await expect2(store.query(ALICE2, { text: "sensitive" })).resolves.toMatchObject({
+        episodes: []
+      });
+      await expect2(
+        store.query(ALICE2, { text: "sensitive", includeArchived: true })
+      ).resolves.toMatchObject({ episodes: [] });
+    });
+    it2("never resurrects a tombstoned episode on re-append", async () => {
+      const input = { kind: "note", summary: "erased content", source: { turnId: "t1" } };
+      const ep = await store.append(ALICE2, input);
+      await store.tombstone(ALICE2, { kind: "episodes", episodeIds: [ep.id] }, T.recent);
+      const reappended = await store.append(ALICE2, input);
+      expect2(reappended.state).toBe("tombstoned");
+      expect2(reappended.summary).toBe("");
+      await expect2(store.query(ALICE2, { text: "erased" })).resolves.toMatchObject({ episodes: [] });
+    });
+    it2("refuses to archive a tombstoned episode", async () => {
+      const ep = await store.append(ALICE2, { kind: "note", summary: "erased" });
+      await store.tombstone(ALICE2, { kind: "episodes", episodeIds: [ep.id] }, T.recent);
+      await expect2(store.archive(ALICE2, [ep.id])).resolves.toBe(0);
+      expect2((await store.get(ALICE2, [ep.id]))[0]).toMatchObject({ state: "tombstoned" });
+    });
+    it2("tombstones every episode of a session, and nothing outside it", async () => {
+      const doomed = await store.append(ALICE2, {
+        kind: "note",
+        summary: "in the doomed session",
+        source: { sessionId: "doomed" }
+      });
+      const kept = await store.append(ALICE2, {
+        kind: "note",
+        summary: "in another session",
+        source: { sessionId: "kept" }
+      });
+      const result = await store.tombstone(ALICE2, { kind: "sessions", sessionIds: ["doomed"] }, T.recent);
+      expect2(result.episodeIds).toEqual([doomed.id]);
+      expect2((await store.get(ALICE2, [kept.id]))[0]).toMatchObject({ state: "active" });
+    });
+    it2("tombstones the whole scope on the 'all' selector, and nothing outside the scope", async () => {
+      const mine = await store.append(ALICE2, { kind: "note", summary: "mine" });
+      const theirs = await store.append(BOB2, { kind: "note", summary: "theirs" });
+      const result = await store.tombstone(ALICE2, { kind: "all" }, T.recent);
+      expect2(result.episodeIds).toEqual([mine.id]);
+      expect2((await store.get(BOB2, [theirs.id]))[0]).toMatchObject({ state: "active" });
+    });
+    it2("reports every copy surface it declares, so erasure can be proven", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "anything" });
+      const result = await store.tombstone(ALICE2, { kind: "all" }, T.recent);
+      expect2(store.copySurfaces.length).toBeGreaterThan(0);
+      for (const surface of store.copySurfaces) {
+        expect2(result.surfaces).toContain(surface.name);
+      }
+    });
+    it2("cannot be pinned to the top of every ranking by a future timestamp", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "honest coffee note", at: T.recent });
+      await store.append(ALICE2, {
+        kind: "note",
+        summary: "coffee spam",
+        dedupeKey: "future",
+        at: "9999-01-01T00:00:00.000Z"
+      });
+      const { episodes } = await store.query(ALICE2, { text: "coffee" });
+      expect2(episodes[0]?.summary).toBe("honest coffee note");
+    });
+    it2("returns nothing for a search whose text carries no usable term", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "private detail", at: T.recent });
+      await expect2(store.query(ALICE2, { text: "a" })).resolves.toMatchObject({ episodes: [] });
+      await expect2(store.query(ALICE2, { text: "???" })).resolves.toMatchObject({ episodes: [] });
+    });
+    it2("normalizes query bounds, so a bound without a timezone means one thing", async () => {
+      await store.append(ALICE2, { kind: "note", summary: "in range", at: "2026-06-15T00:00:00.000Z" });
+      const found = await store.query(ALICE2, { since: "2026-06-01T00:00:00Z" });
+      expect2(summaries(found.episodes)).toEqual(["in range"]);
+      await expect2(store.query(ALICE2, { since: "not a date" })).rejects.toThrow();
+    });
+    it2("bounds every caller-controlled size", async () => {
+      await expect2(
+        store.append(ALICE2, { kind: "note", summary: "x".repeat(1e5) })
+      ).rejects.toThrow();
+      await expect2(store.append(ALICE2, { kind: "NOT A SLUG", summary: "x" })).rejects.toThrow();
+      await expect2(store.append(ALICE2, { kind: "note", summary: "x", importance: 42 })).rejects.toThrow();
+      await expect2(store.query(ALICE2, { limit: 1e7 })).rejects.toThrow();
+      await expect2(store.query(ALICE2, { limit: 1.5 })).rejects.toThrow();
+    });
+    it2("rejects content carrying control characters no backend can store alike", async () => {
+      await expect2(
+        store.append(ALICE2, { kind: "note", summary: "before\0after" })
+      ).rejects.toThrow();
+    });
+    it2("rejects a lone surrogate no backend can store alike", async () => {
+      await expect2(
+        store.append(ALICE2, { kind: "note", summary: "before\uD83Dafter" })
+      ).rejects.toThrow();
+    });
+    it2("keeps a dedupeKey from ever colliding with a content-derived id", async () => {
+      const target = await store.append(ALICE2, {
+        kind: "clinical",
+        summary: "severe penicillin allergy",
+        source: { sessionId: "s1", turnId: "t1" }
+      });
+      const forged = await store.append(ALICE2, {
+        kind: "note",
+        summary: "no known allergies",
+        dedupeKey: JSON.stringify(["clinical", "severe penicillin allergy", "s1", "t1"])
+      });
+      expect2(forged.id).not.toBe(target.id);
+      expect2((await store.get(ALICE2, [target.id]))[0]).toMatchObject({
+        summary: "severe penicillin allergy"
+      });
+    });
+    it2("rejects an invalid scope even on no-op calls", async () => {
+      const bad = { org: "../evil", uid: "user-1" };
+      await expect2(store.append(bad, { kind: "note", summary: "x" })).rejects.toThrow();
+      await expect2(store.query(bad, { limit: 0 })).rejects.toThrow();
+      await expect2(store.get(bad, [])).rejects.toThrow();
+      await expect2(store.tombstone(bad, { kind: "episodes", episodeIds: [] }, T.recent)).rejects.toThrow();
+      await expect2(store.archive(bad, [])).rejects.toThrow();
+    });
+    it2("returns defensive copies \u2014 mutating a result never corrupts the store", async () => {
+      const ep = await store.append(ALICE2, { kind: "note", summary: "original", at: T.mid });
+      const first = await store.query(ALICE2, {});
+      const mutable = first.episodes[0];
+      mutable.summary = "mutated";
+      const [reread] = await store.get(ALICE2, [ep.id]);
+      expect2(reread?.summary).toBe("original");
+    });
+  });
+}
+
+// src/profile-store-contract.ts
+import { afterEach as afterEach3, beforeEach as beforeEach3, describe as describe3, expect as expect3, it as it3 } from "vitest";
+import { isCurrentFact } from "@alma-harness/memory";
+var ALICE3 = { org: "org-a", uid: "user-alice" };
+var BOB3 = { org: "org-a", uid: "user-bob" };
+var T2 = {
+  t1: "2026-06-01T00:00:00.000Z",
+  t2: "2026-07-01T00:00:00.000Z",
+  t3: "2026-08-01T00:00:00.000Z"
+};
+function byKey(facts, key2) {
+  return facts.filter((f) => f.key === key2);
+}
+function describeProfileStoreContract(name, factory) {
+  describe3(`ProfileStore contract: ${name}`, () => {
+    let store;
+    beforeEach3(async () => {
+      store = await factory.create();
+    });
+    afterEach3(async () => {
+      await factory.destroy?.(store);
+    });
+    it3("resolves an empty scope to an empty profile", async () => {
+      await expect3(store.get(ALICE3)).resolves.toMatchObject({ facts: [], truncated: false });
+    });
+    it3("inserts a first observation as the current fact", async () => {
+      const [result] = await store.observe(ALICE3, [
+        { key: "diet.preference", value: "vegetarian", confidence: 0.8, at: T2.t1 }
+      ]);
+      expect3(result).toMatchObject({ key: "diet.preference", outcome: "inserted" });
+      const { facts } = await store.get(ALICE3);
+      expect3(facts).toHaveLength(1);
+      expect3(facts[0]).toMatchObject({
+        key: "diet.preference",
+        value: "vegetarian",
+        confidence: 0.8,
+        observedAt: T2.t1,
+        lastSeenAt: T2.t1
+      });
+      expect3(isCurrentFact(facts[0])).toBe(true);
+    });
+    it3("refreshes a re-observed value instead of versioning it, unioning provenance", async () => {
+      await store.observe(ALICE3, [
+        { key: "city", value: "lisbon", confidence: 0.6, sourceEpisodeIds: ["ep-1"], at: T2.t1 }
+      ]);
+      const [result] = await store.observe(ALICE3, [
+        { key: "city", value: "lisbon", confidence: 0.9, sourceEpisodeIds: ["ep-2"], at: T2.t2 }
+      ]);
+      expect3(result?.outcome).toBe("refreshed");
+      const { facts } = await store.get(ALICE3, { includeHistory: true });
+      expect3(facts).toHaveLength(1);
+      expect3(facts[0]).toMatchObject({
+        value: "lisbon",
+        confidence: 0.9,
+        // corroboration raises confidence, never lowers it
+        observedAt: T2.t1,
+        lastSeenAt: T2.t2
+      });
+      expect3([...facts[0].sourceEpisodeIds].sort()).toEqual(["ep-1", "ep-2"]);
+    });
+    it3("supersedes the current value when a different one arrives at no less confidence", async () => {
+      await store.observe(ALICE3, [{ key: "city", value: "lisbon", confidence: 0.6, at: T2.t1 }]);
+      const [result] = await store.observe(ALICE3, [
+        { key: "city", value: "porto", confidence: 0.7, at: T2.t2 }
+      ]);
+      expect3(result?.outcome).toBe("superseded");
+      const current = await store.get(ALICE3);
+      expect3(current.facts).toHaveLength(1);
+      expect3(current.facts[0]).toMatchObject({ value: "porto" });
+      const history = await store.get(ALICE3, { includeHistory: true });
+      const closed = history.facts.find((f) => f.value === "lisbon");
+      expect3(closed).toMatchObject({ supersededAt: T2.t2, supersededBy: result?.factId });
+    });
+    it3("records a lower-confidence contradiction already closed and keeps the current fact", async () => {
+      await store.observe(ALICE3, [{ key: "city", value: "lisbon", confidence: 0.9, at: T2.t1 }]);
+      const [result] = await store.observe(ALICE3, [
+        { key: "city", value: "madrid", confidence: 0.3, at: T2.t2 }
+      ]);
+      expect3(result?.outcome).toBe("conflict");
+      expect3(result?.detail).toBeTruthy();
+      const current = await store.get(ALICE3);
+      expect3(current.facts).toHaveLength(1);
+      expect3(current.facts[0]).toMatchObject({ value: "lisbon" });
+      const history = await store.get(ALICE3, { includeHistory: true });
+      const rejected = history.facts.find((f) => f.value === "madrid");
+      expect3(rejected).toMatchObject({ supersededAt: T2.t2 });
+      expect3(isCurrentFact(rejected)).toBe(false);
+    });
+    it3("never resurrects a closed version when an old value returns", async () => {
+      await store.observe(ALICE3, [{ key: "city", value: "lisbon", confidence: 0.5, at: T2.t1 }]);
+      await store.observe(ALICE3, [{ key: "city", value: "porto", confidence: 0.6, at: T2.t2 }]);
+      await store.observe(ALICE3, [{ key: "city", value: "lisbon", confidence: 0.7, at: T2.t3 }]);
+      const current = await store.get(ALICE3);
+      expect3(current.facts).toHaveLength(1);
+      expect3(current.facts[0]).toMatchObject({ value: "lisbon", observedAt: T2.t3 });
+      const history = await store.get(ALICE3, { includeHistory: true });
+      expect3(byKey(history.facts, "city")).toHaveLength(3);
+      const closedLisbon = history.facts.find((f) => f.value === "lisbon" && f.observedAt === T2.t1);
+      expect3(closedLisbon?.supersededAt).toBe(T2.t2);
+    });
+    it3("refuses to write a protected profile key through the model path, writing nothing", async () => {
+      const results = await store.observe(ALICE3, [
+        { key: "identity.uid", value: "user-bob", confidence: 1, at: T2.t1 },
+        { key: "hobby", value: "climbing", confidence: 0.5, at: T2.t1 }
+      ]);
+      expect3(results[0]).toMatchObject({ key: "identity.uid", outcome: "refused" });
+      expect3(results[0]?.factId).toBeUndefined();
+      expect3(results[1]?.outcome).toBe("inserted");
+      const { facts } = await store.get(ALICE3, { includeHistory: true });
+      expect3(byKey(facts, "identity.uid")).toEqual([]);
+      expect3(byKey(facts, "hobby")).toHaveLength(1);
+    });
+    it3("lets the product write protected keys, and lets them outrank a confident extraction", async () => {
+      await store.observe(ALICE3, [{ key: "name", value: "wrong", confidence: 0.99, at: T2.t1 }]);
+      const results = await store.setProtected(ALICE3, [
+        { key: "identity.uid", value: "user-alice", at: T2.t2 },
+        { key: "name", value: "right", confidence: 0.1, at: T2.t2 }
+      ]);
+      expect3(results.map((r) => r.outcome)).toEqual(["inserted", "superseded"]);
+      const { facts } = await store.get(ALICE3);
+      expect3(facts.find((f) => f.key === "identity.uid")).toMatchObject({ value: "user-alice" });
+      expect3(facts.find((f) => f.key === "name")).toMatchObject({ value: "right" });
+    });
+    it3("caps the read at the budget, keeping the most trusted facts", async () => {
+      await store.observe(ALICE3, [
+        { key: "a", value: "low", confidence: 0.2, at: T2.t1 },
+        { key: "b", value: "high", confidence: 0.9, at: T2.t1 },
+        { key: "c", value: "mid", confidence: 0.5, at: T2.t1 }
+      ]);
+      const capped = await store.get(ALICE3, { budget: { maxItems: 2 } });
+      expect3(capped.facts.map((f) => f.key)).toEqual(["b", "c"]);
+      expect3(capped.truncated).toBe(true);
+      const uncapped = await store.get(ALICE3);
+      expect3(uncapped.facts).toHaveLength(3);
+      expect3(uncapped.truncated).toBe(false);
+    });
+    it3("invalidates every fact whose provenance intersects the erased episodes", async () => {
+      await store.observe(ALICE3, [
+        { key: "derived", value: "from ep-1", sourceEpisodeIds: ["ep-1"], at: T2.t1 },
+        { key: "independent", value: "from ep-2", sourceEpisodeIds: ["ep-2"], at: T2.t1 }
+      ]);
+      const result = await store.invalidateBySource(ALICE3, ["ep-1"], T2.t3);
+      expect3(result.invalidated).toBe(1);
+      const { facts } = await store.get(ALICE3);
+      expect3(facts.map((f) => f.key)).toEqual(["independent"]);
+      const history = await store.get(ALICE3, { includeHistory: true });
+      const erased = history.facts.filter((f) => f.invalidatedAt !== void 0);
+      expect3(erased).toHaveLength(1);
+      expect3(erased[0]).toMatchObject({ key: "", value: "", invalidatedAt: T2.t3 });
+    });
+    it3("invalidates the whole scope on 'all', without walking provenance", async () => {
+      await store.observe(ALICE3, [{ key: "unsourced", value: "no provenance", at: T2.t1 }]);
+      await store.observe(BOB3, [{ key: "theirs", value: "untouched", at: T2.t1 }]);
+      const result = await store.invalidateBySource(ALICE3, "all", T2.t3);
+      expect3(result.invalidated).toBe(1);
+      await expect3(store.get(ALICE3)).resolves.toMatchObject({ facts: [] });
+      const theirs = await store.get(BOB3);
+      expect3(theirs.facts).toHaveLength(1);
+    });
+    it3("reports every copy surface it declares, so erasure can be proven", async () => {
+      await store.observe(ALICE3, [{ key: "any", value: "thing", at: T2.t1 }]);
+      const result = await store.invalidateBySource(ALICE3, "all", T2.t3);
+      expect3(store.copySurfaces.length).toBeGreaterThan(0);
+      for (const surface of store.copySurfaces) {
+        expect3(result.surfaces).toContain(surface.name);
+      }
+    });
+    it3("normalizes timestamps to canonical UTC, so backends never disagree", async () => {
+      await store.observe(ALICE3, [{ key: "k", value: "v", at: "2026-07-01T02:00:00+02:00" }]);
+      const { facts } = await store.get(ALICE3);
+      expect3(facts[0]).toMatchObject({
+        observedAt: "2026-07-01T00:00:00.000Z",
+        lastSeenAt: "2026-07-01T00:00:00.000Z"
+      });
+    });
+    it3("isolates scopes by uid", async () => {
+      await store.observe(ALICE3, [{ key: "secret", value: "alice's", at: T2.t1 }]);
+      await expect3(store.get(BOB3)).resolves.toMatchObject({ facts: [] });
+    });
+    it3("isolates scopes by org, even for the same uid", async () => {
+      await store.observe(ALICE3, [{ key: "secret", value: "alice's", at: T2.t1 }]);
+      await expect3(store.get({ org: "org-b", uid: ALICE3.uid })).resolves.toMatchObject({
+        facts: []
+      });
+      const result = await store.invalidateBySource({ org: "org-b", uid: ALICE3.uid }, "all", T2.t2);
+      expect3(result.invalidated).toBe(0);
+      await expect3(store.get(ALICE3)).resolves.toMatchObject({
+        facts: [expect3.objectContaining({ key: "secret" })]
+      });
+    });
+    it3("leaves exactly one current version under concurrent observations of one key", async () => {
+      await Promise.all(
+        ["a", "b", "c", "d", "e"].map(
+          (value, i) => store.observe(ALICE3, [
+            { key: "contended", value, confidence: 0.5, at: `2026-08-0${i + 1}T00:00:00.000Z` }
+          ])
+        )
+      );
+      const { facts } = await store.get(ALICE3);
+      expect3(byKey(facts, "contended")).toHaveLength(1);
+    });
+    it3("survives concurrent multi-key observations naming the keys in opposite orders", async () => {
+      const keys = ["k1", "k2", "k3", "k4", "k5", "k6", "k7", "k8"];
+      const forward = keys.map((key2) => ({ key: key2, value: `${key2}-forward`, at: T2.t1 }));
+      const reverse = [...keys].reverse().map((key2) => ({ key: key2, value: `${key2}-reverse`, at: T2.t2 }));
+      await Promise.all([store.observe(ALICE3, forward), store.observe(ALICE3, reverse)]);
+      const { facts } = await store.get(ALICE3);
+      expect3(facts.map((f) => f.key).sort()).toEqual(keys);
+    });
+    it3("refuses every spelling of a protected key, not just the canonical one", async () => {
+      for (const key2 of [
+        "identity.uid",
+        " identity.uid",
+        "Identity.uid",
+        "IDENTITY.uid",
+        "identity\u2024uid",
+        // U+2024 ONE DOT LEADER
+        "\u0131dentity.uid"
+        // U+0131 LATIN SMALL LETTER DOTLESS I
+      ]) {
+        const attempt = store.observe(ALICE3, [{ key: key2, value: "user-bob", confidence: 1, at: T2.t1 }]);
+        const written = await attempt.then(
+          (results) => results[0]?.outcome === "refused" ? false : true,
+          () => false
+          // rejected outright by key validation
+        );
+        expect3(written, `key ${JSON.stringify(key2)} must not be writable`).toBe(false);
+      }
+      const { facts } = await store.get(ALICE3, { includeHistory: true });
+      expect3(facts).toEqual([]);
+    });
+    it3("admits one canonical spelling per key, so no two facts look identical", async () => {
+      await expect3(store.observe(ALICE3, [{ key: "pref.caf\xE9", value: "x" }])).rejects.toThrow();
+      await expect3(store.observe(ALICE3, [{ key: "pref.cafe\u0301", value: "x" }])).rejects.toThrow();
+    });
+    it3("rejects a confidence outside 0..1, which would pin a fact forever", async () => {
+      await store.observe(ALICE3, [{ key: "allergy", value: "severe", confidence: 0.9, at: T2.t1 }]);
+      for (const confidence of [999, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+        await expect3(
+          store.observe(ALICE3, [{ key: "allergy", value: "none", confidence, at: T2.t2 }])
+        ).rejects.toThrow();
+      }
+      expect3((await store.get(ALICE3)).facts[0]).toMatchObject({ value: "severe" });
+    });
+    it3("chains two observations of ONE key inside a single batch", async () => {
+      const results = await store.observe(ALICE3, [
+        { key: "city", value: "lisbon", confidence: 0.5, at: T2.t1 },
+        { key: "city", value: "porto", confidence: 0.9, at: T2.t2 }
+      ]);
+      expect3(results.map((r) => r.outcome)).toEqual(["inserted", "superseded"]);
+      const current = await store.get(ALICE3);
+      expect3(byKey(current.facts, "city")).toHaveLength(1);
+      expect3(current.facts[0]).toMatchObject({ value: "porto" });
+      const history = await store.get(ALICE3, { includeHistory: true });
+      expect3(byKey(history.facts, "city")).toHaveLength(2);
+      expect3(history.facts.find((f) => f.value === "lisbon")).toMatchObject({
+        supersededAt: T2.t2,
+        supersededBy: results[1]?.factId
+      });
+    });
+    it3("refreshes inside a single batch the version that batch just inserted", async () => {
+      const results = await store.observe(ALICE3, [
+        { key: "diet", value: "vegetarian", confidence: 0.4, at: T2.t1 },
+        { key: "diet", value: "vegetarian", confidence: 0.8, at: T2.t2 }
+      ]);
+      expect3(results.map((r) => r.outcome)).toEqual(["inserted", "refreshed"]);
+      const { facts } = await store.get(ALICE3, { includeHistory: true });
+      expect3(byKey(facts, "diet")).toHaveLength(1);
+      expect3(facts[0]).toMatchObject({
+        confidence: 0.8,
+        // corroboration raises it
+        observedAt: T2.t1,
+        lastSeenAt: T2.t2
+      });
+    });
+    it3("applies every outcome a mixed batch calls for, in one pass", async () => {
+      await store.observe(ALICE3, [
+        { key: "a", value: "keep", confidence: 0.9, at: T2.t1 },
+        { key: "b", value: "old", confidence: 0.3, at: T2.t1 },
+        { key: "c", value: "strong", confidence: 0.9, at: T2.t1 }
+      ]);
+      const results = await store.observe(ALICE3, [
+        { key: "a", value: "keep", confidence: 0.95, at: T2.t2 },
+        { key: "b", value: "new", confidence: 0.6, at: T2.t2 },
+        { key: "c", value: "weak", confidence: 0.1, at: T2.t2 },
+        { key: "d", value: "fresh", confidence: 0.5, at: T2.t2 }
+      ]);
+      expect3(results.map((r) => r.outcome)).toEqual([
+        "refreshed",
+        "superseded",
+        "conflict",
+        "inserted"
+      ]);
+      const { facts } = await store.get(ALICE3);
+      expect3(facts.map((f) => `${f.key}=${f.value}`).sort()).toEqual([
+        "a=keep",
+        "b=new",
+        "c=strong",
+        "d=fresh"
+      ]);
+    });
+    it3("applies a batch atomically: one invalid observation writes none of them", async () => {
+      await expect3(
+        store.observe(ALICE3, [
+          { key: "good", value: "written?", at: T2.t1 },
+          { key: "bad", value: "x", confidence: 42, at: T2.t1 }
+        ])
+      ).rejects.toThrow();
+      await expect3(store.get(ALICE3)).resolves.toMatchObject({ facts: [] });
+    });
+    it3("reports a replay as a replay, never as a refresh of the current belief", async () => {
+      await store.observe(ALICE3, [{ key: "city", value: "lisbon", confidence: 0.5, at: T2.t1 }]);
+      await store.observe(ALICE3, [{ key: "city", value: "porto", confidence: 0.6, at: T2.t2 }]);
+      const [result] = await store.observe(ALICE3, [
+        { key: "city", value: "lisbon", confidence: 0.5, at: T2.t1 }
+      ]);
+      expect3(result?.outcome).toBe("replayed");
+      expect3((await store.get(ALICE3)).facts[0]).toMatchObject({ value: "porto" });
+    });
+    it3("bounds every caller-controlled size", async () => {
+      await expect3(
+        store.observe(ALICE3, [{ key: "k", value: "x".repeat(1e5) }])
+      ).rejects.toThrow();
+      await expect3(
+        store.observe(
+          ALICE3,
+          Array.from({ length: 5e3 }, (_, i) => ({ key: `k${i}`, value: "v" }))
+        )
+      ).rejects.toThrow();
+      await expect3(store.observe(ALICE3, [{ key: "k", value: "v", ttlDays: 0.5 }])).rejects.toThrow();
+      await expect3(store.observe(ALICE3, [{ key: "k", value: "v", ttlDays: -1 }])).rejects.toThrow();
+    });
+    it3("accepts a batch whose observations are each within the citation limit", async () => {
+      const cite = (prefix) => Array.from({ length: 600 }, (_, i) => `${prefix}-${i}`);
+      const results = await store.observe(ALICE3, [
+        { key: "wide.a", value: "v", sourceEpisodeIds: cite("a") },
+        { key: "wide.b", value: "v", sourceEpisodeIds: cite("b") }
+      ]);
+      expect3(results.map((r) => r.outcome)).toEqual(["inserted", "inserted"]);
+    });
+    it3("rejects an invalid scope even on no-op calls", async () => {
+      const bad = { org: "../evil", uid: "user-1" };
+      await expect3(store.get(bad)).rejects.toThrow();
+      await expect3(store.observe(bad, [])).rejects.toThrow();
+      await expect3(store.setProtected(bad, [])).rejects.toThrow();
+      await expect3(store.invalidateBySource(bad, [], T2.t3)).rejects.toThrow();
+    });
+    it3("returns defensive copies \u2014 mutating a result never corrupts the store", async () => {
+      await store.observe(ALICE3, [{ key: "stable", value: "original", at: T2.t1 }]);
+      const first = await store.get(ALICE3);
+      first.facts[0].value = "mutated";
+      const second = await store.get(ALICE3);
+      expect3(second.facts[0]?.value).toBe("original");
+    });
+  });
+}
+
+// src/memory-erasure-contract.ts
+import { afterEach as afterEach4, beforeEach as beforeEach4, describe as describe4, expect as expect4, it as it4 } from "vitest";
+var ALICE4 = { org: "org-a", uid: "user-alice" };
+var BOB4 = { org: "org-a", uid: "user-bob" };
+function describeMemoryErasureContract(name, factory) {
+  describe4(`MemoryErasure contract: ${name}`, () => {
+    let fx;
+    beforeEach4(async () => {
+      fx = await factory.create();
+    });
+    afterEach4(async () => {
+      await factory.destroy?.(fx);
+    });
+    async function seedSupportedFact(scope, sessionId, marker) {
+      const episode = await fx.episodes.append(scope, {
+        kind: "conversation",
+        summary: `${marker} disclosed something sensitive`,
+        source: { sessionId }
+      });
+      await fx.profile.observe(scope, [
+        { key: `derived.${marker}`, value: marker, sourceEpisodeIds: [episode.id] }
+      ]);
+      return episode;
+    }
+    it4("erases an episode: content blanked, out of recall, and its derived facts invalidated", async () => {
+      const doomed = await seedSupportedFact(ALICE4, "s1", "doomed");
+      const kept = await seedSupportedFact(ALICE4, "s2", "kept");
+      const report = await fx.erasure.erase(ALICE4, {
+        kind: "episodes",
+        episodeIds: [doomed.id]
+      });
+      expect4(report.tombstonesWritten).toBe(1);
+      expect4(report.derivedInvalidated).toBe(1);
+      expect4(report.complete).toBe(true);
+      const [tombstone] = await fx.episodes.get(ALICE4, [doomed.id]);
+      expect4(tombstone).toMatchObject({ summary: "", state: "tombstoned", erasedAt: report.erasedAt });
+      await expect4(fx.episodes.query(ALICE4, { text: "doomed" })).resolves.toMatchObject({
+        episodes: []
+      });
+      const { facts } = await fx.profile.get(ALICE4);
+      expect4(facts.map((f) => f.key)).toEqual(["derived.kept"]);
+      expect4((await fx.episodes.get(ALICE4, [kept.id]))[0]).toMatchObject({ state: "active" });
+    });
+    it4("erases a session's episodes and nothing outside it", async () => {
+      const doomed = await seedSupportedFact(ALICE4, "doomed-session", "alpha");
+      const kept = await seedSupportedFact(ALICE4, "kept-session", "beta");
+      const report = await fx.erasure.erase(ALICE4, {
+        kind: "sessions",
+        sessionIds: ["doomed-session"]
+      });
+      expect4(report.tombstonesWritten).toBe(1);
+      expect4((await fx.episodes.get(ALICE4, [doomed.id]))[0]).toMatchObject({ state: "tombstoned" });
+      expect4((await fx.episodes.get(ALICE4, [kept.id]))[0]).toMatchObject({ state: "active" });
+      expect4((await fx.profile.get(ALICE4)).facts.map((f) => f.key)).toEqual(["derived.beta"]);
+    });
+    it4("erases the whole scope, invalidating even facts with no provenance link", async () => {
+      await seedSupportedFact(ALICE4, "s1", "sourced");
+      await fx.profile.observe(ALICE4, [{ key: "unsourced", value: "orphan fact" }]);
+      const theirs = await seedSupportedFact(BOB4, "s1", "theirs");
+      const report = await fx.erasure.erase(ALICE4, { kind: "all" });
+      expect4(report.derivedInvalidated).toBe(2);
+      await expect4(fx.profile.get(ALICE4)).resolves.toMatchObject({ facts: [] });
+      await expect4(fx.episodes.query(ALICE4, {})).resolves.toMatchObject({ episodes: [] });
+      expect4((await fx.episodes.get(BOB4, [theirs.id]))[0]).toMatchObject({ state: "active" });
+      expect4((await fx.profile.get(BOB4)).facts).toHaveLength(1);
+    });
+    it4("names every copy surface both stores declare, and reports the erasure complete", async () => {
+      await seedSupportedFact(ALICE4, "s1", "gamma");
+      const report = await fx.erasure.erase(ALICE4, { kind: "all" });
+      const declared = [...fx.episodes.copySurfaces, ...fx.profile.copySurfaces];
+      expect4(declared.length).toBeGreaterThan(0);
+      for (const surface of declared) {
+        expect4(report.surfaces).toContainEqual({
+          name: surface.name,
+          kind: surface.kind,
+          reached: true
+        });
+      }
+      expect4(report.complete).toBe(true);
+    });
+    it4("stamps the scope's erasure watermark for the in-flight job guard", async () => {
+      if (!fx.watermarks) return;
+      await expect4(fx.watermarks.get(ALICE4)).resolves.toBeNull();
+      const report = await fx.erasure.erase(ALICE4, { kind: "all" });
+      await expect4(fx.watermarks.get(ALICE4)).resolves.toBe(report.erasedAt);
+      await expect4(fx.watermarks.get(BOB4)).resolves.toBeNull();
+    });
+    it4("stops at the ORG boundary: erasing a uid in one org never touches its twin elsewhere", async () => {
+      const TWIN = { org: "org-b", uid: ALICE4.uid };
+      await seedSupportedFact(ALICE4, "s1", "mine");
+      const twin = await seedSupportedFact(TWIN, "s1", "twin");
+      await fx.erasure.erase(ALICE4, { kind: "all" });
+      expect4((await fx.episodes.get(TWIN, [twin.id]))[0]).toMatchObject({ state: "active" });
+      expect4((await fx.profile.get(TWIN)).facts).toHaveLength(1);
+      if (fx.watermarks) await expect4(fx.watermarks.get(TWIN)).resolves.toBeNull();
+    });
+    it4("never moves the watermark backwards, whatever clock stamps the second erasure", async () => {
+      if (!fx.watermarks) return;
+      await fx.watermarks.set(ALICE4, "2026-06-01T00:00:10.000Z");
+      await fx.watermarks.set(ALICE4, "2026-06-01T00:00:00.000Z");
+      await expect4(fx.watermarks.get(ALICE4)).resolves.toBe("2026-06-01T00:00:10.000Z");
+    });
+    it4("removes the CONTENT of every derived fact, not just its current flag", async () => {
+      const ep = await seedSupportedFact(ALICE4, "s1", "diagnosis");
+      await fx.erasure.erase(ALICE4, { kind: "episodes", episodeIds: [ep.id] });
+      const history = await fx.profile.get(ALICE4, { includeHistory: true });
+      expect4(history.facts).toHaveLength(1);
+      expect4(history.facts[0]).toMatchObject({ key: "", value: "" });
+      expect4(JSON.stringify(history.facts[0])).not.toContain("diagnosis");
+    });
+    it4("leaves no label behind on a tombstoned episode either", async () => {
+      const ep = await fx.episodes.append(ALICE4, {
+        kind: "clinical",
+        summary: "disclosed something sensitive"
+      });
+      await fx.erasure.erase(ALICE4, { kind: "all" });
+      const [tombstone] = await fx.episodes.get(ALICE4, [ep.id]);
+      expect4(tombstone).toMatchObject({ kind: "", summary: "", state: "tombstoned" });
+    });
+    it4("discloses nothing about WHEN the erased data was last touched", async () => {
+      await fx.profile.observe(ALICE4, [
+        { key: "sensitive", value: "content", at: "2026-06-01T00:00:00.000Z" }
+      ]);
+      await fx.erasure.erase(ALICE4, { kind: "all" });
+      const profile = await fx.profile.get(ALICE4);
+      expect4(profile.facts).toEqual([]);
+      expect4(profile.updatedAt).not.toContain("2026-06-01");
+    });
+    it4("invalidates derived facts on a RE-RUN, so a half-failed erasure self-heals", async () => {
+      const ep = await seedSupportedFact(ALICE4, "s1", "epsilon");
+      await fx.episodes.tombstone(ALICE4, { kind: "episodes", episodeIds: [ep.id] }, (/* @__PURE__ */ new Date()).toISOString());
+      const recovery = await fx.erasure.erase(ALICE4, { kind: "episodes", episodeIds: [ep.id] });
+      expect4(recovery.tombstonesWritten).toBe(0);
+      expect4(recovery.derivedInvalidated).toBe(1);
+      await expect4(fx.profile.get(ALICE4)).resolves.toMatchObject({ facts: [] });
+    });
+    it4("refuses an observation submitted from before the erasure", async () => {
+      if (!fx.watermarks) return;
+      const before = new Date(Date.now() - 6e4).toISOString();
+      await fx.erasure.erase(ALICE4, { kind: "all" });
+      const [result] = await fx.profile.observe(ALICE4, [
+        { key: "resurrected", value: "erased content", at: before }
+      ]);
+      expect4(result?.outcome).toBe("stale");
+      await expect4(fx.profile.get(ALICE4)).resolves.toMatchObject({ facts: [] });
+    });
+    it4("refuses a write that cites an episode this erasure removed", async () => {
+      const ep = await fx.episodes.append(ALICE4, { kind: "clinical", summary: "disclosed" });
+      await fx.erasure.erase(ALICE4, { kind: "episodes", episodeIds: [ep.id] });
+      const [result] = await fx.profile.observe(ALICE4, [
+        // No `at` — "now", which the watermark comparison would wave through.
+        { key: "health.status", value: "positive", sourceEpisodeIds: [ep.id] }
+      ]);
+      expect4(result?.outcome).toBe("stale");
+      await expect4(fx.profile.get(ALICE4)).resolves.toMatchObject({ facts: [] });
+    });
+    it4("refuses an episode stamped before the erasure, not only a fact", async () => {
+      if (!fx.watermarks) return;
+      const before = new Date(Date.now() - 6e4).toISOString();
+      await fx.erasure.erase(ALICE4, { kind: "all" });
+      await expect4(
+        fx.episodes.append(ALICE4, { kind: "note", summary: "in flight", at: before })
+      ).rejects.toThrow();
+    });
+    it4("records a trail even when the erasure fails partway", async () => {
+      if (!fx.accessEvents) return;
+      const before = fx.accessEvents.length;
+      await expect4(
+        fx.erasure.erase(ALICE4, {
+          kind: "episodes",
+          episodeIds: Array.from({ length: 5e3 }, (_, i) => `id-${i}`)
+        })
+      ).rejects.toThrow();
+      expect4(fx.accessEvents.length).toBe(before);
+      if (fx.watermarks) await expect4(fx.watermarks.get(ALICE4)).resolves.toBeNull();
+    });
+    it4("leaves an audit trail proving the erasure ran, carrying no content", async () => {
+      if (!fx.accessEvents) return;
+      await seedSupportedFact(ALICE4, "s1", "zeta");
+      await fx.erasure.erase(ALICE4, { kind: "all" });
+      const erasures = fx.accessEvents.filter((e) => e.action === "delete");
+      expect4(erasures).toHaveLength(1);
+      expect4(erasures[0]).toMatchObject({ scope: ALICE4, action: "delete" });
+      expect4(JSON.stringify(erasures[0])).not.toContain("zeta");
+    });
+    it4("is idempotent: erasing twice writes no second tombstone", async () => {
+      const ep = await seedSupportedFact(ALICE4, "s1", "delta");
+      await fx.erasure.erase(ALICE4, { kind: "episodes", episodeIds: [ep.id] });
+      const second = await fx.erasure.erase(ALICE4, { kind: "episodes", episodeIds: [ep.id] });
+      expect4(second.tombstonesWritten).toBe(0);
+      expect4(second.derivedInvalidated).toBe(0);
+    });
+    it4("rejects an invalid scope", async () => {
+      const bad = { org: "../evil", uid: "user-1" };
+      await expect4(fx.erasure.erase(bad, { kind: "all" })).rejects.toThrow();
+    });
+  });
+}
+
+// src/spend-store-contract.ts
+import { afterEach as afterEach5, beforeEach as beforeEach5, describe as describe5, expect as expect5, it as it5 } from "vitest";
+var ALICE5 = { org: "org-a", uid: "user-alice" };
+var BOB5 = { org: "org-a", uid: "user-bob" };
+var OTHER_ORG3 = { org: "org-b", uid: "user-alice" };
+var T3 = {
+  day1: "2026-08-24T10:00:00.000Z",
+  day1Late: "2026-08-24T23:59:59.000Z",
+  day2: "2026-08-25T00:00:00.000Z",
+  /** 01:00+02:00 on the 25th IS 23:00Z on the 24th. */
+  day1ByOffset: "2026-08-25T01:00:00+02:00"
+};
+function describeSpendStoreContract(name, factory) {
+  describe5(`SpendStore contract: ${name}`, () => {
+    let store;
+    beforeEach5(async () => {
+      store = await factory.create();
+    });
+    afterEach5(async () => {
+      await factory.destroy?.(store);
+    });
+    it5("starts every counter at zero", async () => {
+      await expect5(store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day1 })).resolves.toEqual({
+        sessionUsd: 0,
+        tenantDayUsd: 0
+      });
+    });
+    it5("add returns the post-add totals and accumulates both counters", async () => {
+      const first = await store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1, usd: 0.5 });
+      expect5(first.sessionUsd).toBeCloseTo(0.5, 9);
+      expect5(first.tenantDayUsd).toBeCloseTo(0.5, 9);
+      const second = await store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1, usd: 0.25 });
+      expect5(second.sessionUsd).toBeCloseTo(0.75, 9);
+      expect5(second.tenantDayUsd).toBeCloseTo(0.75, 9);
+      const peeked = await store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day1 });
+      expect5(peeked.sessionUsd).toBeCloseTo(0.75, 9);
+      expect5(peeked.tenantDayUsd).toBeCloseTo(0.75, 9);
+    });
+    it5("isolates the session counter by sessionId, uid, and org \u2014 while the day counter aggregates the org", async () => {
+      await store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1, usd: 1 });
+      await store.add({ scope: ALICE5, sessionId: "s2", at: T3.day1, usd: 2 });
+      await store.add({ scope: BOB5, sessionId: "s1", at: T3.day1, usd: 4 });
+      await store.add({ scope: OTHER_ORG3, sessionId: "s1", at: T3.day1, usd: 8 });
+      const aliceS1 = await store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day1 });
+      expect5(aliceS1.sessionUsd).toBeCloseTo(1, 9);
+      expect5(aliceS1.tenantDayUsd).toBeCloseTo(7, 9);
+      const otherOrg = await store.peek({ scope: OTHER_ORG3, sessionId: "s1", at: T3.day1 });
+      expect5(otherOrg.sessionUsd).toBeCloseTo(8, 9);
+      expect5(otherOrg.tenantDayUsd).toBeCloseTo(8, 9);
+    });
+    it5("buckets the day counter by UTC calendar day \u2014 the session counter has no day dimension", async () => {
+      await store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1, usd: 1 });
+      await store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1Late, usd: 2 });
+      await store.add({ scope: ALICE5, sessionId: "s1", at: T3.day2, usd: 4 });
+      const onDay1 = await store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day1 });
+      expect5(onDay1.tenantDayUsd).toBeCloseTo(3, 9);
+      expect5(onDay1.sessionUsd).toBeCloseTo(7, 9);
+      const onDay2 = await store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day2 });
+      expect5(onDay2.tenantDayUsd).toBeCloseTo(4, 9);
+      expect5(onDay2.sessionUsd).toBeCloseTo(7, 9);
+    });
+    it5("derives the day from the UTC instant, never from the timestamp's local offset", async () => {
+      await store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1ByOffset, usd: 1 });
+      const day1 = await store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day1 });
+      expect5(day1.tenantDayUsd).toBeCloseTo(1, 9);
+      const day2 = await store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day2 });
+      expect5(day2.tenantDayUsd).toBe(0);
+    });
+    it5("accumulates fractional-cent amounts without rounding them away", async () => {
+      for (let i = 0; i < 3; i++) {
+        await store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1, usd: 2e-6 });
+      }
+      const totals = await store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day1 });
+      expect5(totals.sessionUsd).toBeCloseTo(6e-6, 9);
+    });
+    it5("loses no increment under concurrent adds, and every returned total is a distinct running sum", async () => {
+      const results = await Promise.all(
+        Array.from(
+          { length: 20 },
+          () => store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1, usd: 0.01 })
+        )
+      );
+      const totals = await store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day1 });
+      expect5(totals.sessionUsd).toBeCloseTo(0.2, 9);
+      expect5(totals.tenantDayUsd).toBeCloseTo(0.2, 9);
+      const distinct = new Set(results.map((r) => r.sessionUsd.toFixed(8)));
+      expect5(distinct.size).toBe(20);
+    });
+    it5("rejects a negative or non-finite spend, which would poison both counters", async () => {
+      for (const usd of [-1, Number.NaN, Number.POSITIVE_INFINITY]) {
+        await expect5(
+          store.add({ scope: ALICE5, sessionId: "s1", at: T3.day1, usd })
+        ).rejects.toThrow();
+      }
+      await expect5(store.peek({ scope: ALICE5, sessionId: "s1", at: T3.day1 })).resolves.toEqual({
+        sessionUsd: 0,
+        tenantDayUsd: 0
+      });
+    });
+    it5("buckets an offset-less timestamp identically on every backend \u2014 by the process clock, never the server's", async () => {
+      const local = "2026-08-24T12:00:00";
+      const day = new Date(Date.parse(local)).toISOString().slice(0, 10);
+      await store.add({ scope: ALICE5, sessionId: "s1", at: local, usd: 1 });
+      const totals = await store.peek({
+        scope: ALICE5,
+        sessionId: "s1",
+        at: `${day}T12:00:00.000Z`
+      });
+      expect5(totals.tenantDayUsd).toBeCloseTo(1, 9);
+    });
+    it5("rejects an invalid scope even on reads", async () => {
+      const bad = { org: "../evil", uid: "user-1" };
+      await expect5(store.add({ scope: bad, sessionId: "s1", at: T3.day1, usd: 1 })).rejects.toThrow();
+      await expect5(store.peek({ scope: bad, sessionId: "s1", at: T3.day1 })).rejects.toThrow();
+    });
+    it5("rejects an unparseable timestamp instead of inventing a bucket", async () => {
+      await expect5(
+        store.add({ scope: ALICE5, sessionId: "s1", at: "not a date", usd: 1 })
+      ).rejects.toThrow();
+      await expect5(store.peek({ scope: ALICE5, sessionId: "s1", at: "not a date" })).rejects.toThrow();
+    });
+  });
+}
+
+// src/turn-store-contract.ts
+import { afterEach as afterEach6, beforeEach as beforeEach6, describe as describe6, expect as expect6, it as it6 } from "vitest";
+var ALICE6 = { org: "org-a", uid: "user-alice" };
+var BOB6 = { org: "org-a", uid: "user-bob" };
+var OTHER_ORG4 = { org: "org-b", uid: "user-alice" };
+var NEVER_EXPIRES = { ttlMs: 6e4, waitMs: 0 };
+function completedTurn(over = {}) {
+  return {
+    reply: { role: "assistant", blocks: [{ type: "text", text: "the reply" }] },
+    terminalReason: "completed",
+    stopReason: "end_turn",
+    usage: { inputTokens: 10, outputTokens: 5 },
+    costUsd: 3e-5,
+    steps: 2,
+    durationMs: 1234,
+    turnId: "turn-1",
+    at: "2026-08-26T10:00:00.000Z",
+    ...over
+  };
+}
+var key = (scope, sessionId, idempotencyKey) => ({
+  scope,
+  sessionId,
+  idempotencyKey
+});
+function describeTurnStoreContract(name, factory) {
+  describe6(`TurnStore contract: ${name}`, () => {
+    let store;
+    beforeEach6(async () => {
+      store = await factory.create();
+    });
+    afterEach6(async () => {
+      await factory.destroy?.(store);
+    });
+    it6("hands a free session to the caller, and refuses a held one once the wait expires", async () => {
+      const held = await store.acquire(ALICE6, "s1", NEVER_EXPIRES);
+      expect6(held).not.toBeNull();
+      await expect6(store.acquire(ALICE6, "s1", NEVER_EXPIRES)).resolves.toBeNull();
+    });
+    it6("picks exactly ONE winner among concurrent acquirers", async () => {
+      const results = await Promise.all(
+        Array.from({ length: 10 }, () => store.acquire(ALICE6, "s1", NEVER_EXPIRES))
+      );
+      expect6(results.filter((r) => r !== null)).toHaveLength(1);
+    });
+    it6("isolates leases by session, uid, and org", async () => {
+      await store.acquire(ALICE6, "s1", NEVER_EXPIRES);
+      for (const [scope, sessionId] of [
+        [ALICE6, "s2"],
+        [BOB6, "s1"],
+        [OTHER_ORG4, "s1"]
+      ]) {
+        await expect6(store.acquire(scope, sessionId, NEVER_EXPIRES)).resolves.not.toBeNull();
+      }
+    });
+    it6("frees the session on release, so the next caller gets it", async () => {
+      const lease = await store.acquire(ALICE6, "s1", NEVER_EXPIRES);
+      await store.release(ALICE6, "s1", lease);
+      await expect6(store.acquire(ALICE6, "s1", NEVER_EXPIRES)).resolves.not.toBeNull();
+    });
+    it6("ignores a STALE release instead of freeing the current holder's session", async () => {
+      const stale = await store.acquire(ALICE6, "s1", { ttlMs: 20, waitMs: 0 });
+      await new Promise((r) => setTimeout(r, 60));
+      const current = await store.acquire(ALICE6, "s1", { ttlMs: 6e4, waitMs: 200 });
+      expect6(current.token).not.toBe(stale.token);
+      await store.release(ALICE6, "s1", stale);
+      await expect6(store.acquire(ALICE6, "s1", NEVER_EXPIRES)).resolves.toBeNull();
+      await store.release(ALICE6, "s1", current);
+      await expect6(store.acquire(ALICE6, "s1", NEVER_EXPIRES)).resolves.not.toBeNull();
+    });
+    it6("lets a later caller take a lease whose TTL expired \u2014 a crashed holder never blocks a session forever", async () => {
+      await store.acquire(ALICE6, "s1", { ttlMs: 20, waitMs: 0 });
+      await new Promise((r) => setTimeout(r, 60));
+      await expect6(store.acquire(ALICE6, "s1", NEVER_EXPIRES)).resolves.not.toBeNull();
+    });
+    it6("WAITS for a busy session and takes it when the holder releases inside the window", async () => {
+      const lease = await store.acquire(ALICE6, "s1", { ttlMs: 6e4, waitMs: 0 });
+      const waiting = store.acquire(ALICE6, "s1", { ttlMs: 6e4, waitMs: 2e3 });
+      setTimeout(() => void store.release(ALICE6, "s1", lease), 30);
+      await expect6(waiting).resolves.not.toBeNull();
+    });
+    it6("releases idempotently \u2014 a second release is not another holder's release", async () => {
+      const lease = await store.acquire(ALICE6, "s1", NEVER_EXPIRES);
+      await store.release(ALICE6, "s1", lease);
+      const next = await store.acquire(ALICE6, "s1", NEVER_EXPIRES);
+      await store.release(ALICE6, "s1", lease);
+      await expect6(store.acquire(ALICE6, "s1", NEVER_EXPIRES)).resolves.toBeNull();
+      await store.release(ALICE6, "s1", next);
+    });
+    it6("reports a first claim fresh, and replays it once completed", async () => {
+      const k = key(ALICE6, "s1", "wamid-1");
+      await expect6(store.claim(k)).resolves.toEqual({ status: "fresh" });
+      const completed = completedTurn();
+      await store.complete(k, completed);
+      const claim = await store.claim(k);
+      expect6(claim.status).toBe("replay");
+      expect6(claim.status === "replay" && claim.completed).toEqual(completed);
+    });
+    it6("replays a FAILED turn as faithfully as a successful one", async () => {
+      const k = key(ALICE6, "s1", "wamid-err");
+      await store.claim(k);
+      const completed = completedTurn({
+        terminalReason: "error",
+        stopReason: null,
+        reply: { role: "assistant", blocks: [] }
+      });
+      await store.complete(k, completed);
+      const claim = await store.claim(k);
+      expect6(claim.status === "replay" && claim.completed).toEqual(completed);
+    });
+    it6("reports an IN-FLIGHT claim fresh \u2014 a crashed turn must be runnable again", async () => {
+      const k = key(ALICE6, "s1", "wamid-crash");
+      await store.claim(k);
+      await expect6(store.claim(k)).resolves.toEqual({ status: "fresh" });
+    });
+    it6("refuses a malformed reply identically on every adapter", async () => {
+      const k = key(ALICE6, "s1", "wamid-malformed");
+      await store.claim(k);
+      await expect6(
+        store.complete(k, completedTurn({
+          reply: { role: "assistant", blocks: [{ type: "text", text: `bad \uD83D end` }] }
+        }))
+      ).rejects.toThrow(/completed/);
+      await expect6(store.claim(k)).resolves.toEqual({ status: "fresh" });
+    });
+    it6("refuses a malformed reply even for a claim that no longer exists", async () => {
+      const k = key(ALICE6, "s-erased", "wamid-gone");
+      await store.claim(k);
+      await store.erase(ALICE6, "s-erased");
+      await expect6(
+        store.complete(k, completedTurn({
+          reply: { role: "assistant", blocks: [{ type: "text", text: `bad \uD83D end` }] }
+        }))
+      ).rejects.toThrow(/completed/);
+    });
+    it6("makes a claim runnable again after abandon", async () => {
+      const k = key(ALICE6, "s1", "wamid-2");
+      await store.claim(k);
+      await store.complete(k, completedTurn());
+      await store.abandon(k);
+      await expect6(store.claim(k)).resolves.toEqual({ status: "fresh" });
+    });
+    it6("isolates claims by key, session, uid, and org", async () => {
+      const k = key(ALICE6, "s1", "shared-key");
+      await store.claim(k);
+      await store.complete(k, completedTurn());
+      for (const other of [
+        key(ALICE6, "s1", "different-key"),
+        key(ALICE6, "s2", "shared-key"),
+        key(BOB6, "s1", "shared-key"),
+        key(OTHER_ORG4, "s1", "shared-key")
+      ]) {
+        await expect6(store.claim(other)).resolves.toEqual({ status: "fresh" });
+      }
+    });
+    it6("round-trips a reply with astral characters intact", async () => {
+      const k = key(ALICE6, "s1", "wamid-emoji");
+      await store.claim(k);
+      const completed = completedTurn({
+        reply: { role: "assistant", blocks: [{ type: "text", text: "at\xE9 logo \u{1F44B}\u{1F3FD} \u5BB6" }] }
+      });
+      await store.complete(k, completed);
+      const claim = await store.claim(k);
+      expect6(claim.status === "replay" && claim.completed.reply).toEqual(completed.reply);
+    });
+    it6("does not resurrect a claim erased while its turn was still running", async () => {
+      const k = key(ALICE6, "s1", "wamid-erased");
+      await store.claim(k);
+      await store.erase(ALICE6, "s1");
+      await store.complete(k, completedTurn());
+      await expect6(store.claim(k)).resolves.toEqual({ status: "fresh" });
+    });
+    it6("erases one session's claims and lease, leaving its siblings alone", async () => {
+      const target = key(ALICE6, "s1", "wamid-3");
+      const sibling = key(ALICE6, "s2", "wamid-3");
+      for (const k of [target, sibling]) {
+        await store.claim(k);
+        await store.complete(k, completedTurn());
+      }
+      await store.acquire(ALICE6, "s1", NEVER_EXPIRES);
+      await store.erase(ALICE6, "s1");
+      await expect6(store.claim(target)).resolves.toEqual({ status: "fresh" });
+      await expect6(store.acquire(ALICE6, "s1", NEVER_EXPIRES)).resolves.not.toBeNull();
+      const siblingClaim = await store.claim(sibling);
+      expect6(siblingClaim.status).toBe("replay");
+    });
+    it6("erases ONLY the named session, even when a sibling's id extends it", async () => {
+      const target = key(ALICE6, "s1", "wamid-5");
+      const extended = key(ALICE6, "s1/legacy", "wamid-5");
+      for (const k of [target, extended]) {
+        await store.claim(k);
+        await store.complete(k, completedTurn());
+      }
+      await store.erase(ALICE6, "s1");
+      await expect6(store.claim(target)).resolves.toEqual({ status: "fresh" });
+      const survivor = await store.claim(extended);
+      expect6(survivor.status).toBe("replay");
+    });
+    it6("erases every session in a scope without a sessionId, and stops at the scope boundary", async () => {
+      for (const [scope, sessionId] of [
+        [ALICE6, "s1"],
+        [ALICE6, "s2"],
+        [BOB6, "s1"],
+        [OTHER_ORG4, "s1"]
+      ]) {
+        const k = key(scope, sessionId, "wamid-4");
+        await store.claim(k);
+        await store.complete(k, completedTurn());
+      }
+      await store.erase(ALICE6);
+      await expect6(store.claim(key(ALICE6, "s1", "wamid-4"))).resolves.toEqual({ status: "fresh" });
+      await expect6(store.claim(key(ALICE6, "s2", "wamid-4"))).resolves.toEqual({ status: "fresh" });
+      for (const scope of [BOB6, OTHER_ORG4]) {
+        const claim = await store.claim(key(scope, "s1", "wamid-4"));
+        expect6(claim.status).toBe("replay");
+      }
+    });
+    it6("rejects an invalid scope on every surface", async () => {
+      const bad = { org: "../evil", uid: "user-1" };
+      await expect6(store.acquire(bad, "s1", NEVER_EXPIRES)).rejects.toThrow();
+      await expect6(store.claim(key(bad, "s1", "k"))).rejects.toThrow();
+      await expect6(store.complete(key(bad, "s1", "k"), completedTurn())).rejects.toThrow();
+      await expect6(store.abandon(key(bad, "s1", "k"))).rejects.toThrow();
+      await expect6(store.erase(bad)).rejects.toThrow();
+    });
+    it6("rejects a non-finite or negative lease duration instead of holding forever", async () => {
+      for (const opts of [
+        { ttlMs: Number.NaN, waitMs: 0 },
+        { ttlMs: -1, waitMs: 0 },
+        { ttlMs: 1e3, waitMs: Number.NaN }
+      ]) {
+        await expect6(store.acquire(ALICE6, "s1", opts)).rejects.toThrow();
+      }
+    });
+  });
+}
+export {
+  describeEpisodeStoreContract,
+  describeMemoryErasureContract,
+  describeProfileStoreContract,
+  describeSessionStoreContract,
+  describeSpendStoreContract,
+  describeTurnStoreContract
+};
+//# sourceMappingURL=index.js.map