@remnic/core 9.66.0 → 9.66.2

package/src/activity/vault-path.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resolveVaultNotePath } from "./vault-path.js";
+
+test("resolveVaultNotePath expands date tokens", () => {
+  assert.equal(resolveVaultNotePath("{yyyy}-{MM}-{dd}.md", "2026-08-18"), "2026-08-18.md");
+  assert.equal(
+    resolveVaultNotePath("Daily Notes/{yyyy}/{MM}/{yyyy}-{MM}-{dd}.md", "2026-08-18"),
+    "Daily Notes/2026/08/2026-08-18.md",
+  );
+  assert.equal(resolveVaultNotePath("{yy}/{M}/{d}.md", "2026-08-08"), "26/8/8.md");
+  assert.equal(
+    resolveVaultNotePath("{yyyy}-{MM}-{dd}.md", "2026-08-18", { timezone: "America/Chicago" }),
+    "2026-08-18.md",
+  );
+});
+
+test("resolveVaultNotePath expands ISO week {ww} as zero-padded", () => {
+  assert.equal(resolveVaultNotePath("W{ww}.md", "2021-01-01"), "W53.md");
+  assert.equal(resolveVaultNotePath("W{ww}.md", "2024-01-01"), "W01.md");
+  assert.equal(
+    resolveVaultNotePath("{yyyy}/W{ww}/{yyyy}-{MM}-{dd}.md", "2021-01-01"),
+    "2021/W53/2021-01-01.md",
+  );
+});
+
+test("resolveVaultNotePath rejects traversal and absolute templates", () => {
+  assert.throws(() => resolveVaultNotePath("../outside/{yyyy}.md", "2026-08-18"), /\.\.|absolute|traversal/i);
+  assert.throws(() => resolveVaultNotePath("{yyyy}/../../secret.md", "2026-08-18"), /\.\.|absolute|traversal/i);
+  assert.throws(() => resolveVaultNotePath("/abs/{yyyy}.md", "2026-08-18"), /\.\.|absolute|traversal/i);
+  assert.throws(() => resolveVaultNotePath("C:/vault/{yyyy}.md", "2026-08-18"), /\.\.|absolute|traversal/i);
+});
+
+test("resolveVaultNotePath requires a real YYYY-MM-DD date", () => {
+  assert.throws(() => resolveVaultNotePath("{yyyy}.md", "2026-02-30"), /YYYY-MM-DD/);
+  assert.throws(() => resolveVaultNotePath("{yyyy}.md", "20260818"), /YYYY-MM-DD/);
+});

package/src/activity/vault-path.ts

