@remnic/core 9.66.1 → 9.66.3

package/src/activity/timeline/analysis.ts

@@ -0,0 +1,362 @@
+/**
+ * Optional AI analysis over deterministic timeline cards (issue #2050 first slice).
+ *
+ * Injected provider only. parseConfig, registries, and surfaces wait.
+ * Failures leave cards unchanged. Disabled makes zero provider calls.
+ */
+import { extractJsonCandidates } from "../../json-extract.js";
+import { log } from "../../logger.js";
+import { DEFAULT_TIMELINE_CATEGORIES } from "./categories.js";
+import type { TimelineCard, TimelineCategory, TimelineCorrection, TimelineEvidenceRange, TimelineObservation } from "./types.js";
+
+export const TIMELINE_ANALYSIS_PROMPT_VERSION = 1;
+export const TIMELINE_ANALYSIS_BATCH_SIZE = 40;
+export const TIMELINE_ANALYSIS_BATCH_OVERLAP = 2;
+export const TIMELINE_ANALYSIS_DEFAULT_TIMEOUT_MS = 15_000;
+
+export class TimelineAnalysisConfigError extends Error {
+  override readonly name = "TimelineAnalysisConfigError";
+  readonly code = "invalid_config" as const;
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export type TimelineAnalysisStatus = "ok" | "disabled" | "provider_failed" | "invalid_output";
+
+export interface TimelineAnalysisCompleteInput {
+  prompt: string;
+  provider: string;
+  model: string;
+  signal: AbortSignal;
+}
+
+export type TimelineAnalysisComplete = (input: TimelineAnalysisCompleteInput) => Promise<string>;
+
+export interface TimelineAnalysisInput {
+  enabled: boolean;
+  cards: readonly TimelineCard[];
+  observations: readonly TimelineObservation[];
+  provider?: string;
+  model?: string;
+  complete?: TimelineAnalysisComplete;
+  timeoutMs?: number;
+  date?: string;
+  timezone?: string;
+  categories?: readonly TimelineCategory[];
+  preferences?: readonly string[];
+  priorEdits?: readonly TimelineCorrection[];
+  signal?: AbortSignal;
+}
+
+export interface TimelineAnalysisResult {
+  status: TimelineAnalysisStatus;
+  cards: TimelineCard[];
+  provider?: string;
+  model?: string;
+  promptVersion?: number;
+}
+
+interface AnalysisOp {
+  cardId: string;
+  title?: string;
+  summary?: string;
+  categoryId?: string;
+  confidence?: number;
+  uncertainty?: string;
+  evidenceRange: TimelineEvidenceRange;
+}
+
+const INSTRUCTIONS = [
+  "Use only supplied evidence.",
+  "Preserve chronology.",
+  "Do not invent people, places, or tasks.",
+  "Avoid productivity or emotional claims.",
+  "Merge adjacent activity only when the evidence justifies it.",
+  "Return strict JSON: {\"ops\":[...]} with evidenceRange, title, summary, categoryId, confidence, uncertainty.",
+  "Cite evidence ranges for every op. Empty ops is a valid no-op.",
+].join(" ");
+
+function fail(
+  status: Exclude<TimelineAnalysisStatus, "ok" | "disabled">,
+  cards: readonly TimelineCard[],
+  provider: string,
+  model: string,
+): TimelineAnalysisResult {
+  log.info(`timeline analysis status=${status} provider=${provider} model=${model} promptVersion=${TIMELINE_ANALYSIS_PROMPT_VERSION}`);
+  return {
+    status,
+    cards: cards as TimelineCard[],
+    provider,
+    model,
+    promptVersion: TIMELINE_ANALYSIS_PROMPT_VERSION,
+  };
+}
+
+function requiredToken(value: string | undefined, name: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TimelineAnalysisConfigError(`${name} is required`);
+  }
+  return value.trim();
+}
+
+function evidenceKeyOf(observation: TimelineObservation): string {
+  const parsed = Date.parse(observation.capturedAtUtc);
+  const instant = Number.isFinite(parsed) ? new Date(parsed).toISOString() : observation.capturedAtUtc;
+  return `${observation.machine}|${instant}|${observation.contentHash}`;
+}
+
+function sortObservations(observations: readonly TimelineObservation[]): TimelineObservation[] {
+  return [...observations].sort((a, b) => {
+    const time = Date.parse(a.capturedAtUtc) - Date.parse(b.capturedAtUtc);
+    if (time !== 0) return time;
+    if (a.contentHash !== b.contentHash) return a.contentHash < b.contentHash ? -1 : 1;
+    return a.id - b.id;
+  });
+}
+
+function batchObservations(observations: readonly TimelineObservation[]): TimelineObservation[][] {
+  if (observations.length === 0) return [[]];
+  const size = TIMELINE_ANALYSIS_BATCH_SIZE;
+  const overlap = TIMELINE_ANALYSIS_BATCH_OVERLAP;
+  const step = size - overlap;
+  const batches: TimelineObservation[][] = [];
+  for (let start = 0; start < observations.length; start += step) {
+    batches.push(observations.slice(start, start + size));
+    if (start + size >= observations.length) break;
+  }
+  return batches;
+}
+
+function safeObservation(observation: TimelineObservation) {
+  return {
+    id: observation.id,
+    machine: observation.machine,
+    capturedAtUtc: observation.capturedAtUtc,
+    app: observation.app,
+    windowTitle: observation.windowTitle,
+    ...(observation.browserUrl ? { browserUrl: observation.browserUrl } : {}),
+    contentHash: observation.contentHash,
+  };
+}
+
+function safeCard(card: TimelineCard) {
+  return {
+    id: card.id,
+    kind: card.kind,
+    title: card.title,
+    summary: card.summary,
+    categoryId: card.categoryId,
+    confidence: card.confidence,
+    startUtc: card.startUtc,
+    endUtc: card.endUtc,
+    machine: card.machine,
+    evidenceIds: card.evidenceIds,
+    evidenceRange: card.evidenceRange,
+    ...(card.manualEdit ? { manualEdit: card.manualEdit } : {}),
+  };
+}
+
+export function buildTimelineAnalysisPrompt(input: {
+  date?: string;
+  timezone?: string;
+  cards: readonly TimelineCard[];
+  observations: readonly TimelineObservation[];
+  categories: readonly TimelineCategory[];
+  preferences?: readonly string[];
+  priorEdits?: readonly TimelineCorrection[];
+}): string {
+  const payload = {
+    date: input.date ?? null,
+    timezone: input.timezone ?? null,
+    categories: input.categories.map((category) => ({ id: category.id, name: category.name })),
+    preferences: input.preferences ?? [],
+    priorEdits: input.priorEdits ?? [],
+    cards: input.cards.map(safeCard),
+    observations: input.observations.map(safeObservation),
+  };
+  return `${INSTRUCTIONS}\n${JSON.stringify(payload)}`;
+}
+
+async function callComplete(
+  complete: TimelineAnalysisComplete,
+  prompt: string,
+  provider: string,
+  model: string,
+  timeoutMs: number,
+  parent?: AbortSignal,
+): Promise<string> {
+  const { promise: timeoutPromise, reject } = Promise.withResolvers<string>();
+  const failOnce = (message: string, name: string) => {
+    reject(Object.assign(new Error(message), { name }));
+  };
+  const timer = setTimeout(() => failOnce("timeline analysis timed out", "TimeoutError"), timeoutMs);
+  if (parent?.aborted) {
+    clearTimeout(timer);
+    throw Object.assign(new Error("timeline analysis aborted"), { name: "AbortError" });
+  }
+  const onAbort = () => failOnce("timeline analysis aborted", "AbortError");
+  parent?.addEventListener("abort", onAbort, { once: true });
+  const signal = parent ? AbortSignal.any([parent, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+  try {
+    return await Promise.race([complete({ prompt, provider, model, signal }), timeoutPromise]);
+  } finally {
+    clearTimeout(timer);
+    parent?.removeEventListener("abort", onAbort);
+  }
+}
+
+function parseOps(raw: string): AnalysisOp[] | null {
+  if (typeof raw !== "string" || raw.trim().length === 0) return null;
+  for (const candidate of extractJsonCandidates(raw)) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !("ops" in parsed)) continue;
+      const ops = parsed.ops;
+      if (!Array.isArray(ops)) continue;
+      const out: AnalysisOp[] = [];
+      let valid = true;
+      for (const item of ops) {
+        const op = asOp(item);
+        if (!op) {
+          valid = false;
+          break;
+        }
+        out.push(op);
+      }
+      if (valid) return out;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function asOp(value: unknown): AnalysisOp | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (!("cardId" in value) || typeof value.cardId !== "string" || value.cardId.length === 0) return null;
+  if (!("evidenceRange" in value)) return null;
+  const range = value.evidenceRange;
+  if (!range || typeof range !== "object" || Array.isArray(range)) return null;
+  if (!("firstKey" in range) || typeof range.firstKey !== "string" || range.firstKey.length === 0) return null;
+  if (!("lastKey" in range) || typeof range.lastKey !== "string" || range.lastKey.length === 0) return null;
+  if ("title" in value && value.title !== undefined && typeof value.title !== "string") return null;
+  if ("summary" in value && value.summary !== undefined && typeof value.summary !== "string") return null;
+  if ("categoryId" in value && value.categoryId !== undefined && typeof value.categoryId !== "string") return null;
+  if ("uncertainty" in value && value.uncertainty !== undefined && typeof value.uncertainty !== "string") return null;
+  if (
+    "confidence" in value &&
+    value.confidence !== undefined &&
+    (typeof value.confidence !== "number" || value.confidence < 0 || value.confidence > 1)
+  ) {
+    return null;
+  }
+  return {
+    cardId: value.cardId,
+    title: "title" in value && typeof value.title === "string" ? value.title : undefined,
+    summary: "summary" in value && typeof value.summary === "string" ? value.summary : undefined,
+    categoryId: "categoryId" in value && typeof value.categoryId === "string" ? value.categoryId : undefined,
+    confidence: "confidence" in value && typeof value.confidence === "number" ? value.confidence : undefined,
+    uncertainty: "uncertainty" in value && typeof value.uncertainty === "string" ? value.uncertainty : undefined,
+    evidenceRange: { firstKey: range.firstKey, lastKey: range.lastKey },
+  };
+}
+
+function knownEvidenceKeys(cards: readonly TimelineCard[], observations: readonly TimelineObservation[]): Set<string> {
+  const keys = new Set<string>();
+  for (const observation of observations) keys.add(evidenceKeyOf(observation));
+  for (const card of cards) {
+    if (card.evidenceRange) {
+      keys.add(card.evidenceRange.firstKey);
+      keys.add(card.evidenceRange.lastKey);
+    }
+  }
+  return keys;
+}
+
+function applyOps(
+  cards: readonly TimelineCard[],
+  ops: readonly AnalysisOp[],
+  categories: readonly TimelineCategory[],
+  evidenceKeys: ReadonlySet<string>,
+): TimelineCard[] | null {
+  if (ops.length === 0) return cards as TimelineCard[];
+  const byId = new Map(cards.map((card) => [card.id, card]));
+  const allowedCategories = new Set(categories.map((category) => category.id));
+  const next = new Map<string, TimelineCard>();
+  for (const op of ops) {
+    const card = byId.get(op.cardId);
+    if (!card) return null;
+    if (!evidenceKeys.has(op.evidenceRange.firstKey) || !evidenceKeys.has(op.evidenceRange.lastKey)) return null;
+    if (op.categoryId !== undefined && !allowedCategories.has(op.categoryId)) return null;
+    if (card.manualEdit) continue;
+    next.set(card.id, {
+      ...card,
+      ...(op.title !== undefined ? { title: op.title } : {}),
+      ...(op.summary !== undefined ? { summary: op.summary } : {}),
+      ...(op.categoryId !== undefined ? { categoryId: op.categoryId } : {}),
+      ...(op.confidence !== undefined ? { confidence: op.confidence } : {}),
+    });
+  }
+  if (next.size === 0) return cards as TimelineCard[];
+  return cards.map((card) => next.get(card.id) ?? card);
+}
+
+/** Analyze one day of cards. Failures return the input cards unchanged. */
+export async function analyzeTimelineCards(input: TimelineAnalysisInput): Promise<TimelineAnalysisResult> {
+  const cards = input.cards as TimelineCard[];
+  if (!input.enabled) {
+    return { status: "disabled", cards };
+  }
+
+  const provider = requiredToken(input.provider, "provider");
+  const model = requiredToken(input.model, "model");
+  const complete = input.complete;
+  if (typeof complete !== "function") {
+    throw new TimelineAnalysisConfigError("complete is required");
+  }
+  const timeoutMs = input.timeoutMs ?? TIMELINE_ANALYSIS_DEFAULT_TIMEOUT_MS;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new TimelineAnalysisConfigError("timeoutMs must be a positive integer");
+  }
+  if (input.cards.length === 0 && input.observations.length === 0) {
+    return fail("invalid_output", cards, provider, model);
+  }
+
+  const categories = input.categories ?? DEFAULT_TIMELINE_CATEGORIES;
+  const ordered = sortObservations(input.observations);
+  const batches = batchObservations(ordered);
+  const merged = new Map<string, AnalysisOp>();
+
+  try {
+    for (const batch of batches) {
+      const prompt = buildTimelineAnalysisPrompt({
+        date: input.date,
+        timezone: input.timezone,
+        cards: input.cards,
+        observations: batch,
+        categories,
+        preferences: input.preferences,
+        priorEdits: input.priorEdits,
+      });
+      const raw = await callComplete(complete, prompt, provider, model, timeoutMs, input.signal);
+      const ops = parseOps(raw);
+      if (!ops) return fail("invalid_output", cards, provider, model);
+      for (const op of ops) merged.set(op.cardId, op);
+    }
+  } catch {
+    return fail("provider_failed", cards, provider, model);
+  }
+
+  const applied = applyOps(cards, [...merged.values()], categories, knownEvidenceKeys(cards, ordered));
+  if (!applied) return fail("invalid_output", cards, provider, model);
+
+  log.info(`timeline analysis status=ok provider=${provider} model=${model} promptVersion=${TIMELINE_ANALYSIS_PROMPT_VERSION}`);
+  return {
+    status: "ok",
+    cards: applied,
+    provider,
+    model,
+    promptVersion: TIMELINE_ANALYSIS_PROMPT_VERSION,
+  };
+}

