@remnic/core 9.66.8 → 9.66.9

package/dist/who-knows.d.ts

@@ -1,6 +1,6 @@
-export { bA as WHO_KNOWS_AUTHORSHIP_BONUS, bB as WHO_KNOWS_DEFAULT_LIMIT, bC as WHO_KNOWS_MAX_EVIDENCE, bD as WHO_KNOWS_MAX_LIMIT, bE as WHO_KNOWS_MCP_TOOLS, bF as WhoKnowsEntity, bG as WhoKnowsEvidence, bH as WhoKnowsHit, bI as WhoKnowsHttpOutcome, W as WhoKnowsResult, bJ as WhoKnowsStorage, bT as computeWhoKnows, bZ as handleWhoKnowsHttpQuery, c2 as loadWhoKnowsEntities, c9 as tokenizeTopic, ca as validateWhoKnowsInput } from './access-service-C2tV2-uL.js';
-import './types-CIpfYz1I.js';
-import './orchestrator-CaqnwNwM.js';
+export { bA as WHO_KNOWS_AUTHORSHIP_BONUS, bB as WHO_KNOWS_DEFAULT_LIMIT, bC as WHO_KNOWS_MAX_EVIDENCE, bD as WHO_KNOWS_MAX_LIMIT, bE as WHO_KNOWS_MCP_TOOLS, bF as WhoKnowsEntity, bG as WhoKnowsEvidence, bH as WhoKnowsHit, bI as WhoKnowsHttpOutcome, W as WhoKnowsResult, bJ as WhoKnowsStorage, bT as computeWhoKnows, bZ as handleWhoKnowsHttpQuery, c2 as loadWhoKnowsEntities, c9 as tokenizeTopic, ca as validateWhoKnowsInput } from './access-service-DcfM0Vf0.js';
+import './types-eM7QIcX2.js';
+import './orchestrator-Btq9lzAN.js';
 import './recall-state.js';
 import './utils/serialize-mutations.js';
 import './search/port.js';
@@ -16,7 +16,7 @@ import './active-context-config.js';
 import './types-continuity.js';
 import './included-memories.js';
 import './briefing.js';
-import './storage-CtsaojWD.js';
+import './storage-6fn7BPmb.js';
 import './corpus-read-cancellation.js';
 import './artifact-search.js';
 import './active-context-transform.js';
@@ -39,8 +39,8 @@ import './resolve-provider-secret.js';
 import './transcript.js';
 import './session-integrity.js';
 import './summarizer.js';
-import './maintenance-BBeaeYRR.js';
-import './catalog-C2jA-gLm.js';
+import './maintenance-BRcc3Hx8.js';
+import './catalog-BmBXTtOs.js';
 import './namespaces/search.js';
 import './compounding/engine.js';
 import './shared-context/manager.js';
@@ -50,7 +50,7 @@ import './utility-runtime.js';
 import './tier-routing.js';
 import './lifecycle.js';
 import './orchestration/compression-guideline-coordinator.js';
-import './semantic-consolidation-BiX68wZA.js';
+import './semantic-consolidation-DW3rEUoW.js';
 import './connectors/codex-materialize.js';
 import './logger.js';
 import './embedding-fallback.js';
@@ -72,10 +72,10 @@ import './conversation-index/chunker.js';
 import './conversation-index/backend.js';
 import './faiss-adapter-BHecI1fF.js';
 import './runtime/child-process.js';
-import './dependency-propagation-delivery-D4WMbOwA.js';
+import './dependency-propagation-delivery-BC3bCEet.js';
 import './namespaces/storage.js';
 import './threading.js';
-import './scope-profiles-DFaojvoP.js';
+import './scope-profiles-DqbxQXIS.js';
 import './graph-444E-DrF.js';
 import './recall-xray.js';
 import './memory-provenance.js';
@@ -88,7 +88,7 @@ import './negative.js';
 import './session-observer-state.js';
 import './semantic-BalR6EXU.js';
 import './replay/types.js';
-import './service-D5h2zZ0M.js';
+import './service-B2vJU_Bx.js';
 import './extraction-judge.js';
 import './lcm/engine.js';
 import './lcm/archive.js';
@@ -110,7 +110,7 @@ import './recall-audit.js';
 import './types-B1VHaf2w.js';
 import './transfer/capsule-import.js';
 import './transfer/types.js';
