@remnic/core 10.0.83 → 10.0.85

package/src/compounding/weekly-evidence.test.ts

@@ -0,0 +1,237 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import type { MemoryFile } from "../types.js";
+import { rememberRawFrontmatter } from "../storage/memory-frontmatter-metadata.js";
+import {
+  CORRECTION_FILE_BYTE_LIMIT,
+  WEEKLY_CORRECTION_READ_LIMIT,
+  WEEKLY_CORRECTION_SCAN_LIMIT,
+  buildActionFailurePatterns,
+  capWeeklyPatternDetails,
+  isoWeekStartMs,
+  provenanceVisibleInStoreRecall,
+  readFeedbackEntriesForWeekFile,
+  readWeeklyCorrections,
+  type WeeklyActionEvent,
+  type WeeklyEvidenceStorage,
+} from "./weekly-evidence.js";
+import { isoWeekId } from "./iso-week.js";
+
+test("isoWeekStartMs returns Monday UTC for valid ids and null otherwise", () => {
+  const start = isoWeekStartMs("2026-W01");
+  assert.ok(start !== null);
+  assert.equal(new Date(start).toISOString(), "2025-12-29T00:00:00.000Z");
+  assert.equal(isoWeekId(new Date(start)), "2026-W01");
+
+  const w02 = isoWeekStartMs("2026-W02");
+  assert.ok(w02 !== null);
+  assert.equal(w02 - start!, 7 * 86_400_000);
+
+  assert.equal(isoWeekStartMs("2026-W1"), null);
+  assert.equal(isoWeekStartMs("2026-W00"), null);
+  assert.equal(isoWeekStartMs("not-a-week"), null);
+  assert.equal(isoWeekStartMs("2026-W54"), null);
+  // 2026 has 53 weeks only if the calendar emits it; W53 that does not land is null.
+  const w53 = isoWeekStartMs("2015-W53");
+  assert.ok(w53 !== null);
+  assert.equal(isoWeekId(new Date(w53)), "2015-W53");
+  assert.equal(isoWeekStartMs("2016-W53"), null);
+});
+
+test("readFeedbackEntriesForWeekFile filters by ISO week and skips bad lines", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-feedback-"));
+  try {
+    const inbox = path.join(root, "feedback.jsonl");
+    const inWeek = "2026-01-02T12:00:00.000Z"; // 2026-W01
+    const otherWeek = "2026-01-08T12:00:00.000Z"; // 2026-W02
+    await writeFile(
+      inbox,
+      [
+        JSON.stringify({
+          agent: "alpha",
+          decision: "approved",
+          reason: "looks good",
+          date: inWeek,
+        }),
+        "not-json",
+        JSON.stringify({ agent: "", decision: "approved", reason: "x", date: inWeek }),
+        JSON.stringify({
+          agent: "beta",
+          decision: "rejected",
+          reason: "no",
+          date: otherWeek,
+        }),
+        JSON.stringify({
+          agent: "gamma",
+          decision: "approved_with_feedback",
+          reason: "tweak",
+          date: "2025-12-30T08:00:00.000Z",
+        }),
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+
+    const entries = await readFeedbackEntriesForWeekFile(inbox, "2026-W01");
+    assert.equal(entries.length, 2);
+    assert.deepEqual(
+      entries.map((row) => row.entry.agent).sort(),
+      ["alpha", "gamma"],
+    );
+    assert.equal(entries.find((row) => row.entry.agent === "alpha")?.sourceLine, 1);
+    assert.equal(entries.find((row) => row.entry.agent === "gamma")?.sourceLine, 5);
+
+    assert.deepEqual(await readFeedbackEntriesForWeekFile(path.join(root, "missing.jsonl"), "2026-W01"), []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("buildActionFailurePatterns keeps failures, skips, and policy decisions", () => {
+  const events: WeeklyActionEvent[] = [
+    {
+      line: 1,
+      action: "forget",
+      outcome: "failed",
+      policyDecision: null,
+      namespace: "default",
+      reason: "locked",
+      ledgerLabel: "memory-actions.jsonl",
+      actionId: "a1",
+    },
+    {
+      line: 2,
+      action: "promote",
+      outcome: "applied",
+      policyDecision: null,
+      namespace: "default",
+      reason: null,
+      ledgerLabel: "memory-actions.jsonl",
+      actionId: "a2",
+    },
+    {
+      line: 3,
+      action: "edit",
+      outcome: "applied",
+      policyDecision: "deny",
+      namespace: "ns1",
+      reason: "  blocked by policy  ",
+      ledgerLabel: "namespaces/ns1/state/memory-actions.jsonl",
+      actionId: "a3",
+    },
+    {
+      line: 4,
+      action: "merge",
+      outcome: "skipped",
+      policyDecision: null,
+      namespace: "default",
+      reason: null,
+      ledgerLabel: "memory-actions.jsonl",
+      actionId: "a4",
+    },
+  ];
+
+  const patterns = buildActionFailurePatterns(events);
+  assert.equal(patterns.length, 3);
+  assert.match(patterns[0]!.pattern, /memory-action\/default: forget failed - locked/);
+  assert.equal(patterns[0]!.provenance, "memory-actions.jsonl:*");
+  assert.match(patterns[1]!.pattern, /memory-action\/ns1: edit applied\/deny - blocked by policy/);
+  assert.match(patterns[2]!.pattern, /memory-action\/default: merge skipped$/);
+});
+
+test("readWeeklyCorrections skips files over the byte cap and keeps in-week active ones", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-weekly-corr-"));
+  try {
+    const correctionsDir = path.join(root, "corrections");
+    await mkdir(correctionsDir, { recursive: true });
+
+    const inWeekMs = Date.parse("2026-01-02T15:00:00.000Z");
+    const smallName = `correction-${inWeekMs}.md`;
+    const largeName = `correction-${inWeekMs + 1000}.md`;
+    const smallBody = `---
+id: corr-small
+category: correction
+status: active
+created: 2026-01-02T15:00:00.000Z
+---
+
+Fix the pricing table.
+`;
+    await writeFile(path.join(correctionsDir, smallName), smallBody, "utf8");
+    await writeFile(
+      path.join(correctionsDir, largeName),
+      `${"x".repeat(CORRECTION_FILE_BYTE_LIMIT + 1)}`,
+      "utf8",
+    );
+
+    // SAFETY: rememberRawFrontmatter reads only path, content and frontmatter; this literal sets all three.
+    const smallMemory = rememberRawFrontmatter(
+      {
+        path: path.join(correctionsDir, smallName),
+        content: "Fix the pricing table.",
+        frontmatter: {
+          id: "corr-small",
+          category: "correction",
+          status: "active",
+          created: "2026-01-02T15:00:00.000Z",
+        },
+      } as MemoryFile,
+      smallBody,
+    );
+    const byPath = new Map<string, MemoryFile>([[path.join(correctionsDir, smallName), smallMemory]]);
+
+    const storage: WeeklyEvidenceStorage = {
+      async readMemoryByPath(filePath) {
+        return byPath.get(filePath) ?? null;
+      },
+      async readMemoryActionEventRows() {
+        return [];
+      },
+    };
+
+    const evidence = await readWeeklyCorrections({
+      storage,
+      memoryDir: root,
+      weekId: "2026-W01",
+    });
+    assert.equal(evidence.length, 1);
+    assert.equal(evidence[0]!.id, "corr-small");
+    assert.equal(evidence[0]!.note, "Fix the pricing table.");
+    assert.equal(evidence[0]!.provenance, `corrections/${smallName}`);
+
+    assert.ok(CORRECTION_FILE_BYTE_LIMIT === 256 * 1024);
+    assert.ok(WEEKLY_CORRECTION_READ_LIMIT === 500);
+    assert.ok(WEEKLY_CORRECTION_SCAN_LIMIT === 2000);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("provenanceVisibleInStoreRecall and capWeeklyPatternDetails prefer visible actions", () => {
+  assert.equal(provenanceVisibleInStoreRecall(["facts/a.md"]), true);
+  assert.equal(provenanceVisibleInStoreRecall(["namespaces/other/x.md"]), false);
+  assert.equal(provenanceVisibleInStoreRecall(["namespaces/home/x.md"], "namespaces/home/"), true);
+  assert.equal(provenanceVisibleInStoreRecall([]), true);
+
+  const details = [
+    { pattern: "foreign", provenance: ["namespaces/other/a.md"] as const },
+    { pattern: "action-a", provenance: ["memory-actions.jsonl:*"] as const },
+    { pattern: "corr", provenance: ["corrections/c.md"] as const },
+    { pattern: "action-b", provenance: ["memory-actions.jsonl:*"] as const },
+    { pattern: "overflow", provenance: ["facts/x.md"] as const },
+  ];
+  const capped = capWeeklyPatternDetails(
+    details,
+    (pattern) => (pattern.startsWith("action") ? "action" : "correction"),
+    null,
+    3,
+  );
+  assert.deepEqual(
+    capped.map((row) => row.pattern),
+    ["action-a", "action-b", "corr"],
+  );
+});

package/src/entity-mention-index-cache.ts

@@ -3,6 +3,7 @@ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { raceAbort } from "./abort-error.js";
 import { entityMentionEpoch } from "./entity-mention-epoch.js";
 import { log } from "./logger.js";
+import { compareStrings } from "./eval-trajectory-contracts.js";
 
 /**
  * In-memory entity mention index.
@@ -158,12 +159,6 @@ function throwIfMentionAborted(signal?: AbortSignal): void {
   throw reason instanceof Error ? reason : new Error("entity mention rebuild aborted");
 }
 
-function compareStrings(left: string, right: string): number {
-  if (left < right) return -1;
-  if (left > right) return 1;
-  return 0;
-}
-
 function deduped(values: readonly string[]): string[] {
   const seen = new Set<string>();
   const out: string[] = [];

package/src/extraction-quote-grounding.test.ts

@@ -410,6 +410,55 @@ test("a claim that inverts a negated quote is rejected, a restated exclusion is
   assert.deepEqual(keptContents(grounded), ["Alice would avoid approving the budget."]);
 });
 
+test("a claim that keeps one quote negation and flips another is rejected", () => {
+  const source = "Notes: Alice did not approve the budget. Bob did not review the ledger.";
+  const quote = "Alice did not approve the budget. Bob did not review the ledger.";
+  const grounded = filterExtractionResultBySource(
+    resultOf([
+      { content: "Alice did not approve the budget, and Bob reviewed the ledger.", quote },
+      {
+        content: "Alice did not approve the budget, and Bob did not review the ledger.",
+        quote,
+      },
+    ]),
+    source,
+    source,
+  );
+  assert.deepEqual(keptContents(grounded), [
+    "Alice did not approve the budget, and Bob did not review the ledger.",
+  ]);
+});
+
+test("a claim that keeps the denial in a pronoun clause is kept", () => {
+  const source = "Notes: Alice did not approve the budget.";
+  const quote = "Alice did not approve the budget.";
+  const claims = [
+    "Alice discussed the budget; she did not approve it.",
+    "Alice reviewed the budget, but she did not approve it.",
+  ];
+  const grounded = filterExtractionResultBySource(
+    resultOf(claims.map((content) => ({ content, quote }))),
+    source,
+    source,
+  );
+  assert.deepEqual(keptContents(grounded), claims);
+});
+
+test("a negator in a claim clause that shares only the subject does not keep the denial", () => {
+  const source = "Notes: Alice did not approve the budget. Alice did not review the contract.";
+  const grounded = filterExtractionResultBySource(
+    resultOf([
+      {
+        content: "Alice did not review the contract. She approved the budget.",
+        quote: "Alice did not approve the budget.",
+      },
+    ]),
+    source,
+    source,
+  );
+  assert.equal(grounded.facts.length, 0);
+});
+
 test("a claim that inverts a denial verb in the quote is rejected", () => {
   const source = "Notes: Alice denied approving the budget. Bob reviewed it.";
   const grounded = filterExtractionResultBySource(

package/src/extraction-quote-grounding.ts

@@ -130,24 +130,62 @@ function hasNegation(text: string): boolean {
   return NEGATOR_PATTERN.test(text.replace(/[\u2018\u2019]/gu, "'")) || hasDenialReporting(text);
 }
 
+const CLAUSE_PATTERN = /[^;.!?\n]+[;.!?]*/gu;
+/** Split "X, and Y" claim coordination without touching list commas. */
+const CLAIM_COORD_SPLIT = /,\s{1,8}(?:and|but|or|nor)\s{1,8}/iu;
+
+function splitClaimClauses(content: string): string[] {
+  return (content.match(CLAUSE_PATTERN) ?? [content]).flatMap((clause) => {
+    const parts = clause
+      .split(CLAIM_COORD_SPLIT)
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0);
+    return parts.length > 0 ? parts : [clause];
+  });
+}
+
+function clauseOverlap(clauseTokens: readonly string[], target: string) {
+  const has = tokenPool(tokenize(target));
+  const shared = clauseTokens.filter(has).length;
+  return { shared, ratio: clauseTokens.length === 0 ? 0 : shared / clauseTokens.length };
+}
+
+/** What a quote clause's first negator governs: the words after it. */
+function negatedScope(clause: string): string {
+  const match = NEGATOR_PATTERN.exec(clause.replace(/[\u2018\u2019]/gu, "'"));
+  return match ? clause.slice(match.index + match[0].length) : clause;
+}
+
 /**
  * True when the claim asserts what a quote clause denies or does not assert:
  * "did not approve the budget" or "denied approving it" restated as "approved
  * the budget", "suspects Bob stole funds" or "Is Alice the CEO?" restated as a
- * plain statement. A claim that keeps a negator, exclusion word, or reporting
- * marker ("do not X" reworded as "X is excluded") is not a misstatement.
+ * plain statement. The claim must restate the quote clause, and none of its
+ * clauses that share a word with what the negator governs may keep the
+ * negator, exclusion word, or reporting marker ("do not X" reworded as "X is
+ * excluded", or "Alice reviewed it, but she did not approve it"). A negator in
+ * a clause about something else does not count, so a claim that keeps one
+ * quote negation can still misstate another quote clause, and a claim clause
+ * that shares only the subject does not satisfy the check.
  */
 function misstatesQuote(content: string, quote: string): boolean {
-  const keepsNegation = hasNegation(content) || EXCLUSION_PATTERN.test(content);
-  const keepsReporting = hasNonAssertiveReporting(content) || content.trim().endsWith("?");
-  const contentHas = tokenPool(tokenize(content));
-  return (quote.match(/[^;.!?\n]+[;.!?]*/gu) ?? []).some((clause) => {
-    const negated = hasNegation(clause) && !keepsNegation;
-    const unasserted = (clause.trim().endsWith("?") || hasNonAssertiveReporting(clause)) && !keepsReporting;
-    if (!negated && !unasserted) return false;
-    const clauseTokens = [...tokenize(clause)];
-    const shared = clauseTokens.filter(contentHas).length;
-    return shared >= GROUNDING_MIN_SHARED_TOKENS && shared / clauseTokens.length >= 0.5;
+  const claimClauses = splitClaimClauses(content);
+  return (quote.match(CLAUSE_PATTERN) ?? []).some((quoteClause) => {
+    const needsNegation = hasNegation(quoteClause);
+    const needsReporting = quoteClause.trim().endsWith("?") || hasNonAssertiveReporting(quoteClause);
+    if (!needsNegation && !needsReporting) return false;
+    const clauseTokens = [...tokenize(quoteClause)];
+    const whole = clauseOverlap(clauseTokens, content);
+    if (whole.shared < GROUNDING_MIN_SHARED_TOKENS || whole.ratio < 0.5) return false;
+    const clausesSharing = (tokens: readonly string[]) =>
+      claimClauses.filter((claimClause) => clauseOverlap(tokens, claimClause).shared > 0);
+    if (needsNegation) {
+      const scopeTokens = [...tokenize(negatedScope(quoteClause))];
+      const related = clausesSharing(scopeTokens.length > 0 ? scopeTokens : clauseTokens);
+      if (!related.some((text) => hasNegation(text) || EXCLUSION_PATTERN.test(text))) return true;
+    }
+    return needsReporting
+      && !clausesSharing(clauseTokens).some((text) => hasNonAssertiveReporting(text) || text.trim().endsWith("?"));
   });
 }
 

package/src/fact-dedup-window.test.ts

@@ -1,14 +1,27 @@
-import test from "node:test";
+import test, { mock } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { StorageManager } from "./storage.js";
 import { withHeldFileLock } from "./utils/serialize-mutations.js";
 import { confirmActiveFactDuplicate, persistUnderFactDedupWindow } from "./orchestration/fact-dedup-window.js";
 
-function probe(storage: StorageManager) {
-  return { hasContentHashDedup: (s: StorageManager, key: string) => s.hasFactContentHash(key) };
+const SKY_OPTS = {
+  category: "fact",
+  contentHashDedupKey: "the sky is blue",
+  connector: undefined,
+  citationEnabled: false,
+  citationTemplate: "",
+} as const;
+const CONTENDED_LOCK_OPTIONS = { maxWaitMs: 40, pollMs: 10, retryMaxAttempts: 2, retryBaseMs: 10 };
+
+/** Hold a fresh fact-hash index lock the way a peer mid-publish does; returns the release. */
+async function holdIndexLock(root: string): Promise<() => Promise<void>> {
+  const lockPath = path.join(root, "state", "fact-hashes.txt.lock");
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  await writeFile(lockPath, `99999 peer-owner ${new Date().toISOString()}\n`);
+  return () => rm(lockPath, { force: true });
 }
 
 async function makeStorage(): Promise<{ storage: StorageManager; cleanup: () => Promise<void> }> {
@@ -19,14 +32,7 @@ async function makeStorage(): Promise<{ storage: StorageManager; cleanup: () =>
 test("confirmActiveFactDuplicate sees a fact another session committed into the same namespace", async () => {
   const { storage, cleanup } = await makeStorage();
   try {
-    const recheck = () =>
-      confirmActiveFactDuplicate(probe(storage), storage, {
-        category: "fact",
-        contentHashDedupKey: "the sky is blue",
-        connector: undefined,
-        citationEnabled: false,
-        citationTemplate: "",
-      });
+    const recheck = () => confirmActiveFactDuplicate(storage, SKY_OPTS);
     assert.equal(await recheck(), false, "clean namespace must not report a duplicate");
 
     // A concurrent session (separate manager, same dir) commits the fact.
@@ -48,14 +54,7 @@ test("persistUnderFactDedupWindow suppresses on recheck hit and writes on a miss
       await storage.writeMemory("fact", "the sky is blue");
       return "written";
     };
-    const recheck = () =>
-      confirmActiveFactDuplicate(probe(storage), storage, {
-        category: "fact",
-        contentHashDedupKey: "the sky is blue",
-        connector: undefined,
-        citationEnabled: false,
-        citationTemplate: "",
-      });
+    const recheck = () => confirmActiveFactDuplicate(storage, SKY_OPTS);
 
     // First session: recheck misses, write proceeds.
     const first = await persistUnderFactDedupWindow(storage["baseDir"], recheck, write);
@@ -114,3 +113,87 @@ test("persistUnderFactDedupWindow fails closed when a peer holds fact-dedup.lock
     await cleanup();
   }
 });
+
+test("lookupContentHash never pairs a stale MISS with authority while a peer holds the index lock", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    storage.factHashIndexLockOptions = CONTENDED_LOCK_OPTIONS;
+    assert.equal(await storage.isFactContentHashAuthoritative(), true, "starts authoritative");
+    const peer = new StorageManager(storage["baseDir"]);
+    await peer.writeMemory("fact", "The sky is BLUE!");
+    const release = await holdIndexLock(storage["baseDir"]);
+    try {
+      assert.deepEqual(
+        await storage.lookupContentHash(SKY_OPTS.contentHashDedupKey),
+        { present: false, authoritative: false },
+        "the rebuild cannot run, so the stale MISS must not claim authority",
+      );
+      assert.equal(await confirmActiveFactDuplicate(storage, SKY_OPTS), true, "the corpus confirms the peer's fact");
+    } finally {
+      await release();
+    }
+    assert.deepEqual(
+      await storage.lookupContentHash(SKY_OPTS.contentHashDedupKey),
+      { present: true, authoritative: true },
+      "once the lock is free the rebuild publishes and the hit is authoritative",
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+test("confirmActiveFactDuplicate stays a duplicate when the peer releases the index lock right after the lookup", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    storage.factHashIndexLockOptions = CONTENDED_LOCK_OPTIONS;
+    assert.equal(await storage.isFactContentHashAuthoritative(), true, "starts authoritative");
+    const peer = new StorageManager(storage["baseDir"]);
+    await peer.writeMemory("fact", "The sky is BLUE!");
+    const release = await holdIndexLock(storage["baseDir"]);
+    const lookup = storage.lookupContentHash.bind(storage);
+    mock.method(storage, "lookupContentHash", async (content: string) => {
+      const answer = await lookup(content);
+      await release();
+      return answer;
+    });
+    assert.equal(
+      await confirmActiveFactDuplicate(storage, SKY_OPTS),
+      true,
+      "a lock released after the lookup must not turn the stale MISS into a clean not-duplicate",
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+test("two managers on one directory commit the same fact through the window exactly once", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const peer = new StorageManager(storage["baseDir"]);
+    const commit = (manager: StorageManager) =>
+      persistUnderFactDedupWindow(
+        manager.dir,
+        () => confirmActiveFactDuplicate(manager, SKY_OPTS),
+        () => manager.writeMemory("fact", "The sky is blue"),
+      );
+    const outcomes = await Promise.all([commit(storage), commit(peer)]);
+    assert.equal(outcomes.filter((outcome) => !outcome.suppressed).length, 1, "one writer wins, the other is suppressed");
+    const stored = await new StorageManager(storage["baseDir"]).readAllMemories();
+    assert.equal(stored.filter((memory) => memory.content.includes("sky is blue")).length, 1);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("confirmActiveFactDuplicate keeps the authoritative MISS fast path", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    assert.equal(await storage.isFactContentHashAuthoritative(), true, "warm the index so no rebuild reads the corpus");
+    const corpusReads = mock.method(storage, "readAllMemories");
+    assert.equal(await confirmActiveFactDuplicate(storage, SKY_OPTS), false);
+    assert.equal(corpusReads.mock.callCount(), 0, "authoritative MISS must not scan the corpus");
+  } finally {
+    await cleanup();
+  }
+});
+

package/src/maintenance/rebuild-memory-projection-runner.test.ts

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+import { PROJECTION_REBUILD_RUNNER_FLAG } from "./rebuild-memory-projection-runner.js";
+
+const RUNNER = fileURLToPath(new URL("./rebuild-memory-projection-runner.ts", import.meta.url));
+
+type RunnerMessage =
+  | { ok: true; currentRows: number; timelineRows: number; entityMentionRows: number }
+  | { ok: false; error: string };
+
+async function runRunner(args: string[]): Promise<{
+  code: number | null;
+  messages: RunnerMessage[];
+  stderr: string;
+}> {
+  const child = spawn(
+    process.execPath,
+    ["--import", "tsx", RUNNER, PROJECTION_REBUILD_RUNNER_FLAG, ...args],
+    {
+      stdio: ["ignore", "ignore", "pipe", "ipc"],
+      env: { ...process.env },
+    },
+  );
+  const messages: RunnerMessage[] = [];
+  let stderr = "";
+  child.stderr?.setEncoding("utf8");
+  child.stderr?.on("data", (chunk: string) => {
+    stderr += chunk;
+  });
+  child.on("message", (message) => {
+    // SAFETY: the runner posts only RunnerMessage values over IPC; the assertions below check each field.
+    messages.push(message as RunnerMessage);
+  });
+  const { promise: exitPromise, resolve, reject } = Promise.withResolvers<number | null>();
+  child.once("error", reject);
+  child.once("exit", (exitCode) => resolve(exitCode));
+  const code = await exitPromise;
+  return { code, messages, stderr };
+}
+
+test("PROJECTION_REBUILD_RUNNER_FLAG is the documented argv marker", () => {
+  assert.equal(PROJECTION_REBUILD_RUNNER_FLAG, "--remnic-projection-rebuild-runner");
+});
+
+test("runner rejects missing argv with an IPC failure message", async () => {
+  const result = await runRunner([]);
+  assert.equal(result.code, 1);
+  assert.equal(result.messages.length, 1);
+  assert.equal(result.messages[0]!.ok, false);
+  if (result.messages[0]!.ok === false) {
+    assert.match(result.messages[0]!.error, /requires memoryDir, defaultNamespace, and now/);
+  }
+});
+
+test("runner rejects a non-timestamp now value", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-runner-bad-now-"));
+  try {
+    const result = await runRunner([root, "default", "not-a-date"]);
+    assert.equal(result.code, 1);
+    assert.equal(result.messages[0]!.ok, false);
+    if (result.messages[0]!.ok === false) {
+      assert.match(result.messages[0]!.error, /not a timestamp/);
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("runner rebuilds an empty memory dir and reports zero rows", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-runner-ok-"));
+  try {
+    const result = await runRunner([root, "default", "2026-06-01T00:00:00.000Z"]);
+    assert.equal(result.code, 0, result.stderr || JSON.stringify(result.messages));
+    assert.equal(result.messages.length, 1);
+    assert.deepEqual(result.messages[0], {
+      ok: true,
+      currentRows: 0,
+      timelineRows: 0,
+      entityMentionRows: 0,
+    });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});