package/src/activity/timeline/index.ts

@@ -6,3 +6,16 @@ export * from "./build.js";
 export * from "./corrections.js";
 export * from "./query.js";
 export * from "./journal-recap.js";
+export * from "./journal-recap-persist.js";
+export * from "./weekly.js";
+export * from "./weekly-persist.js";
+export * from "./analysis.js";
+export * from "./recap-export.js";
+export * from "./recap-markdown.js";
+export * from "./week-export.js";
+export * from "./week-snapshot.js";
+export * from "./analysis-batch.js";
+export * from "./analysis-evidence.js";
+export * from "./analysis-prompt.js";
+export * from "./analysis-claim.js";
+export * from "./analysis-order.js";

package/src/activity/timeline/journal-recap-persist.test.ts

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { journalPath } from "../journal.js";
+import { persistDeterministicJournal } from "./journal-recap-persist.js";
+import { renderDeterministicJournal } from "./journal-recap.js";
+import type { TimelineCard } from "./types.js";
+
+const DATE = "2026-08-17";
+const TZ = "UTC";
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id" | "startUtc" | "endUtc">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "Untitled",
+    summary: "none",
+    categoryId: "development",
+    confidence: 1,
+    dayKey: DATE,
+    timezone: TZ,
+    machine: "ws-a",
+    evidenceIds: [],
+    evidenceRange: null,
+    ...overrides,
+  };
+}
+
+function activityCards(): TimelineCard[] {
+  return [
+    card({
+      id: "act-1",
+      title: "Terminal",
+      startUtc: "2026-08-17T14:00:00.000Z",
+      endUtc: "2026-08-17T15:30:00.000Z",
+    }),
+  ];
+}
+
+function otherCards(): TimelineCard[] {
+  return [
+    card({
+      id: "act-2",
+      title: "Browser",
+      startUtc: "2026-08-17T16:00:00.000Z",
+      endUtc: "2026-08-17T17:00:00.000Z",
+    }),
+  ];
+}
+
+function withMemoryDir(fn: (memoryDir: string) => void): void {
+  const memoryDir = mkdtempSync(path.join(tmpdir(), "remnic-journal-recap-persist-"));
+  try {
+    fn(memoryDir);
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+}
+
+test("persist is a hard no-op without force", () => {
+  withMemoryDir((memoryDir) => {
+    const first = persistDeterministicJournal({
+      memoryDir,
+      date: DATE,
+      cards: activityCards(),
+      timezone: TZ,
+    });
+    assert.equal(first.wrote, true);
+    assert.equal(first.path, journalPath(memoryDir, DATE));
+    const original = readFileSync(first.path);
+    assert.equal(
+      original.toString("utf8"),
+      renderDeterministicJournal(activityCards(), { date: DATE, timezone: TZ }),
+    );
+
+    const second = persistDeterministicJournal({
+      memoryDir,
+      date: DATE,
+      cards: otherCards(),
+      timezone: TZ,
+    });
+    assert.equal(second.wrote, false);
+    assert.equal(second.path, first.path);
+    assert.deepEqual(readFileSync(second.path), original);
+  });
+});
+
+test("persist with force overwrites the existing file", () => {
+  withMemoryDir((memoryDir) => {
+    persistDeterministicJournal({
+      memoryDir,
+      date: DATE,
+      cards: activityCards(),
+      timezone: TZ,
+    });
+    const original = readFileSync(journalPath(memoryDir, DATE), "utf8");
+    const forced = persistDeterministicJournal({
+      memoryDir,
+      date: DATE,
+      cards: otherCards(),
+      timezone: TZ,
+      force: true,
+    });
+    assert.equal(forced.wrote, true);
+    const next = readFileSync(forced.path, "utf8");
+    assert.notEqual(next, original);
+    assert.equal(next, renderDeterministicJournal(otherCards(), { date: DATE, timezone: TZ }));
+  });
+});
+
+test("empty day still writes a valid journal file", () => {
+  withMemoryDir((memoryDir) => {
+    const result = persistDeterministicJournal({
+      memoryDir,
+      date: DATE,
+      cards: [],
+      timezone: TZ,
+    });
+    assert.equal(result.wrote, true);
+    const relative = path.relative(memoryDir, result.path).replace(/\\/g, "/");
+    assert.equal(relative, "journal/2026-08-17.md");
+    assert.equal(
+      readFileSync(result.path, "utf8"),
+      renderDeterministicJournal([], { date: DATE, timezone: TZ }),
+    );
+  });
+});
+
+test("existing foreign file without force stays byte-identical", () => {
+  withMemoryDir((memoryDir) => {
+    const filePath = journalPath(memoryDir, DATE);
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, "user notes\n");
+    const original = readFileSync(filePath);
+    const result = persistDeterministicJournal({
+      memoryDir,
+      date: DATE,
+      cards: activityCards(),
+      timezone: TZ,
+    });
+    assert.equal(result.wrote, false);
+    assert.deepEqual(readFileSync(filePath), original);
+  });
+});

