@remnic/core 9.66.2 → 9.66.3

package/src/activity/heading-level.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseAtxHeadingLevel } from "./heading-level.js";
+
+test("h1 is level 1", () => {
+  assert.deepEqual(parseAtxHeadingLevel("# Title"), { ok: true, level: 1 });
+});
+
+test("h6 is level 6", () => {
+  assert.deepEqual(parseAtxHeadingLevel("###### Title"), { ok: true, level: 6 });
+});
+
+test("no hashes is not_heading", () => {
+  assert.deepEqual(parseAtxHeadingLevel("Title"), { ok: false, error: "not_heading" });
+});
+
+test("seven hashes is invalid_level", () => {
+  assert.deepEqual(parseAtxHeadingLevel("####### Title"), {
+    ok: false,
+    error: "invalid_level",
+  });
+});

package/src/activity/heading-level.ts

@@ -0,0 +1,21 @@
+/**
+ * Parse an ATX heading level (issue #1987 leftover).
+ *
+ * Trim, then walk leading `#` chars. 1-6 is a heading. No hashes is
+ * not_heading. Seven or more is invalid_level. No regex.
+ */
+
+export type ParseAtxHeadingLevelResult =
+  | { ok: true; level: number }
+  | { ok: false; error: "not_heading" | "invalid_level" };
+
+export function parseAtxHeadingLevel(line: string): ParseAtxHeadingLevelResult {
+  const trimmed = line.trim();
+  let level = 0;
+  while (level < trimmed.length && trimmed[level] === "#") {
+    level++;
+  }
+  if (level === 0) return { ok: false, error: "not_heading" };
+  if (level > 6) return { ok: false, error: "invalid_level" };
+  return { ok: true, level };
+}

package/src/activity/heading-title.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseAtxHeadingTitle } from "./heading-title.js";
+
+test("parseAtxHeadingTitle returns the title", () => {
+  assert.deepEqual(parseAtxHeadingTitle("## Journal"), { ok: true, title: "Journal" });
+  assert.deepEqual(parseAtxHeadingTitle("  # Title  "), { ok: true, title: "Title" });
+  assert.deepEqual(parseAtxHeadingTitle("###### Deep"), { ok: true, title: "Deep" });
+});
+
+test("parseAtxHeadingTitle rejects an empty title", () => {
+  assert.deepEqual(parseAtxHeadingTitle("#"), { ok: false, error: "empty_title" });
+  assert.deepEqual(parseAtxHeadingTitle("##   "), { ok: false, error: "empty_title" });
+});
+
+test("parseAtxHeadingTitle rejects a non-heading", () => {
+  assert.deepEqual(parseAtxHeadingTitle("Journal"), { ok: false, error: "not_heading" });
+  assert.deepEqual(parseAtxHeadingTitle("#Title"), { ok: false, error: "not_heading" });
+  assert.deepEqual(parseAtxHeadingTitle("####### Too many"), { ok: false, error: "not_heading" });
+});

package/src/activity/heading-title.ts

@@ -0,0 +1,26 @@
+/**
+ * Parse an ATX heading title (issue #1987 leftover).
+ *
+ * Trim, then walk 1-6 leading `#` plus one space. Empty title is
+ * empty_title. Anything else is not_heading. Walk chars. No regex.
+ */
+
+export type ParseAtxHeadingTitleResult =
+  | { ok: true; title: string }
+  | { ok: false; error: "empty_title" | "not_heading" };
+
+export function parseAtxHeadingTitle(line: string): ParseAtxHeadingTitleResult {
+  const trimmed = line.trim();
+  let i = 0;
+  while (i < trimmed.length && trimmed[i] === "#") {
+    i++;
+  }
+  if (i < 1 || i > 6) return { ok: false, error: "not_heading" };
+  if (i < trimmed.length && trimmed[i] !== " ") {
+    return { ok: false, error: "not_heading" };
+  }
+  if (i < trimmed.length) i++;
+  const title = trimmed.slice(i);
+  if (title.length === 0) return { ok: false, error: "empty_title" };
+  return { ok: true, title };
+}