-import './access-namespace-preflight-50VIkPhB.js';
+import './access-namespace-preflight-S8fhQcCo.js';
 import './access-token-capabilities.js';
 import 'node:async_hooks';
 import './recall-explain-renderer.js';

package/dist/who-knows.js

@@ -9,21 +9,21 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-VYIPVLRX.js";
-import "./chunk-K7NUAY36.js";
-import "./chunk-UHVXE24Y.js";
+} from "./chunk-AAJK3PZ6.js";
+import "./chunk-G775FE2E.js";
 import "./chunk-4ZWCQJNM.js";
+import "./chunk-UHVXE24Y.js";
 import "./chunk-WVGXCBOC.js";
-import "./chunk-OERZXNSK.js";
-import "./chunk-6BYJQ3L2.js";
+import "./chunk-B3TZLAO4.js";
+import "./chunk-5NZIRM4Q.js";
+import "./chunk-GIC6BASP.js";
 import "./chunk-YQNNHLCG.js";
 import "./chunk-6KTXE6A3.js";
 import "./chunk-N37X5RU7.js";
 import "./chunk-NNBZS3DY.js";
-import "./chunk-CYEPCZN5.js";
-import "./chunk-GIC6BASP.js";
 import "./chunk-W7IGLX4G.js";
 import "./chunk-GUMZC2BO.js";
+import "./chunk-CYEPCZN5.js";
 import "./chunk-227UFSEQ.js";
 import "./chunk-ET356KSB.js";
 import "./chunk-72A4L5JJ.js";
@@ -49,10 +49,10 @@ import "./chunk-RBOJCG4T.js";
 import "./chunk-NNZFPYYX.js";
 import "./chunk-5WITETWU.js";
 import "./chunk-6CIAGZ6X.js";
-import "./chunk-C24UZSFW.js";
+import "./chunk-CEH2AFXG.js";
 import "./chunk-JXN77SGO.js";
-import "./chunk-ZLQ37WJX.js";
 import "./chunk-IUM3VSHI.js";
+import "./chunk-ZLQ37WJX.js";
 import "./chunk-WKAXBXVA.js";
 import "./chunk-BT7NVCML.js";
 import "./chunk-C64XATK7.js";

package/dist/write-envelope.d.ts

@@ -1,4 +1,4 @@
-import { y as MemoryCategory, N as MemorySubject } from './types-CIpfYz1I.js';
+import { y as MemoryCategory, N as MemorySubject } from './types-eM7QIcX2.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './operator-doctor-types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.66.8",
+  "version": "9.66.9",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3217,7 +3217,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.66.8"
+    "@remnic/coding-graph": "^9.66.9"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/scripts/ensure-better-sqlite3.mjs

@@ -30,6 +30,7 @@ if (!rebuild.ok) {
   console.error(
     "[remnic] Install the package dependencies so node-gyp is available locally, then retry installation.",
   );
+  console.error(recoveryHint());
   process.exit(rebuild.status ?? 1);
 }
 
@@ -41,6 +42,7 @@ try {
   console.error(
     `[remnic] better-sqlite3 rebuild completed but the binding still does not load: ${errorMessage(error)}`,
   );
+  console.error(recoveryHint());
   process.exit(1);
 }
 
@@ -123,3 +125,11 @@ function clearBetterSqlite3RequireCache(packageDir) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+
+function recoveryHint() {
+  const nodeMajor = process.versions.node.split(".")[0];
+  return (
+    `[remnic] Recovery: run \`npm rebuild better-sqlite3 --build-from-source\` with Node ${nodeMajor} ` +
+    `(ABI ${process.versions.modules}) — the shipped binding does not match this Node/ABI.`
+  );
+}

package/src/access-mcp-output-schemas.ts

@@ -82,7 +82,7 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
     skipped: T_NUMBER,
     removed: T_ARRAY,
   }),
