@remnic/core 9.66.0 → 9.66.2

package/src/activity/journal-vault-read.ts

@@ -0,0 +1,214 @@
+/**
+ * Read-only vault daily-note journal section (issue #1987 first slice).
+ *
+ * Pure: file text in, journal body out. Never writes. Strips Remnic-owned
+ * marker regions and publisher-owned headings so published timeline text
+ * cannot re-enter the journal. Path templates stay in vault-publish.
+ */
+
+export interface ReadVaultJournalInput {
+  fileText: string | null | undefined;
+  journalSection: string;
+  publishSectionNames?: readonly string[];
+}
+
+export type ReadVaultJournalResult =
+  | { ok: true; exists: false; reason: "missing_file" | "missing_heading" }
+  | { ok: true; exists: true; text: string; heading: string; warnings: readonly string[] }
+  | { ok: false; reason: "duplicate_heading"; lines: readonly number[] };
+
+const REMNIC_OPEN = "<!-- remnic:";
+
+export function readVaultJournal(input: ReadVaultJournalInput): ReadVaultJournalResult {
+  if (input.fileText === null || input.fileText === undefined) {
+    return { ok: true, exists: false, reason: "missing_file" };
+  }
+  if (input.journalSection.length === 0) {
+    return { ok: true, exists: false, reason: "missing_heading" };
+  }
+
+  const lines = splitFileLines(input.fileText);
+  const hits: number[] = [];
+  const levels: number[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const heading = parseAtxHeading(lines[i]!);
+    if (heading && heading.text === input.journalSection) {
+      hits.push(i + 1);
+      levels.push(heading.level);
+    }
+  }
+  if (hits.length === 0) return { ok: true, exists: false, reason: "missing_heading" };
+  if (hits.length > 1) return { ok: false, reason: "duplicate_heading", lines: hits };
+
+  const headingIndex = hits[0]! - 1;
+  const level = levels[0]!;
+  let endIndex = lines.length;
+  for (let i = headingIndex + 1; i < lines.length; i++) {
+    const heading = parseAtxHeading(lines[i]!);
+    if (heading && heading.level <= level) {
+      endIndex = i;
+      break;
+    }
+  }
+
+  const body = lines.slice(headingIndex + 1, endIndex).join("\n");
+  const stripped = stripRemnicOwnedRegions(body, input.publishSectionNames ?? []);
+  return {
+    ok: true,
+    exists: true,
+    text: trimNewlines(stripped.text),
+    heading: input.journalSection,
+    warnings: stripped.warnings,
+  };
+}
+
+/** Remove Remnic marker pairs and publisher-owned heading sections. */
+export function stripRemnicOwnedRegions(
+  text: string,
+  publishSectionNames: readonly string[] = [],
+): { text: string; warnings: readonly string[] } {
+  const marked = cutIntervals(text, remnicIntervals(text));
+  return {
+    text: stripPublishHeadings(marked.text, publishSectionNames),
+    warnings: marked.warnings,
+  };
+}
+
+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) };
+}
+
+function remnicIntervals(text: string): {
+  intervals: Array<{ start: number; end: number }>;
+  warnings: string[];
+} {
+  const starts: Array<{ name: string; start: number; after: number }> = [];
+  const ends: Array<{ name: string; start: number; end: number }> = [];
+
+  let from = 0;
+  while (from < text.length) {
+    const open = text.indexOf(REMNIC_OPEN, from);
+    if (open === -1) break;
+    const afterOpen = open + REMNIC_OPEN.length;
+    const commentEnd = text.indexOf("-->", afterOpen);
+    if (commentEnd === -1) break;
+    const inner = text.slice(afterOpen, commentEnd).trim();
+    if (inner.endsWith(":start")) {
+      const name = inner.slice(0, -":start".length);
+      if (name.length > 0) starts.push({ name, start: open, after: commentEnd + 3 });
+    } else if (inner.endsWith(":end")) {
+      const name = inner.slice(0, -":end".length);
+      if (name.length > 0) ends.push({ name, start: open, end: commentEnd + 3 });
+    }
+    from = commentEnd + 3;
+  }
+
+  const usedEnds = new Set<number>();
+  const intervals: Array<{ start: number; end: number }> = [];
+  const warnings: string[] = [];
+
+  for (const start of starts) {
+    const match = ends.find((end) => end.name === start.name && end.start >= start.after && !usedEnds.has(end.start));
+    if (match) {
+      usedEnds.add(match.start);
+      intervals.push({ start: start.start, end: eatTrailingNewline(text, match.end) });
+    } else {
+      intervals.push({ start: start.start, end: text.length });
+      warnings.push(`unclosed remnic region "${start.name}"`);
+    }
+  }
+
+  for (const end of ends) {
+    if (usedEnds.has(end.start)) continue;
+    const startBefore = starts.some((start) => start.start < end.start);
+    if (!startBefore) intervals.push({ start: 0, end: eatTrailingNewline(text, end.end) });
+  }
+
+  return { intervals: mergeIntervals(intervals), warnings };
+}
+
+function eatTrailingNewline(text: string, index: number): number {
+  if (text[index] === "\n") return index + 1;
+  if (text[index] === "\r" && text[index + 1] === "\n") return index + 2;
+  if (text[index] === "\r") return index + 1;
+  return index;
+}
+
+function mergeIntervals(items: Array<{ start: number; end: number }>): Array<{ start: number; end: number }> {
+  if (items.length === 0) return [];
+  const sorted = items.slice().sort((a, b) => a.start - b.start || a.end - b.end);
+  const out = [{ start: sorted[0]!.start, end: sorted[0]!.end }];
+  for (let i = 1; i < sorted.length; i++) {
+    const cur = sorted[i]!;
+    const last = out[out.length - 1]!;
+    if (cur.start <= last.end) last.end = Math.max(last.end, cur.end);
+    else out.push({ start: cur.start, end: cur.end });
+  }
+  return out;
+}
+
+function cutIntervals(
+  text: string,
+  found: { intervals: Array<{ start: number; end: number }>; warnings: string[] },
+): { text: string; warnings: string[] } {
+  let out = "";
+  let pos = 0;
+  for (const interval of found.intervals) {
+    if (interval.start > pos) out += text.slice(pos, interval.start);
+    pos = Math.max(pos, interval.end);
+  }
+  if (pos < text.length) out += text.slice(pos);
+  return { text: out, warnings: found.warnings };
+}
+
+function stripPublishHeadings(text: string, names: readonly string[]): string {
+  if (names.length === 0 || text.length === 0) return text;
+  const lines = text.split("\n");
+  const keep = lines.map(() => true);
+  for (let i = 0; i < lines.length; i++) {
+    if (!keep[i]) continue;
+    const heading = parseAtxHeading(lines[i]!);
+    if (!heading || !names.includes(heading.text)) continue;
+    keep[i] = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      const next = parseAtxHeading(lines[j]!);
+      if (next && next.level <= heading.level) break;
+      keep[j] = false;
+    }
+  }
+  return lines.filter((_, i) => keep[i]).join("\n");
+}
+
+function trimNewlines(text: string): string {
+  let start = 0;
+  let end = text.length;
+  while (start < end && (text[start] === "\n" || text[start] === "\r")) start++;
+  while (end > start && (text[end - 1] === "\n" || text[end - 1] === "\r")) end--;
+  return text.slice(start, end);
+}