package/src/activity/index.ts

@@ -19,5 +19,11 @@ export * from "./journal.js";
 export * from "./journal-vault-read.js";
 export * from "./memory-gen.js";
 export * from "./privacy.js";
+export * from "./privacy-window.js";
 export * from "./vault-path.js";
 export * from "./vault-publish.js";
+export * from "./vault-frontmatter.js";
+export * from "./vault-wikilink.js";
+export * from "./vault-region.js";
+export * from "./vault-suffix.js";
+export * from "./vault-join.js";

package/src/activity/journal-heading.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { normalizeJournalHeading } from "./journal-heading.js";
+
+test("normalizeJournalHeading accepts a heading", () => {
+  assert.deepEqual(normalizeJournalHeading("Journal"), { ok: true, heading: "Journal" });
+});
+
+test("normalizeJournalHeading rejects an empty heading", () => {
+  assert.deepEqual(normalizeJournalHeading(""), { ok: false, error: "empty_heading" });
+  assert.deepEqual(normalizeJournalHeading("   "), { ok: false, error: "empty_heading" });
+});
+
+test("normalizeJournalHeading rejects a heading with a newline", () => {
+  assert.deepEqual(normalizeJournalHeading("Jour\nnal"), { ok: false, error: "invalid_heading" });
+  assert.deepEqual(normalizeJournalHeading("Jour\rnal"), { ok: false, error: "invalid_heading" });
+});
+
+test("normalizeJournalHeading trims surrounding whitespace", () => {
+  assert.deepEqual(normalizeJournalHeading("  Journal  "), { ok: true, heading: "Journal" });
+});

package/src/activity/journal-heading.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalize a journal section heading (issue #1987 leftover).
+ *
+ * Trim. Empty is empty_heading. Newline is invalid_heading.
+ */
+
+export type NormalizeJournalHeadingResult =
+  | { ok: true; heading: string }
+  | { ok: false; error: "empty_heading" | "invalid_heading" };
+
+export function normalizeJournalHeading(value: string): NormalizeJournalHeadingResult {
+  const heading = value.trim();
+  if (heading.length === 0) return { ok: false, error: "empty_heading" };
+  if (heading.includes("\n") || heading.includes("\r")) {
+    return { ok: false, error: "invalid_heading" };
+  }
+  return { ok: true, heading };
+}

package/src/activity/journal-mode.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseJournalMode } from "./journal-mode.js";
+
+test("file is allowed", () => {
+  assert.deepEqual(parseJournalMode("file"), {
+    ok: true,
+    mode: "file",
+  });
+});
+
+test("vault is allowed", () => {
+  assert.deepEqual(parseJournalMode("vault"), {
+    ok: true,
+    mode: "vault",
+  });
+});
+
+test("unknown mode is unknown_mode", () => {
+  assert.deepEqual(parseJournalMode("memoryDir"), {
+    ok: false,
+    error: "unknown_mode",
+  });
+});
+
+test("empty mode is unknown_mode", () => {
+  assert.deepEqual(parseJournalMode(""), {
+    ok: false,
+    error: "unknown_mode",
+  });
+});

package/src/activity/journal-mode.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse journal mode (issue #1987 leftover).
+ *
+ * Pure. Surfaces wait. Allow file or vault. Unknown or empty is unknown_mode.
+ */
+
+const JOURNAL_MODES = ["file", "vault"] as const;
+
+export type JournalMode = (typeof JOURNAL_MODES)[number];
+
+export type ParseJournalModeResult =
+  | { ok: true; mode: JournalMode }
+  | { ok: false; error: "unknown_mode" };
+
+export function parseJournalMode(value: string): ParseJournalModeResult {
+  if ((JOURNAL_MODES as readonly string[]).includes(value)) {
+    return { ok: true, mode: value as JournalMode };
+  }
+  return { ok: false, error: "unknown_mode" };
+}

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

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseJournalFilePath } from "./journal-path.js";
+
+test("parseJournalFilePath accepts a relative path", () => {
+  assert.deepEqual(parseJournalFilePath("journal/2026-08-19.md"), {
+    ok: true,
+    path: "journal/2026-08-19.md",
+  });
+  assert.deepEqual(parseJournalFilePath("  notes/today.md  "), {
+    ok: true,
+    path: "notes/today.md",
+  });
+});
+
+test("parseJournalFilePath rejects an empty path", () => {
+  assert.deepEqual(parseJournalFilePath(""), { ok: false, error: "missing_path" });
+  assert.deepEqual(parseJournalFilePath("   "), { ok: false, error: "missing_path" });
+});
+
+test("parseJournalFilePath rejects ..", () => {
+  assert.deepEqual(parseJournalFilePath("../secret"), { ok: false, error: "invalid_path" });
+  assert.deepEqual(parseJournalFilePath("foo/../bar"), { ok: false, error: "invalid_path" });
+});

