@remnic/core 9.66.1 → 9.66.2

package/src/activity/timeline/weekly-persist.ts

@@ -0,0 +1,103 @@
+/**
+ * Versioned weekly time/activity snapshot store (issue #2052).
+ *
+ * Files live at `<memoryDir>/activity/weekly/<ns>/<week>--<identity>.json`,
+ * outside recall fallback dirs. Same inputs skip rewrite by content hash.
+ * A new sourceRevision or configHash is a new file.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { namespaceIdentityToken } from "../../namespaces/identity.js";
+import { hashActivityBody, isValidActivityDate } from "../digest.js";
+import type { WeeklyActivitySummary } from "./weekly.js";
+
+export const WEEKLY_SNAPSHOT_FORMAT_VERSION = 1;
+export const WEEKLY_SNAPSHOT_DIR = path.join("activity", "weekly");
+
+export interface PersistWeeklySnapshotInput {
+  memoryDir: string;
+  namespace: string;
+  summary: WeeklyActivitySummary;
+  sourceRevision: string;
+  configHash: string;
+}
+
+export interface PersistWeeklySnapshotResult {
+  path: string;
+  written: boolean;
+}
+
+function requireToken(value: string, name: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+export function weeklySnapshotPath(input: PersistWeeklySnapshotInput): string {
+  const memoryDir = requireToken(input.memoryDir, "memoryDir");
+  const namespace = requireToken(input.namespace, "namespace");
+  const sourceRevision = requireToken(input.sourceRevision, "sourceRevision");
+  const configHash = requireToken(input.configHash, "configHash");
+  const weekStartUtc = input.summary?.weekStartUtc;
+  if (typeof weekStartUtc !== "string") {
+    throw new TypeError("summary.weekStartUtc must be an ISO timestamp");
+  }
+  const weekDate = weekStartUtc.slice(0, 10);
+  if (!isValidActivityDate(weekDate)) {
+    throw new RangeError("summary.weekStartUtc must be an ISO timestamp");
+  }
+  const identity = hashActivityBody(
+    `${input.summary.weekStartUtc}\0${input.summary.weekEndUtc}\0${sourceRevision}\0${configHash}`,
+  );
+  return path.join(
+    path.resolve(memoryDir),
+    WEEKLY_SNAPSHOT_DIR,
+    namespaceIdentityToken(namespace),
+    `${weekDate}--${identity}.json`,
+  );
+}
+
+/** Persist one weekly snapshot. Same bytes are a no-op. */
+export function persistWeeklySnapshot(input: PersistWeeklySnapshotInput): PersistWeeklySnapshotResult {
+  const namespace = requireToken(input.namespace, "namespace");
+  const sourceRevision = requireToken(input.sourceRevision, "sourceRevision");
+  const configHash = requireToken(input.configHash, "configHash");
+  const filePath = weeklySnapshotPath(input);
+  const payload = {
+    formatVersion: WEEKLY_SNAPSHOT_FORMAT_VERSION,
+    namespace,
+    sourceRevision,
+    configHash,
+    summary: input.summary,
+  };
+  const contentHash = hashActivityBody(JSON.stringify(payload));
+  const text = `${JSON.stringify({ ...payload, contentHash })}\n`;
+
+  try {
+    if (readFileSync(filePath, "utf8") === text) {
+      return { path: filePath, written: false };
+    }
+  } catch (error) {
+    if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+
+  mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmpPath = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+  writeFileSync(tmpPath, text, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(tmpPath, filePath);
+  } catch (error) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // Best-effort cleanup of the temp file.
+    }
+    throw error;
+  }
+  return { path: filePath, written: true };
+}

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