-  standup: objectSchema({ date: T_STRING, yesterday: T_STRING, today: T_STRING, highlights: T_ARRAY, blockers: T_ARRAY, activityGrid: T_STRING, markdown: T_STRING }),
+  standup: objectSchema({ date: T_STRING, yesterday: T_STRING, today: T_STRING, highlights: T_ARRAY, priorities: T_ARRAY, blockers: T_ARRAY, activityGrid: T_STRING, markdown: T_STRING }),
   action_confidence: objectSchema({
     schemaVersion: T_NUMBER,
     decision: T_STRING,

package/src/activity/config.test.ts

@@ -17,7 +17,7 @@ test("parseActivityConfig defaults to an inert, search-only configuration", () =
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
-    timeline: { enabled: false, journal: { enabled: false }, qa: { enabled: false, maxRangeDays: 31 } },
+    timeline: { enabled: false, journal: { enabled: false, source: "file" }, qa: { enabled: false, maxRangeDays: 31 } },
   });
   assert.deepEqual(parseActivityConfig(undefined), defaultActivityConfig());
 });

package/src/activity/config.ts

@@ -1,5 +1,6 @@
 import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
 import { assertValidTimezone } from "./digest.js";
+import { resolveJournalSource } from "./journal-source.js";
 import type { ImportanceLevel } from "../types.js";
 import type {
   ActivityConfig,
@@ -29,7 +30,7 @@ export function defaultActivityConfig(): ActivityConfig {
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
-    timeline: { enabled: false, journal: { enabled: false }, qa: { enabled: false, maxRangeDays: 31 } },
+    timeline: { enabled: false, journal: { enabled: false, source: "file" }, qa: { enabled: false, maxRangeDays: 31 } },
   };
 }
 
@@ -200,7 +201,7 @@ export function parseActivityConfig(raw: unknown): ActivityConfig {
  * is malformed and must fail rather than silently disabling the layer.
  */
 function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
-  if (raw === undefined) return { enabled: false, journal: { enabled: false }, qa: parseTimelineQaConfig(undefined) };
+  if (raw === undefined) return { enabled: false, journal: { enabled: false, source: "file" }, qa: parseTimelineQaConfig(undefined) };
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new TypeError("activity.timeline must be an object");
   }
@@ -217,7 +218,7 @@ function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
 }
 
 function parseTimelineJournalConfig(raw: unknown): ActivityTimelineJournalConfig {
-  if (raw === undefined) return { enabled: false };
+  if (raw === undefined) return { enabled: false, source: "file" };
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new TypeError("activity.timeline.journal must be an object");
   }
@@ -226,7 +227,22 @@ function parseTimelineJournalConfig(raw: unknown): ActivityTimelineJournalConfig
   if (journal.enabled !== undefined && enabledValue === undefined) {
     throw new TypeError("activity.timeline.journal.enabled must be a boolean");
   }
-  return { enabled: enabledValue ?? false };
+  const heading = journal.heading;
+  if (heading !== undefined && typeof heading !== "string") {
+    throw new TypeError("activity.timeline.journal.heading must be a string");
+  }
+  const source = journal.source === undefined ? "file" : typeof journal.source === "string" ? journal.source : "";
+  const resolved = resolveJournalSource({ source, heading: heading ?? "" });
+  if (!resolved.ok) {
+    if (resolved.error === "unknown_source") {
+      throw new RangeError('activity.timeline.journal.source must be one of "file", "vault"');
+    }
+    throw new RangeError('activity.timeline.journal.heading must be a non-empty string when source is "vault"');
+  }
+  if (resolved.mode === "vault") {
+    return { enabled: enabledValue ?? false, source: "vault", heading: resolved.heading };
+  }
+  return { enabled: enabledValue ?? false, source: "file" };
 }
 
 function parseTimelineQaConfig(raw: unknown): ActivityTimelineQaConfig {

package/src/activity/journal.test.ts

@@ -32,6 +32,46 @@ test("activity.timeline.journal.enabled defaults off", () => {
   );
 });
 