package/src/activity/journal-path.ts

@@ -0,0 +1,27 @@
+/**
+ * Parse a journal file path (issue #1987 leftover).
+ *
+ * Trim. Empty is missing_path. Absolute, `..`, backslash, or newline
+ * is invalid_path.
+ */
+import { posix, win32 } from "node:path";
+
+export type ParseJournalFilePathResult =
+  | { ok: true; path: string }
+  | { ok: false; error: "missing_path" | "invalid_path" };
+
+export function parseJournalFilePath(value: string): ParseJournalFilePathResult {
+  const journalPath = value.trim();
+  if (journalPath.length === 0) return { ok: false, error: "missing_path" };
+  if (
+    journalPath.includes("\\") ||
+    journalPath.includes("\n") ||
+    journalPath.includes("\r") ||
+    posix.isAbsolute(journalPath) ||
+    win32.isAbsolute(journalPath) ||
+    journalPath.split("/").includes("..")
+  ) {
+    return { ok: false, error: "invalid_path" };
+  }
+  return { ok: true, path: journalPath };
+}

package/src/activity/journal-section.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { extractJournalSection } from "./journal-section.js";
+
+test("extractJournalSection returns null when the heading is missing", () => {
+  const markdown = ["# Day", "## Notes", "cards", ""].join("\n");
+  assert.equal(extractJournalSection(markdown, "Journal"), null);
+});
+
+test("extractJournalSection returns the unique heading body until the next same-or-higher heading", () => {
+  const markdown = [
+    "# Day",
+    "## Journal",
+    "walked the dog",
+    "### Nested",
+    "still journal",
+    "## Notes",
+    "not journal",
+    "",
+  ].join("\n");
+  assert.equal(
+    extractJournalSection(markdown, "Journal"),
+    ["walked the dog", "### Nested", "still journal"].join("\n"),
+  );
+});
+
+test("extractJournalSection refuses a duplicate heading", () => {
+  const markdown = ["# Day", "## Journal", "first", "## Notes", "## Journal", "second", ""].join("\n");
+  assert.deepEqual(extractJournalSection(markdown, "Journal"), { error: "duplicate_heading" });
+});
+
+test("extractJournalSection rejects an empty heading", () => {
+  const markdown = ["## Journal", "hi", ""].join("\n");
+  assert.deepEqual(extractJournalSection(markdown, ""), { error: "empty_heading" });
+  assert.deepEqual(extractJournalSection(markdown, "   "), { error: "empty_heading" });
+});

package/src/activity/journal-section.ts