@@ -164,3 +164,105 @@ test("publishVaultRegion never creates a 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

@@ -1,10 +1,10 @@
 /**
- * Managed-region vault publisher (issue #1985 first slice).
+ * Managed-region vault publisher (issue #1985).
  *
- * Replaces only the bytes between `<!-- remnic:<name>:start -->` and
- * `<!-- remnic:<name>:end -->`. Missing markers leave the file unchanged.
- * `activity.timeline.vault.enabled` stays default-false until a later parse
- * slice; this module does not read config.
+ * 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";
@@ -14,7 +14,8 @@ import { expandTildePath } from "../utils/path.js";
 
 export type ApplyManagedRegionResult =
   | { ok: true; text: string }
-  | { ok: false; reason: "no_marker"; 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" }
@@ -22,8 +23,10 @@ export type PublishVaultRegionResult =
 
 export function applyManagedRegion(
   fileText: string,
-  opts: { strategy: "markers"; name: string; content: 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);
@@ -31,17 +34,93 @@ export function applyManagedRegion(
   const endIdx = fileText.indexOf(endMarker, startIdx + startMarker.length);
   if (endIdx === -1) return { ok: false, reason: "no_marker", text: fileText };
 
-  const eol = fileText.includes("\r\n") ? "\r\n" : "\n";
-  let body = opts.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);
-
+  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;
@@ -79,7 +158,7 @@ export function publishVaultRegion(input: {
     name: input.name,
     content: input.content,
   });
-  if (!applied.ok) return { ok: false, reason: applied.reason };
+  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");

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

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

@@ -0,0 +1,34 @@
+/**
+ * Persist seam for merge-on-write (issue #2330 leftover slice).
+ *
+ * Default off. Failures and disabled gates create. Persist callers inject
+ * writeMerged / writeNew. This module does not touch extraction-persist.
+ */
+
+import {
+  applyMergeOnWrite,
+  type MergeJudge,
+  type MergeOnWritePair,
+} from "./merge-on-write.js";
+
+export async function applyMergeOnWriteAtPersist<T>(opts: {
+  enabled?: boolean;
+  pair: MergeOnWritePair;
+  judge: MergeJudge;
+  mergeMin?: number;
+  skipThreshold?: number;
+  writeMerged: (id: string) => T | Promise<T>;
+  writeNew: () => T | Promise<T>;
+}): Promise<T> {
+  const decision = await applyMergeOnWrite({
+    enabled: opts.enabled,
+    pair: opts.pair,
+    judge: opts.judge,
+    mergeMin: opts.mergeMin,
+    skipThreshold: opts.skipThreshold,
+  });
+  if (decision === "merge" && opts.pair.existingId) {
+    return opts.writeMerged(opts.pair.existingId);
+  }
+  return opts.writeNew();
+}

package/src/extraction-span-wire.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { applySpanMode } from "./extraction-span-wire.js";
+
+const TEXT = "Alice moved to Seattle";
+
+test("applySpanMode: disabled or 0 is identity", () => {
+  const span = { text: TEXT, start: 6, end: 11 };
+  assert.deepEqual(applySpanMode({ enabled: false, ...span }), { text: TEXT });
+  assert.deepEqual(applySpanMode({ enabled: 0, ...span }), { text: TEXT });
+  assert.deepEqual(applySpanMode(span), { text: TEXT });
+});
+
+test("applySpanMode: enabled slices half-open [start, end)", () => {
+  assert.deepEqual(applySpanMode({ enabled: true, text: TEXT, start: 6, end: 11 }), {
+    text: "moved",
+    start: 6,
+    end: 11,
+  });
+});

package/src/extraction-span-wire.ts

@@ -0,0 +1,17 @@
+/**
+ * Extraction seam for span mode (issue #2333 leftover slice).
+ *
+ * Default off. Callers pass `enabled`. This module does not touch
+ * extraction.ts; Phase A still gates production wiring.
+ */
+
+import { parseSpanOffsets, type ParsedSpan } from "./extraction-span.js";
+
+export function applySpanMode(opts: {
+  enabled?: boolean | 0 | 1;
+  text: string;
+  start: number;
+  end: number;
+}): ParsedSpan {
+  return parseSpanOffsets(opts.text, { start: opts.start, end: opts.end }, opts.enabled);
+}

package/src/extraction-span.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { parseSpanOffsets } from "./extraction-span.js";
+
+const TEXT = "Alice moved to Seattle";
+
+test("parseSpanOffsets: disabled or 0 is identity", () => {
+  const offsets = { start: 6, end: 11 };
+  assert.deepEqual(parseSpanOffsets(TEXT, offsets, false), { text: TEXT });
+  assert.deepEqual(parseSpanOffsets(TEXT, offsets, 0), { text: TEXT });
+  assert.deepEqual(parseSpanOffsets(TEXT, offsets), { text: TEXT });
+});
+
+test("parseSpanOffsets: enabled slices half-open [start, end)", () => {
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: 6, end: 11 }, true), {
+    text: "moved",
+    start: 6,
+    end: 11,
+  });
+});
+
+test("parseSpanOffsets: boundary offsets stay inside the string", () => {
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: 0, end: TEXT.length }, true), {
+    text: TEXT,
+    start: 0,
+    end: TEXT.length,
+  });
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: 0, end: 1 }, true), {
+    text: "A",
+    start: 0,
+    end: 1,
+  });
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: TEXT.length - 1, end: TEXT.length }, true), {
+    text: "e",
+    start: TEXT.length - 1,
+    end: TEXT.length,
+  });
+});
+
+test("parseSpanOffsets: reversed and out-of-range offsets reject", () => {
+  assert.throws(() => parseSpanOffsets(TEXT, { start: 12, end: 6 }, true), /reversed|out of range|invalid span/i);
+  assert.throws(() => parseSpanOffsets(TEXT, { start: -1, end: 6 }, true), /out of range|invalid span/i);
+  assert.throws(() => parseSpanOffsets(TEXT, { start: 0, end: TEXT.length + 1 }, true), /out of range|invalid span/i);
+});
+
+test("parseSpanOffsets: empty source and empty span", () => {
+  assert.deepEqual(parseSpanOffsets("", { start: 0, end: 0 }, false), { text: "" });
+  assert.deepEqual(parseSpanOffsets("", { start: 0, end: 0 }, true), {
+    text: "",
+    start: 0,
+    end: 0,
+  });
+  assert.deepEqual(parseSpanOffsets(TEXT, { start: 6, end: 6 }, true), {
+    text: "",
+    start: 6,
+    end: 6,
+  });
+  assert.throws(() => parseSpanOffsets("", { start: 0, end: 1 }, true), /out of range|invalid span/i);
+});