@remnic/core 9.69.53 → 9.69.55

package/src/activity/timeline/week-dashboard.test.ts

@@ -0,0 +1,362 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { planActivityDeletion } from "../privacy-delete-plan.js";
+import type { TimelineCard, TimelineCategory } from "./types.js";
+import {
+  DEFAULT_TOP_SOURCE_LIMIT,
+  WEEKLY_DASHBOARD_FORMAT_VERSION,
+  buildWeeklyDashboard,
+  type WeekSourceAttribution,
+} from "./week-dashboard.js";
+import { persistWeeklySnapshot } from "./weekly-persist.js";
+
+const HOUR = 3_600_000;
+const WEEK_START = "2026-07-13T00:00:00.000Z";
+const WEEK_END = "2026-07-20T00:00:00.000Z";
+const PREV_WEEK_START = "2026-07-06T00:00:00.000Z";
+
+const CATEGORIES: TimelineCategory[] = [
+  { id: "development", name: "Development", color: "#111111", description: "d", order: 1 },
+  { id: "communication", name: "Communication", color: "#222222", description: "c", order: 2 },
+];
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id" | "startUtc" | "endUtc">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "Untitled",
+    summary: "none",
+    categoryId: "development",
+    confidence: 1,
+    dayKey: overrides.startUtc.slice(0, 10),
+    timezone: "UTC",
+    machine: "ws-a",
+    evidenceIds: [],
+    evidenceRange: null,
+    ...overrides,
+  };
+}
+
+function options(overrides: Partial<Parameters<typeof buildWeeklyDashboard>[1]> = {}) {
+  return {
+    timezone: "UTC",
+    weekStartUtc: WEEK_START,
+    weekEndUtc: WEEK_END,
+    categories: CATEGORIES,
+    ...overrides,
+  };
+}
+
+function attributions(...entries: Array<[string, WeekSourceAttribution]>): Map<string, WeekSourceAttribution> {
+  return new Map(entries);
+}
+
+test("empty week yields zero sources, no recurring patterns, zero evidence, unavailable previous period", () => {
+  const dashboard = buildWeeklyDashboard([], options());
+  assert.equal(dashboard.dashboardFormatVersion, WEEKLY_DASHBOARD_FORMAT_VERSION);
+  assert.deepEqual(dashboard.sources, { applications: [], domains: [] });
+  assert.deepEqual(dashboard.recurring, { categories: [], applications: [] });
+  assert.deepEqual(dashboard.evidence, {
+    activityCardCount: 0,
+    idleCardCount: 0,
+    pauseCardCount: 0,
+    evidenceCount: 0,
+    distinctEvidenceCount: 0,
+  });
+  assert.deepEqual(dashboard.uncertainty, {
+    clippedCardCount: 0,
+    manualEditCount: 0,
+    unclassifiedCardCount: 0,
+  });
+  assert.deepEqual(dashboard.previousPeriod, { available: false });
+});
+
+test("top applications and domains aggregate clipped durations; equal totals tie-break by key", () => {
+  const cards = [
+    card({ id: "a", startUtc: "2026-07-13T10:00:00.000Z", endUtc: "2026-07-13T11:00:00.000Z" }),
+    card({ id: "b", startUtc: "2026-07-13T11:00:00.000Z", endUtc: "2026-07-13T12:00:00.000Z" }),
+    card({ id: "c", startUtc: "2026-07-15T09:00:00.000Z", endUtc: "2026-07-15T10:00:00.000Z" }),
+    card({ id: "d", startUtc: "2026-07-17T09:00:00.000Z", endUtc: "2026-07-17T10:00:00.000Z" }),
+    card({ id: "e", startUtc: "2026-07-17T10:00:00.000Z", endUtc: "2026-07-17T11:00:00.000Z" }),
+  ];
+  const dashboard = buildWeeklyDashboard(cards, {
+    ...options(),
+    attributions: attributions(
+      ["a", { app: "  Code  " }],
+      ["b", { app: "Chrome", domain: "GitHub.com" }],
+      ["c", { app: "Chrome", domain: "github.com" }],
+      ["d", { app: "Zed" }],
+      ["e", { app: "Alpha" }],
+    ),
+  });
+  // Chrome 2h, Code 1h; Zed and Alpha tie at 1h and sort by key ascending.
+  assert.deepEqual(dashboard.sources.applications, [
+    { key: "Chrome", durationMs: 2 * HOUR },
+    { key: "Alpha", durationMs: HOUR },
+    { key: "Code", durationMs: HOUR },
+    { key: "Zed", durationMs: HOUR },
+  ]);
+  // Domains are normalized to lowercase; only attributed browser time counts.
+  assert.deepEqual(dashboard.sources.domains, [{ key: "github.com", durationMs: 2 * HOUR }]);
+});
+
+test("a card crossing a week bound is clipped once and flagged as uncertain coverage", () => {
+  const cards = [
+    card({
+      id: "spills-before",
+      startUtc: "2026-07-12T23:00:00.000Z",
+      endUtc: "2026-07-13T01:00:00.000Z",
+    }),
+  ];
+  const dashboard = buildWeeklyDashboard(cards, {
+    ...options(),
+    attributions: attributions(["spills-before", { app: "Code" }]),
+  });
+  assert.equal(dashboard.sources.applications[0]?.durationMs, HOUR);
+  assert.equal(dashboard.uncertainty.clippedCardCount, 1);
+  // The in-week part lands on Monday only; Sunday belongs to the prior week.
+  assert.equal(dashboard.days.find((day) => day.date === "2026-07-13")?.activeMs, HOUR);
+});
+
+test("topSourceLimit caps each source list; default limit is 10", () => {
+  assert.equal(DEFAULT_TOP_SOURCE_LIMIT, 10);
+  const cards = [
+    card({ id: "a", startUtc: "2026-07-13T10:00:00.000Z", endUtc: "2026-07-13T11:00:00.000Z" }),
+    card({ id: "b", startUtc: "2026-07-14T10:00:00.000Z", endUtc: "2026-07-14T11:00:00.000Z" }),
+  ];
+  const dashboard = buildWeeklyDashboard(cards, {
+    ...options(),
+    topSourceLimit: 1,
+    attributions: attributions(["a", { app: "Beta" }], ["b", { app: "Alpha" }]),
+  });
+  assert.deepEqual(dashboard.sources.applications, [{ key: "Alpha", durationMs: HOUR }]);
+});
+
+test("recurring patterns gate on distinct days for categories and applications", () => {
+  const cards = [
+    // development on Mon/Tue/Wed -> recurring.
+    card({ id: "d1", startUtc: "2026-07-13T10:00:00.000Z", endUtc: "2026-07-13T11:00:00.000Z" }),
+    card({ id: "d2", startUtc: "2026-07-14T10:00:00.000Z", endUtc: "2026-07-14T11:00:00.000Z" }),
+    card({ id: "d3", startUtc: "2026-07-15T10:00:00.000Z", endUtc: "2026-07-15T11:00:00.000Z" }),
+    // communication on Mon/Tue only -> not recurring.
+    card({
+      id: "c1",
+      categoryId: "communication",
+      startUtc: "2026-07-13T12:00:00.000Z",
+      endUtc: "2026-07-13T13:00:00.000Z",
+    }),
+    card({
+      id: "c2",
+      categoryId: "communication",
+      startUtc: "2026-07-14T12:00:00.000Z",
+      endUtc: "2026-07-14T13:00:00.000Z",
+    }),
+  ];
+  const dashboard = buildWeeklyDashboard(cards, {
+    ...options(),
+    attributions: attributions(
+      ["d1", { app: "Code" }],
+      ["d2", { app: "Code" }],
+      ["d3", { app: "Code" }],
+      ["c1", { app: "Chat" }],
+      ["c2", { app: "Chat" }],
+    ),
+  });
+  assert.deepEqual(dashboard.recurring.categories, [
+    { key: "development", dayCount: 3, totalDurationMs: 3 * HOUR },
+  ]);
+  assert.deepEqual(dashboard.recurring.applications, [
+    { key: "Code", dayCount: 3, totalDurationMs: 3 * HOUR },
+  ]);
+});
+
+test("previous week cards produce explicit deltas; absent stays explicitly unavailable", () => {
+  const current = [
+    card({ id: "now", startUtc: "2026-07-13T10:00:00.000Z", endUtc: "2026-07-13T12:00:00.000Z" }),
+  ];
+  const previous = [
+    card({ id: "then", startUtc: "2026-07-06T10:00:00.000Z", endUtc: "2026-07-06T13:00:00.000Z" }),
+  ];
+  const compared = buildWeeklyDashboard(current, { ...options(), previousWeekCards: previous });
+  assert.equal(compared.previousPeriod.available, true);
+  if (compared.previousPeriod.available) {
+    assert.equal(compared.previousPeriod.previousStartUtc, PREV_WEEK_START);
+    assert.equal(compared.previousPeriod.previousEndUtc, WEEK_START);
+    assert.equal(compared.previousPeriod.deltaActiveMs, -HOUR);
+    assert.equal(compared.previousPeriod.deltaIdleMs, 0);
+  }
+  const first = buildWeeklyDashboard(current, options());
+  assert.deepEqual(first.previousPeriod, { available: false });
+});
+
+test("evidence counts and uncertainty flags reflect only in-week activity", () => {
+  const cards = [
+    card({
+      id: "plain",
+      startUtc: "2026-07-13T10:00:00.000Z",
+      endUtc: "2026-07-13T11:00:00.000Z",
+      evidenceIds: [1, 2],
+    }),
+    card({
+      id: "repeat",
+      startUtc: "2026-07-14T10:00:00.000Z",
+      endUtc: "2026-07-14T11:00:00.000Z",
+      evidenceIds: [2, 3],
+    }),
+    card({
+      id: "edited",
+      startUtc: "2026-07-15T10:00:00.000Z",
+      endUtc: "2026-07-15T11:00:00.000Z",
+      manualEdit: { editedAtUtc: "2026-07-15T12:00:00.000Z" },
+    }),
+    card({
+      id: "mystery",
+      categoryId: "system.unknown",
+      confidence: 0,
+      startUtc: "2026-07-16T10:00:00.000Z",
+      endUtc: "2026-07-16T11:00:00.000Z",
+    }),
+    card({
+      id: "idle",
+      kind: "idle",
+      categoryId: "system.idle",
+      startUtc: "2026-07-13T15:00:00.000Z",
+      endUtc: "2026-07-13T16:00:00.000Z",
+    }),
+    card({
+      id: "pause",
+      kind: "pause",
+      categoryId: "system.pause",
+      startUtc: "2026-07-13T16:00:00.000Z",
+      endUtc: "2026-07-13T17:00:00.000Z",
+    }),
+    // Fully outside the week: counted nowhere.
+    card({ id: "outside", startUtc: "2026-08-01T10:00:00.000Z", endUtc: "2026-08-01T11:00:00.000Z" }),
+  ];
+  const dashboard = buildWeeklyDashboard(cards, options());
+  assert.deepEqual(dashboard.evidence, {
+    activityCardCount: 4,
+    idleCardCount: 1,
+    pauseCardCount: 1,
+    evidenceCount: 4,
+    distinctEvidenceCount: 3,
+  });
+  assert.deepEqual(dashboard.uncertainty, {
+    clippedCardCount: 0,
+    manualEditCount: 1,
+    unclassifiedCardCount: 1,
+  });
+});
+
+test("a deleted category flows to unclassified and never recurs as a pattern", () => {
+  const cards = [
+    card({ id: "g1", categoryId: "gone", startUtc: "2026-07-13T10:00:00.000Z", endUtc: "2026-07-13T11:00:00.000Z" }),
+    card({ id: "g2", categoryId: "gone", startUtc: "2026-07-14T10:00:00.000Z", endUtc: "2026-07-14T11:00:00.000Z" }),
+    card({ id: "g3", categoryId: "gone", startUtc: "2026-07-15T10:00:00.000Z", endUtc: "2026-07-15T11:00:00.000Z" }),
+  ];
+  const dashboard = buildWeeklyDashboard(cards, options());
+  assert.equal(dashboard.unclassifiedMs, 3 * HOUR);
+  assert.deepEqual(dashboard.recurring.categories, []);
+  assert.ok(dashboard.categories.every((total) => total.categoryId !== "gone"));
+});
+
+test("card input order never changes the serialized snapshot bytes", () => {
+  const cards = [
+    card({ id: "a", startUtc: "2026-07-13T10:00:00.000Z", endUtc: "2026-07-13T11:00:00.000Z" }),
+    card({ id: "b", startUtc: "2026-07-14T10:00:00.000Z", endUtc: "2026-07-14T11:00:00.000Z" }),
+    card({ id: "c", startUtc: "2026-07-15T10:00:00.000Z", endUtc: "2026-07-15T11:00:00.000Z" }),
+  ];
+  const base = {
+    ...options(),
+    attributions: attributions(
+      ["a", { app: "Code", domain: "github.com" }],
+      ["b", { app: "Chat" }],
+      ["c", { app: "Code", domain: "github.com" }],
+    ),
+  };
+  const forward = JSON.stringify(buildWeeklyDashboard(cards, base));
+  const reversed = JSON.stringify(buildWeeklyDashboard([...cards].reverse(), base));
+  assert.equal(forward, reversed);
+});
+
+test("dashboard persists through the weekly snapshot store idempotently", () => {
+  const memoryDir = mkdtempSync(path.join(tmpdir(), "remnic-week-dashboard-"));
+  const cards = [
+    card({ id: "a", startUtc: "2026-07-13T10:00:00.000Z", endUtc: "2026-07-13T11:00:00.000Z" }),
+  ];
+  const dashboard = buildWeeklyDashboard(cards, {
+    ...options(),
+    attributions: attributions(["a", { app: "Code", domain: "github.com" }]),
+  });
+  const shared = {
+    memoryDir,
+    namespace: "dash-1",
+    summary: dashboard,
+    sourceRevision: "rev-1",
+    configHash: "cfg-1",
+  };
+  const first = persistWeeklySnapshot(shared);
+  assert.equal(first.written, true);
+  assert.ok(first.path.includes(path.join("activity", "weekly")));
+  const bytes = readFileSync(first.path, "utf8");
+  const parsed = JSON.parse(bytes);
+  assert.equal(parsed.namespace, "dash-1");
+  assert.equal(parsed.summary.sources.domains[0].key, "github.com");
+
+  const again = persistWeeklySnapshot(shared);
+  assert.equal(again.written, false);
+  assert.equal(again.path, first.path);
+  assert.equal(readFileSync(first.path, "utf8"), bytes);
+
+  const reconfigured = persistWeeklySnapshot({ ...shared, configHash: "cfg-2" });
+  assert.equal(reconfigured.written, true);
+  assert.notEqual(reconfigured.path, first.path);
+  assert.equal(readFileSync(first.path, "utf8"), bytes);
+});
+
+test("retention plans expired weekly snapshots for deletion and keeps fresh ones", () => {
+  const now = Date.parse("2026-07-20T00:00:00.000Z");
+  const DAY = 86_400_000;
+  const expired = now - 40 * DAY;
+  const plan = planActivityDeletion({
+    candidates: [
+      { scope: "weekly", relPath: "activity/weekly/dash-1/2026-06-08--abc.json", capturedAtMs: expired },
+      { scope: "weekly", relPath: "activity/weekly/dash-1/2026-07-13--def.json", capturedAtMs: now - DAY },
+    ],
+    scopes: ["weekly"],
+    retentionDays: 30,
+    nowMs: now,
+  });
+  assert.deepEqual(plan.deletePaths, ["activity/weekly/dash-1/2026-06-08--abc.json"]);
+});
+
+test("invalid inputs throw RangeError without partial output", () => {
+  const cards = [
+    card({ id: "a", startUtc: "2026-07-13T10:00:00.000Z", endUtc: "2026-07-13T11:00:00.000Z" }),
+  ];
+  assert.throws(
+    () => buildWeeklyDashboard(cards, { ...options(), topSourceLimit: 0 }),
+    (err: unknown) => err instanceof RangeError && /topSourceLimit/.test((err as Error).message),
+  );
+  assert.throws(
+    () =>
+      buildWeeklyDashboard(cards, {
+        ...options(),
+        attributions: attributions(["a", { app: "   " }]),
+      }),
+    (err: unknown) => err instanceof RangeError && /app/.test((err as Error).message),
+  );
+  assert.throws(
+    () =>
+      buildWeeklyDashboard(cards, {
+        ...options(),
+        attributions: attributions(["a", { app: "Code", domain: "" }]),
+      }),
+    (err: unknown) => err instanceof RangeError && /domain/.test((err as Error).message),
+  );
+});

