@remnic/core 9.69.45 → 9.69.47

package/src/activity/timeline/recap-export-range.test.ts

@@ -0,0 +1,289 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { TimelineCard } from "./types.js";
+import {
+  DEFAULT_RECAP_RANGE_MAX_DAYS,
+  exportDeterministicRecapRange,
+  renderDeterministicJournalRange,
+} from "./recap-export-range.js";
+import { renderDeterministicJournal } from "./journal-recap.js";
+
+const TZ = "UTC";
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id" | "dayKey">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "Untitled",
+    summary: "none",
+    categoryId: "development",
+    confidence: 1,
+    startUtc: `${overrides.dayKey}T09:00:00.000Z`,
+    endUtc: `${overrides.dayKey}T10:00:00.000Z`,
+    timezone: TZ,
+    machine: "ws-a",
+    evidenceIds: [],
+    evidenceRange: null,
+    ...overrides,
+  };
+}
+
+function okRange(options: Parameters<typeof exportDeterministicRecapRange>[0]) {
+  const result = exportDeterministicRecapRange(options);
+  assert.equal(result.ok, true);
+  assert.ok(result.ok);
+  return result.range;
+}
+
+test("empty range days are exported with empty card lists", () => {
+  const range = okRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-18",
+    timezone: TZ,
+    cards: [],
+  });
+  assert.deepEqual(
+    range.days.map((d) => [d.date, d.cards.length]),
+    [
+      ["2026-08-17", 0],
+      ["2026-08-18", 0],
+    ],
+  );
+});
+
+test("cards land on their dayKey; out-of-range cards are dropped", () => {
+  const range = okRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-18",
+    timezone: TZ,
+    cards: [
+      card({ id: "b", dayKey: "2026-08-18" }),
+      card({ id: "a", dayKey: "2026-08-17" }),
+      card({ id: "x", dayKey: "2026-08-16" }),
+      card({ id: "y", dayKey: "2026-08-19" }),
+    ],
+  });
+  assert.deepEqual(
+    range.days.map((d) => d.cards.map((c) => c.id)),
+    [["a"], ["b"]],
+  );
+});
+
+test("determinism: same inputs, shuffled card order, identical JSON bytes", () => {
+  const cards = [
+    card({ id: "c2", dayKey: "2026-08-17" }),
+    card({ id: "c1", dayKey: "2026-08-18" }),
+    card({ id: "c3", dayKey: "2026-08-17" }),
+  ];
+  const first = JSON.stringify(
+    exportDeterministicRecapRange({
+      startDate: "2026-08-17",
+      endDate: "2026-08-18",
+      timezone: TZ,
+      cards,
+    }),
+  );
+  const second = JSON.stringify(
+    exportDeterministicRecapRange({
+      startDate: "2026-08-17",
+      endDate: "2026-08-18",
+      timezone: TZ,
+      cards: [cards[1], cards[2], cards[0]],
+    }),
+  );
+  assert.equal(first, second);
+  assert.equal(
+    first,
+    JSON.stringify(
+      exportDeterministicRecapRange({
+        startDate: "2026-08-17",
+        endDate: "2026-08-18",
+        timezone: TZ,
+        cards,
+      }),
+    ),
+  );
+});
+
+test("privacy boundary: titles are omitted by default in range exports", () => {
+  const range = okRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-17",
+    timezone: TZ,
+    cards: [card({ id: "a", dayKey: "2026-08-17", title: "Secret Window Title" })],
+  });
+  const json = JSON.stringify(range);
+  assert.equal(json.includes("Secret Window Title"), false);
+  assert.equal(range.days[0].cards[0].title, undefined);
+});
+
+test("privacy boundary: includeObservations keeps titles in range exports", () => {
+  const range = okRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-17",
+    timezone: TZ,
+    cards: [card({ id: "a", dayKey: "2026-08-17", title: "Secret Window Title" })],
+    includeObservations: true,
+  });
+  assert.equal(range.days[0].cards[0].title, "Secret Window Title");
+});
+
+test("markdown: redacted days render card ids, never titles", () => {
+  const rendered = renderDeterministicJournalRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-17",
+    timezone: TZ,
+    cards: [card({ id: "card-a", dayKey: "2026-08-17", title: "Secret Window Title" })],
+  });
+  assert.ok(rendered.ok);
+  assert.ok(rendered.ok);
+  assert.equal(rendered.markdown.includes("Secret Window Title"), false);
+  assert.equal(rendered.markdown.includes("- 60m card-a"), true);
+});
+
+test("markdown: a single-day range equals the single-day renderer", () => {
+  const cards = [card({ id: "a", dayKey: "2026-08-17", title: "Terminal" })];
+  const rendered = renderDeterministicJournalRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-17",
+    timezone: TZ,
+    cards,
+    includeObservations: true,
+  });
+  assert.ok(rendered.ok);
+  assert.ok(rendered.ok);
+  assert.equal(
+    rendered.markdown,
+    renderDeterministicJournal(cards, { date: "2026-08-17", timezone: TZ }),
+  );
+});
+
+test("markdown: multi-day ranges emit ascending per-day sections", () => {
+  const rendered = renderDeterministicJournalRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-19",
+    timezone: TZ,
+    cards: [],
+  });
+  assert.ok(rendered.ok);
+  assert.ok(rendered.ok);
+  assert.equal(rendered.dayCount, 3);
+  const headings = rendered.markdown
+    .split("\n")
+    .filter((line) => line.startsWith("# Journal — "));
+  assert.deepEqual(headings, [
+    "# Journal — 2026-08-17 (UTC)",
+    "# Journal — 2026-08-18 (UTC)",
+    "# Journal — 2026-08-19 (UTC)",
+  ]);
+});
+
+test("invalid and inverted ranges fail with typed errors", () => {
+  const cases: Array<
+    [Parameters<typeof exportDeterministicRecapRange>[0], string]
+  > = [
+    [{ startDate: "", endDate: "2026-08-18", timezone: TZ, cards: [] }, "invalid_start_date"],
+    [{ startDate: "2026-8-17", endDate: "2026-08-18", timezone: TZ, cards: [] }, "invalid_start_date"],
+    [{ startDate: "2026-02-30", endDate: "2026-03-01", timezone: TZ, cards: [] }, "invalid_start_date"],
+    [{ startDate: "2026-08-17", endDate: "2026-13-01", timezone: TZ, cards: [] }, "invalid_end_date"],
+    [{ startDate: "2026-08-18", endDate: "2026-08-17", timezone: TZ, cards: [] }, "end_before_start"],
+  ];
+  for (const [options, error] of cases) {
+    const result = exportDeterministicRecapRange(options);
+    assert.equal(result.ok, false, JSON.stringify(options));
+    assert.ok(!result.ok);
+    assert.deepEqual(
+      { error: result.error, limit: result.limit },
+      { error, limit: undefined },
+    );
+  }
+});
+
+test("range bound: spans past the default 366 days fail with the limit", () => {
+  const result = exportDeterministicRecapRange({
+    startDate: "2026-01-01",
+    endDate: "2027-01-02",
+    timezone: TZ,
+    cards: [],
+  });
+  assert.ok(!result.ok);
+  assert.deepEqual(
+    { error: result.error, limit: result.limit },
+    { error: "range_too_large", limit: DEFAULT_RECAP_RANGE_MAX_DAYS },
+  );
+  // Exactly the bound still passes.
+  const atBound = exportDeterministicRecapRange({
+    startDate: "2026-01-01",
+    endDate: "2026-12-31",
+    timezone: TZ,
+    cards: [],
+  });
+  assert.ok(atBound.ok);
+  assert.ok(atBound.ok);
+  assert.equal(atBound.range.days.length, 365);
+});
+
+test("range bound: maxDays override is enforced and validated", () => {
+  const denied = exportDeterministicRecapRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-20",
+    timezone: TZ,
+    cards: [],
+    maxDays: 2,
+  });
+  assert.ok(!denied.ok);
+  assert.equal(denied.error, "range_too_large");
+  assert.equal(denied.limit, 2);
+  assert.throws(
+    () =>
+      exportDeterministicRecapRange({
+        startDate: "2026-08-17",
+        endDate: "2026-08-17",
+        timezone: TZ,
+        cards: [],
+        maxDays: 0,
+      }),
+    RangeError,
+  );
+});
+
+test("a card spanning midnight attributes only to its stored dayKey", () => {
+  const range = okRange({
+    startDate: "2026-08-17",
+    endDate: "2026-08-18",
+    timezone: TZ,
+    cards: [
+      card({
+        id: "spans",
+        dayKey: "2026-08-17",
+        startUtc: "2026-08-17T23:00:00.000Z",
+        endUtc: "2026-08-18T01:00:00.000Z",
+      }),
+    ],
+    includeObservations: true,
+  });
+  assert.deepEqual(
+    range.days.map((d) => d.cards.map((c) => c.id)),
+    [["spans"], []],
+  );
+  // The markdown render clips the spanning card to each day window: it
+  // contributes 60m to day 1 and nothing to day 2.
+  const day2 = renderDeterministicJournalRange({
+    startDate: "2026-08-18",
+    endDate: "2026-08-18",
+    timezone: TZ,
+    cards: [
+      card({
+        id: "spans",
+        dayKey: "2026-08-17",
+        startUtc: "2026-08-17T23:00:00.000Z",
+        endUtc: "2026-08-18T01:00:00.000Z",
+      }),
+    ],
+  });
+  assert.ok(day2.ok);
+  assert.ok(day2.ok);
+  assert.equal(day2.markdown.includes("- 60m spans"), false);
+});

