@remnic/core 9.66.0 → 9.66.2

package/src/activity/timeline/weekly-persist.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { RECALL_FALLBACK_DIRS } from "../../utils/category-dir.js";
+import type { TimelineCategory } from "./types.js";
+import { persistWeeklySnapshot } from "./weekly-persist.js";
+import { buildWeeklyActivitySummary } from "./weekly.js";
+
+const WEEK_START = "2026-07-13T00:00:00.000Z";
+const WEEK_END = "2026-07-20T00:00:00.000Z";
+const OTHER_WEEK_START = "2026-07-20T00:00:00.000Z";
+const OTHER_WEEK_END = "2026-07-27T00:00:00.000Z";
+
+const CATEGORIES: TimelineCategory[] = [
+  { id: "development", name: "Development", color: "#333333", description: "d", order: 1 },
+];
+
+function summary(weekStartUtc = WEEK_START, weekEndUtc = WEEK_END) {
+  return buildWeeklyActivitySummary([], {
+    timezone: "UTC",
+    weekStartUtc,
+    weekEndUtc,
+    categories: CATEGORIES,
+  });
+}
+
+function withMemoryDir(fn: (memoryDir: string) => void): void {
+  const memoryDir = mkdtempSync(path.join(tmpdir(), "remnic-weekly-persist-"));
+  try {
+    fn(memoryDir);
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+}
+
+function assertOutsideRecallRoots(filePath: string, memoryDir: string): void {
+  const relative = path.relative(memoryDir, filePath);
+  assert.ok(relative.startsWith(`activity${path.sep}weekly${path.sep}`));
+  assert.ok(
+    !RECALL_FALLBACK_DIRS.some((dir) => relative === dir || relative.startsWith(`${dir}${path.sep}`)),
+  );
+}
+
+test("same inputs skip rewrite by content hash", () => {
+  withMemoryDir((memoryDir) => {
+    const input = {
+      memoryDir,
+      namespace: "team",
+      summary: summary(),
+      sourceRevision: "rev-1",
+      configHash: "cfg-1",
+    };
+    const first = persistWeeklySnapshot(input);
+    assert.equal(first.written, true);
+    assertOutsideRecallRoots(first.path, memoryDir);
+    const firstBytes = readFileSync(first.path, "utf8");
+    const firstStat = statSync(first.path);
+    const snapshot = JSON.parse(firstBytes) as { contentHash: string };
+    assert.equal(typeof snapshot.contentHash, "string");
+    assert.equal(snapshot.contentHash.length, 64);
+
+    const second = persistWeeklySnapshot(input);
+    assert.equal(second.written, false);
+    assert.equal(second.path, first.path);
+    assert.equal(readFileSync(first.path, "utf8"), firstBytes);
+    assert.equal(statSync(first.path).mtimeMs, firstStat.mtimeMs);
+  });
+});
+
+test("changed sourceRevision or configHash writes a new file and leaves other weeks", () => {
+  withMemoryDir((memoryDir) => {
+    const base = {
+      memoryDir,
+      namespace: "team",
+      summary: summary(),
+      sourceRevision: "rev-1",
+      configHash: "cfg-1",
+    };
+    const original = persistWeeklySnapshot(base);
+    const originalBytes = readFileSync(original.path, "utf8");
+
+    const revised = persistWeeklySnapshot({ ...base, sourceRevision: "rev-2" });
+    assert.notEqual(revised.path, original.path);
+    assert.equal(revised.written, true);
+    assert.equal(readFileSync(original.path, "utf8"), originalBytes);
+
+    const reconfigured = persistWeeklySnapshot({ ...base, configHash: "cfg-2" });
+    assert.notEqual(reconfigured.path, original.path);
+    assert.notEqual(reconfigured.path, revised.path);
+    assert.equal(readFileSync(original.path, "utf8"), originalBytes);
+
+    const otherWeek = persistWeeklySnapshot({
+      ...base,
+      summary: summary(OTHER_WEEK_START, OTHER_WEEK_END),
+    });
+    assert.notEqual(otherWeek.path, original.path);
+    assert.equal(readFileSync(original.path, "utf8"), originalBytes);
+    assert.equal(JSON.parse(readFileSync(otherWeek.path, "utf8")).summary.weekStartUtc, OTHER_WEEK_START);
+  });
+});
+
+test("snapshots are namespace scoped", () => {
+  withMemoryDir((memoryDir) => {
+    const shared = {
+      memoryDir,
+      summary: summary(),
+      sourceRevision: "rev-1",
+      configHash: "cfg-1",
+    };
+    const alpha = persistWeeklySnapshot({ ...shared, namespace: "alpha" });
+    const beta = persistWeeklySnapshot({ ...shared, namespace: "beta" });
+    assert.notEqual(alpha.path, beta.path);
+    assert.equal(JSON.parse(readFileSync(alpha.path, "utf8")).namespace, "alpha");
+    assert.equal(JSON.parse(readFileSync(beta.path, "utf8")).namespace, "beta");
+    assert.equal(readdirSync(path.dirname(alpha.path)).length, 1);
+    assert.equal(readdirSync(path.dirname(beta.path)).length, 1);
+  });
+});

package/src/activity/timeline/weekly-persist.ts

@@ -0,0 +1,103 @@
+/**
+ * Versioned weekly time/activity snapshot store (issue #2052).
+ *
+ * Files live at `<memoryDir>/activity/weekly/<ns>/<week>--<identity>.json`,
+ * outside recall fallback dirs. Same inputs skip rewrite by content hash.
+ * A new sourceRevision or configHash is a new file.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { namespaceIdentityToken } from "../../namespaces/identity.js";
+import { hashActivityBody, isValidActivityDate } from "../digest.js";
+import type { WeeklyActivitySummary } from "./weekly.js";
+
+export const WEEKLY_SNAPSHOT_FORMAT_VERSION = 1;
+export const WEEKLY_SNAPSHOT_DIR = path.join("activity", "weekly");
+
+export interface PersistWeeklySnapshotInput {
+  memoryDir: string;
+  namespace: string;
+  summary: WeeklyActivitySummary;
+  sourceRevision: string;
+  configHash: string;
+}
+
+export interface PersistWeeklySnapshotResult {
+  path: string;
+  written: boolean;
+}
+
+function requireToken(value: string, name: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+export function weeklySnapshotPath(input: PersistWeeklySnapshotInput): string {
+  const memoryDir = requireToken(input.memoryDir, "memoryDir");
+  const namespace = requireToken(input.namespace, "namespace");
+  const sourceRevision = requireToken(input.sourceRevision, "sourceRevision");
+  const configHash = requireToken(input.configHash, "configHash");
+  const weekStartUtc = input.summary?.weekStartUtc;
+  if (typeof weekStartUtc !== "string") {
+    throw new TypeError("summary.weekStartUtc must be an ISO timestamp");
+  }
+  const weekDate = weekStartUtc.slice(0, 10);
+  if (!isValidActivityDate(weekDate)) {
+    throw new RangeError("summary.weekStartUtc must be an ISO timestamp");
+  }
+  const identity = hashActivityBody(
+    `${input.summary.weekStartUtc}\0${input.summary.weekEndUtc}\0${sourceRevision}\0${configHash}`,
+  );
+  return path.join(
+    path.resolve(memoryDir),
+    WEEKLY_SNAPSHOT_DIR,
+    namespaceIdentityToken(namespace),
+    `${weekDate}--${identity}.json`,
+  );
+}
+
+/** Persist one weekly snapshot. Same bytes are a no-op. */
+export function persistWeeklySnapshot(input: PersistWeeklySnapshotInput): PersistWeeklySnapshotResult {
+  const namespace = requireToken(input.namespace, "namespace");
+  const sourceRevision = requireToken(input.sourceRevision, "sourceRevision");
+  const configHash = requireToken(input.configHash, "configHash");
+  const filePath = weeklySnapshotPath(input);
+  const payload = {
+    formatVersion: WEEKLY_SNAPSHOT_FORMAT_VERSION,
+    namespace,
+    sourceRevision,
+    configHash,
+    summary: input.summary,
+  };
+  const contentHash = hashActivityBody(JSON.stringify(payload));
+  const text = `${JSON.stringify({ ...payload, contentHash })}\n`;
+
+  try {
+    if (readFileSync(filePath, "utf8") === text) {
+      return { path: filePath, written: false };
+    }
+  } catch (error) {
+    if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+
+  mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmpPath = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+  writeFileSync(tmpPath, text, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(tmpPath, filePath);
+  } catch (error) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // Best-effort cleanup of the temp file.
+    }
+    throw error;
+  }
+  return { path: filePath, written: true };
+}

