@remnic/core 9.66.8 → 9.66.10

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/timeline/week-previous.test.ts

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { compareWeeklyPreviousPeriod } from "./week-previous.js";
+
+const CURRENT = {
+  activeMs: 3_600_000,
+  idleMs: 600_000,
+  pauseMs: 120_000,
+  gapMs: 300_000,
+  unclassifiedMs: 60_000,
+};
+
+const PREVIOUS = {
+  activeMs: 1_800_000,
+  idleMs: 900_000,
+  pauseMs: 120_000,
+  gapMs: 100_000,
+  unclassifiedMs: 0,
+};
+
+test("null previous is unavailable, not zero", () => {
+  const result = compareWeeklyPreviousPeriod({
+    previous: null,
+    current: CURRENT,
+    previousStartUtc: "2026-07-06T00:00:00Z",
+    previousEndUtc: "2026-07-13T00:00:00Z",
+  });
+  assert.deepEqual(result, { available: false });
+  assert.equal("deltaActiveMs" in result, false);
+});
+
+test("undefined previous is unavailable", () => {
+  const result = compareWeeklyPreviousPeriod({
+    previous: undefined,
+    current: CURRENT,
+  });
+  assert.deepEqual(result, { available: false });
+});
+
+test("previous without timestamps is unavailable", () => {
+  const result = compareWeeklyPreviousPeriod({ previous: PREVIOUS, current: CURRENT });
+  assert.deepEqual(result, { available: false });
+});
+
+test("previous with blank timestamps is unavailable", () => {
+  const result = compareWeeklyPreviousPeriod({
+    previous: PREVIOUS,
+    current: CURRENT,
+    previousStartUtc: "   ",
+    previousEndUtc: "\t",
+  });
+  assert.deepEqual(result, { available: false });
+});
+
+test("mixed deltas keep sign and trim timestamps", () => {
+  const result = compareWeeklyPreviousPeriod({
+    previous: PREVIOUS,
+    current: CURRENT,
+    previousStartUtc: " 2026-07-06T00:00:00Z ",
+    previousEndUtc: " 2026-07-13T00:00:00Z ",
+  });
+  assert.equal(result.available, true);
+  if (!result.available) return;
+  assert.equal(result.previousStartUtc, "2026-07-06T00:00:00Z");
+  assert.equal(result.previousEndUtc, "2026-07-13T00:00:00Z");
+  assert.equal(result.deltaActiveMs, 1_800_000);
+  assert.equal(result.deltaIdleMs, -300_000);
+  assert.equal(result.deltaPauseMs, 0);
+  assert.equal(result.deltaGapMs, 200_000);
+  assert.equal(result.deltaUnclassifiedMs, 60_000);
+});
+
+test("NaN duration on previous throws TypeError", () => {
+  assert.throws(
+    () =>
+      compareWeeklyPreviousPeriod({
+        previous: { ...PREVIOUS, gapMs: Number.NaN },
+        current: CURRENT,
+        previousStartUtc: "2026-07-06T00:00:00Z",
+        previousEndUtc: "2026-07-13T00:00:00Z",
+      }),
+    TypeError,
+  );
+});
+
+test("Infinity duration on current throws TypeError", () => {
+  assert.throws(
+    () =>
+      compareWeeklyPreviousPeriod({
+        previous: PREVIOUS,
+        current: { ...CURRENT, activeMs: Number.POSITIVE_INFINITY },
+      }),
+    /current\.activeMs/,
+  );
+});
+
+test("all-zero current with present previous is available with negative deltas", () => {
+  const zeros = {
+    activeMs: 0,
+    idleMs: 0,
+    pauseMs: 0,
+    gapMs: 0,
+    unclassifiedMs: 0,
+  };
+  const result = compareWeeklyPreviousPeriod({
+    previous: PREVIOUS,
+    current: zeros,
+    previousStartUtc: "2026-07-06T00:00:00Z",
+    previousEndUtc: "2026-07-13T00:00:00Z",
+  });
+  assert.equal(result.available, true);
+  if (!result.available) return;
+  assert.equal(result.deltaActiveMs, -PREVIOUS.activeMs);
+  assert.equal(result.deltaIdleMs, -PREVIOUS.idleMs);
+  assert.equal(result.deltaPauseMs, -PREVIOUS.pauseMs);
+  assert.equal(result.deltaGapMs, -PREVIOUS.gapMs);
+  assert.equal(result.deltaUnclassifiedMs, 0);
+});

package/src/activity/timeline/week-previous.ts