@@ -0,0 +1,75 @@
+/**
+ * Extract a unique ATX heading section (issue #1987).
+ *
+ * Pure string helper. No filesystem. Missing heading returns null.
+ * Duplicate headings refuse. Empty headings are rejected.
+ */
+
+export type ExtractJournalSectionResult =
+  | string
+  | null
+  | { error: "duplicate_heading" }
+  | { error: "empty_heading" };
+
+export function extractJournalSection(
+  markdown: string,
+  heading: string,
+): ExtractJournalSectionResult {
+  const wanted = heading.trim();
+  if (wanted.length === 0) return { error: "empty_heading" };
+
+  const lines = splitFileLines(markdown);
+  const hits: number[] = [];
+  const levels: number[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const parsed = parseAtxHeading(lines[i]!);
+    if (parsed && parsed.text === wanted) {
+      hits.push(i);
+      levels.push(parsed.level);
+    }
+  }
+  if (hits.length === 0) return null;
+  if (hits.length > 1) return { error: "duplicate_heading" };
+
+  const headingIndex = hits[0]!;
+  const level = levels[0]!;
+  let endIndex = lines.length;
+  for (let i = headingIndex + 1; i < lines.length; i++) {
+    const parsed = parseAtxHeading(lines[i]!);
+    if (parsed && parsed.level <= level) {
+      endIndex = i;
+      break;
+    }
+  }
+  return lines.slice(headingIndex + 1, endIndex).join("\n");
+}
+
+function splitFileLines(fileText: string): string[] {
+  const lines = fileText.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.endsWith("\r")) lines[i] = line.slice(0, -1);
+  }
+  return lines;
+}
+
+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) };
+}

package/src/activity/journal-source.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resolveJournalSource } from "./journal-source.js";
+
+test("source file resolves to file mode", () => {
+  assert.deepEqual(resolveJournalSource({ source: "file", heading: "" }), {
+    ok: true,
+    mode: "file",
+  });
+});
+
+test("source vault with a heading resolves to vault mode", () => {
+  assert.deepEqual(resolveJournalSource({ source: "vault", heading: "Journal" }), {
+    ok: true,
+    mode: "vault",
+    heading: "Journal",
+  });
+});
+
+test("source vault with an empty heading is missing_heading", () => {
+  assert.deepEqual(resolveJournalSource({ source: "vault", heading: "" }), {
+    ok: false,
+    error: "missing_heading",
+  });
+  assert.deepEqual(resolveJournalSource({ source: "vault", heading: "   " }), {
+    ok: false,
+    error: "missing_heading",
+  });
+});
+
+test("unknown source is unknown_source", () => {
+  assert.deepEqual(resolveJournalSource({ source: "memoryDir", heading: "Journal" }), {
+    ok: false,
+    error: "unknown_source",
+  });
+});

package/src/activity/journal-source.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve journal source mode (issue #1987 leftover).
+ *
+ * Pure. File mode ignores heading. Vault mode needs a non-empty heading.
+ */
+
+export type JournalSourceResult =
+  | { ok: true; mode: "file" }
+  | { ok: true; mode: "vault"; heading: string }
+  | { ok: false; error: "missing_heading" | "unknown_source" };
+
+export function resolveJournalSource(input: {
+  source: string;
+  heading: string;
+}): JournalSourceResult {
+  if (input.source === "file") return { ok: true, mode: "file" };
+  if (input.source === "vault") {
+    const heading = input.heading.trim();
+    if (heading.length === 0) return { ok: false, error: "missing_heading" };
+    return { ok: true, mode: "vault", heading };
+  }
+  return { ok: false, error: "unknown_source" };
+}

package/src/activity/privacy-enabled.test.ts

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parsePrivacyEnabled } from "./privacy-enabled.js";
+
+test("boolean passthrough returns enabled", () => {
+  assert.deepEqual(parsePrivacyEnabled(true), { ok: true, enabled: true });
+  assert.deepEqual(parsePrivacyEnabled(false), { ok: true, enabled: false });
+});
+
+test("string false tokens return enabled false", () => {
+  assert.deepEqual(parsePrivacyEnabled("false"), { ok: true, enabled: false });
+  assert.deepEqual(parsePrivacyEnabled("0"), { ok: true, enabled: false });
+  assert.deepEqual(parsePrivacyEnabled("no"), { ok: true, enabled: false });
+  assert.deepEqual(parsePrivacyEnabled("off"), { ok: true, enabled: false });
+});
+
+test("string true tokens return enabled true", () => {
+  assert.deepEqual(parsePrivacyEnabled("true"), { ok: true, enabled: true });
+  assert.deepEqual(parsePrivacyEnabled("1"), { ok: true, enabled: true });
+  assert.deepEqual(parsePrivacyEnabled("yes"), { ok: true, enabled: true });
+  assert.deepEqual(parsePrivacyEnabled("on"), { ok: true, enabled: true });
+});
+
+test("unknown values are invalid_enabled", () => {
+  assert.deepEqual(parsePrivacyEnabled("maybe"), { ok: false, error: "invalid_enabled" });
+  assert.deepEqual(parsePrivacyEnabled(2), { ok: false, error: "invalid_enabled" });
+  assert.deepEqual(parsePrivacyEnabled(null), { ok: false, error: "invalid_enabled" });
+  assert.deepEqual(parsePrivacyEnabled({}), { ok: false, error: "invalid_enabled" });
+});