package/src/activity/timeline/weekly.test.ts

@@ -0,0 +1,215 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { TimelineCard, TimelineCategory } from "./types.js";
+import { buildWeeklyActivitySummary } from "./weekly.js";
+
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+const WEEK_START = "2026-07-13T00:00:00.000Z";
+const WEEK_END = "2026-07-20T00:00:00.000Z";
+const WEEK_MS = 7 * DAY;
+
+const CATEGORIES: TimelineCategory[] = [
+  { id: "alpha", name: "Alpha", color: "#111111", description: "a", order: 1 },
+  { id: "beta", name: "Beta", color: "#222222", description: "b", order: 2 },
+  { id: "development", name: "Development", color: "#333333", description: "d", order: 3 },
+];
+
+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 buildWeeklyActivitySummary>[1]> = {}) {
+  return {
+    timezone: "UTC",
+    weekStartUtc: WEEK_START,
+    weekEndUtc: WEEK_END,
+    categories: CATEGORIES,
+    ...overrides,
+  };
+}
+
+test("empty week reports zeros, full gap, and previous period unavailable", () => {
+  const summary = buildWeeklyActivitySummary([], options());
+  assert.equal(summary.formatVersion, 1);
+  assert.equal(summary.activeMs, 0);
+  assert.equal(summary.idleMs, 0);
+  assert.equal(summary.pauseMs, 0);
+  assert.equal(summary.unclassifiedMs, 0);
+  assert.equal(summary.gapMs, WEEK_MS);
+  assert.deepEqual(
+    summary.categories.map((row) => row.durationMs),
+    [0, 0, 0],
+  );
+  assert.equal(summary.days.length, 7);
+  assert.ok(summary.days.every((day) => day.gapMs === DAY && day.activeMs === 0));
+  assert.deepEqual(summary.previousPeriod, { available: false });
+  assert.equal("durationMs" in summary.previousPeriod, false);
+  const blob = JSON.stringify(summary);
+  assert.equal(/productivity|mood|intent|score/i.test(blob), false);
+});
+
+test("exact midnight boundary is not double-counted", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "ends-at-midnight",
+        categoryId: "alpha",
+        startUtc: "2026-07-13T23:00:00.000Z",
+        endUtc: "2026-07-14T00:00:00.000Z",
+      }),
+      card({
+        id: "starts-at-midnight",
+        categoryId: "beta",
+        startUtc: "2026-07-14T00:00:00.000Z",
+        endUtc: "2026-07-14T01:00:00.000Z",
+      }),
+      card({
+        id: "before-week",
+        categoryId: "development",
+        startUtc: "2026-07-12T23:00:00.000Z",
+        endUtc: WEEK_START,
+      }),
+      card({
+        id: "after-week",
+        categoryId: "development",
+        startUtc: WEEK_END,
+        endUtc: "2026-07-20T01:00:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  assert.equal(summary.categories.find((row) => row.categoryId === "alpha")?.durationMs, HOUR);
+  assert.equal(summary.categories.find((row) => row.categoryId === "beta")?.durationMs, HOUR);
+  assert.equal(summary.categories.find((row) => row.categoryId === "development")?.durationMs, 0);
+  assert.equal(summary.activeMs, 2 * HOUR);
+
+  const day13 = summary.days.find((day) => day.date === "2026-07-13");
+  const day14 = summary.days.find((day) => day.date === "2026-07-14");
+  assert.equal(day13?.categories.find((row) => row.categoryId === "alpha")?.durationMs, HOUR);
+  assert.equal(day13?.categories.find((row) => row.categoryId === "beta")?.durationMs, 0);
+  assert.equal(day14?.categories.find((row) => row.categoryId === "beta")?.durationMs, HOUR);
+  assert.equal(day14?.categories.find((row) => row.categoryId === "alpha")?.durationMs, 0);
+});
+
+test("idle and pause kinds are distinct from active", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "work",
+        startUtc: "2026-07-13T10:00:00.000Z",
+        endUtc: "2026-07-13T11:00:00.000Z",
+      }),
+      card({
+        id: "idle",
+        kind: "idle",
+        categoryId: "alpha",
+        startUtc: "2026-07-13T11:00:00.000Z",
+        endUtc: "2026-07-13T11:30:00.000Z",
+      }),
+      card({
+        id: "pause",
+        kind: "pause",
+        categoryId: "beta",
+        startUtc: "2026-07-13T11:30:00.000Z",
+        endUtc: "2026-07-13T11:45:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  assert.equal(summary.activeMs, HOUR);
+  assert.equal(summary.idleMs, 30 * 60_000);
+  assert.equal(summary.pauseMs, 15 * 60_000);
+  assert.equal(summary.gapMs, WEEK_MS - HOUR - 30 * 60_000 - 15 * 60_000);
+});
+
+test("unknown category is unclassified, not a silent zero row", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "mystery",
+        categoryId: "not-configured",
+        startUtc: "2026-07-15T08:00:00.000Z",
+        endUtc: "2026-07-15T09:00:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  assert.equal(summary.unclassifiedMs, HOUR);
+  assert.equal(summary.activeMs, HOUR);
+  assert.equal(summary.categories.some((row) => row.categoryId === "not-configured"), false);
+  assert.ok(summary.categories.every((row) => row.durationMs === 0));
+});
+
+test("configured category with no cards stays at zero", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "only-dev",
+        categoryId: "development",
+        startUtc: "2026-07-16T12:00:00.000Z",
+        endUtc: "2026-07-16T13:00:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  const byId = Object.fromEntries(summary.categories.map((row) => [row.categoryId, row.durationMs]));
+  assert.equal(byId.development, HOUR);
+  assert.equal(byId.alpha, 0);
+  assert.equal(byId.beta, 0);
+  assert.equal(summary.categories.length, 3);
+});
+
+test("equal durations sort by categoryId ascending", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "a",
+        categoryId: "alpha",
+        startUtc: "2026-07-13T09:00:00.000Z",
+        endUtc: "2026-07-13T10:00:00.000Z",
+      }),
+      card({
+        id: "b",
+        categoryId: "beta",
+        startUtc: "2026-07-13T10:00:00.000Z",
+        endUtc: "2026-07-13T12:00:00.000Z",
+      }),
+      card({
+        id: "d",
+        categoryId: "development",
+        startUtc: "2026-07-13T12:00:00.000Z",
+        endUtc: "2026-07-13T14:00:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  assert.deepEqual(
+    summary.categories.map((row) => row.categoryId),
+    ["beta", "development", "alpha"],
+  );
+  assert.deepEqual(
+    summary.categories.map((row) => row.durationMs),
+    [2 * HOUR, 2 * HOUR, HOUR],
+  );
+  const day13 = summary.days.find((day) => day.date === "2026-07-13");
+  assert.deepEqual(
+    day13?.categories.map((row) => row.categoryId),
+    ["beta", "development", "alpha"],
+  );
+});