package/src/activity/timeline/journal-recap-persist.ts

@@ -0,0 +1,37 @@
+/**
+ * Persist a deterministic daily journal recap (issue #2051).
+ *
+ * Writes journal/<YYYY-MM-DD>.md through writeJournalFile. Existing files
+ * stay byte-identical unless force is set. Body is renderDeterministicJournal.
+ */
+import { journalPath, writeJournalFile } from "../journal.js";
+import { renderDeterministicJournal } from "./journal-recap.js";
+import type { TimelineCard } from "./types.js";
+
+export interface PersistDeterministicJournalInput {
+  memoryDir: string;
+  date: string;
+  cards: readonly TimelineCard[];
+  timezone: string;
+  force?: boolean;
+}
+
+export interface PersistDeterministicJournalResult {
+  path: string;
+  wrote: boolean;
+}
+
+export function persistDeterministicJournal(
+  input: PersistDeterministicJournalInput,
+): PersistDeterministicJournalResult {
+  const filePath = journalPath(input.memoryDir, input.date);
+  const wrote = writeJournalFile(
+    filePath,
+    renderDeterministicJournal(input.cards, {
+      date: input.date,
+      timezone: input.timezone,
+    }),
+    input.force === true,
+  );
+  return { path: filePath, wrote };
+}