package/src/activity/journal.test.ts

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { isSearchExcludedPath } from "../orchestration/generic-recall-paths.js";
+import { ALL_CATEGORY_DIRS, RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
+import { parseActivityConfig } from "./config.js";
+import { isJournalDayPath, journalPath, seedJournal } from "./journal.js";
+
+const DATE = "2026-08-17";
+
+function withMemoryDir(fn: (memoryDir: string) => void): void {
+  const memoryDir = mkdtempSync(path.join(tmpdir(), "remnic-journal-"));
+  try {
+    fn(memoryDir);
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+}
+
+test("activity.timeline.journal.enabled defaults off", () => {
+  assert.equal(parseActivityConfig(undefined).timeline.journal.enabled, false);
+  assert.equal(
+    parseActivityConfig({ timeline: { journal: { enabled: true } } }).timeline.journal.enabled,
+    true,
+  );
+  assert.throws(
+    () => parseActivityConfig({ timeline: { journal: "on" } }),
+    /activity\.timeline\.journal must be an object/,
+  );
+});
+
+test("seed is a hard no-op without force", () => {
+  withMemoryDir((memoryDir) => {
+    const first = seedJournal({
+      memoryDir,
+      date: DATE,
+      cards: [{ title: "Write seed", startUtc: "2026-08-17T14:00:00.000Z", endUtc: "2026-08-17T14:45:00.000Z" }],
+    });
+    assert.equal(first.wrote, true);
+    assert.equal(first.path, journalPath(memoryDir, DATE));
+    const original = readFileSync(first.path);
+    const second = seedJournal({
+      memoryDir,
+      date: DATE,
+      cards: [{ title: "Different card", startUtc: "2026-08-17T15:00:00.000Z", endUtc: "2026-08-17T16:00:00.000Z" }],
+    });
+    assert.equal(second.wrote, false);
+    assert.deepEqual(readFileSync(second.path), original);
+  });
+});
+
+test("seed with force overwrites the existing file", () => {
+  withMemoryDir((memoryDir) => {
+    seedJournal({ memoryDir, date: DATE });
+    const original = readFileSync(journalPath(memoryDir, DATE), "utf8");
+    const forced = seedJournal({
+      memoryDir,
+      date: DATE,
+      force: true,
+      cards: [{ title: "Forced rewrite", startUtc: "2026-08-17T10:00:00.000Z", endUtc: "2026-08-17T11:30:00.000Z" }],
+    });
+    assert.equal(forced.wrote, true);
+    const next = readFileSync(forced.path, "utf8");
+    assert.notEqual(next, original);
+    assert.match(next, /# Journal — 2026-08-17/);
+    assert.match(next, /## Day at a glance/);
+    assert.match(next, /- 90m Forced rewrite/);
+    assert.match(next, /## Notes/);
+  });
+});
+
+test("journal day files sit outside scan roots and generic search", () => {
+  assert.equal(ALL_CATEGORY_DIRS.includes("journal"), false);
+  assert.equal(RECALL_FALLBACK_DIRS.includes("journal"), false);
+  assert.equal(isJournalDayPath("journal/2026-08-17.md"), true);
+  assert.equal(
+    isJournalDayPath("facts/journal/2026-08-17.md", "/tmp/remnic-fixture-memory"),
+    false,
+    "nested stays recallable",
+  );
+  assert.equal(isSearchExcludedPath("journal/2026-08-17.md"), true);
+  assert.equal(
+    isSearchExcludedPath("facts/journal/2026-08-17.md", { memoryDir: "/tmp/remnic-fixture-memory" }),
+    false,
+  );
+
+  withMemoryDir((memoryDir) => {
+    const result = seedJournal({ memoryDir, date: DATE });
+    const relative = path.relative(memoryDir, result.path).replace(/\\/g, "/");
+    assert.equal(relative, "journal/2026-08-17.md");
+    assert.equal(isSearchExcludedPath(relative), true);
+    assert.equal(isSearchExcludedPath(result.path, { memoryDir }), true);
+  });
+});

package/src/activity/journal.ts

@@ -0,0 +1,113 @@
+/**
+ * User-owned daily journal (issue #1984 PR1).
+ *
+ * Files live at `<memoryDir>/journal/<YYYY-MM-DD>.md` — inside the memory
+ * directory but outside scan roots, same placement as activity digests.
+ * Once written, Remnic never rewrites the file except `seed` with force.
+ * All writes go through writeJournalFile, which stats first.
+ */
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { isValidActivityDate } from "./digest.js";
+
+export const JOURNAL_DIR_NAME = "journal";
+
+/** Minimal card shape the seed renderer needs. TimelineCard is assignable. */
+export interface JournalSeedCard {
+  title: string;
+  startUtc: string;
+  endUtc: string;
+}
+
+export interface SeedJournalInput {
+  memoryDir: string;
+  date: string;
+  cards?: readonly JournalSeedCard[];
+  force?: boolean;
+}
+
+export interface SeedJournalResult {
+  path: string;
+  wrote: boolean;
+}
+
+const JOURNAL_DAY_TOPLEVEL = /^journal[\\/]\d{4}-\d{2}-\d{2}\.md$/i;
+const JOURNAL_DAY_ANYWHERE = /(?:^|[\\/])journal[\\/]\d{4}-\d{2}-\d{2}\.md$/i;
+
+export function journalPath(memoryDir: string, date: string): string {
+  if (!isValidActivityDate(date)) {
+    throw new RangeError(`Invalid journal date "${date}"; expected YYYY-MM-DD.`);
+  }
+  return path.join(memoryDir, JOURNAL_DIR_NAME, `${date}.md`);
+}
+
+/**
+ * Root-aware journal day-file check. With a memory root, only the top-level
+ * `journal/<date>.md` matches so a nested `facts/journal/<date>.md` stays
+ * recallable. Without a root, fall back to the day-file shape anywhere.
+ */
+export function isJournalDayPath(filePath: string, memoryRoot?: string): boolean {
+  if (memoryRoot !== undefined && memoryRoot.length > 0) {
+    const relative = path.relative(memoryRoot, path.resolve(memoryRoot, filePath));
+    return JOURNAL_DAY_TOPLEVEL.test(relative);
+  }
+  return JOURNAL_DAY_ANYWHERE.test(filePath);
+}
+
+export function todayJournalDate(now: Date = new Date()): string {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function formatCardDuration(card: JournalSeedCard): string {
+  const start = Date.parse(card.startUtc);
+  const end = Date.parse(card.endUtc);
+  const minutes =
+    Number.isFinite(start) && Number.isFinite(end) && end > start
+      ? Math.round((end - start) / 60_000)
+      : 0;
+  return `${minutes}m`;
+}
+
+function renderJournalSeed(date: string, cards: readonly JournalSeedCard[]): string {
+  const ordered = [...cards].sort((left, right) => {
+    const byStart = left.startUtc.localeCompare(right.startUtc);
+    return byStart !== 0 ? byStart : left.title.localeCompare(right.title);
+  });
+  const glance =
+    ordered.length === 0
+      ? ["_No cards._"]
+      : ordered.map((card) => `- ${formatCardDuration(card)} ${card.title}`);
+  return [`# Journal — ${date}`, "", "## Day at a glance", "", ...glance, "", "## Notes", "", ""].join(
+    "\n",
+  );
+}
+
+/** The only journal write. Stats first; existing files are a no-op unless force. */
+export function writeJournalFile(filePath: string, content: string, force: boolean): boolean {
+  let exists = false;
+  try {
+    statSync(filePath);
+    exists = true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") throw err;
+  }
+  if (exists && !force) return false;
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content);
+  return true;
+}
+
+export function seedJournal(input: SeedJournalInput): SeedJournalResult {
+  const filePath = journalPath(input.memoryDir, input.date);
+  const wrote = writeJournalFile(
+    filePath,
+    renderJournalSeed(input.date, input.cards ?? []),
+    input.force === true,
+  );
+  return { path: filePath, wrote };
+}

package/src/activity/privacy.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  MS_PER_DAY,
+  observationsForExport,
+  parseActivityPrivacy,
+  shouldRetain,
+} from "./privacy.js";
+
+test("retentionDays 0 keeps forever", () => {
+  const policy = parseActivityPrivacy({ enabled: true, retentionDays: 0 });
+  assert.equal(policy.retentionDays, 0);
+  const now = 1_700_000_000_000;
+  assert.equal(shouldRetain(now - 400 * MS_PER_DAY, now, policy.retentionDays), true);
+  assert.equal(shouldRetain(now, now, 0), true);
+});
+
+test("negative retentionDays throws", () => {
+  assert.throws(() => parseActivityPrivacy({ retentionDays: -1 }), /non-negative integer/);
+  assert.throws(() => parseActivityPrivacy({ retentionDays: -30 }), /non-negative integer/);
+  assert.throws(() => shouldRetain(0, 0, -1), /non-negative integer/);
+});
+
+test("exact expiry boundary is half-open", () => {
+  const now = 1_700_000_000_000;
+  const days = 30;
+  const captured = now - days * MS_PER_DAY;
+  assert.equal(shouldRetain(captured, now, days), false);
+  assert.equal(shouldRetain(captured + 1, now, days), true);
+  assert.equal(shouldRetain(captured - 1, now, days), false);
+});
+
+test("disabled master denies retain and empties export", () => {
+  const policy = parseActivityPrivacy({
+    enabled: false,
+    retentionDays: 0,
+    exportIncludeObservations: true,
+  });
+  assert.equal(policy.enabled, false);
+  assert.equal(shouldRetain(1_700_000_000_000, 1_700_000_000_000, policy.retentionDays, policy.enabled), false);
+  assert.deepEqual(observationsForExport(["obs"], policy), []);
+  assert.equal(parseActivityPrivacy(undefined).enabled, false);
+});
+
+test("exportIncludeObservations defaults false", () => {
+  assert.equal(parseActivityPrivacy(undefined).exportIncludeObservations, false);
+  assert.equal(parseActivityPrivacy({ enabled: true }).exportIncludeObservations, false);
+  const policy = parseActivityPrivacy({ enabled: true });
+  assert.deepEqual(observationsForExport(["obs"], policy), []);
+  const included = parseActivityPrivacy({ enabled: true, exportIncludeObservations: true });
+  assert.deepEqual(observationsForExport(["obs"], included), ["obs"]);
+});

package/src/activity/privacy.ts

@@ -0,0 +1,80 @@
+/**
+ * Activity retention and export policy (issue #2053 first slice).
+ *
+ * Pure helpers. Surfaces and parseConfig wiring wait for a later PR.
+ * Master `activity.enabled` false denies retain and empties export.
+ */
+import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
+
+export const MS_PER_DAY = 86_400_000;
+
+export interface ActivityPrivacyPolicy {
+  enabled: boolean;
+  /** `0` keeps forever. */
+  retentionDays: number;
+  exportIncludeObservations: boolean;
+}
+
+function asRecord(value: unknown, name: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseGate(value: unknown, key: string, fallback: boolean): boolean {
+  if (value === undefined) return fallback;
+  const parsed = coerceBooleanLike(value, key);
+  if (parsed === undefined) throw new TypeError(`${key} must be a boolean`);
+  return parsed;
+}
+
+/** Parse retention and export knobs. Independent of timeline/journal/weekly blocks. */
+export function parseActivityPrivacy(raw?: unknown): ActivityPrivacyPolicy {
+  if (raw === undefined || raw === null) {
+    return { enabled: false, retentionDays: 0, exportIncludeObservations: false };
+  }
+  const config = asRecord(raw, "activity");
+  const enabled = parseGate(config.enabled, "activity.enabled", false);
+  let retentionDays = 0;
+  if (config.retentionDays !== undefined) {
+    const parsed = coerceNumber(config.retentionDays, "activity.retentionDays");
+    if (parsed === undefined || !Number.isInteger(parsed) || parsed < 0) {
+      throw new RangeError("activity.retentionDays must be a non-negative integer");
+    }
+    retentionDays = parsed;
+  }
+  const exportIncludeObservations = parseGate(
+    config.exportIncludeObservations,
+    "activity.exportIncludeObservations",
+    false,
+  );
+  return { enabled, retentionDays, exportIncludeObservations };
+}
+
+/**
+ * Half-open retain window: keep when age is in `[0, retentionDays)`.
+ * `retentionDays === 0` keeps forever. Master off denies.
+ */
+export function shouldRetain(
+  capturedAtMs: number,
+  nowMs: number,
+  retentionDays: number,
+  enabled = true,
+): boolean {
+  if (!enabled) return false;
+  if (retentionDays < 0 || !Number.isInteger(retentionDays)) {
+    throw new RangeError("activity.retentionDays must be a non-negative integer");
+  }
+  if (retentionDays === 0) return true;
+  return nowMs - capturedAtMs < retentionDays * MS_PER_DAY;
+}
+
+/** Export payload. Master off or the export gate off returns empty. */
+export function observationsForExport<T>(
+  observations: readonly T[],
+  policy: Pick<ActivityPrivacyPolicy, "enabled" | "exportIncludeObservations">,
+): readonly T[] {
+  if (!policy.enabled || !policy.exportIncludeObservations) return [];
+  return observations;
+}

package/src/activity/timeline/analysis-batch.test.ts

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { batchObservations } from "./analysis-batch.js";
+import type { TimelineBatchObservation } from "./analysis-batch.js";
+
+function obs(id: number, capturedAtUtc: string): TimelineBatchObservation {
+  return { id, capturedAtUtc };
+}
+
+test("empty observations return no batches", () => {
+  assert.deepEqual(batchObservations([], { maxBatch: 3, overlap: 1 }), []);
+});
+
+test("maxBatch 0 returns no batches", () => {
+  assert.deepEqual(
+    batchObservations([obs(1, "2026-08-17T10:00:00.000Z")], { maxBatch: 0, overlap: 0 }),
+    [],
+  );
+});
+
+test("overlap shares the trailing window with the next batch", () => {
+  const items = [1, 2, 3, 4, 5].map((id) => obs(id, `2026-08-17T10:0${id}:00.000Z`));
+  const batches = batchObservations(items, { maxBatch: 3, overlap: 1 });
+  assert.deepEqual(
+    batches.map((batch) => batch.map((item) => item.id)),
+    [
+      [1, 2, 3],
+      [3, 4, 5],
+    ],
+  );
+});
+
+test("order is capturedAtUtc then id, not input order", () => {
+  const items = [
+    obs(3, "2026-08-17T12:00:00.000Z"),
+    obs(2, "2026-08-17T10:00:00.000Z"),
+    obs(1, "2026-08-17T10:00:00.000Z"),
+  ];
+  const batches = batchObservations(items, { maxBatch: 3, overlap: 0 });
+  assert.deepEqual(
+    batches.map((batch) => batch.map((item) => item.id)),
+    [[1, 2, 3]],
+  );
+});
+
+test("maxBatch below 1 is rejected except 0", () => {
+  assert.throws(() => batchObservations([], { maxBatch: -1, overlap: 0 }), RangeError);
+  assert.throws(() => batchObservations([], { maxBatch: 0.5, overlap: 0 }), RangeError);
+});
+
+test("negative overlap and overlap covering the batch are rejected", () => {
+  assert.throws(() => batchObservations([], { maxBatch: 3, overlap: -1 }), RangeError);
+  assert.throws(() => batchObservations([], { maxBatch: 3, overlap: 3 }), RangeError);
+  assert.throws(() => batchObservations([], { maxBatch: 3, overlap: 4 }), RangeError);
+});

package/src/activity/timeline/analysis-batch.ts

@@ -0,0 +1,45 @@
+/**
+ * Bounded overlapping observation batches for timeline analysis (issue #2050).
+ */
+import type { TimelineObservation } from "./types.js";
+
+export type TimelineBatchObservation = Pick<TimelineObservation, "id" | "capturedAtUtc">;
+
+export interface BatchObservationsOptions {
+  maxBatch: number;
+  overlap: number;
+}
+
+function compareObservations(a: TimelineBatchObservation, b: TimelineBatchObservation): number {
+  const time = Date.parse(a.capturedAtUtc) - Date.parse(b.capturedAtUtc);
+  if (time !== 0) return time;
+  return a.id - b.id;
+}
+
+/** Split observations into overlapping windows. Order is capturedAtUtc, then id. */
+export function batchObservations<T extends TimelineBatchObservation>(
+  observations: readonly T[],
+  options: BatchObservationsOptions,
+): T[][] {
+  const { maxBatch, overlap } = options;
+  if (!Number.isInteger(overlap) || overlap < 0) {
+    throw new RangeError("overlap must be a non-negative integer");
+  }
+  if (maxBatch === 0) return [];
+  if (!Number.isInteger(maxBatch) || maxBatch < 1) {
+    throw new RangeError("maxBatch must be 0 or a positive integer");
+  }
+  if (overlap >= maxBatch) {
+    throw new RangeError("overlap must be less than maxBatch");
+  }
+  if (observations.length === 0) return [];
+
+  const ordered = [...observations].sort(compareObservations);
+  const step = maxBatch - overlap;
+  const batches: T[][] = [];
+  for (let start = 0; start < ordered.length; start += step) {
+    batches.push(ordered.slice(start, start + maxBatch));
+    if (start + maxBatch >= ordered.length) break;
+  }
+  return batches;
+}