@remnic/core 9.7.15 → 9.9.0

package/src/testing/subjects/serialized-write-chain.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Serialized-write-chain lifecycle subject for the scenario-matrix harness
+ * (issue #1993, PR2). The session-toggle store (session-toggles.ts) is §28's
+ * origin — a session-scoped, restart-recoverable subsystem whose durability
+ * hinges on a serialized write chain (`queueWrite`) that must not lose an
+ * update under concurrent read-modify-write. Retrofitted as the second
+ * reference `LifecycleSubject` so the matrix's concurrency/restart rows guard
+ * that chain directly.
+ *
+ * The nine rows are realized honestly against the store's real behavior — no
+ * mocks: identity binding, remembered vs sparse bindings, rebinding, restart
+ * reload, burst compaction, concurrent flush ordering, and idempotent replay.
+ */
+
+import assert from "node:assert/strict";
+import { readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { createFileToggleStore, type SessionToggleStore } from "../../session-toggles.js";
+import { mkTempMemoryDir } from "../orchestrator-lite.js";
+import { type LifecycleSubject, type MatrixRow, runLifecycleMatrix } from "../lifecycle-matrix.js";
+
+interface SerializedWriteState {
+  dir: string;
+  filePath: string;
+  store: SessionToggleStore;
+}
+
+const AGENT = "engram";
+
+/** Read the raw persisted toggle file (validates it is well-formed JSON). */
+async function readToggleFileEntries(filePath: string): Promise<Record<string, { disabled: boolean }>> {
+  const raw = await readFile(filePath, "utf8");
+  const parsed: unknown = JSON.parse(raw);
+  if (
+    parsed &&
+    typeof parsed === "object" &&
+    "entries" in parsed &&
+    parsed.entries &&
+    typeof parsed.entries === "object"
+  ) {
+    return parsed.entries as Record<string, { disabled: boolean }>;
+  }
+  throw new Error(`toggle file is not a well-formed ToggleFile: ${raw}`);
+}
+
+const subject: LifecycleSubject<SerializedWriteState> = {
+  async setup(row: MatrixRow): Promise<SerializedWriteState> {
+    const dir = await mkTempMemoryDir(`toggles-${row.id}`);
+    try {
+      const filePath = path.join(dir, "session-toggles.json");
+      return { dir, filePath, store: createFileToggleStore(filePath) };
+    } catch (err) {
+      // Transactional setup: a partial build must not leak the temp dir.
+      await rm(dir, { recursive: true, force: true });
+      throw err;
+    }
+  },
+
+  async exercise(state: SerializedWriteState, row: MatrixRow): Promise<void> {
+    switch (row.id) {
+      case "explicit-provider-identity": {
+        await state.store.setDisabled("session-explicit", AGENT, true);
+        return;
+      }
+      case "sparse-metadata-with-binding": {
+        // A binding remembered on disk from a prior session — no write in THIS
+        // session, yet the sparse lookup resolves it through the persisted file.
+        await writeFile(
+          state.filePath,
+          JSON.stringify(
+            {
+              version: 1,
+              entries: {
+                [`${encodeURIComponent("session-remembered")}::${encodeURIComponent(AGENT)}`]: {
+                  disabled: true,
+                  updatedAt: new Date(Date.now() - 3600_000).toISOString(),
+                },
+              },
+            },
+            null,
+            2,
+          ),
+          "utf8",
+        );
+        return;
+      }
+      case "sparse-metadata-without-binding": {
+        // No write, no seed — nothing to resolve.
+        return;
+      }
+      case "provider-rebinding": {
+        await state.store.setDisabled("session-rebind", AGENT, true);
+        await state.store.setDisabled("session-rebind", AGENT, false);
+        return;
+      }
+      case "restart-reload-recovery": {
+        await state.store.setDisabled("session-restart", AGENT, true);
+        // Simulate a restart: a brand-new store over the same file.
+        state.store = createFileToggleStore(state.filePath);
+        return;
+      }
+      case "compaction-flush": {
+        for (let i = 0; i < 6; i += 1) {
+          await state.store.setDisabled(`session-compact-${i}`, AGENT, true);
+        }
+        for (let i = 0; i < 6; i += 1) {
+          await state.store.clear(`session-compact-${i}`, AGENT);
+        }
+        return;
+      }
+      case "before-reset": {
+        // Serialized-write-chain core: fire many concurrent read-modify-write
+        // toggles at once. The queue must apply every one — a broken chain
+        // loses updates (last-writer-wins clobbering).
+        await Promise.all(
+          Array.from({ length: 12 }, (_unused, i) =>
+            state.store.setDisabled(`session-burst-${i}`, AGENT, true),
+          ),
+        );
+        return;
+      }
+      case "session-end": {
+        // Concurrent set + clear on the SAME key, then a final drain. Ordering
+        // is deterministic (queue order), and the file must stay well-formed.
+        await Promise.all([
+          state.store.setDisabled("session-final", AGENT, true),
+          state.store.setDisabled("session-final", AGENT, false),
+          state.store.clear("session-final", AGENT),
+          state.store.setDisabled("session-final", AGENT, true),
+        ]);
+        return;
+      }
+      case "dedupe-replay": {
+        await state.store.setDisabled("session-replay", AGENT, true);
+        await state.store.setDisabled("session-replay", AGENT, true);
+        return;
+      }
+      default: {
+        const exhaustive: never = row.id;
+        throw new Error(`unhandled row ${String(exhaustive)}`);
+      }
+    }
+  },
+
+  async invariants(state: SerializedWriteState, row: MatrixRow): Promise<void> {
+    switch (row.id) {
+      case "explicit-provider-identity": {
+        const resolved = await state.store.resolve("session-explicit", AGENT);
+        assert.equal(resolved.disabled, true);
+        assert.equal(resolved.source, "primary", "an explicit write binds the primary source");
+        return;
+      }
+      case "sparse-metadata-with-binding": {
+        const resolved = await state.store.resolve("session-remembered", AGENT);
+        assert.equal(resolved.disabled, true, "the remembered binding resolves for a sparse lookup");
+        assert.equal(resolved.source, "primary");
+        return;
+      }
+      case "sparse-metadata-without-binding": {
+        const resolved = await state.store.resolve("session-unknown", AGENT);
+        assert.equal(resolved.disabled, false, "an unbound lookup must not fabricate a disabled state");
+        assert.equal(resolved.source, "none");
+        return;
+      }
+      case "provider-rebinding": {
+        const resolved = await state.store.resolve("session-rebind", AGENT);
+        assert.equal(resolved.disabled, false, "the rebind's last serialized write wins");
+        return;
+      }
+      case "restart-reload-recovery": {
+        const resolved = await state.store.resolve("session-restart", AGENT);
+        assert.equal(resolved.disabled, true, "the restarted store reloads prior durable state");
+        return;
+      }
+      case "compaction-flush": {
+        const entries = await readToggleFileEntries(state.filePath);
+        assert.equal(Object.keys(entries).length, 0, "clearing every key compacts the file to no entries");
+        assert.equal((await state.store.list()).length, 0);
+        return;
+      }
+      case "before-reset": {
+        const entries = await readToggleFileEntries(state.filePath);
+        assert.equal(
+          Object.keys(entries).length,
+          12,
+          "the serialized write chain must apply every concurrent write — no lost update",
+        );
+        for (let i = 0; i < 12; i += 1) {
+          const resolved = await state.store.resolve(`session-burst-${i}`, AGENT);
+          assert.equal(resolved.disabled, true, `burst write ${i} must have survived`);
+        }
+        return;
+      }
+      case "session-end": {
+        // The chain drains deterministically; the file is valid and the key's
+        // final state is the last-queued write (setDisabled true).
+        const entries = await readToggleFileEntries(state.filePath);
+        const resolved = await state.store.resolve("session-final", AGENT);
+        assert.equal(resolved.disabled, true, "the last serialized operation determines the final state");
+        assert.ok(Object.keys(entries).length <= 1, "no torn/duplicate entries for the single key");
+        return;
+      }
+      case "dedupe-replay": {
+        const entries = await readToggleFileEntries(state.filePath);
+        const matching = Object.keys(entries).filter((key) => key.includes(encodeURIComponent("session-replay")));
+        assert.equal(matching.length, 1, "a replayed identical write is idempotent — one entry, not two");
+        const resolved = await state.store.resolve("session-replay", AGENT);
+        assert.equal(resolved.disabled, true);
+        return;
+      }
+      default: {
+        const exhaustive: never = row.id;
+        throw new Error(`unhandled row ${String(exhaustive)}`);
+      }
+    }
+  },
+
+  async teardown(state: SerializedWriteState): Promise<void> {
+    await rm(state.dir, { recursive: true, force: true });
+  },
+};
+
+runLifecycleMatrix("serialized-write-chain", subject);

package/src/trust-score-stage.test.ts

@@ -348,3 +348,157 @@ test("adapter: no half-life → no decay (raw counters)", () => {
   // Without decay, 5/1 success-heavy → confidence ~6 (raw count).
   assert.ok(worth!.confidence >= 5, "no half-life → raw confidence (no decay)");
 });
+
+test("signal cache: an aged entry re-derives even when the corpus version matches (#1905, Codex)", async () => {
+  // Trust signals bake wall-clock time into their values (ageDays,
+  // computeMemoryWorth(..., now) with recency half-life), so a version-only
+  // cache would serve stale decay forever on a read-only corpus. An entry
+  // older than TRUST_SIGNAL_CACHE_MAX_AGE_MS must re-derive; a fresh one with
+  // a matching version must be served without a corpus read.
+  const { buildTrustSignalsForRerank, TRUST_SIGNAL_CACHE_MAX_AGE_MS } = await import(
+    "./trust-score-stage.js"
+  );
+  const now = new Date("2026-07-01T12:00:00.000Z");
+  let corpusReads = 0;
+  const deps = {
+    readNamespaceMemories: async () => {
+      corpusReads += 1;
+      return [
+        { path: "a.md", frontmatter: { mw_success: 3, mw_fail: 0, lastAccessed: "2026-06-30" } },
+      ];
+    },
+    readMemoryFrontmatter: async () => null,
+    getNamespaceVersion: async () => 7,
+  };
+  const staleSignals = buildTrustSignalMap(
+    [{ path: "a.md", frontmatter: { mw_success: 3, mw_fail: 0, lastAccessed: "2026-06-30" } }],
+    new Date(now.getTime() - TRUST_SIGNAL_CACHE_MAX_AGE_MS - 1),
+    {},
+  );
+  const cache = {
+    cache: new Map([
+      [
+        "default",
+        {
+          version: 7,
+          cachedAt: now.getTime() - TRUST_SIGNAL_CACHE_MAX_AGE_MS - 1,
+          signals: staleSignals,
+        },
+      ],
+    ]),
+  };
+
+  await buildTrustSignalsForRerank(["a.md"], ["default"], deps, cache, now, {});
+  assert.equal(corpusReads, 1, "aged entry (version match) must re-derive from the corpus");
+
+  corpusReads = 0;
+  await buildTrustSignalsForRerank(["a.md"], ["default"], deps, cache, now, {});
+  assert.equal(corpusReads, 0, "fresh entry with matching version must serve from cache");
+});
+
+test("preloaded-but-neutral candidates skip the corpus and direct-read fallbacks (#1905, Cursor/Codex)", async () => {
+  // buildTrustSignalMap deliberately OMITS neutral memories (no trust fields),
+  // so a preloaded candidate can be examined yet absent from `signals`. It must
+  // be treated as EXAMINED — not missing — or every uninstrumented hot
+  // candidate re-triggers the namespace-wide corpus scan and a direct re-read,
+  // defeating the O(candidates) fast path.
+  const { buildTrustSignalsForRerank } = await import("./trust-score-stage.js");
+  const now = new Date("2026-07-01T12:00:00.000Z");
+  let corpusReads = 0;
+  let directReads = 0;
+  const deps = {
+    readNamespaceMemories: async () => {
+      corpusReads += 1;
+      return [];
+    },
+    readMemoryFrontmatter: async () => {
+      directReads += 1;
+      return null;
+    },
+    getNamespaceVersion: async () => 1,
+  };
+  const cache = { cache: new Map() };
+  // Neutral frontmatter: no mw_* / trust fields at all.
+  const preloadedFrontmatter = new Map([
+    ["a.md", { frontmatter: {} }],
+    ["b.md", { frontmatter: {} }],
+  ]);
+
+  const signals = await buildTrustSignalsForRerank(
+    ["a.md", "b.md"],
+    ["default"],
+    deps,
+    cache,
+    now,
+    { preloadedFrontmatter },
+  );
+
+  assert.equal(corpusReads, 0, "neutral preloaded candidates must not trigger a corpus scan");
+  assert.equal(directReads, 0, "neutral preloaded candidates must not trigger direct reads");
+  assert.equal(signals.size, 0, "neutral candidates stay absent (multiplier 1.0 downstream)");
+});
+
+test("cooperative abort stops the corpus and direct-read fallbacks at loop boundaries (#1905, Codex)", async () => {
+  const { buildTrustSignalsForRerank } = await import("./trust-score-stage.js");
+  const now = new Date("2026-07-01T12:00:00.000Z");
+  let corpusReads = 0;
+  let directReads = 0;
+  const deps = {
+    readNamespaceMemories: async () => {
+      corpusReads += 1;
+      return [];
+    },
+    readMemoryFrontmatter: async () => {
+      directReads += 1;
+      return null;
+    },
+    getNamespaceVersion: async () => 1,
+  };
+  const controller = new AbortController();
+  controller.abort(); // the recall deadline already won the race
+
+  await buildTrustSignalsForRerank(
+    ["a.md"],
+    ["ns1", "ns2"],
+    deps,
+    { cache: new Map() },
+    now,
+    { abortSignal: controller.signal },
+  );
+
+  assert.equal(corpusReads, 0, "an aborted signal must stop namespace scans before they start");
+  assert.equal(directReads, 0, "an aborted signal must stop direct-read batches before they start");
+});
+
+test("trust direct-read fallback threads the candidate namespace (#2020)", async () => {
+  // A namespace-fanout candidate carries a relative path plus its owning
+  // namespace. The cold-tier direct read MUST pass that namespace so the
+  // relative path resolves against the right store instead of the first
+  // fallback namespace (which would apply the wrong memory's trust signals).
+  const { buildTrustSignalsForRerank } = await import("./trust-score-stage.js");
+  const now = new Date("2026-07-01T12:00:00.000Z");
+  const directReads: Array<{ path: string; namespace?: string }> = [];
+  const deps = {
+    readNamespaceMemories: async () => [],
+    readMemoryFrontmatter: async (path: string, preferredNamespace?: string) => {
+      directReads.push({ path, namespace: preferredNamespace });
+      return null;
+    },
+    getNamespaceVersion: async () => 1,
+  };
+
+  await buildTrustSignalsForRerank(
+    [{ path: "facts/a.md", signalKey: "shared\u0000facts/a.md", namespace: "shared" }],
+    ["shared"],
+    deps,
+    { cache: new Map() },
+    now,
+    { corpusFallbackEnabled: false },
+  );
+
+  assert.deepEqual(
+    directReads,
+    [{ path: "facts/a.md", namespace: "shared" }],
+    "direct read must receive the candidate's owning namespace",
+  );
+});