@remnic/core 9.66.1 → 9.66.3

package/src/activity/vault-name-trim.ts

@@ -0,0 +1,16 @@
+/**
+ * Trim a managed-region name (issue #1985).
+ *
+ * Empty after trim throws. Newline throws. Else the trimmed string.
+ */
+
+export function trimRegionName(value: string): string {
+  const name = value.trim();
+  if (name.length === 0) {
+    throw new RangeError("Region name must be non-empty.");
+  }
+  if (name.includes("\n") || name.includes("\r")) {
+    throw new RangeError("Region name must not contain a newline.");
+  }
+  return name;
+}

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

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { assertBeginEndPair } from "./vault-region-pair.js";
+
+test("assertBeginEndPair accepts a matching pair", () => {
+  assert.deepEqual(assertBeginEndPair({ beginName: "timeline", endName: "timeline" }), { ok: true });
+  assert.deepEqual(assertBeginEndPair({ beginName: "  timeline  ", endName: "timeline" }), {
+    ok: true,
+  });
+  assert.deepEqual(assertBeginEndPair({ beginName: "timeline", endName: "  timeline  " }), {
+    ok: true,
+  });
+});
+
+test("assertBeginEndPair rejects a name mismatch", () => {
+  assert.deepEqual(assertBeginEndPair({ beginName: "timeline", endName: "weekly" }), {
+    ok: false,
+    error: "name_mismatch",
+  });
+});
+
+test("assertBeginEndPair throws on an empty name", () => {
+  assert.throws(() => assertBeginEndPair({ beginName: "", endName: "timeline" }), /empty/i);
+  assert.throws(() => assertBeginEndPair({ beginName: "timeline", endName: "   " }), /empty/i);
+});

package/src/activity/vault-region-pair.ts

@@ -0,0 +1,24 @@
+/**
+ * Assert a managed-region begin/end name pair (issue #1985).
+ *
+ * Trim both names. Empty throws. Mismatch is name_mismatch. Else ok.
+ */
+
+export type BeginEndPairInput = {
+  beginName: string;
+  endName: string;
+};
+
+export type BeginEndPairResult = { ok: true } | { ok: false; error: "name_mismatch" };
+
+export function assertBeginEndPair({ beginName, endName }: BeginEndPairInput): BeginEndPairResult {
+  const begin = beginName.trim();
+  const end = endName.trim();
+  if (begin.length === 0 || end.length === 0) {
+    throw new RangeError("Region name must be non-empty.");
+  }
+  if (begin !== end) {
+    return { ok: false, error: "name_mismatch" };
+  }
+  return { ok: true };
+}

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

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { validateRegionName } from "./vault-region.js";
+
+test("validateRegionName trims a valid name", () => {
+  assert.deepEqual(validateRegionName("timeline"), { ok: true, name: "timeline" });
+  assert.deepEqual(validateRegionName("  weekly  "), { ok: true, name: "weekly" });
+});
+
+test("validateRegionName rejects empty and whitespace-only names", () => {
+  assert.deepEqual(validateRegionName(""), { ok: false, error: "invalid_name" });
+  assert.deepEqual(validateRegionName("   "), { ok: false, error: "invalid_name" });
+});
+
+test("validateRegionName rejects names with newlines", () => {
+  assert.deepEqual(validateRegionName("time\nline"), { ok: false, error: "invalid_name" });
+  assert.deepEqual(validateRegionName("time\rline"), { ok: false, error: "invalid_name" });
+});
+
+test("validateRegionName rejects the HTML comment closer", () => {
+  assert.deepEqual(validateRegionName("foo-->bar"), { ok: false, error: "invalid_name" });
+  assert.deepEqual(validateRegionName("timeline-->"), { ok: false, error: "invalid_name" });
+});

package/src/activity/vault-region.ts