package/src/activity/timeline/week-dashboard.ts

@@ -0,0 +1,273 @@
+/**
+ * Weekly dashboard snapshot composition (issue #2052).
+ *
+ * Composes the #2052 helpers into one machine-readable week document:
+ * duration/category/day totals (`weekly.ts`), an explicit previous-period
+ * comparison (`week-previous.ts`), threshold-gated recurrence
+ * (`week-recurring.ts`), top application/domain summaries, source
+ * card/evidence counts, and uncertainty flags. Pure: no I/O, no clock, no
+ * LLM. This is a time/activity summary, never a score; it makes no claim
+ * about mood, productivity, intent, presence, or quality of work.
+ *
+ * The result extends `WeeklyActivitySummary`, so `persistWeeklySnapshot`
+ * accepts it unchanged: identical inputs rewrite nothing, and a new
+ * sourceRevision or configHash keys a new snapshot file instead of mutating
+ * an unrelated period. Application/domain attribution arrives as structured
+ * per-card metadata (from the observations that built the cards), never
+ * parsed back out of card prose.
+ */
+import type { TimelineCard } from "./types.js";
+import { compareWeeklyPreviousPeriod, type WeeklyPreviousPeriod } from "./week-previous.js";
+import {
+  findRecurringPatterns,
+  type RecurringPattern,
+  type WeekDayOccurrence,
+} from "./week-recurring.js";
+import {
+  buildWeeklyActivitySummary,
+  type WeeklyActivityOptions,
+  type WeeklyActivitySummary,
+} from "./weekly.js";
+
+export const WEEKLY_DASHBOARD_FORMAT_VERSION = 1;
+export const DEFAULT_TOP_SOURCE_LIMIT = 10;
+const DAY_MS = 86_400_000;
+const WEEK_DAYS_MS = 7 * DAY_MS;
+
+/** Structured activity metadata for one card, keyed by card id. */
+export interface WeekSourceAttribution {
+  /** Application name from the card's source observations. */
+  app: string;
+  /** Lowercased browser hostname, when the frontmost window was a browser. */
+  domain?: string;
+}
+
+export interface WeeklySourceTotal {
+  key: string;
+  durationMs: number;
+}
+
+export interface WeeklyEvidenceStats {
+  activityCardCount: number;
+  idleCardCount: number;
+  pauseCardCount: number;
+  /** Evidence ids summed across in-week activity cards; repeats possible. */
+  evidenceCount: number;
+  /** Distinct evidence ids across in-week activity cards. */
+  distinctEvidenceCount: number;
+}
+
+export interface WeeklyUncertainty {
+  /** In-week cards clipped at a week bound: the week sees only part of them. */
+  clippedCardCount: number;
+  /** In-week cards carrying a manual edit; totals may not match raw captures. */
+  manualEditCount: number;
+  /** In-week cards classified with confidence 0 (unclassified signal). */
+  unclassifiedCardCount: number;
+}
+
+export interface WeeklyDashboardSources {
+  applications: WeeklySourceTotal[];
+  domains: WeeklySourceTotal[];
+}
+
+export interface WeeklyDashboardRecurring {
+  categories: RecurringPattern[];
+  applications: RecurringPattern[];
+}
+
+export interface WeeklyDashboard extends WeeklyActivitySummary {
+  dashboardFormatVersion: number;
+  sources: WeeklyDashboardSources;
+  recurring: WeeklyDashboardRecurring;
+  evidence: WeeklyEvidenceStats;
+  uncertainty: WeeklyUncertainty;
+}
+
+export interface WeeklyDashboardOptions extends WeeklyActivityOptions {
+  /** Per-card application/domain metadata; cards without an entry are skipped in `sources`. */
+  attributions?: ReadonlyMap<string, WeekSourceAttribution>;
+  /** Cards of the immediately preceding week; absent keeps `previousPeriod` explicitly unavailable. */
+  previousWeekCards?: readonly TimelineCard[];
+  /** Distinct-day threshold passed to `findRecurringPatterns`. */
+  recurrenceMinDays?: number;
+  /** Max entries per source list; >= 1. */
+  topSourceLimit?: number;
+}
+
+interface ClippedCard {
+  card: TimelineCard;
+  startMs: number;
+  endMs: number;
+  clipStartMs: number;
+  clipEndMs: number;
+}
+
+function clippedInWeek(
+  cards: readonly TimelineCard[],
+  weekStartMs: number,
+  weekEndMs: number,
+): ClippedCard[] {
+  const clipped: ClippedCard[] = [];
+  for (const card of cards) {
+    const startMs = Date.parse(card.startUtc);
+    const endMs = Date.parse(card.endUtc);
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs <= startMs) continue;
+    const clipStartMs = Math.max(startMs, weekStartMs);
+    const clipEndMs = Math.min(endMs, weekEndMs);
+    if (clipEndMs > clipStartMs) {
+      clipped.push({ card, startMs, endMs, clipStartMs, clipEndMs });
+    }
+  }
+  return clipped;
+}
+
+function normalizedAttribution(
+  cardId: string,
+  attributions: ReadonlyMap<string, WeekSourceAttribution> | undefined,
+): { app: string; domain?: string } | null {
+  const attribution = attributions?.get(cardId);
+  if (attribution === undefined) return null;
+  if (typeof attribution.app !== "string" || attribution.app.trim() === "") {
+    throw new RangeError(`attribution for card ${cardId} must have a non-blank app`);
+  }
+  const app = attribution.app.trim();
+  if (attribution.domain === undefined) return { app };
+  if (typeof attribution.domain !== "string" || attribution.domain.trim() === "") {
+    throw new RangeError(`attribution for card ${cardId} must have a non-blank domain when present`);
+  }
+  return { app, domain: attribution.domain.trim().toLowerCase() };
+}
+
+function rankTotals(totals: Map<string, number>, limit: number): WeeklySourceTotal[] {
+  return [...totals.entries()]
+    .map(([key, durationMs]) => ({ key, durationMs }))
+    .sort(
+      (a, b) =>
+        b.durationMs - a.durationMs || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0),
+    )
+    .slice(0, limit);
+}
+
+/** Build the full dashboard snapshot for one half-open week. Pure. */
+export function buildWeeklyDashboard(
+  cards: readonly TimelineCard[],
+  options: WeeklyDashboardOptions,
+): WeeklyDashboard {
+  const summary = buildWeeklyActivitySummary(cards, options);
+  const topSourceLimit = options.topSourceLimit ?? DEFAULT_TOP_SOURCE_LIMIT;
+  if (!Number.isInteger(topSourceLimit) || topSourceLimit < 1) {
+    throw new RangeError(`topSourceLimit must be an integer >= 1; got ${topSourceLimit}`);
+  }
+
+  // Canonical bounds from the summary: identical clipping arithmetic to
+  // weekly.ts regardless of how the caller spelled the input timestamps.
+  const weekStartMs = Date.parse(summary.weekStartUtc);
+  const weekEndMs = Date.parse(summary.weekEndUtc);
+  const inWeek = clippedInWeek(cards, weekStartMs, weekEndMs);
+
+  const applicationTotals = new Map<string, number>();
+  const domainTotals = new Map<string, number>();
+  const applicationOccurrences: WeekDayOccurrence[] = [];
+  const categoryOccurrences: WeekDayOccurrence[] = [];
+  const evidence: WeeklyEvidenceStats = {
+    activityCardCount: 0,
+    idleCardCount: 0,
+    pauseCardCount: 0,
+    evidenceCount: 0,
+    distinctEvidenceCount: 0,
+  };
+  const uncertainty: WeeklyUncertainty = {
+    clippedCardCount: 0,
+    manualEditCount: 0,
+    unclassifiedCardCount: 0,
+  };
+  const distinctEvidence = new Set<number>();
+  const dayWindows = summary.days.map((day) => ({
+    date: day.date,
+    startMs: Date.parse(day.startUtc),
+    endMs: Date.parse(day.endUtc),
+  }));
+
+  for (const day of summary.days) {
+    for (const total of day.categories) {
+      if (total.durationMs > 0) {
+        categoryOccurrences.push({ date: day.date, key: total.categoryId, durationMs: total.durationMs });
+      }
+    }
+  }
+
+  for (const { card, startMs, endMs, clipStartMs, clipEndMs } of inWeek) {
+    if (startMs < weekStartMs || endMs > weekEndMs) {
+      uncertainty.clippedCardCount++;
+    }
+    if (card.kind === "idle") {
+      evidence.idleCardCount++;
+      continue;
+    }
+    if (card.kind === "pause") {
+      evidence.pauseCardCount++;
+      continue;
+    }
+    evidence.activityCardCount++;
+    for (const id of card.evidenceIds) {
+      evidence.evidenceCount++;
+      distinctEvidence.add(id);
+    }
+    if (card.manualEdit !== undefined) uncertainty.manualEditCount++;
+    if (card.confidence === 0) uncertainty.unclassifiedCardCount++;
+
+    const attribution = normalizedAttribution(card.id, options.attributions);
+    if (attribution === null) continue;
+    const durationMs = clipEndMs - clipStartMs;
+    applicationTotals.set(attribution.app, (applicationTotals.get(attribution.app) ?? 0) + durationMs);
+    if (attribution.domain !== undefined) {
+      domainTotals.set(attribution.domain, (domainTotals.get(attribution.domain) ?? 0) + durationMs);
+    }
+    for (const day of dayWindows) {
+      const dayStartMs = Math.max(clipStartMs, day.startMs);
+      const dayEndMs = Math.min(clipEndMs, day.endMs);
+      if (dayEndMs > dayStartMs) {
+        applicationOccurrences.push({ date: day.date, key: attribution.app, durationMs: dayEndMs - dayStartMs });
+      }
+    }
+  }
+  evidence.distinctEvidenceCount = distinctEvidence.size;
+
+  let previousPeriod: WeeklyPreviousPeriod = { available: false };
+  if (options.previousWeekCards !== undefined) {
+    const previousSummary = buildWeeklyActivitySummary(options.previousWeekCards, {
+      ...options,
+      weekStartUtc: new Date(weekStartMs - WEEK_DAYS_MS).toISOString(),
+      weekEndUtc: summary.weekStartUtc,
+    });
+    previousPeriod = compareWeeklyPreviousPeriod({
+      previous: previousSummary,
+      current: summary,
+      previousStartUtc: previousSummary.weekStartUtc,
+      previousEndUtc: previousSummary.weekEndUtc,
+    });
+  }
+
+  return {
+    ...summary,
+    previousPeriod,
+    dashboardFormatVersion: WEEKLY_DASHBOARD_FORMAT_VERSION,
+    sources: {
+      applications: rankTotals(applicationTotals, topSourceLimit),
+      domains: rankTotals(domainTotals, topSourceLimit),
+    },
+    recurring: {
+      categories: findRecurringPatterns({
+        occurrences: categoryOccurrences,
+        minDays: options.recurrenceMinDays,
+      }),
+      applications: findRecurringPatterns({
+        occurrences: applicationOccurrences,
+        minDays: options.recurrenceMinDays,
+      }),
+    },
+    evidence,
+    uncertainty,
+  };
+}

package/src/activity/timeline/weekly.ts

@@ -8,6 +8,7 @@
  */
 import { parseFlexibleIsoTimestamp } from "../../utils/iso-timestamp.js";
 import { activityDayWindow, assertValidTimezone } from "../digest.js";
+import type { WeeklyPreviousPeriod } from "./week-previous.js";
 import type { TimelineCard, TimelineCardKind, TimelineCategory } from "./types.js";
 
 export const WEEKLY_ACTIVITY_FORMAT_VERSION = 1;
@@ -51,7 +52,7 @@ export interface WeeklyActivitySummary extends WeeklyKindTotals {
   weekEndUtc: string;
   categories: WeeklyCategoryTotal[];
   days: WeeklyDayTotal[];
-  previousPeriod: WeeklyPreviousPeriodUnavailable;
+  previousPeriod: WeeklyPreviousPeriod;
 }
 
 interface Acc extends WeeklyKindTotals {