@@ -0,0 +1,83 @@
+/**
+ * Previous-week duration comparison (issue #2052).
+ *
+ * The prior week is explicit when unavailable. It is never silently treated
+ * as zero.
+ */
+
+export interface WeeklyDurationTotals {
+  activeMs: number;
+  idleMs: number;
+  pauseMs: number;
+  gapMs: number;
+  unclassifiedMs: number;
+}
+
+export type WeeklyPreviousPeriod =
+  | { available: false }
+  | {
+      available: true;
+      previousStartUtc: string;
+      previousEndUtc: string;
+      deltaActiveMs: number;
+      deltaIdleMs: number;
+      deltaPauseMs: number;
+      deltaGapMs: number;
+      deltaUnclassifiedMs: number;
+    };
+
+const DURATION_FIELDS = [
+  "activeMs",
+  "idleMs",
+  "pauseMs",
+  "gapMs",
+  "unclassifiedMs",
+] as const;
+
+function assertFiniteTotals(totals: WeeklyDurationTotals, label: string): void {
+  for (const field of DURATION_FIELDS) {
+    const value = totals[field];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new TypeError(`${label}.${field} must be a finite number; got ${String(value)}.`);
+    }
+  }
+}
+
+/**
+ * Compare this week's duration totals against the previous week's.
+ *
+ * `previous` absent (null/undefined) or lacking trimmed start/end timestamps
+ * returns `{ available: false }` — never zero deltas. Otherwise returns the
+ * per-field deltas (`current - previous`, may be negative). Pure.
+ */
+export function compareWeeklyPreviousPeriod(input: {
+  previous: WeeklyDurationTotals | null | undefined;
+  current: WeeklyDurationTotals;
+  previousStartUtc?: string;
+  previousEndUtc?: string;
+}): WeeklyPreviousPeriod {
+  const { previous, current, previousStartUtc, previousEndUtc } = input;
+  assertFiniteTotals(current, "current");
+
+  if (previous === null || previous === undefined) {
+    return { available: false };
+  }
+  assertFiniteTotals(previous, "previous");
+
+  const start = previousStartUtc?.trim() ?? "";
+  const end = previousEndUtc?.trim() ?? "";
+  if (start === "" || end === "") {
+    return { available: false };
+  }
+
+  return {
+    available: true,
+    previousStartUtc: start,
+    previousEndUtc: end,
+    deltaActiveMs: current.activeMs - previous.activeMs,
+    deltaIdleMs: current.idleMs - previous.idleMs,
+    deltaPauseMs: current.pauseMs - previous.pauseMs,
+    deltaGapMs: current.gapMs - previous.gapMs,
+    deltaUnclassifiedMs: current.unclassifiedMs - previous.unclassifiedMs,
+  };
+}

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/activity/vault-insert.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { insertMarkersUnderHeading } from "./vault-insert.js";
+
+const START = "<!-- remnic:daily:start -->";
+const END = "<!-- remnic:daily:end -->";
+
+test("inserts markers under a unique heading before existing body", () => {
+  const fileText = ["# Notes", "", "## Journal", "", "Existing entry.", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, {
+    heading: "Journal",
+    name: "daily",
+    content: "Line one.\nLine two.",
+  });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(
+    result.text,
+    ["# Notes", "", "## Journal", START, "Line one.", "Line two.", END, "", "Existing entry.", ""].join("\n"),
+  );
+});
+
+test("returns text unchanged when both markers already exist", () => {
+  const fileText = ["## Journal", START, "old", END, "tail", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "new" });
+  assert.deepEqual(result, { ok: true, text: fileText, inserted: false });
+});
+
+test("fails with no_heading when no heading matches exactly", () => {
+  const fileText = ["## Journal entry", "body", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "new" });
+  assert.deepEqual(result, { ok: false, reason: "no_heading", text: fileText });
+});
+
+test("fails with duplicate_heading and both 1-based line numbers", () => {
+  const fileText = ["# Top", "## Journal", "a", "## Journal", "b", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "new" });
+  assert.ok(!result.ok && result.reason === "duplicate_heading");
+  assert.deepEqual(result.lines, [2, 4]);
+  assert.equal(result.text, fileText);
+});
+
+test("inserts before a later same-level heading and leaves that section intact", () => {
+  const fileText = ["## Journal", "existing", "## Other", "other body", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "cards" });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(
+    result.text,
+    ["## Journal", START, "cards", END, "existing", "## Other", "other body", ""].join("\n"),
+  );
+});
+
+test("deeper headings do not end the section", () => {
+  const fileText = ["## Journal", "### Nested", "nested body", "## Other", ""].join("\n");
+  const result = insertMarkersUnderHeading(fileText, { heading: "Journal", name: "daily", content: "cards" });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(
+    result.text,
+    ["## Journal", START, "cards", END, "### Nested", "nested body", "## Other", ""].join("\n"),
+  );
+});
+
+test("inserts under a heading at EOF without trailing newline", () => {
+  const result = insertMarkersUnderHeading("## Journal", { heading: "Journal", name: "daily", content: "cards" });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(result.text, `## Journal\n${START}\ncards\n${END}\n`);
+});
+
+test("keeps content ending in a newline without doubling it", () => {
+  const result = insertMarkersUnderHeading("## Journal\nbody\n", {
+    heading: "Journal",
+    name: "daily",
+    content: "cards\n",
+  });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(result.text, `## Journal\n${START}\ncards\n${END}\nbody\n`);
+});
+
+test("empty content inserts adjacent markers", () => {
+  const result = insertMarkersUnderHeading("## Journal\n", { heading: "Journal", name: "daily", content: "" });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(result.text, `## Journal\n${START}\n${END}\n`);
+});
+
+test("preserves CRLF as the dominant EOL", () => {
+  const fileText = ["## Journal", "body", ""].join("\r\n");
+  const result = insertMarkersUnderHeading(fileText, {
+    heading: "Journal",
+    name: "daily",
+    content: "line a\r\nline b",
+  });
+  assert.ok(result.ok && result.inserted);
+  assert.equal(result.text, `## Journal\r\n${START}\r\nline a\r\nline b\r\n${END}\r\nbody\r\n`);
+});
+
+test("empty heading or name throws RangeError", () => {
+  assert.throws(
+    () => insertMarkersUnderHeading("## Journal\n", { heading: "", name: "daily", content: "" }),
+    (err) => err instanceof RangeError && /empty/i.test(err.message),
+  );
+  assert.throws(
+    () => insertMarkersUnderHeading("## Journal\n", { heading: "Journal", name: "", content: "" }),
+    (err) => err instanceof RangeError && /empty/i.test(err.message),
+  );
+});