@@ -0,0 +1,59 @@
+/**
+ * Vault note path templates (issue #1985).
+ *
+ * Expands date tokens on a YYYY-MM-DD day. Returns a vault-relative path.
+ * Rejects `..` segments and absolute templates.
+ */
+import path from "node:path";
+
+import { assertValidTimezone, isValidActivityDate } from "./digest.js";
+
+const TOKEN_RE = /\{yyyy\}|\{yy\}|\{MM\}|\{dd\}|\{M\}|\{d\}|\{ww\}/g;
+
+export function resolveVaultNotePath(
+  template: string,
+  date: string,
+  options?: { timezone?: string },
+): string {
+  if (!isValidActivityDate(date)) {
+    throw new RangeError(`Invalid vault date "${date}"; expected YYYY-MM-DD.`);
+  }
+  if (options?.timezone !== undefined) {
+    assertValidTimezone(options.timezone);
+  }
+  if (typeof template !== "string" || template.length === 0) {
+    throw new RangeError("Vault note path template must be a non-empty relative path.");
+  }
+  if (path.posix.isAbsolute(template) || path.win32.isAbsolute(template)) {
+    throw new RangeError("Vault note path template must be relative; absolute templates are rejected.");
+  }
+
+  const [yyyy, mm, dd] = date.split("-");
+  const tokens: Record<string, string> = {
+    "{yyyy}": yyyy,
+    "{yy}": yyyy.slice(2),
+    "{MM}": mm,
+    "{dd}": dd,
+    "{M}": String(Number(mm)),
+    "{d}": String(Number(dd)),
+    "{ww}": isoWeekNumber(date),
+  };
+  const expanded = template.replace(TOKEN_RE, (token) => tokens[token] ?? token);
+  if (expanded.split(/[\\/]/).some((segment) => segment === "..")) {
+    throw new RangeError("Vault note path template must not contain `..` segments.");
+  }
+  if (path.posix.isAbsolute(expanded) || path.win32.isAbsolute(expanded)) {
+    throw new RangeError("Vault note path template must be relative; absolute templates are rejected.");
+  }
+  return expanded;
+}
+
+function isoWeekNumber(date: string): string {
+  const [year, month, day] = date.split("-").map(Number);
+  const utc = new Date(Date.UTC(year, month - 1, day));
+  const dayNum = utc.getUTCDay() || 7;
+  utc.setUTCDate(utc.getUTCDate() + 4 - dayNum);
+  const yearStart = new Date(Date.UTC(utc.getUTCFullYear(), 0, 1));
+  const weekNo = Math.ceil(((utc.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+  return String(weekNo).padStart(2, "0");
+}

package/src/activity/vault-publish.test.ts

@@ -0,0 +1,268 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { applyManagedRegion, publishVaultRegion } from "./vault-publish.js";
+
+const START = "<!-- remnic:timeline:start -->";
+const END = "<!-- remnic:timeline:end -->";
+
+function withVault(fn: (vaultPath: string) => void): void {
+  const vaultPath = mkdtempSync(path.join(tmpdir(), "remnic-vault-"));
+  try {
+    fn(vaultPath);
+  } finally {
+    rmSync(vaultPath, { recursive: true, force: true });
+  }
+}
+
+test("applyManagedRegion replaces only the marked region", () => {
+  const fileText = [
+    "---",
+    "title: daily",
+    "---",
+    "",
+    "human notes",
+    START,
+    "old cards",
+    END,
+    "more human",
+    "",
+  ].join("\n");
+  const result = applyManagedRegion(fileText, {
+    strategy: "markers",
+    name: "timeline",
+    content: "new cards",
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(
+    result.text,
+    [
+      "---",
+      "title: daily",
+      "---",
+      "",
+      "human notes",
+      START,
+      "new cards",
+      END,
+      "more human",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("applyManagedRegion is a no-op when markers are missing", () => {
+  const fileText = "no managed region here\n";
+  const result = applyManagedRegion(fileText, {
+    strategy: "markers",
+    name: "timeline",
+    content: "new cards",
+  });
+  assert.deepEqual(result, { ok: false, reason: "no_marker", text: fileText });
+});
+
+test("applyManagedRegion preserves CRLF outside and inside the owned region", () => {
+  const fileText = [
+    "---",
+    "title: daily",
+    "---",
+    "",
+    "human notes",
+    START,
+    "old cards",
+    END,
+    "more human",
+    "",
+  ].join("\r\n");
+  const result = applyManagedRegion(fileText, {
+    strategy: "markers",
+    name: "timeline",
+    content: "new cards\nline two",
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(
+    result.text,
+    [
+      "---",
+      "title: daily",
+      "---",
+      "",
+      "human notes",
+      START,
+      "new cards",
+      "line two",
+      END,
+      "more human",
+      "",
+    ].join("\r\n"),
+  );
+  assert.equal(result.text.includes("\n") && !result.text.includes("\r\n"), false);
+});
+
+test("applyManagedRegion keeps every outside byte identical", () => {
+  const prefix = "---\nkeep: me\n---\n\n- [ ] task\n```dataview\nLIST\n```\n";
+  const suffix = "\n<!-- other-agent:start -->\nleave this\n<!-- other-agent:end -->\n  trailing  \n";
+  const fileText = `${prefix}${START}\nold\n${END}${suffix}`;
+  const startAt = fileText.indexOf(START);
+  const endAt = fileText.indexOf(END);
+  const before = Buffer.from(fileText.slice(0, startAt + START.length), "utf8");
+  const after = Buffer.from(fileText.slice(endAt), "utf8");
+  const result = applyManagedRegion(fileText, {
+    strategy: "markers",
+    name: "timeline",
+    content: "replacement",
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  const nextStart = result.text.indexOf(START);
+  const nextEnd = result.text.indexOf(END);
+  assert.deepEqual(Buffer.from(result.text.slice(0, nextStart + START.length), "utf8"), before);
+  assert.deepEqual(Buffer.from(result.text.slice(nextEnd), "utf8"), after);
+});
+
+test("publishVaultRegion updates an existing note and skips an unchanged rewrite", () => {
+  withVault((vaultPath) => {
+    const relativeFile = "Daily Notes/2026-08-17.md";
+    const dest = path.join(vaultPath, relativeFile);
+    mkdirSync(path.dirname(dest), { recursive: true });
+    writeFileSync(dest, `intro\n${START}\nold\n${END}\noutro\n`);
+    const first = publishVaultRegion({
+      vaultPath,
+      relativeFile,
+      name: "timeline",
+      content: "new cards",
+    });
+    assert.deepEqual(first, { ok: true, status: "updated" });
+    assert.equal(readFileSync(dest, "utf8"), `intro\n${START}\nnew cards\n${END}\noutro\n`);
+    const mtime = statSync(dest).mtimeMs;
+    const second = publishVaultRegion({
+      vaultPath,
+      relativeFile,
+      name: "timeline",
+      content: "new cards",
+    });
+    assert.deepEqual(second, { ok: true, status: "unchanged" });
+    assert.equal(statSync(dest).mtimeMs, mtime);
+  });
+});
+
+test("publishVaultRegion never creates a missing file", () => {
+  withVault((vaultPath) => {
+    const relativeFile = "missing.md";
+    const result = publishVaultRegion({
+      vaultPath,
+      relativeFile,
+      name: "timeline",
+      content: "new cards",
+    });
+    assert.deepEqual(result, { ok: false, reason: "missing_file" });
+    assert.equal(existsSync(path.join(vaultPath, relativeFile)), false);
+  });
+});
+
+test("applyManagedRegion heading replaces only the named section", () => {
+  const fileText = [
+    "---",
+    "title: daily",
+    "---",
+    "",
+    "scratchpad",
+    "## Timeline",
+    "old cards",
+    "## Notes",
+    "keep me",
+    "",
+  ].join("\n");
+  const result = applyManagedRegion(fileText, {
+    strategy: "heading",
+    name: "Timeline",
+    content: "new cards",
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(
+    result.text,
+    [
+      "---",
+      "title: daily",
+      "---",
+      "",
+      "scratchpad",
+      "## Timeline",
+      "new cards",
+      "## Notes",
+      "keep me",
+      "",
+    ].join("\n"),
+  );
+
+  const crlf = fileText.replace(/\n/g, "\r\n");
+  const crlfResult = applyManagedRegion(crlf, {
+    strategy: "heading",
+    name: "Timeline",
+    content: "new cards\nline two",
+  });
+  assert.equal(crlfResult.ok, true);
+  if (!crlfResult.ok) return;
+  assert.equal(
+    crlfResult.text,
+    [
+      "---",
+      "title: daily",
+      "---",
+      "",
+      "scratchpad",
+      "## Timeline",
+      "new cards",
+      "line two",
+      "## Notes",
+      "keep me",
+      "",
+    ].join("\r\n"),
+  );
+
+  const prefix = "---\nkeep: me\n---\n\nscratchpad\n## Timeline";
+  const suffix = "\n## Notes\nkeep me\n";
+  const outside = `${prefix}\nold\n${suffix}`;
+  const headingAt = outside.indexOf("## Timeline");
+  const notesAt = outside.indexOf("\n## Notes");
+  const headingLineEnd = headingAt + "## Timeline".length;
+  const before = Buffer.from(outside.slice(0, headingLineEnd), "utf8");
+  const after = Buffer.from(outside.slice(notesAt), "utf8");
+  const byteResult = applyManagedRegion(outside, {
+    strategy: "heading",
+    name: "Timeline",
+    content: "replacement",
+  });
+  assert.equal(byteResult.ok, true);
+  if (!byteResult.ok) return;
+  const nextHeading = byteResult.text.indexOf("## Timeline");
+  const nextNotes = byteResult.text.indexOf("\n## Notes");
+  assert.deepEqual(Buffer.from(byteResult.text.slice(0, nextHeading + "## Timeline".length), "utf8"), before);
+  assert.deepEqual(Buffer.from(byteResult.text.slice(nextNotes), "utf8"), after);
+});
+
+test("applyManagedRegion heading is a no-op when the heading is missing", () => {
+  const fileText = "# Daily\n\nno timeline here\n";
+  const result = applyManagedRegion(fileText, {
+    strategy: "heading",
+    name: "Timeline",
+    content: "new cards",
+  });
+  assert.deepEqual(result, { ok: false, reason: "no_heading", text: fileText });
+});
+
+test("applyManagedRegion heading refuses duplicate headings and lists line numbers", () => {
+  const fileText = ["# Daily", "", "## Timeline", "first", "", "## Timeline", "second", ""].join("\n");
+  const result = applyManagedRegion(fileText, {
+    strategy: "heading",
+    name: "Timeline",
+    content: "new cards",
+  });
+  assert.deepEqual(result, { ok: false, reason: "duplicate_heading", lines: [3, 6], text: fileText });
+});

package/src/activity/vault-publish.ts

@@ -0,0 +1,180 @@
+/**
+ * Managed-region vault publisher (issue #1985).
+ *
+ * Markers replace bytes between `<!-- remnic:<name>:start -->` and
+ * `<!-- remnic:<name>:end -->`. Heading replaces the body after a unique
+ * ATX heading until the next same-or-higher heading. The heading line stays.
+ * This module does not read config.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { expandTildePath } from "../utils/path.js";
+
+export type ApplyManagedRegionResult =
+  | { ok: true; text: string }
+  | { ok: false; reason: "no_marker" | "no_heading"; text: string }
+  | { ok: false; reason: "duplicate_heading"; lines: readonly number[]; text: string };
+
+export type PublishVaultRegionResult =
+  | { ok: true; status: "updated" | "unchanged" }
+  | { ok: false; reason: "no_marker" | "missing_file" | "not_directory" };
+
+export function applyManagedRegion(
+  fileText: string,
+  opts: { strategy: "markers" | "heading"; name: string; content: string },
+): ApplyManagedRegionResult {
+  if (opts.strategy === "heading") return applyHeadingRegion(fileText, opts.name, opts.content);
+
+  const startMarker = `<!-- remnic:${opts.name}:start -->`;
+  const endMarker = `<!-- remnic:${opts.name}:end -->`;
+  const startIdx = fileText.indexOf(startMarker);
+  if (startIdx === -1) return { ok: false, reason: "no_marker", text: fileText };
+  const endIdx = fileText.indexOf(endMarker, startIdx + startMarker.length);
+  if (endIdx === -1) return { ok: false, reason: "no_marker", text: fileText };
+
+  const { body, eol } = ownedBody(fileText, opts.content);
+  return {
+    ok: true,
+    text: `${fileText.slice(0, startIdx + startMarker.length)}${eol}${body}${eol}${fileText.slice(endIdx)}`,
+  };
+}
+
+function applyHeadingRegion(fileText: string, name: string, content: string): ApplyManagedRegionResult {
+  const wanted = name.trim();
+  const hits: Array<{ line: number; level: number; next: number }> = [];
+  for (const row of fileLines(fileText)) {
+    const heading = parseAtxHeading(row.line);
+    if (heading && heading.text === wanted) {
+      hits.push({ line: row.number, level: heading.level, next: row.next });
+    }
+  }
+  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.line), text: fileText };
+  }
+
+  const hit = hits[0]!;
+  let sectionEnd = fileText.length;
+  for (const row of fileLines(fileText)) {
+    if (row.start < hit.next) continue;
+    const heading = parseAtxHeading(row.line);
+    if (heading && heading.level <= hit.level) {
+      sectionEnd = row.start;
+      break;
+    }
+  }
+
+  const { body, eol } = ownedBody(fileText, content);
+  const prefix =
+    hit.next === fileText.length && !fileText.endsWith("\n") && !fileText.endsWith("\r")
+      ? `${fileText}${eol}`
+      : fileText.slice(0, hit.next);
+  return { ok: true, text: `${prefix}${body}${eol}${fileText.slice(sectionEnd)}` };
+}
+
+function ownedBody(fileText: string, content: string): { body: string; eol: string } {
+  const eol = fileText.includes("\r\n") ? "\r\n" : "\n";
+  let body = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (eol === "\r\n") body = body.replace(/\n/g, "\r\n");
+  if (body.endsWith(eol)) body = body.slice(0, -eol.length);
+  return { body, eol };
+}
+
+function fileLines(fileText: string): Array<{ line: string; start: number; next: number; number: number }> {
+  const rows: Array<{ line: string; start: number; next: number; number: number }> = [];
+  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) return null;
+  const after = line[level];
+  if (after !== " " && after !== "\t") return null;
+
+  let start = level + 1;
+  let end = line.length;
+  while (start < end && (line[start] === " " || line[start] === "\t")) start++;
+  while (end > start && (line[end - 1] === " " || line[end - 1] === "\t")) end--;
+
+  let hashEnd = end;
+  while (hashEnd > start && line[hashEnd - 1] === "#") hashEnd--;
+  if (hashEnd < end && hashEnd > start && (line[hashEnd - 1] === " " || line[hashEnd - 1] === "\t")) {
+    end = hashEnd;
+    while (end > start && (line[end - 1] === " " || line[end - 1] === "\t")) end--;
+  }
+  return { level, text: line.slice(start, end) };
+}
+
+export function publishVaultRegion(input: {
+  vaultPath: string;
+  relativeFile: string;
+  name: string;
+  content: string;
+}): PublishVaultRegionResult {
+  const vault = expandTildePath(input.vaultPath);
+  try {
+    if (!statSync(vault).isDirectory()) return { ok: false, reason: "not_directory" };
+  } catch {
+    return { ok: false, reason: "not_directory" };
+  }
+
+  if (input.relativeFile.length === 0 || path.isAbsolute(input.relativeFile)) {
+    return { ok: false, reason: "missing_file" };
+  }
+  const root = path.resolve(vault);
+  const dest = path.resolve(root, input.relativeFile);
+  const rel = path.relative(root, dest);
+  if (rel.length === 0 || rel.startsWith("..") || path.isAbsolute(rel)) {
+    return { ok: false, reason: "missing_file" };
+  }
+
+  let existing: string;
+  try {
+    if (!statSync(dest).isFile()) return { ok: false, reason: "missing_file" };
+    existing = readFileSync(dest, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { ok: false, reason: "missing_file" };
+    throw err;
+  }
+
+  const applied = applyManagedRegion(existing, {
+    strategy: "markers",
+    name: input.name,
+    content: input.content,
+  });
+  if (!applied.ok) return { ok: false, reason: "no_marker" };
+
+  const prevHash = createHash("sha256").update(existing, "utf8").digest("hex");
+  const nextHash = createHash("sha256").update(applied.text, "utf8").digest("hex");
+  if (prevHash === nextHash) return { ok: true, status: "unchanged" };
+
+  const tmpPath = path.join(path.dirname(dest), `.remnic-vault-${randomBytes(8).toString("hex")}.tmp`);
+  writeFileSync(tmpPath, applied.text);
+  try {
+    renameSync(tmpPath, dest);
+  } catch (renameErr) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // temp cleanup is best-effort
+    }
+    throw renameErr;
+  }
+  return { ok: true, status: "updated" };
+}

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 },
+    timeline: { enabled: false, journal: { enabled: false }, qa: { enabled: false, maxRangeDays: 31 } },
   });
 });
 

package/src/config.ts

@@ -48,6 +48,7 @@ import { parseSkillProjectionConfig } from "./procedural/skill-projection.js";
 import { parseDriftDetectionConfig } from "./preferences/drift-config.js";
 import { parseContradictionLocalizationConfig, parseContradictionScanConfig } from "./contradiction-config.js";
 import { parseGraphPathScoringConfig } from "./graph-path-scoring-config.js";
+import { parseWritePathDedupConfig } from "./dedup/novelty-gate.js";
 import { hasLegacyConnectorEntries } from "./connectors/paths.js";
 import {
   parseQmdChunkStrategy,
@@ -3190,28 +3191,7 @@ export function parseConfig(
 
     // v6.0 Fact deduplication & archival
     factDeduplicationEnabled: cfg.factDeduplicationEnabled !== false,
-    // Issue #373 — write-time semantic similarity guard
-    semanticDedupEnabled: cfg.semanticDedupEnabled !== false,
-    // Guard against NaN / Infinity — Number.isFinite rejects both and falls
-    // back to the documented default so the semantic dedup guard cannot be
-    // silently disabled by a malformed config value.
-    semanticDedupThreshold:
-      typeof cfg.semanticDedupThreshold === "number" &&
-      Number.isFinite(cfg.semanticDedupThreshold)
-        ? Math.min(1, Math.max(0, cfg.semanticDedupThreshold))
-        : 0.92,
-    // Zero is a valid "disable candidate lookup" signal and must be preserved.
-    // Only negative or non-finite values fall back to the default of 5.
-    // Fractional values in (0, 1) floor to 0, which would silently disable
-    // semantic dedup despite a clearly non-zero operator intent — clamp to 1.
-    semanticDedupCandidates: (() => {
-      const raw = cfg.semanticDedupCandidates;
-      if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) return 5;
-      const n = Math.floor(raw);
-      // Positive fractional input (e.g. 0.5) should mean "at least 1 candidate",
-      // not "disabled". Only explicit 0 is the operator's disable signal.
-      return raw > 0 && n === 0 ? 1 : n;
-    })(),
+    ...parseWritePathDedupConfig(cfg),
     factArchivalEnabled: cfg.factArchivalEnabled === true,
     factArchivalAgeDays:
       typeof cfg.factArchivalAgeDays === "number" ? cfg.factArchivalAgeDays : 90,

package/src/dedup/merge-on-write-wire.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { MergeJudge, MergeJudgeVerdict, MergeOnWritePair } from "./merge-on-write.js";
+import { applyMergeOnWriteAtPersist } from "./merge-on-write-wire.js";
+
+type PersistResult = { action: "merged"; id: string } | { action: "created" };
+
+function pair(overrides: Partial<MergeOnWritePair> = {}): MergeOnWritePair {
+  return {
+    category: "fact",
+    score: 0.85,
+    incomingContent: "User prefers dark mode on laptops.",
+    existingContent: "User likes dark mode.",
+    existingId: "mem-1",
+    ...overrides,
+  };
+}
+
+function trackers() {
+  const merged: string[] = [];
+  const created: number[] = [];
+  return {
+    merged,
+    created,
+    writeMerged: async (id: string): Promise<PersistResult> => {
+      merged.push(id);
+      return { action: "merged", id };
+    },
+    writeNew: async (): Promise<PersistResult> => {
+      created.push(1);
+      return { action: "created" };
+    },
+  };
+}
+
+const mergeJudge: MergeJudge = async (): Promise<MergeJudgeVerdict> => "merge";
+const createJudge: MergeJudge = async (): Promise<MergeJudgeVerdict> => "create";
+
+test("merge-on-write-wire: disabled writes a new fact", async () => {
+  let judged = 0;
+  const io = trackers();
+  const result = await applyMergeOnWriteAtPersist({
+    enabled: false,
+    pair: pair(),
+    judge: async (): Promise<MergeJudgeVerdict> => {
+      judged += 1;
+      return "merge";
+    },
+    writeMerged: io.writeMerged,
+    writeNew: io.writeNew,
+  });
+  assert.equal(result.action, "created");
+  assert.deepEqual(io.merged, []);
+  assert.equal(io.created.length, 1);
+  assert.equal(judged, 0);
+});
+
+test("merge-on-write-wire: mergeMin 0 writes a new fact", async () => {
+  let judged = 0;
+  const io = trackers();
+  const result = await applyMergeOnWriteAtPersist({
+    enabled: true,
+    mergeMin: 0,
+    pair: pair(),
+    judge: mergeJudge,
+    writeMerged: io.writeMerged,
+    writeNew: io.writeNew,
+  });
+  assert.equal(result.action, "created");
+  assert.deepEqual(io.merged, []);
+  assert.equal(io.created.length, 1);
+  assert.equal(judged, 0);
+});
+
+test("merge-on-write-wire: merge updates the existing id", async () => {
+  const io = trackers();
+  const result = await applyMergeOnWriteAtPersist({
+    enabled: true,
+    pair: pair(),
+    judge: mergeJudge,
+    writeMerged: io.writeMerged,
+    writeNew: io.writeNew,
+  });
+  assert.deepEqual(result, { action: "merged", id: "mem-1" });
+  assert.deepEqual(io.merged, ["mem-1"]);
+  assert.equal(io.created.length, 0);
+});
+
+test("merge-on-write-wire: create writes a new fact", async () => {
+  const io = trackers();
+  const result = await applyMergeOnWriteAtPersist({
+    enabled: true,
+    pair: pair(),
+    judge: createJudge,
+    writeMerged: io.writeMerged,
+    writeNew: io.writeNew,
+  });
+  assert.equal(result.action, "created");
+  assert.deepEqual(io.merged, []);
+  assert.equal(io.created.length, 1);
+});