@@ -0,0 +1,24 @@
+/**
+ * Validate a managed-region name for vault markers (issue #1985).
+ *
+ * Empty, whitespace-only, newline, and `-->` names are rejected so they
+ * cannot break `<!-- remnic:<name>:start -->` markers.
+ */
+
+export type ValidateRegionNameResult =
+  | { ok: true; name: string }
+  | { ok: false; error: "invalid_name" };
+
+export function validateRegionName(name: string): ValidateRegionNameResult {
+  if (typeof name !== "string") {
+    return { ok: false, error: "invalid_name" };
+  }
+  if (name.includes("\n") || name.includes("\r") || name.includes("-->")) {
+    return { ok: false, error: "invalid_name" };
+  }
+  const trimmed = name.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, error: "invalid_name" };
+  }
+  return { ok: true, name: trimmed };
+}

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

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { stripVaultMdSuffix } from "./vault-suffix.js";
+
+test("stripVaultMdSuffix drops a trailing .md", () => {
+  assert.equal(stripVaultMdSuffix("Daily Notes/2026-08-18.md"), "Daily Notes/2026-08-18");
+});
+
+test("stripVaultMdSuffix leaves a path with no suffix unchanged", () => {
+  assert.equal(stripVaultMdSuffix("Daily Notes/2026-08-18"), "Daily Notes/2026-08-18");
+});
+
+test("stripVaultMdSuffix throws on empty input", () => {
+  assert.throws(() => stripVaultMdSuffix(""), /empty/i);
+});
+
+test("stripVaultMdSuffix does not strip .markdown", () => {
+  assert.equal(stripVaultMdSuffix("Daily Notes/2026-08-18.markdown"), "Daily Notes/2026-08-18.markdown");
+});

package/src/activity/vault-suffix.ts

@@ -0,0 +1,12 @@
+/**
+ * Strip a trailing `.md` suffix from a vault note path (issue #1985).
+ *
+ * Case-sensitive. Does not strip `.markdown`. Empty input is rejected.
+ */
+
+export function stripVaultMdSuffix(notePath: string): string {
+  if (typeof notePath !== "string" || notePath.length === 0) {
+    throw new RangeError("Vault path must be non-empty.");
+  }
+  return notePath.endsWith(".md") ? notePath.slice(0, -3) : notePath;
+}

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

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { formatVaultWikilink } from "./vault-wikilink.js";
+
+test("formatVaultWikilink returns a wikilink without the .md suffix", () => {
+  assert.equal(formatVaultWikilink("Daily Notes/2026-08-18.md"), "[[Daily Notes/2026-08-18]]");
+  assert.equal(formatVaultWikilink("Places/ACME Office"), "[[Places/ACME Office]]");
+});
+
+test("formatVaultWikilink rejects absolute paths", () => {
+  assert.throws(() => formatVaultWikilink("/abs/note.md"), /absolute/i);
+  assert.throws(() => formatVaultWikilink("C:/vault/note.md"), /absolute/i);
+});
+
+test("formatVaultWikilink rejects parent segments", () => {
+  assert.throws(() => formatVaultWikilink("../outside.md"), /\.\./);
+  assert.throws(() => formatVaultWikilink("notes/../../secret.md"), /\.\./);
+});
+
+test("formatVaultWikilink rejects empty and newline paths", () => {
+  assert.throws(() => formatVaultWikilink(""), /empty/i);
+  assert.throws(() => formatVaultWikilink("   "), /empty/i);
+  assert.throws(() => formatVaultWikilink(".md"), /empty/i);
+  assert.throws(() => formatVaultWikilink("foo\nbar.md"), /newline/i);
+  assert.throws(() => formatVaultWikilink("foo\rbar.md"), /newline/i);
+});

package/src/activity/vault-wikilink.ts