package/src/activity/timeline/weekly.ts

@@ -0,0 +1,234 @@
+/**
+ * Deterministic weekly time/activity summary over timeline cards (issue #2052).
+ *
+ * Pure: cards + week bounds + category registry in, snapshot out. Half-open
+ * UTC [weekStart, weekEnd). Previous-period comparison is omitted in this
+ * slice and marked unavailable, never a silent zero. Later surfaces
+ * (CLI/MCP/HTTP/UI) consume this shape; they are not built here.
+ */
+import { parseFlexibleIsoTimestamp } from "../../utils/iso-timestamp.js";
+import { activityDayWindow, assertValidTimezone } from "../digest.js";
+import type { TimelineCard, TimelineCardKind, TimelineCategory } from "./types.js";
+
+export const WEEKLY_ACTIVITY_FORMAT_VERSION = 1;
+
+export interface WeeklyActivityOptions {
+  timezone: string;
+  weekStartUtc: string;
+  weekEndUtc: string;
+  categories: readonly TimelineCategory[];
+}
+
+export interface WeeklyCategoryTotal {
+  categoryId: string;
+  durationMs: number;
+}
+
+export interface WeeklyKindTotals {
+  activeMs: number;
+  idleMs: number;
+  pauseMs: number;
+  gapMs: number;
+  unclassifiedMs: number;
+}
+
+export interface WeeklyDayTotal extends WeeklyKindTotals {
+  date: string;
+  startUtc: string;
+  endUtc: string;
+  categories: WeeklyCategoryTotal[];
+}
+
+/** First slice never computes a prior week; the field is present so callers cannot treat absence as zero. */
+export interface WeeklyPreviousPeriodUnavailable {
+  available: false;
+}
+
+export interface WeeklyActivitySummary extends WeeklyKindTotals {
+  formatVersion: number;
+  timezone: string;
+  weekStartUtc: string;
+  weekEndUtc: string;
+  categories: WeeklyCategoryTotal[];
+  days: WeeklyDayTotal[];
+  previousPeriod: WeeklyPreviousPeriodUnavailable;
+}
+
+interface Acc extends WeeklyKindTotals {
+  byCategory: Map<string, number>;
+  intervals: Array<[number, number]>;
+}
+
+function parseBound(value: string, label: string): number {
+  const ms = parseFlexibleIsoTimestamp(value);
+  if (ms === null) {
+    throw new RangeError(`${label} is not a valid ISO timestamp`);
+  }
+  return ms;
+}
+
+function clip(start: number, end: number, winStart: number, winEnd: number): [number, number] | null {
+  const clippedStart = Math.max(start, winStart);
+  const clippedEnd = Math.min(end, winEnd);
+  return clippedEnd > clippedStart ? [clippedStart, clippedEnd] : null;
+}
+
+function unionDuration(intervals: readonly (readonly [number, number])[]): number {
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  let total = 0;
+  let curStart = Number.NaN;
+  let curEnd = Number.NaN;
+  for (const [start, end] of sorted) {
+    if (!Number.isFinite(curStart)) {
+      curStart = start;
+      curEnd = end;
+      continue;
+    }
+    if (start <= curEnd) {
+      curEnd = Math.max(curEnd, end);
+      continue;
+    }
+    total += curEnd - curStart;
+    curStart = start;
+    curEnd = end;
+  }
+  if (Number.isFinite(curStart)) total += curEnd - curStart;
+  return total;
+}
+
+function localDateOf(ms: number, timezone: string): string {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(ms));
+  const get = (type: string): string => parts.find((part) => part.type === type)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")}`;
+}
+
+function shiftIsoDate(date: string, days: number): string {
+  const parsed = new Date(`${date}T00:00:00Z`);
+  parsed.setUTCDate(parsed.getUTCDate() + days);
+  return parsed.toISOString().slice(0, 10);
+}
+
+function daysOverlappingWeek(
+  weekStartMs: number,
+  weekEndMs: number,
+  timezone: string,
+): Array<{ date: string; startMs: number; endMs: number }> {
+  if (weekEndMs <= weekStartMs) return [];
+  let date = localDateOf(weekStartMs, timezone);
+  let window = activityDayWindow(date, timezone);
+  if (Date.parse(window.startUtc) > weekStartMs) {
+    date = shiftIsoDate(date, -1);
+    window = activityDayWindow(date, timezone);
+  }
+  const days: Array<{ date: string; startMs: number; endMs: number }> = [];
+  while (Date.parse(window.startUtc) < weekEndMs) {
+    const startMs = Math.max(Date.parse(window.startUtc), weekStartMs);
+    const endMs = Math.min(Date.parse(window.endUtc), weekEndMs);
+    if (endMs > startMs) days.push({ date, startMs, endMs });
+    date = shiftIsoDate(date, 1);
+    window = activityDayWindow(date, timezone);
+  }
+  return days;
+}
+
+function emptyAcc(categoryIds: readonly string[]): Acc {
+  return {
+    activeMs: 0,
+    idleMs: 0,
+    pauseMs: 0,
+    gapMs: 0,
+    unclassifiedMs: 0,
+    byCategory: new Map(categoryIds.map((id) => [id, 0])),
+    intervals: [],
+  };
+}
+
+function addClipped(acc: Acc, kind: TimelineCardKind, categoryId: string, known: ReadonlySet<string>, start: number, end: number): void {
+  const duration = end - start;
+  acc.intervals.push([start, end]);
+  if (kind === "idle") acc.idleMs += duration;
+  else if (kind === "pause") acc.pauseMs += duration;
+  else acc.activeMs += duration;
+  if (known.has(categoryId)) {
+    acc.byCategory.set(categoryId, (acc.byCategory.get(categoryId) ?? 0) + duration);
+  } else {
+    acc.unclassifiedMs += duration;
+  }
+}
+
+function sortCategoryTotals(byCategory: Map<string, number>): WeeklyCategoryTotal[] {
+  return [...byCategory.entries()]
+    .map(([categoryId, durationMs]) => ({ categoryId, durationMs }))
+    .sort((a, b) => b.durationMs - a.durationMs || (a.categoryId < b.categoryId ? -1 : a.categoryId > b.categoryId ? 1 : 0));
+}
+
+function finish(acc: Acc, windowMs: number): WeeklyKindTotals & { categories: WeeklyCategoryTotal[] } {
+  const covered = unionDuration(acc.intervals);
+  return {
+    activeMs: acc.activeMs,
+    idleMs: acc.idleMs,
+    pauseMs: acc.pauseMs,
+    gapMs: Math.max(0, windowMs - covered),
+    unclassifiedMs: acc.unclassifiedMs,
+    categories: sortCategoryTotals(acc.byCategory),
+  };
+}
+
+/** Build a time/activity summary for one half-open week. Pure. */
+export function buildWeeklyActivitySummary(
+  cards: readonly TimelineCard[],
+  options: WeeklyActivityOptions,
+): WeeklyActivitySummary {
+  assertValidTimezone(options.timezone);
+  const weekStartMs = parseBound(options.weekStartUtc, "weekStartUtc");
+  const weekEndMs = parseBound(options.weekEndUtc, "weekEndUtc");
+  if (weekStartMs > weekEndMs) {
+    throw new RangeError("reversed range: weekStartUtc must be <= weekEndUtc");
+  }
+
+  const categoryIds = options.categories.map((category) => category.id);
+  const known = new Set(categoryIds);
+  const week = emptyAcc(categoryIds);
+  const dayWindows = daysOverlappingWeek(weekStartMs, weekEndMs, options.timezone);
+  const dayAccs = dayWindows.map(() => emptyAcc(categoryIds));
+
+  for (const card of cards) {
+    const start = Date.parse(card.startUtc);
+    const end = Date.parse(card.endUtc);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) continue;
+    const weekClip = clip(start, end, weekStartMs, weekEndMs);
+    if (!weekClip) continue;
+    addClipped(week, card.kind, card.categoryId, known, weekClip[0], weekClip[1]);
+    for (let i = 0; i < dayWindows.length; i++) {
+      const day = dayWindows[i];
+      const dayClip = clip(start, end, day.startMs, day.endMs);
+      if (dayClip) addClipped(dayAccs[i], card.kind, card.categoryId, known, dayClip[0], dayClip[1]);
+    }
+  }
+
+  const weekTotals = finish(week, weekEndMs - weekStartMs);
+  const days: WeeklyDayTotal[] = dayWindows.map((day, i) => {
+    const totals = finish(dayAccs[i], day.endMs - day.startMs);
+    return {
+      date: day.date,
+      startUtc: new Date(day.startMs).toISOString(),
+      endUtc: new Date(day.endMs).toISOString(),
+      ...totals,
+    };
+  });
+
+  return {
+    formatVersion: WEEKLY_ACTIVITY_FORMAT_VERSION,
+    timezone: options.timezone,
+    weekStartUtc: new Date(weekStartMs).toISOString(),
+    weekEndUtc: new Date(weekEndMs).toISOString(),
+    ...weekTotals,
+    days,
+    previousPeriod: { available: false },
+  };
+}

package/src/activity/types.ts

@@ -96,9 +96,23 @@ export interface ActivitySourceConfig {
   token?: string;
 }
 
+/** Opt-in daily journal settings (issue #1984). Default off. */
+export interface ActivityTimelineJournalConfig {
+  enabled: boolean;
+}
+
+/** Opt-in timeline Q&A range/search settings (issue #1983 PR1). Default off. */
+export interface ActivityTimelineQaConfig {
+  enabled: boolean;
+  /** Inclusive max half-open range length in 24h days. Integer 1..366. */
+  maxRangeDays: number;
+}
+
 /** Opt-in timeline-card derivation settings (issue #2049). Default off. */
 export interface ActivityTimelineConfig {
   enabled: boolean;
+  journal: ActivityTimelineJournalConfig;
+  qa: ActivityTimelineQaConfig;
 }
 
 /** Opt-in activity synchronization + trust-gated extraction settings. */