+test("activity.timeline.journal source defaults to file with no heading", () => {
+  const journal = parseActivityConfig(undefined).timeline.journal;
+  assert.equal(journal.source, "file");
+  assert.equal(journal.heading, undefined);
+});
+
+test("activity.timeline.journal vault mode trims and stores the heading", () => {
+  const journal = parseActivityConfig({ timeline: { journal: { enabled: true, source: "vault", heading: " Journal " } } }).timeline.journal;
+  assert.deepEqual(journal, { enabled: true, source: "vault", heading: "Journal" });
+});
+
+test("activity.timeline.journal vault mode requires a non-empty heading", () => {
+  for (const heading of [undefined, "", "   "]) {
+    assert.throws(
+      () => parseActivityConfig({ timeline: { journal: { source: "vault", heading } } }),
+      RangeError,
+    );
+  }
+});
+
+test("activity.timeline.journal rejects an unknown source", () => {
+  assert.throws(
+    () => parseActivityConfig({ timeline: { journal: { source: "memoryDir" } } }),
+    /activity\.timeline\.journal\.source must be one of "file", "vault"/,
+  );
+});
+
+test("activity.timeline.journal rejects a non-string heading", () => {
+  assert.throws(
+    () => parseActivityConfig({ timeline: { journal: { heading: 5 } } }),
+    /activity\.timeline\.journal\.heading must be a string/,
+  );
+});
+
+test("activity.timeline.journal file mode ignores a provided heading", () => {
+  const journal = parseActivityConfig({ timeline: { journal: { source: "file", heading: "Ignored" } } }).timeline.journal;
+  assert.deepEqual(journal, { enabled: false, source: "file" });
+  assert.equal("heading" in journal, false);
+});
+
 test("seed is a hard no-op without force", () => {
   withMemoryDir((memoryDir) => {
     const first = seedJournal({

package/src/activity/timeline/index.ts

@@ -19,3 +19,4 @@ export * from "./analysis-evidence.js";
 export * from "./analysis-prompt.js";
 export * from "./analysis-claim.js";
 export * from "./analysis-order.js";
+export * from "./recap-window.js";

package/src/activity/timeline/recap-window.test.ts

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  clipCardsToRecapWindow,
+  type RecapWindowCard,
+} from "./recap-window.js";
+
+const MINUTE = 60_000;
+const DAY_START = Date.UTC(2026, 0, 15); // 2026-01-15T00:00:00Z
+const DAY_END = DAY_START + 24 * 60 * 60_000;
+
+const iso = (ms: number): string => new Date(ms).toISOString();
+
+const card = (id: string, startMs: number, endMs: number): RecapWindowCard => ({
+  id,
+  startUtc: iso(startMs),
+  endUtc: iso(endMs),
+});
+
+describe("clipCardsToRecapWindow", () => {
+  it("returns [] for empty input", () => {
+    assert.deepEqual(clipCardsToRecapWindow([], DAY_START, DAY_END), []);
+  });
+
+  it("excludes a card ending exactly at windowStart and one starting exactly at windowEnd", () => {
+    const before = card("before", DAY_START - 2 * MINUTE, DAY_START);
+    const after = card("after", DAY_END, DAY_END + 2 * MINUTE);
+    const inside = card("inside", DAY_START, DAY_END);
+
+    const result = clipCardsToRecapWindow([before, after, inside], DAY_START, DAY_END);
+
+    assert.deepEqual(
+      result.map((c) => c.id),
+      ["inside"],
+    );
+    assert.equal(result[0]?.startMs, DAY_START);
+    assert.equal(result[0]?.endMs, DAY_END);
+    assert.equal(result[0]?.durationMs, DAY_END - DAY_START);
+
+    // Each midnight-touching card lands in exactly one adjacent window.
+    const windowMs = DAY_END - DAY_START;
+    const prevDay = clipCardsToRecapWindow([before], DAY_START - windowMs, DAY_START);
+    const nextDay = clipCardsToRecapWindow([after], DAY_END, DAY_END + windowMs);
+    assert.equal(prevDay[0]?.id, "before");
+    assert.equal(nextDay[0]?.id, "after");
+  });
+
+  it("clips a card straddling the window start", () => {
+    const straddle = card("straddle", DAY_START - 30 * MINUTE, DAY_START + 90 * MINUTE);
+
+    const result = clipCardsToRecapWindow([straddle], DAY_START, DAY_END);
+
+    assert.equal(result.length, 1);
+    assert.equal(result[0]?.startMs, DAY_START);
+    assert.equal(result[0]?.endMs, DAY_START + 90 * MINUTE);
+    assert.equal(result[0]?.durationMs, 90 * MINUTE);
+  });
+
+  it("clips a card straddling the window end", () => {
+    const straddle = card("tail", DAY_END - 5 * MINUTE, DAY_END + 45 * MINUTE);
+
+    const result = clipCardsToRecapWindow([straddle], DAY_START, DAY_END);
+
+    assert.equal(result.length, 1);
+    assert.equal(result[0]?.endMs, DAY_END);
+    assert.equal(result[0]?.durationMs, 5 * MINUTE);
+  });
+
+  it("skips cards with unparseable timestamps without throwing", () => {
+    const good = card("good", DAY_START + MINUTE, DAY_START + 10 * MINUTE);
+    const bad: RecapWindowCard[] = [
+      { id: "bad-start", startUtc: "not-a-date", endUtc: iso(DAY_START + 5 * MINUTE) },
+      { id: "bad-end", startUtc: iso(DAY_START), endUtc: "" },
+      good,
+    ];
+
+    const result = clipCardsToRecapWindow(bad, DAY_START, DAY_END);
+
+    assert.deepEqual(
+      result.map((c) => c.id),
+      ["good"],
+    );
+    assert.equal(result[0]?.durationMs, 9 * MINUTE);
+  });
+
+  it("throws RangeError on inverted or empty window", () => {
+    assert.throws(
+      () => clipCardsToRecapWindow([], DAY_END, DAY_START),
+      RangeError,
+    );
+    assert.throws(
+      () => clipCardsToRecapWindow([], DAY_START, DAY_START),
+      RangeError,
+    );
+  });
+
+  it("throws RangeError on non-finite window bounds", () => {
+    // NaN and Infinity pass `end <= start`, so without an explicit finite
+    // check they would produce NaN timestamps instead of an error.
+    for (const [start, end] of [
+      [Number.NaN, DAY_END],
+      [DAY_START, Number.NaN],
+      [Number.POSITIVE_INFINITY, DAY_END],
+      [DAY_START, Number.POSITIVE_INFINITY],
+    ] as const) {
+      assert.throws(() => clipCardsToRecapWindow([], start, end), /finite/);
+    }
+  });
+
+  it("sorts by startMs then id, byte-identical across calls", () => {
+    const same = DAY_START + 60 * MINUTE;
+    const cards: RecapWindowCard[] = [
+      card("z-late", DAY_START + 120 * MINUTE, DAY_START + 130 * MINUTE),
+      card("b-tie", same, same + 10 * MINUTE),
+      card("a-tie", same, same + 10 * MINUTE),
+      card("early", DAY_START + 5 * MINUTE, DAY_START + 6 * MINUTE),
+    ];
+
+    const first = clipCardsToRecapWindow(cards, DAY_START, DAY_END);
+    const second = clipCardsToRecapWindow(cards, DAY_START, DAY_END);
+
+    assert.deepEqual(
+      first.map((c) => c.id),
+      ["early", "a-tie", "b-tie", "z-late"],
+    );
+    assert.deepEqual(first, second);
+  });
+});

package/src/activity/timeline/recap-window.ts

@@ -0,0 +1,55 @@
+/**
+ * Deterministic half-open recap window clip (issue #2051).
+ *
+ * Clips cards to [windowStartMs, windowEndMs) so recap renderers share one
+ * day-boundary derivation instead of re-deriving it per renderer.
+ */
+export interface RecapWindowCard {
+  id: string;
+  startUtc: string;
+  endUtc: string;
+}
+
+export interface ClippedRecapCard {
+  id: string;
+  startMs: number;
+  endMs: number;
+  durationMs: number;
+}
+
+export function clipCardsToRecapWindow(
+  cards: readonly RecapWindowCard[],
+  windowStartMs: number,
+  windowEndMs: number,
+): ClippedRecapCard[] {
+  // NaN fails every comparison, so an unchecked non-finite bound slips past the
+  // ordering guard and emits NaN timestamps and durations — `durationMs <= 0`
+  // is also false for NaN, so the card is not even dropped.
+  if (!Number.isFinite(windowStartMs) || !Number.isFinite(windowEndMs)) {
+    throw new RangeError(
+      `recap window bounds must be finite; got start ${windowStartMs} and end ${windowEndMs}`,
+    );
+  }
+  if (windowEndMs <= windowStartMs) {
+    throw new RangeError(
+      `recap window end ${windowEndMs} must be greater than start ${windowStartMs}`,
+    );
+  }
+  const out: ClippedRecapCard[] = [];
+  for (const card of cards) {
+    const startMs = Date.parse(card.startUtc);
+    const endMs = Date.parse(card.endUtc);
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) {
+      continue;
+    }
+    const clippedStart = Math.max(startMs, windowStartMs);
+    const clippedEnd = Math.min(endMs, windowEndMs);
+    const durationMs = clippedEnd - clippedStart;
+    if (durationMs <= 0) {
+      continue;
+    }
+    out.push({ id: card.id, startMs: clippedStart, endMs: clippedEnd, durationMs });
+  }
+  out.sort((a, b) => a.startMs - b.startMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return out;
+}

package/src/activity/types.ts

@@ -99,6 +99,10 @@ export interface ActivitySourceConfig {
 /** Opt-in daily journal settings (issue #1984). Default off. */
 export interface ActivityTimelineJournalConfig {
   enabled: boolean;
+  /** Where the journal text is read from (issue #1987). */
+  source: "file" | "vault";
+  /** Vault section heading, trimmed. Required when `source` is `"vault"`; not stored in `"file"` mode. */
+  heading?: string;
 }
 
 /** Opt-in timeline Q&A range/search settings (issue #1983 PR1). Default off. */

package/src/config.test.ts

@@ -2569,7 +2569,7 @@ test("parseConfig forwards activity source settings", () => {
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
-    timeline: { enabled: false, journal: { enabled: false }, qa: { enabled: false, maxRangeDays: 31 } },
+    timeline: { enabled: false, journal: { enabled: false, source: "file" }, qa: { enabled: false, maxRangeDays: 31 } },
   });
 });
 

package/src/dedup/index.ts

@@ -460,3 +460,10 @@ function walkMdFiles(
     }
   }
 }
+
+export {
+  decideMergeOnWrite,
+  type MergeCandidate,
+  type MergeDecision,
+  type MergeDecisionOptions,
+} from "./merge-decision.js";

package/src/dedup/merge-decision.test.ts

@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  decideMergeOnWrite,
+  type MergeCandidate,
+  type MergeDecisionOptions,
+} from "./merge-decision.js";
+
+const OPTS: MergeDecisionOptions = { updateThreshold: 0.8, duplicateThreshold: 0.92 };
+
+function candidate(overrides: Partial<MergeCandidate> = {}): MergeCandidate {
+  return {
+    id: "fact-1",
+    similarity: 0.85,
+    updatedAt: "2026-01-02T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+test("no candidates creates", () => {
+  assert.deepEqual(decideMergeOnWrite([], OPTS), { action: "create" });
+});
+
+test("best similarity at or above duplicateThreshold skips as duplicate", () => {
+  assert.deepEqual(
+    decideMergeOnWrite(
+      [candidate({ id: "low", similarity: 0.5 }), candidate({ id: "dup", similarity: 0.92 })],
+      OPTS,
+    ),
+    { action: "skip", reason: "duplicate" },
+  );
+});
+
+test("best similarity between thresholds updates the best candidate", () => {
+  assert.deepEqual(
+    decideMergeOnWrite(
+      [candidate({ id: "best", similarity: 0.9 }), candidate({ id: "worst", similarity: 0.81 })],
+      OPTS,
+    ),
+    { action: "update", targetId: "best" },
+  );
+});
+
+test("best similarity below updateThreshold creates", () => {
+  assert.deepEqual(
+    decideMergeOnWrite([candidate({ similarity: 0.79 })], OPTS),
+    { action: "create" },
+  );
+});
+
+test("invalid thresholds throw RangeError", () => {
+  const bad: MergeDecisionOptions[] = [
+    { updateThreshold: Number.NaN, duplicateThreshold: 0.9 },
+    { updateThreshold: 0.8, duplicateThreshold: Number.POSITIVE_INFINITY },
+    { updateThreshold: -0.1, duplicateThreshold: 0.9 },
+    { updateThreshold: 0.8, duplicateThreshold: 1.1 },
+    { updateThreshold: 0.92, duplicateThreshold: 0.8 }, // duplicate < update
+  ];
+  for (const options of bad) {
+    assert.throws(() => decideMergeOnWrite([], options), RangeError);
+  }
+});
+
+test("updateThreshold 0 is honored, never coerced up", () => {
+  const zero = { updateThreshold: 0, duplicateThreshold: 0.92 };
+  // similarity 0 is >= 0 -> update, not create and not default-band behavior
+  assert.deepEqual(
+    decideMergeOnWrite([candidate({ similarity: 0 })], zero),
+    { action: "update", targetId: "fact-1" },
+  );
+  // no candidates still creates
+  assert.deepEqual(decideMergeOnWrite([], zero), { action: "create" });
+});
+
+test("malformed candidates are ignored, never thrown on", () => {
+  assert.deepEqual(
+    decideMergeOnWrite(
+      [
+        { id: "", similarity: 0.99, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "  ", similarity: 0.99, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "nan", similarity: Number.NaN, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "inf", similarity: Number.POSITIVE_INFINITY, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "high", similarity: 1.5, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "neg", similarity: -0.2, updatedAt: "2026-01-01T00:00:00.000Z" },
+        { id: "good", similarity: 0.85, updatedAt: "2026-01-02T00:00:00.000Z" },
+      ],
+      OPTS,
+    ),
+    { action: "update", targetId: "good" },
+  );
+  // all-malformed behaves like no candidates
+  assert.deepEqual(
+    decideMergeOnWrite([{ id: "nan", similarity: Number.NaN, updatedAt: "x" }], OPTS),
+    { action: "create" },
+  );
+});
+
+test("identical similarity and updatedAt tie-breaks on id ascending, deterministically", () => {
+  const candidates = [
+    candidate({ id: "b", similarity: 0.9, updatedAt: "2026-03-01T00:00:00.000Z" }),
+    candidate({ id: "a", similarity: 0.9, updatedAt: "2026-03-01T00:00:00.000Z" }),
+    candidate({ id: "c", similarity: 0.9, updatedAt: "2026-03-01T00:00:00.000Z" }),
+  ];
+  const first = decideMergeOnWrite(candidates, OPTS);
+  const second = decideMergeOnWrite([...candidates].reverse(), OPTS);
+  assert.deepEqual(first, second);
+  assert.deepEqual(first, { action: "update", targetId: "a" });
+});
+
+test("unparseable updatedAt sorts last", () => {
+  const candidates = [
+    candidate({ id: "bad-date", similarity: 0.9, updatedAt: "not-a-timestamp" }),
+    candidate({ id: "good-date", similarity: 0.9, updatedAt: "2026-03-01T00:00:00.000Z" }),
+  ];
+  assert.deepEqual(decideMergeOnWrite(candidates, OPTS), { action: "update", targetId: "good-date" });
+  // newer timestamp wins when both parse
+  assert.deepEqual(
+    decideMergeOnWrite(
+      [
+        candidate({ id: "older", updatedAt: "2026-01-01T00:00:00.000Z" }),
+        candidate({ id: "newer", updatedAt: "2026-06-01T00:00:00.000Z" }),
+      ],
+      OPTS,
+    ),
+    { action: "update", targetId: "newer" },
+  );
+});
+
+// Two unparseable timestamps must not make the comparator asymmetric: testing
+// each side against NaN independently returned 1 for both orderings, so the
+// winner depended on array order.
+test("two unparseable updatedAt values break the tie by id, whatever the order", () => {
+  const options = { updateThreshold: 0.5, duplicateThreshold: 0.95 };
+  const alpha = { id: "alpha", similarity: 0.7, updatedAt: "not-a-date" };
+  const beta = { id: "beta", similarity: 0.7, updatedAt: "also-not-a-date" };
+
+  for (const candidates of [[alpha, beta], [beta, alpha]]) {
+    assert.deepEqual(decideMergeOnWrite(candidates, options), {
+      action: "update",
+      targetId: "alpha",
+    });
+  }
+});
+
+test("a parseable updatedAt still outranks an unparseable one in both orders", () => {
+  const options = { updateThreshold: 0.5, duplicateThreshold: 0.95 };
+  const dated = { id: "zeta", similarity: 0.7, updatedAt: "2026-08-19T00:00:00.000Z" };
+  const undated = { id: "alpha", similarity: 0.7, updatedAt: "nope" };
+
+  for (const candidates of [[dated, undated], [undated, dated]]) {
+    assert.deepEqual(decideMergeOnWrite(candidates, options), {
+      action: "update",
+      targetId: "zeta",
+    });
+  }
+});