package/src/activity/timeline/recap-export-range.ts

@@ -0,0 +1,169 @@
+/**
+ * Deterministic recap export over a bounded date range (issue #2051).
+ *
+ * Pure: cards + inclusive [startDate, endDate] + timezone in, stable JSON or
+ * Markdown out. No LLM, no I/O. Every date in the range gets a day entry —
+ * empty days included — and cards land on their stored `dayKey`, so reruns
+ * with the same inputs always produce the same bytes regardless of input
+ * card order. Cards whose `dayKey` falls outside the range are not exported.
+ *
+ * The range is bounded: at most `maxDays` days (default 366) per call, so a
+ * swapped start/end or a multi-year span fails with a typed error instead of
+ * producing an unbounded document.
+ */
+import { isValidActivityDate } from "../digest.js";
+import { parseRecapDate } from "./recap-date.js";
+import { renderDeterministicJournal } from "./journal-recap.js";
+import {
+  projectCardForRecapExport,
+  type RecapExportCard,
+} from "./recap-export.js";
+import type { TimelineCard } from "./types.js";
+
+export const DEFAULT_RECAP_RANGE_MAX_DAYS = 366;
+
+export interface DeterministicRecapRangeOptions {
+  /** Inclusive first local day, YYYY-MM-DD. */
+  startDate: string;
+  /** Inclusive last local day, YYYY-MM-DD. */
+  endDate: string;
+  timezone: string;
+  cards: readonly TimelineCard[];
+  /** Include observation-derived card content (`title`). Default false. */
+  includeObservations?: boolean;
+  /** Hard upper bound on exported days; default 366. */
+  maxDays?: number;
+}
+
+export interface DeterministicRecapDay {
+  date: string;
+  timezone: string;
+  cards: RecapExportCard[];
+}
+
+export interface DeterministicRecapRange {
+  startDate: string;
+  endDate: string;
+  timezone: string;
+  days: DeterministicRecapDay[];
+}
+
+export type DeterministicRecapRangeResult =
+  | { ok: true; range: DeterministicRecapRange }
+  | {
+      ok: false;
+      error:
+        | "invalid_start_date"
+        | "invalid_end_date"
+        | "end_before_start"
+        | "range_too_large";
+      /** The enforced day bound, present on range_too_large. */
+      limit?: number;
+    };
+
+export type DeterministicRecapRangeMarkdownResult =
+  | { ok: true; markdown: string; dayCount: number }
+  | Extract<DeterministicRecapRangeResult, { ok: false }>;
+
+function compareCardIds(a: RecapExportCard, b: RecapExportCard): number {
+  if (a.id < b.id) return -1;
+  if (a.id > b.id) return 1;
+  return 0;
+}
+
+/** UTC-midnight stepping over validated real calendar dates. */
+function* isoDays(startDate: string, endDate: string): Generator<string> {
+  const endMs = Date.parse(`${endDate}T00:00:00Z`);
+  let cursor = new Date(`${startDate}T00:00:00Z`);
+  while (cursor.getTime() <= endMs) {
+    yield cursor.toISOString().slice(0, 10);
+    cursor = new Date(cursor.getTime() + 86_400_000);
+  }
+}
+
+function dayCount(startDate: string, endDate: string): number {
+  return (
+    (Date.parse(`${endDate}T00:00:00Z`) - Date.parse(`${startDate}T00:00:00Z`)) /
+      86_400_000 +
+    1
+  );
+}
+
+/**
+ * Build the byte-stable JSON recap document for an inclusive local-day
+ * range. Day entries are ascending; day cards are sorted by id; per-card
+ * key order is fixed by `projectCardForRecapExport`.
+ */
+export function exportDeterministicRecapRange(
+  options: DeterministicRecapRangeOptions,
+): DeterministicRecapRangeResult {
+  const start = parseRecapDate(options.startDate);
+  if (!start.ok || !isValidActivityDate(start.date)) {
+    return { ok: false, error: "invalid_start_date" };
+  }
+  const end = parseRecapDate(options.endDate);
+  if (!end.ok || !isValidActivityDate(end.date)) {
+    return { ok: false, error: "invalid_end_date" };
+  }
+  if (Date.parse(`${end.date}T00:00:00Z`) < Date.parse(`${start.date}T00:00:00Z`)) {
+    return { ok: false, error: "end_before_start" };
+  }
+  const limit = options.maxDays ?? DEFAULT_RECAP_RANGE_MAX_DAYS;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new RangeError(`maxDays must be a positive integer; got ${options.maxDays}`);
+  }
+  if (dayCount(start.date, end.date) > limit) {
+    return { ok: false, error: "range_too_large", limit };
+  }
+
+  const includeObservations = options.includeObservations === true;
+  const byDay = new Map<string, RecapExportCard[]>();
+  for (const card of options.cards) {
+    if (card.dayKey < start.date || card.dayKey > end.date) continue;
+    const bucket = byDay.get(card.dayKey);
+    const projected = projectCardForRecapExport(card, includeObservations);
+    if (bucket === undefined) byDay.set(card.dayKey, [projected]);
+    else bucket.push(projected);
+  }
+
+  const days: DeterministicRecapDay[] = [];
+  for (const date of isoDays(start.date, end.date)) {
+    days.push({
+      date,
+      timezone: options.timezone,
+      cards: (byDay.get(date) ?? []).sort(compareCardIds),
+    });
+  }
+  return {
+    ok: true,
+    range: {
+      startDate: start.date,
+      endDate: end.date,
+      timezone: options.timezone,
+      days,
+    },
+  };
+}
+
+/**
+ * Render the byte-stable Markdown recap for an inclusive local-day range:
+ * one `renderDeterministicJournal` section per day, ascending. Validation
+ * and bounds match `exportDeterministicRecapRange`.
+ */
+export function renderDeterministicJournalRange(
+  options: DeterministicRecapRangeOptions,
+): DeterministicRecapRangeMarkdownResult {
+  const exported = exportDeterministicRecapRange(options);
+  if (!exported.ok) return exported;
+  const sections = exported.range.days.map((day) =>
+    renderDeterministicJournal(day.cards, {
+      date: day.date,
+      timezone: day.timezone,
+    }),
+  );
+  return {
+    ok: true,
+    markdown: sections.join("\n"),
+    dayCount: exported.range.days.length,
+  };
+}