@@ -0,0 +1,28 @@
+/**
+ * Format a vault-relative note path as an Obsidian wikilink (issue #1985).
+ *
+ * Relative paths only. Rejects absolute paths, `..` segments, empty input,
+ * and newlines. Strips a trailing `.md` suffix.
+ */
+import path from "node:path";
+
+export function formatVaultWikilink(notePath: string): string {
+  if (typeof notePath !== "string" || notePath.trim().length === 0) {
+    throw new RangeError("Vault wikilink path must be a non-empty relative path.");
+  }
+  if (notePath.includes("\n") || notePath.includes("\r")) {
+    throw new RangeError("Vault wikilink path must not contain newlines.");
+  }
+  if (path.posix.isAbsolute(notePath) || path.win32.isAbsolute(notePath)) {
+    throw new RangeError("Vault wikilink path must be relative; absolute paths are rejected.");
+  }
+  if (notePath.split(/[\\/]/).some((segment) => segment === "..")) {
+    throw new RangeError("Vault wikilink path must not contain `..` segments.");
+  }
+
+  const stripped = notePath.endsWith(".md") ? notePath.slice(0, -3) : notePath;
+  if (stripped.length === 0) {
+    throw new RangeError("Vault wikilink path must be a non-empty relative path.");
+  }
+  return `[[${stripped}]]`;
+}

package/src/activity/window-order.test.ts

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { assertHalfOpenWindow } from "./window-order.js";
+
+test("ordered window is ok", () => {
+  assert.deepEqual(assertHalfOpenWindow({ fromMs: 0, toMs: 1 }), { ok: true });
+});
+
+test("equal bounds are empty_window", () => {
+  assert.deepEqual(assertHalfOpenWindow({ fromMs: 10, toMs: 10 }), {
+    ok: false,
+    error: "empty_window",
+  });
+});
+
+test("inverted bounds are empty_window", () => {
+  assert.deepEqual(assertHalfOpenWindow({ fromMs: 20, toMs: 10 }), {
+    ok: false,
+    error: "empty_window",
+  });
+});
+
+test("NaN bounds throw", () => {
+  assert.throws(() => assertHalfOpenWindow({ fromMs: Number.NaN, toMs: 1 }), /finite/);
+  assert.throws(() => assertHalfOpenWindow({ fromMs: 0, toMs: Number.NaN }), /finite/);
+});

package/src/activity/window-order.ts

@@ -0,0 +1,24 @@
+/**
+ * Assert a half-open activity window [fromMs, toMs) (issue #2053 leftover).
+ *
+ * Non-finite bounds throw. `toMs <= fromMs` is empty_window.
+ */
+
+export type AssertHalfOpenWindowResult =
+  | { ok: true }
+  | { ok: false; error: "empty_window" };
+
+/** Validate `[fromMs, toMs)`. Empty or inverted windows fail closed. */
+export function assertHalfOpenWindow(window: {
+  fromMs: number;
+  toMs: number;
+}): AssertHalfOpenWindowResult {
+  const { fromMs, toMs } = window;
+  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) {
+    throw new RangeError(
+      `activity window bounds must be finite; got fromMs=${fromMs} toMs=${toMs}`,
+    );
+  }
+  if (toMs <= fromMs) return { ok: false, error: "empty_window" };
+  return { ok: true };
+}

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

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { countMergeCandidates } from "./merge-count.js";
+
+test("empty list is 0", () => {
+  assert.equal(countMergeCandidates([]), 0);
+});
+
+test("counts unique ids", () => {
+  assert.equal(countMergeCandidates(["alpha", "beta", "alpha"]), 2);
+  assert.equal(countMergeCandidates(["alpha", "beta", "gamma"]), 3);
+});
+
+test("drops empty strings and does not mutate", () => {
+  const ids = ["alpha", "", "beta", "", "alpha"];
+  assert.equal(countMergeCandidates(ids), 2);
+  assert.deepEqual(ids, ["alpha", "", "beta", "", "alpha"]);
+});

package/src/dedup/merge-count.ts

@@ -0,0 +1,13 @@
+/**
+ * Merge-candidate counter (issue #2330 leftover).
+ *
+ * Unique ids after dropping empty strings. Does not mutate input.
+ */
+
+export function countMergeCandidates(ids: readonly string[]): number {
+  const unique = new Set<string>();
+  for (const id of ids) {
+    if (id !== "") unique.add(id);
+  }
+  return unique.size;
+}