package/src/activity/privacy-enabled.ts

@@ -0,0 +1,33 @@
+/**
+ * Parse the activity privacy enabled flag (issue #2053 leftover).
+ *
+ * Boolean passthrough. String tokens true/1/yes/on and false/0/no/off.
+ * Unknown values fail closed as invalid_enabled.
+ */
+
+export type ParsePrivacyEnabledResult =
+  | { ok: true; enabled: boolean }
+  | { ok: false; error: "invalid_enabled" };
+
+const ENABLED_TOKENS: Record<string, boolean> = {
+  true: true,
+  "1": true,
+  yes: true,
+  on: true,
+  false: false,
+  "0": false,
+  no: false,
+  off: false,
+};
+
+/** Accept a boolean or known token. Unknown values are invalid_enabled. */
+export function parsePrivacyEnabled(value: unknown): ParsePrivacyEnabledResult {
+  if (typeof value === "boolean") return { ok: true, enabled: value };
+  if (typeof value === "string") {
+    const token = value.trim().toLowerCase();
+    if (Object.hasOwn(ENABLED_TOKENS, token)) {
+      return { ok: true, enabled: ENABLED_TOKENS[token] };
+    }
+  }
+  return { ok: false, error: "invalid_enabled" };
+}

package/src/activity/privacy-keys.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { normalizeDropKeys } from "./privacy-keys.js";
+
+test("empty keys return []", () => {
+  assert.deepEqual(normalizeDropKeys([]), []);
+});
+
+test("trims keys and drops empty", () => {
+  assert.deepEqual(normalizeDropKeys(["  secret  ", "", "  ", "title"]), ["secret", "title"]);
+});
+
+test("unique keys sort by localeCompare", () => {
+  assert.deepEqual(normalizeDropKeys(["zeta", "alpha", "zeta", "beta"]), ["alpha", "beta", "zeta"]);
+});
+
+test("does not mutate the input list", () => {
+  const keys = ["  zeta  ", "alpha", "alpha"];
+  normalizeDropKeys(keys);
+  assert.deepEqual(keys, ["  zeta  ", "alpha", "alpha"]);
+});