package/src/activity/timeline/recap-export.test.ts

@@ -2,7 +2,10 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import type { TimelineCard } from "./types.js";
-import { exportDeterministicRecap } from "./recap-export.js";
+import {
+  exportDeterministicRecap,
+  projectCardForRecapExport,
+} from "./recap-export.js";
 
 const DATE = "2026-08-17";
 
@@ -76,3 +79,72 @@ test("input cards are not mutated and reruns are stable", () => {
   assert.deepEqual(input.map((c) => c.id), ["card-b", "card-a"]);
   assert.equal(JSON.stringify(first), JSON.stringify(second));
 });
+
+test("privacy boundary: default export omits observation-derived titles", () => {
+  const recap = exportDeterministicRecap({
+    date: DATE,
+    timezone: "UTC",
+    cards: [card({ id: "card-a", title: "Secret Window Title" })],
+  });
+  const json = JSON.stringify(recap);
+  assert.equal(json.includes("Secret Window Title"), false);
+  assert.equal(recap.cards[0].title, undefined);
+  // Evidence references survive: the export points at content, never copies it.
+  assert.deepEqual(recap.cards[0].evidenceIds, [1]);
+  assert.equal(recap.cards[0].dayKey, DATE);
+});
+
+test("privacy boundary: includeObservations keeps the title", () => {
+  const recap = exportDeterministicRecap({
+    date: DATE,
+    timezone: "UTC",
+    cards: [card({ id: "card-a", title: "Secret Window Title" })],
+    includeObservations: true,
+  });
+  assert.equal(recap.cards[0].title, "Secret Window Title");
+});
+
+test("manualEdit provenance is kept and sorts last in the projected card", () => {
+  const projected = projectCardForRecapExport(
+    card({
+      id: "card-a",
+      manualEdit: { categoryId: "focus", editedAtUtc: "2026-08-17T12:00:00.000Z" },
+    }),
+    false,
+  );
+  assert.equal(projected.manualEdit?.categoryId, "focus");
+  assert.equal(Object.keys(projected).at(-1), "manualEdit");
+});
+test("projectCardForRecapExport emits a fixed key order without the title", () => {
+  const projected = projectCardForRecapExport(card({ id: "card-a" }), false);
+  assert.deepEqual(Object.keys(projected), [
+    "id",
+    "kind",
+    "summary",
+    "categoryId",
+    "confidence",
+    "startUtc",
+    "endUtc",
+    "dayKey",
+    "timezone",
+    "machine",
+    "evidenceIds",
+    "evidenceRange",
+  ]);
+});
+
+
+test("projected exports are byte-identical across reruns and shuffled input", () => {
+  const cards = [card({ id: "c3" }), card({ id: "c1" }), card({ id: "c2" })];
+  const first = JSON.stringify(
+    exportDeterministicRecap({ date: DATE, timezone: "UTC", cards }),
+  );
+  const second = JSON.stringify(
+    exportDeterministicRecap({
+      date: DATE,
+      timezone: "UTC",
+      cards: [cards[2], cards[0], cards[1]],
+    }),
+  );
+  assert.equal(first, second);
+});

