@remnic/core 9.3.712 → 9.3.714

package/src/recall-handles-wiring.test.ts

@@ -0,0 +1,477 @@
+/**
+ * recall-handles-wiring.test.ts — PR2 integration tests for injection-time
+ * memory handles (issue #1582).
+ *
+ * Proves the wiring built on the pure recall-handles module (PR1):
+ *  - the sanitizer surface (stripMemoryHandles) strips `[m:xxxx]` tokens;
+ *  - the QMD injection formatter appends handles only when the gate is ON
+ *    (gate-off is byte-identical to the pre-#1582 output — rule 39);
+ *  - the shared resolver (Orchestrator.resolveMemoryIdOrHandle) returns the
+ *    exact memory id for a cited handle, and throws on miss/ambiguity (rule
+ *    34/51) with snapshot depth respected;
+ *  - the extraction buffer never holds handle text (hygiene §2 — rule 23);
+ *  - consumers (memory_get, correction plan) resolve id-or-handle through the
+ *    one shared access-service helper (rule 22).
+ *
+ * The full Done-When round-trip (recall injects `[m:xxxx]` → a later turn cites
+ * it → it resolves to the exact id → a correction targets that memory) is the
+ * last test in each section.
+ */
+
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, rm, readdir, readFile, stat } from "node:fs/promises";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { Orchestrator } from "./orchestrator.js";
+import { EngramAccessService, EngramAccessInputError } from "./access-service.js";
+import { stripMemoryHandles } from "./sanitize.js";
+import { handleFor, renderHandle } from "./recall-handles.js";
+import type { PluginConfig, QmdSearchResult } from "./types.js";
+
+// ─── helpers ──────────────────────────────────────────────────────────────
+
+interface Harness {
+  orchestrator: Orchestrator;
+  service: EngramAccessService;
+  memoryDir: string;
+}
+
+async function makeHarness(
+  overrides: Partial<PluginConfig> = {},
+): Promise<Harness> {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-handles-"));
+  const config = parseConfig({
+    openaiApiKey: "sk-test",
+    memoryDir,
+    workspaceDir: path.join(memoryDir, "workspace"),
+    // Keep the pipeline quiet: no QMD/graph/judge competing with the assertions.
+    qmdEnabled: false,
+    multiGraphMemoryEnabled: false,
+    entityGraphEnabled: false,
+    timeGraphEnabled: false,
+    causalGraphEnabled: false,
+    extractionJudgeEnabled: false,
+    temporalSupersessionEnabled: false,
+    contradictionDetectionEnabled: false,
+    chunkingEnabled: false,
+    embeddingFallbackEnabled: false,
+    extractionMinChars: 0,
+    extractionMinImportanceLevel: "trivial",
+    inlineSourceAttributionEnabled: false,
+    ...overrides,
+  });
+  const orchestrator = new Orchestrator(config);
+  const service = new EngramAccessService(orchestrator);
+  return { orchestrator, service, memoryDir };
+}
+
+/** QMD results carry `.path` ending in `<memoryId>.md`; that is the id handles derive from. */
+function qmdResult(memoryId: string, snippet = "snippet", score = 0.9): QmdSearchResult {
+  return {
+    docid: memoryId,
+    path: `/mem/default/${memoryId}.md`,
+    line: 1,
+    snippet,
+    score,
+  };
+}
+
+/**
+ * Test-only view of the private QMD results formatter. `formatQmdResults` is
+ * private on the Orchestrator; this named interface is the single auditable
+ * unchecked assertion (rule: no inline cast for a property read).
+ */
+interface FormatQmdResultsAccess {
+  formatQmdResults(
+    title: string,
+    results: QmdSearchResult[],
+    sessionKey?: string,
+  ): string;
+}
+
+function formatQmd(
+  orch: Orchestrator,
+  title: string,
+  results: QmdSearchResult[],
+  sessionKey?: string,
+): string {
+  const internals = orch as unknown as FormatQmdResultsAccess;
+  return internals.formatQmdResults(title, results, sessionKey);
+}
+
+const SESSION = "sess-handles-test";
+const ID_A = "fact-1770469224307-eelr";
+const ID_B = "fact-1770469224308-bxkq";
+
+// ─── stripMemoryHandles (sanitizer surface) ─────────────────────────────────
+
+test("stripMemoryHandles removes a trailing handle token and its preceding space", () => {
+  assert.equal(
+    stripMemoryHandles("API rate limit is 1000 rpm. [m:4f2a]"),
+    "API rate limit is 1000 rpm.",
+  );
+});
+
+test("stripMemoryHandles removes multiple inline handles and tidies spacing", () => {
+  assert.equal(
+    stripMemoryHandles("see [m:4f2a] and also [m:9b1c] for more"),
+    "see and also for more",
+  );
+});
+
+test("stripMemoryHandles leaves handle-free text unchanged", () => {
+  assert.equal(stripMemoryHandles("plain text, no handles"), "plain text, no handles");
+});
+
+// ─── formatQmdResults: gate-off characterization + gate-on rendering ────────
+
+test("formatQmdResults: handles OFF emits no [m:xxxx] (byte-identical to pre-#1582)", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: false });
+  try {
+    const out = formatQmd(orchestrator, "Workspace Context", [
+      qmdResult(ID_A, "The API rate limit is 1000 rpm."),
+    ]);
+    assert.doesNotMatch(out, /\[m:[0-9a-f]{4,8}\]/);
+    // The line layout is unchanged: numbered source line then snippet.
+    // source line carries the path + line number, e.g. `[1] /mem/.../fact-x.md:1 (score: 0.900)`.
+    assert.match(out, /\[1\] .*\.md.*\(score: /);
+    assert.match(out, /The API rate limit is 1000 rpm\./);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("formatQmdResults: handles ON appends [m:xxxx] derived from the memory id", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    const out = formatQmd(orchestrator, "Workspace Context", [
+      qmdResult(ID_A, "The API rate limit is 1000 rpm."),
+    ], SESSION);
+    const expected = `[m:${handleFor(ID_A)}]`;
+    assert.ok(
+      out.includes(expected),
+      `expected rendered handle ${expected} in output:\n${out}`,
+    );
+    // The handle lands at the snippet tail, not on the source/path line.
+    const esc = expected.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    assert.match(out, new RegExp(`The API rate limit is 1000 rpm\\. ${esc}`));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("formatQmdResults: result without an .md id gets no handle (entity reconstructions)", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    const out = formatQmd(orchestrator, "Workspace Context", [
+      { docid: "Widget", path: "/entities/Widget.json", line: 3, snippet: "entity reconstruction", score: 0.5 },
+    ], SESSION);
+    assert.doesNotMatch(out, /\[m:[0-9a-f]{4,8}\]/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("formatQmdResults: a non-memory .md row (entity reconstruction) gets no handle (codex review)", async () => {
+  // Entity reconstructions can carry an `.md` path whose basename is a bare
+  // entity name (e.g. entities/Widget.md). Such a basename is not a loadable
+  // memory id, so it must NOT receive a handle — citing one would resolve to
+  // "Widget", which no storage can getMemoryById.
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    const out = formatQmd(orchestrator, "Workspace Context", [
+      { docid: "Widget", path: "/mem/default/entities/Widget.md", line: 1, snippet: "entity reconstruction", score: 0.5 },
+      qmdResult(ID_A, "real memory"),
+    ], SESSION);
+    assert.doesNotMatch(out, /\[m:[0-9a-f]{4,8}\].*Widget|Widget.*\[m:/);
+    // The real memory still gets its handle.
+    assert.ok(out.includes(`[m:${handleFor(ID_A)}]`));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("formatQmdResults: handles OFF when sessionKey is absent even if config is on (cursor review)", async () => {
+  // A recall that injects context without a session key renders NO handles:
+  // the handle history is only recorded when sessionKey is present, so tokens
+  // shown without it could never be resolved (cursor review of #1582).
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    const out = formatQmd(orchestrator, "Workspace Context", [
+      qmdResult(ID_A, "The API rate limit is 1000 rpm."),
+    ]);
+    assert.doesNotMatch(out, /\[m:[0-9a-f]{4,8}\]/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// ─── resolveMemoryIdOrHandle: the shared resolver every consumer calls ──────
+
+test("resolveMemoryIdOrHandle: raw memory id passes through unchanged", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    assert.equal(orchestrator.resolveMemoryIdOrHandle(ID_A), ID_A);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("resolveMemoryIdOrHandle: handle resolves to the exact memory id after a recall record (round-trip)", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    await orchestrator.handleHistory.record(SESSION, [ID_A, ID_B]);
+    const token = renderHandle(ID_A); // [m:4f2a]
+    assert.equal(orchestrator.resolveMemoryIdOrHandle(token, SESSION), ID_A);
+    // bare hex form also resolves
+    assert.equal(
+      orchestrator.resolveMemoryIdOrHandle(handleFor(ID_A), SESSION),
+      ID_A,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("resolveMemoryIdOrHandle: unknown handle throws (rule 34 — never silent)", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    // No recorded history for this session → any handle misses.
+    assert.throws(
+      () => orchestrator.resolveMemoryIdOrHandle("[m:dead]", SESSION),
+      /not found in the recent recall history/i,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("resolveMemoryIdOrHandle: ambiguous handle throws listing candidates (rule 51)", async () => {
+  // Force a genuine width-4 collision: two distinct ids whose 4-hex handle
+  // matches. Birthday bound in a 65 536-space is ~300 samples, so a single
+  // linear pass with a Map finds one quickly (and deterministically for a fixed
+  // search prefix). In practice collisions across ~10–40 memories are
+  // vanishingly rare; this pins the disambiguation contract regardless.
+  const handles = new Map<string, string>();
+  let idA = "";
+  let idB = "";
+  for (let i = 0; i < 5000 && !idB; i++) {
+    const id = `fact-collide-${i}`;
+    const h = handleFor(id);
+    const existing = handles.get(h);
+    if (existing) {
+      idA = existing;
+      idB = id;
+    } else {
+      handles.set(h, id);
+    }
+  }
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    if (!idB) {
+      // No collision found in the budget — skip rather than fake the scenario.
+      // The pure-module test (recall-handles.test.ts) covers the ambiguous
+      // branch with fixture snapshots directly.
+      assert.ok(true, "no width-4 collision found in synthetic search; ambiguous branch covered by PR1 unit tests");
+      return;
+    }
+    await orchestrator.handleHistory.record(SESSION, [idA, idB]);
+    assert.throws(
+      () => orchestrator.resolveMemoryIdOrHandle(renderHandle(idA), SESSION),
+      (err: Error) =>
+        /ambiguous/i.test(err.message) &&
+        err.message.includes(idA) &&
+        err.message.includes(idB),
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("resolveMemoryIdOrHandle: snapshot depth respected — older-than-N is a miss", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({
+    recallMemoryHandles: true,
+    recallHandleSnapshotDepth: 1,
+  });
+  try {
+    // Record two recalls; with depth=1 only the newest is searchable.
+    await orchestrator.handleHistory.record(SESSION, [ID_A]);
+    await orchestrator.handleHistory.record(SESSION, [ID_B]);
+    // ID_A is now outside the depth-1 window → its handle misses.
+    assert.throws(
+      () => orchestrator.resolveMemoryIdOrHandle(renderHandle(ID_A), SESSION),
+      /not found/i,
+    );
+    // ID_B is the newest → still resolves.
+    assert.equal(
+      orchestrator.resolveMemoryIdOrHandle(renderHandle(ID_B), SESSION),
+      ID_B,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// ─── hygiene §2: handles never enter the extraction buffer ─────────────────
+
+test("processTurn strips echoed handles from buffered content when the feature is ON", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    const handleToken = renderHandle(ID_A);
+    await orchestrator.processTurn("user", `That ${handleToken} is stale.`, SESSION);
+    const turns = orchestrator.buffer.getTurns(SESSION);
+    assert.ok(turns.length > 0, "turn was buffered");
+    const buffered = turns[turns.length - 1]!.content;
+    assert.doesNotMatch(buffered, /\[m:[0-9a-f]{4,8}\]/);
+    assert.ok(buffered.includes("stale"), "non-handle text is preserved");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("processTurn leaves content byte-identical when the feature is OFF", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: false });
+  try {
+    // Even if a handle-shaped token appears (e.g. user typed it), the OFF path
+    // does not strip: nothing is injected, so buffering must be untouched.
+    const content = "see [m:4f2a] for context";
+    await orchestrator.processTurn("user", content, SESSION);
+    const turns = orchestrator.buffer.getTurns(SESSION);
+    assert.equal(turns[turns.length - 1]!.content, content);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// ─── consumer wiring: memory_get + correction plan via the shared resolver ──
+
+test("memoryGet resolves a handle to the underlying memory via sessionKey", async () => {
+  const { orchestrator, service, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    // Seed a memory in the default namespace so getMemoryById finds it, then
+    // cite its handle. writeMemory returns the persisted id directly.
+    const defaultNs = orchestrator.config.defaultNamespace;
+    const storage = await orchestrator.getStorage(defaultNs);
+    const writtenId = await storage.writeMemory(
+      "fact",
+      "The API rate limit is 1000 rpm.",
+      { confidence: 0.9, source: "test" },
+    );
+    await orchestrator.handleHistory.record(SESSION, [writtenId]);
+
+    const res = await service.memoryGet(
+      renderHandle(writtenId),
+      undefined,
+      undefined,
+      SESSION,
+    );
+    assert.equal(res.found, true);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("correctionPlan: a handle in targetIds is resolved before planning; an unknown handle is an input error", async () => {
+  const { service, memoryDir } = await makeHarness({
+    recallMemoryHandles: true,
+    correctionEnabled: true,
+  });
+  try {
+    // No recorded recall history → any handle cited as a target misses, and the
+    // shared resolver surfaces it as an input error BEFORE the planner runs.
+    await assert.rejects(
+      () =>
+        service.correctionPlan({
+          text: "that memory is wrong",
+          targetIds: ["[m:dead]"],
+          sessionKey: SESSION,
+        }),
+      (err: unknown) =>
+        err instanceof EngramAccessInputError && /not found/i.test((err as Error).message),
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("correctionPlan: a resolved handle targetIds set reaches the planner as concrete ids (round-trip)", async () => {
+  const { orchestrator, service, memoryDir } = await makeHarness({
+    recallMemoryHandles: true,
+    correctionEnabled: true,
+  });
+  try {
+    await orchestrator.handleHistory.record(SESSION, [ID_A]);
+    // The planner runs after resolution. With a known id it proceeds to
+    // search/locate; the contract we assert is that resolution did NOT throw
+    // (i.e. the handle was accepted and mapped). A downstream contract fault
+    // (empty candidate set / LLM unavailable) is out of scope here — the
+    // resolver's job is done once the handle maps to an id without error, which
+    // we prove by confirming no handle-resolution miss escapes.
+    try {
+      await service.correctionPlan({
+        text: "that memory is wrong",
+        targetIds: [renderHandle(ID_A)],
+        sessionKey: SESSION,
+      });
+    } catch (err) {
+      assert.ok(
+        !(err instanceof EngramAccessInputError && /not found|handle/i.test((err as Error).message)),
+        `handle resolution should have succeeded, got: ${(err as Error).message}`,
+      );
+    }
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// ─── corpus scan: no handle text in any persisted memory file ───────────────
+
+async function scanTreeForHandles(dir: string): Promise<string[]> {
+  const hits: string[] = [];
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return hits;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry);
+    let s;
+    try {
+      s = await stat(full);
+    } catch {
+      continue;
+    }
+    if (s.isDirectory()) {
+      hits.push(...(await scanTreeForHandles(full)));
+    } else if (entry.endsWith(".md")) {
+      const text = await readFile(full, "utf-8");
+      if (/\[m:[0-9a-f]{4,8}\]/.test(text)) hits.push(full);
+    }
+  }
+  return hits;
+}
+
+test("corpus scan: handles stripped before buffering never appear in persisted memory files", async () => {
+  const { orchestrator, memoryDir } = await makeHarness({ recallMemoryHandles: true });
+  try {
+    const handleToken = renderHandle(ID_A);
+    // Buffer several turns whose raw content echoes an injected handle.
+    await orchestrator.processTurn("user", `The limit is 1000 rpm. ${handleToken}`, SESSION);
+    await orchestrator.processTurn("assistant", `Got it, noting ${handleToken}.`, SESSION);
+    // Read the buffered turns directly and assert the strip held — the buffer is
+    // the extraction source, so if it is clean the persisted corpus is clean.
+    const turns = orchestrator.buffer.getTurns(SESSION);
+    for (const t of turns) {
+      assert.doesNotMatch(t.content, /\[m:[0-9a-f]{4,8}\]/);
+    }
+    // And confirm the on-disk memory tree has no handle text today.
+    const hits = await scanTreeForHandles(memoryDir);
+    assert.deepEqual(hits, [], `no persisted file should contain a handle token, found: ${hits.join(", ")}`);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});