package/src/activity/privacy-keys.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalize activity privacy drop keys (issue #2053).
+ *
+ * Trim, drop empty, unique, localeCompare sort.
+ * Does not mutate the input list.
+ */
+
+export function normalizeDropKeys(keys: readonly string[]): string[] {
+  const unique = [...new Set(keys.map((key) => key.trim()).filter((key) => key.length > 0))];
+  unique.sort((a, b) => a.localeCompare(b));
+  return unique;
+}

package/src/activity/privacy-redact.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { redactActivityFields } from "./privacy-redact.js";
+
+test("drops listed keys and ignores unknown keys", () => {
+  const item = { id: "a", title: "kept", secret: "drop-me" };
+  const redacted = redactActivityFields(item, {
+    dropKeys: ["secret", "missing"],
+  });
+  assert.deepEqual(redacted, { id: "a", title: "kept" });
+});
+
+test("does not mutate the input item", () => {
+  const item = { id: "a", secret: "drop-me" };
+  redactActivityFields(item, { dropKeys: ["secret"] });
+  assert.deepEqual(item, { id: "a", secret: "drop-me" });
+});
+
+test("empty dropKeys returns a shallow copy", () => {
+  const item = { id: "a", title: "kept" };
+  const redacted = redactActivityFields(item, { dropKeys: [] });
+  assert.deepEqual(redacted, item);
+  assert.notEqual(redacted, item);
+});

package/src/activity/privacy-redact.ts

@@ -0,0 +1,23 @@
+/**
+ * Drop listed keys from one activity item (issue #2053).
+ */
+
+export interface ActivityRedactOptions {
+  dropKeys: readonly string[];
+}
+
+/**
+ * Return a shallow copy without `dropKeys`.
+ * Unknown keys are ignored. Empty `dropKeys` is a shallow copy.
+ * Does not mutate `item`.
+ */
+export function redactActivityFields<T extends Record<string, unknown>>(
+  item: T,
+  options: ActivityRedactOptions,
+): T {
+  const result: Record<string, unknown> = { ...item };
+  for (const key of options.dropKeys) {
+    delete result[key];
+  }
+  return result as T;
+}

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

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MS_PER_DAY } from "./privacy.js";
+import { filterPrivacyWindow } from "./privacy-window.js";
+
+function item(capturedAtMs: number, id = capturedAtMs) {
+  return { id, capturedAtMs };
+}
+
+test("window is half-open [fromMs, toMs)", () => {
+  const fromMs = 1_000;
+  const toMs = 2_000;
+  const kept = filterPrivacyWindow(
+    [item(fromMs - 1), item(fromMs), item(toMs - 1), item(toMs)],
+    { fromMs, toMs, retainDays: 0 },
+  );
+  assert.deepEqual(
+    kept.map((entry) => entry.capturedAtMs),
+    [fromMs, toMs - 1],
+  );
+});
+
+test("retainDays 0 keeps all ages inside the window", () => {
+  const toMs = 400 * MS_PER_DAY;
+  const old = item(toMs - 390 * MS_PER_DAY, 1);
+  const kept = filterPrivacyWindow([old], { fromMs: 0, toMs, retainDays: 0 });
+  assert.deepEqual(kept, [old]);
+});
+
+test("retainDays N drops older than N days before toMs", () => {
+  const toMs = 10 * MS_PER_DAY;
+  const fromMs = 0;
+  const cutoff = toMs - 3 * MS_PER_DAY;
+  const kept = filterPrivacyWindow(
+    [item(cutoff - 1, 1), item(cutoff, 2), item(cutoff + 1, 3), item(toMs - 1, 4)],
+    { fromMs, toMs, retainDays: 3 },
+  );
+  assert.deepEqual(
+    kept.map((entry) => entry.id),
+    [3, 4],
+  );
+});
+
+test("empty items or inverted window return []", () => {
+  assert.deepEqual(filterPrivacyWindow([], { fromMs: 0, toMs: 10, retainDays: 0 }), []);
+  assert.deepEqual(filterPrivacyWindow([item(5)], { fromMs: 10, toMs: 10, retainDays: 0 }), []);
+  assert.deepEqual(filterPrivacyWindow([item(5)], { fromMs: 10, toMs: 0, retainDays: 0 }), []);
+});

package/src/activity/privacy-window.ts

@@ -0,0 +1,32 @@
+/**
+ * Half-open activity privacy window (issue #2053).
+ */
+import { shouldRetain } from "./privacy.js";
+
+export interface PrivacyWindowItem {
+  capturedAtMs: number;
+}
+
+export interface PrivacyWindowOptions {
+  fromMs: number;
+  toMs: number;
+  retainDays: number;
+}
+
+/**
+ * Keep items in `[fromMs, toMs)`.
+ * `retainDays` 0 keeps all ages. `retainDays` N drops older than N days before `toMs`.
+ * `toMs <= fromMs` returns `[]`.
+ */
+export function filterPrivacyWindow<T extends PrivacyWindowItem>(
+  items: readonly T[],
+  options: PrivacyWindowOptions,
+): T[] {
+  const { fromMs, toMs, retainDays } = options;
+  if (toMs <= fromMs) return [];
+  return items.filter((item) => {
+    const capturedAtMs = item.capturedAtMs;
+    if (capturedAtMs < fromMs || capturedAtMs >= toMs) return false;
+    return shouldRetain(capturedAtMs, toMs, retainDays);
+  });
+}