package/src/activity/vault-insert.ts

@@ -0,0 +1,86 @@
+/**
+ * Managed-region marker insertion (issue #1985).
+ *
+ * Inserts a `<!-- remnic:<name>:start/end -->` pair under a unique ATX
+ * heading when the region is absent. This helper never replaces (see
+ * `vault-publish.ts`), never creates files, and never invents a heading.
+ * Pure string-in/string-out.
+ */
+
+export type InsertVaultRegionResult =
+  | { ok: true; text: string; inserted: true }
+  | { ok: true; text: string; inserted: false }
+  | { ok: false; reason: "no_heading"; text: string }
+  | { ok: false; reason: "duplicate_heading"; lines: readonly number[]; text: string };
+
+export function insertMarkersUnderHeading(
+  fileText: string,
+  opts: { heading: string; name: string; content: string },
+): InsertVaultRegionResult {
+  if (typeof opts.heading !== "string" || opts.heading.length === 0) {
+    throw new RangeError("Heading must be non-empty.");
+  }
+  if (typeof opts.name !== "string" || opts.name.length === 0) {
+    throw new RangeError("Region name must be non-empty.");
+  }
+
+  const startMarker = `<!-- remnic:${opts.name}:start -->`;
+  const endMarker = `<!-- remnic:${opts.name}:end -->`;
+  if (fileText.includes(startMarker) && fileText.includes(endMarker)) {
+    return { ok: true, text: fileText, inserted: false };
+  }
+
+  const rows = fileLines(fileText);
+  const hits: Array<{ row: (typeof rows)[number]; level: number }> = [];
+  for (const row of rows) {
+    const heading = parseAtxHeading(row.line);
+    if (heading && heading.text === opts.heading) {
+      hits.push({ row, level: heading.level });
+    }
+  }
+  if (hits.length === 0) return { ok: false, reason: "no_heading", text: fileText };
+  if (hits.length > 1) {
+    return { ok: false, reason: "duplicate_heading", lines: hits.map((hit) => hit.row.number), text: fileText };
+  }
+
+  const hit = hits[0]!;
+
+  const eol = fileText.includes("\r\n") ? "\r\n" : "\n";
+  const prefix =
+    hit.row.next === fileText.length && !fileText.endsWith("\n") && !fileText.endsWith("\r")
+      ? `${fileText}${eol}`
+      : fileText.slice(0, hit.row.next);
+  let content = opts.content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (eol === "\r\n") content = content.replace(/\n/g, "\r\n");
+  if (content.length > 0 && !content.endsWith(eol)) content += eol;
+
+  const text = `${prefix}${startMarker}${eol}${content}${endMarker}${eol}${fileText.slice(hit.row.next)}`;
+  return { ok: true, text, inserted: true };
+}
+
+type FileLine = { line: string; start: number; next: number; number: number };
+
+function fileLines(fileText: string): FileLine[] {
+  const rows: FileLine[] = [];
+  let start = 0;
+  let number = 1;
+  while (start < fileText.length) {
+    let i = start;
+    while (i < fileText.length && fileText[i] !== "\n" && fileText[i] !== "\r") i++;
+    let next = i;
+    if (fileText[i] === "\r" && fileText[i + 1] === "\n") next = i + 2;
+    else if (fileText[i] === "\n" || fileText[i] === "\r") next = i + 1;
+    else next = fileText.length;
+    rows.push({ line: fileText.slice(start, i), start, next, number });
+    number += 1;
+    start = next;
+  }
+  return rows;
+}
+
+function parseAtxHeading(line: string): { level: number; text: string } | null {
+  let level = 0;
+  while (level < line.length && level < 6 && line[level] === "#") level++;
+  if (level === 0 || line[level] !== " ") return null;
+  return { level, text: line.slice(level + 1) };
+}

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",
+    });
+  }
+});