package/src/activity/timeline/recap-export.ts

@@ -4,6 +4,12 @@
  * Pure: cards + date + timezone in, stable JSON out. No LLM, no I/O, no
  * persistence. Same cards always serialize to the same bytes, regardless of
  * input array order: cards are sorted by id before serialization.
+ *
+ * Privacy boundary (issue #2053 policy): a card `title` is captured
+ * observation content (the source window title). It is excluded unless the
+ * export explicitly permits observations — the same default as
+ * `activity.exportIncludeObservations`. Evidence references (store row ids,
+ * identity hashes) are always kept: they point at content without copying it.
  */
 import type { TimelineCard } from "./types.js";
 
@@ -11,15 +17,58 @@ export interface DeterministicRecapOptions {
   date: string;
   timezone: string;
   cards: readonly TimelineCard[];
+  /**
+   * Include observation-derived card content (`title`). Default false,
+   * matching the `activity.exportIncludeObservations` policy default.
+   */
+  includeObservations?: boolean;
+}
+
+/** Card projected for export: `title` present only when the policy permits. */
+export interface RecapExportCard extends Omit<TimelineCard, "title"> {
+  title?: string;
 }
 
 export interface DeterministicRecap {
   date: string;
   timezone: string;
-  cards: TimelineCard[];
+  cards: RecapExportCard[];
+}
+
+/**
+ * Project one card for export with a fixed key order. Observation-derived
+ * `title` is dropped unless `includeObservations`; user-authored provenance
+ * (manual edits, pause reasons inside `summary`) stays, and evidence
+ * references always stay.
+ */
+export function projectCardForRecapExport(
+  card: TimelineCard,
+  includeObservations: boolean,
+): RecapExportCard {
+  const projected: RecapExportCard = {
+    id: card.id,
+    kind: card.kind,
+    summary: card.summary,
+    categoryId: card.categoryId,
+    confidence: card.confidence,
+    startUtc: card.startUtc,
+    endUtc: card.endUtc,
+    dayKey: card.dayKey,
+    timezone: card.timezone,
+    machine: card.machine,
+    evidenceIds: card.evidenceIds,
+    evidenceRange: card.evidenceRange,
+  };
+  if (card.manualEdit !== undefined) {
+    projected.manualEdit = card.manualEdit;
+  }
+  if (includeObservations) {
+    projected.title = card.title;
+  }
+  return projected;
 }
 
-function compareCardIds(a: TimelineCard, b: TimelineCard): number {
+function compareCardIds(a: RecapExportCard, b: RecapExportCard): number {
   if (a.id < b.id) return -1;
   if (a.id > b.id) return 1;
   return 0;
@@ -28,14 +77,18 @@ function compareCardIds(a: TimelineCard, b: TimelineCard): number {
 /**
  * Build the byte-stable JSON recap document for one local day.
  * Callers may `JSON.stringify` the returned object; construction order
- * (date, timezone, cards) is fixed, so serialization is deterministic.
+ * (date, timezone, cards, and the per-card key order) is fixed, so
+ * serialization is deterministic.
  */
 export function exportDeterministicRecap(
   options: DeterministicRecapOptions,
 ): DeterministicRecap {
+  const includeObservations = options.includeObservations === true;
   return {
     date: options.date,
     timezone: options.timezone,
-    cards: [...options.cards].sort(compareCardIds),
+    cards: options.cards
+      .map((card) => projectCardForRecapExport(card, includeObservations))
+      .sort(compareCardIds),
   };
 }