package/src/activity/timeline/recap-card-id.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseRecapCardId } from "./recap-card-id.js";
+
+test("ok card id returns trimmed id", () => {
+  assert.deepEqual(parseRecapCardId("card-1"), { ok: true, id: "card-1" });
+});
+
+test("empty card id is missing_id", () => {
+  assert.deepEqual(parseRecapCardId(""), { ok: false, error: "missing_id" });
+  assert.deepEqual(parseRecapCardId("   "), { ok: false, error: "missing_id" });
+});
+
+test("newline in card id is invalid_id", () => {
+  assert.deepEqual(parseRecapCardId("card-1\ncard-2"), { ok: false, error: "invalid_id" });
+});
+
+test("trims surrounding whitespace", () => {
+  assert.deepEqual(parseRecapCardId("  card-1  "), { ok: true, id: "card-1" });
+});

package/src/activity/timeline/recap-card-id.ts

@@ -0,0 +1,16 @@
+/**
+ * Parse a recap card id (issue #2051 leftover).
+ *
+ * Pure. Empty is missing_id. Newline is invalid_id.
+ */
+
+export type ParseRecapCardIdResult =
+  | { ok: true; id: string }
+  | { ok: false; error: "missing_id" | "invalid_id" };
+
+export function parseRecapCardId(value: string): ParseRecapCardIdResult {
+  const id = value.trim();
+  if (id.length === 0) return { ok: false, error: "missing_id" };
+  if (id.includes("\n")) return { ok: false, error: "invalid_id" };
+  return { ok: true, id };
+}

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

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseRecapDate } from "./recap-date.js";
+
+test("accepts a trimmed YYYY-MM-DD date", () => {
+  assert.deepEqual(parseRecapDate("2026-08-19"), { ok: true, date: "2026-08-19" });
+  assert.deepEqual(parseRecapDate("  2026-08-19  "), { ok: true, date: "2026-08-19" });
+});
+
+test("empty and whitespace-only values are missing_date", () => {
+  assert.deepEqual(parseRecapDate(""), { ok: false, error: "missing_date" });
+  assert.deepEqual(parseRecapDate("   "), { ok: false, error: "missing_date" });
+});
+
+test("rejects strings that are not YYYY-MM-DD", () => {
+  assert.deepEqual(parseRecapDate("20260819"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseRecapDate("2026-8-19"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseRecapDate("2026-08-19T00:00:00Z"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseRecapDate("not-a-date"), { ok: false, error: "invalid_date" });
+});

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

@@ -0,0 +1,19 @@
+/**
+ * Parse a recap local-day string (issue #2051 leftover).
+ *
+ * Trim first. Empty → missing_date. Bounded YYYY-MM-DD only (no ReDoS).
+ */
+
+export type RecapDateResult =
+  | { ok: true; date: string }
+  | { ok: false; error: "missing_date" | "invalid_date" };
+
+const RECAP_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Trim and accept YYYY-MM-DD, or return a typed error. */
+export function parseRecapDate(value: string): RecapDateResult {
+  const date = value.trim();
+  if (date.length === 0) return { ok: false, error: "missing_date" };
+  if (!RECAP_DATE.test(date)) return { ok: false, error: "invalid_date" };
+  return { ok: true, date };
+}

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

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isEmptyRecapCards } from "./recap-empty.js";
+
+test("null, undefined, and empty array are empty", () => {
+  assert.equal(isEmptyRecapCards(null), true);
+  assert.equal(isEmptyRecapCards(undefined), true);
+  assert.equal(isEmptyRecapCards([]), true);
+});
+
+test("a non-empty array is not empty", () => {
+  assert.equal(isEmptyRecapCards([{ id: 1 }]), false);
+  assert.equal(isEmptyRecapCards([0]), false);
+});
+
+test("a non-array throws", () => {
+  assert.throws(() => isEmptyRecapCards({}), TypeError);
+  assert.throws(() => isEmptyRecapCards("cards"), TypeError);
+  assert.throws(() => isEmptyRecapCards(1), TypeError);
+});

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

@@ -0,0 +1,14 @@
+/**
+ * Empty-set guard for timeline recap cards (issue #2051 leftover).
+ *
+ * null, undefined, and [] are empty. A non-array throws. Any other array is not empty.
+ */
+
+/** True when the recap card list is absent or has no items. */
+export function isEmptyRecapCards(cards: unknown): boolean {
+  if (cards == null) return true;
+  if (!Array.isArray(cards)) {
+    throw new TypeError("cards must be an array");
+  }
+  return cards.length === 0;
+}