@remnic/core 9.65.8 → 9.66.1

package/src/activity/timeline/query.ts

@@ -0,0 +1,313 @@
+/**
+ * Timeline range/search query (issue #1983 PR1).
+ *
+ * Pure functions over an in-memory card list. Half-open UTC [from, to).
+ * A zero-length range is an instant: include the card whose [start, end)
+ * contains it. Search returns distinct empty vs store_unreadable shapes.
+ *
+ * Config: activity.timeline.qa.{enabled, maxRangeDays}.
+ * MCP/HTTP and recall injection are later PRs.
+ */
+import { parseFlexibleIsoTimestamp } from "../../utils/iso-timestamp.js";
+import type { ActivityTimelineQaConfig } from "../types.js";
+import type { TimelineCard } from "./types.js";
+
+const RANGE_FORMATS = ["cards", "compact"] as const;
+const MS_PER_DAY = 86_400_000;
+const DEFAULT_MAX_RANGE_DAYS = 31;
+const DEFAULT_SEARCH_LIMIT = 10;
+const MIN_SEARCH_LIMIT = 1;
+const MAX_SEARCH_LIMIT = 50;
+
+export type TimelineRangeFormat = (typeof RANGE_FORMATS)[number];
+
+/** Card fields the query layer reads; later slices may add optional extras. */
+export type TimelineQueryCard = TimelineCard & {
+  detailedSummary?: string;
+  distraction?: boolean;
+};
+
+export interface TimelineRangeQuery {
+  from: string;
+  to: string;
+  categories?: readonly string[];
+  includeDistractions?: boolean;
+  format: TimelineRangeFormat;
+  maxRangeDays?: number;
+}
+
+export interface TimelineCompactCard {
+  start: string;
+  end: string;
+  category: string;
+  title: string;
+  summary: string;
+}
+
+export interface TimelineCompactRange {
+  day: string;
+  cards: TimelineCompactCard[];
+}
+
+export interface TimelineSearchQuery {
+  query: string;
+  from?: string;
+  to?: string;
+  limit?: number;
+}
+
+export type TimelineSearchResult =
+  | { ok: true; results: TimelineQueryCard[] }
+  | { ok: false; error: "store_unreadable" };
+
+export interface TimelineCliIo {
+  stdout: { write(chunk: string): unknown };
+  stderr: { write(chunk: string): unknown };
+}
+
+/** Inject cards so CLI tests never need ActivityStore. */
+export interface TimelineCliDeps {
+  cards: readonly TimelineQueryCard[] | null;
+  qa: ActivityTimelineQaConfig;
+  timelineEnabled?: boolean;
+}
+
+const USAGE = `Usage: timeline <command> [options]
+
+Commands:
+  range --from <ISO> --to <ISO> [--format cards|compact] [--categories id,id] [--include-distractions]
+  search --query <text> [--from <ISO>] [--to <ISO>] [--limit N]
+`;
+
+const VALUE_FLAGS: Record<string, true> = {
+  "--from": true,
+  "--to": true,
+  "--format": true,
+  "--categories": true,
+  "--query": true,
+  "--limit": true,
+};
+const BOOLEAN_FLAGS: Record<string, true> = { "--include-distractions": true };
+
+function parseInstant(value: string, label: string): number {
+  const ms = parseFlexibleIsoTimestamp(value);
+  if (ms === null) {
+    throw new TypeError(`${label} must be an ISO date or datetime`);
+  }
+  return ms;
+}
+
+function assertRange(fromMs: number, toMs: number, maxRangeDays: number): void {
+  if (fromMs > toMs) {
+    throw new RangeError("reversed range: from must be <= to");
+  }
+  if (fromMs === toMs) return;
+  if (toMs - fromMs > maxRangeDays * MS_PER_DAY) {
+    throw new RangeError(`range exceeds timeline.qa.maxRangeDays (${maxRangeDays})`);
+  }
+}
+
+function cardOverlaps(card: TimelineQueryCard, fromMs: number, toMs: number): boolean {
+  const start = Date.parse(card.startUtc);
+  const end = Date.parse(card.endUtc);
+  if (fromMs === toMs) return start <= fromMs && fromMs < end;
+  return start < toMs && end > fromMs;
+}
+
+function passesFilters(
+  card: TimelineQueryCard,
+  categories: ReadonlySet<string> | undefined,
+  includeDistractions: boolean,
+): boolean {
+  if (!includeDistractions && card.distraction === true) return false;
+  if (categories && !categories.has(card.categoryId)) return false;
+  return true;
+}
+
+function filterRange(
+  cards: readonly TimelineQueryCard[],
+  fromMs: number,
+  toMs: number,
+  categories: ReadonlySet<string> | undefined,
+  includeDistractions: boolean,
+): TimelineQueryCard[] {
+  return cards.filter(
+    (card) => cardOverlaps(card, fromMs, toMs) && passesFilters(card, categories, includeDistractions),
+  );
+}
+
+function toCompact(cards: readonly TimelineQueryCard[], from: string): TimelineCompactRange {
+  const day = from.length >= 10 ? from.slice(0, 10) : cards[0]?.dayKey ?? from;
+  return {
+    day,
+    cards: cards.map((card) => ({
+      start: card.startUtc,
+      end: card.endUtc,
+      category: card.categoryId,
+      title: card.title,
+      summary: card.summary,
+    })),
+  };
+}
+
+export function queryTimelineRange(
+  cards: readonly TimelineQueryCard[],
+  query: TimelineRangeQuery,
+): TimelineCard[] | TimelineCompactRange {
+  if (!RANGE_FORMATS.includes(query.format)) {
+    throw new TypeError(`format must be one of: ${RANGE_FORMATS.join(", ")}`);
+  }
+  const maxRangeDays = query.maxRangeDays ?? DEFAULT_MAX_RANGE_DAYS;
+  const fromMs = parseInstant(query.from, "from");
+  const toMs = parseInstant(query.to, "to");
+  assertRange(fromMs, toMs, maxRangeDays);
+  const categories = query.categories ? new Set(query.categories) : undefined;
+  const matched = filterRange(cards, fromMs, toMs, categories, query.includeDistractions === true);
+  if (query.format === "compact") return toCompact(matched, query.from);
+  return matched;
+}
+
+function haystack(card: TimelineQueryCard): string {
+  const parts = [card.title, card.summary];
+  if (card.detailedSummary) parts.push(card.detailedSummary);
+  return parts.join(" ").toLowerCase();
+}
+
+function tokenMatchCount(card: TimelineQueryCard, tokens: readonly string[]): number {
+  const text = haystack(card);
+  let count = 0;
+  for (const token of tokens) {
+    if (text.includes(token)) count += 1;
+  }
+  return count;
+}
+
+export function queryTimelineSearch(
+  cards: readonly TimelineQueryCard[] | null | undefined,
+  query: TimelineSearchQuery,
+): TimelineSearchResult {
+  if (!Array.isArray(cards)) return { ok: false, error: "store_unreadable" };
+  const tokens = query.query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  const limit = query.limit ?? DEFAULT_SEARCH_LIMIT;
+  if (!Number.isInteger(limit) || limit < MIN_SEARCH_LIMIT || limit > MAX_SEARCH_LIMIT) {
+    throw new RangeError(`limit must be an integer from ${MIN_SEARCH_LIMIT} to ${MAX_SEARCH_LIMIT}`);
+  }
+  let pool = cards;
+  if (query.from !== undefined || query.to !== undefined) {
+    const fromMs = parseInstant(query.from ?? query.to!, "from");
+    const toMs = parseInstant(query.to ?? query.from!, "to");
+    assertRange(fromMs, toMs, DEFAULT_MAX_RANGE_DAYS);
+    pool = filterRange(cards, fromMs, toMs, undefined, true);
+  }
+  if (tokens.length === 0) return { ok: true, results: [] };
+  const ranked = pool
+    .map((card) => ({ card, matches: tokenMatchCount(card, tokens) }))
+    .filter((row) => row.matches > 0)
+    .sort((a, b) => {
+      if (a.matches !== b.matches) return b.matches - a.matches;
+      const recency = Date.parse(b.card.endUtc) - Date.parse(a.card.endUtc);
+      if (recency !== 0) return recency;
+      return a.card.id < b.card.id ? -1 : a.card.id > b.card.id ? 1 : 0;
+    })
+    .slice(0, limit)
+    .map((row) => row.card);
+  return { ok: true, results: ranked };
+}
+
+function parseFlags(args: string[]): { flags: Map<string, string | true>; positional: string[] } {
+  const flags = new Map<string, string | true>();
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    if (VALUE_FLAGS[arg] === true) {
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new TypeError(`flag ${arg} requires a value`);
+      }
+      flags.set(arg, value);
+      i += 1;
+      continue;
+    }
+    if (BOOLEAN_FLAGS[arg] === true) {
+      flags.set(arg, true);
+      continue;
+    }
+    const known = [...Object.keys(VALUE_FLAGS), ...Object.keys(BOOLEAN_FLAGS)].sort().join(", ");
+    throw new TypeError(`unknown flag ${arg} (valid: ${known})`);
+  }
+  return { flags, positional };
+}
+
+function flagString(flags: Map<string, string | true>, name: string): string | undefined {
+  const value = flags.get(name);
+  return typeof value === "string" ? value : undefined;
+}
+
+/** Shared CLI runner. `deps.cards` may be an in-memory fixture. */
+export async function runTimelineCliCommand(
+  deps: TimelineCliDeps,
+  args: string[],
+  io: TimelineCliIo,
+): Promise<number> {
+  const [command, ...rest] = args;
+  try {
+    if (command === undefined || command === "help" || command === "--help") {
+      io.stdout.write(USAGE);
+      return command === undefined ? 1 : 0;
+    }
+    if (deps.timelineEnabled === false || !deps.qa.enabled) {
+      io.stderr.write("timeline qa disabled — set activity.timeline.qa.enabled=true\n");
+      return 1;
+    }
+    const { flags } = parseFlags(rest);
+    if (command === "range") {
+      const from = flagString(flags, "--from");
+      const to = flagString(flags, "--to");
+      if (!from || !to) throw new TypeError("range requires --from and --to");
+      if (!Array.isArray(deps.cards)) {
+        io.stderr.write("store_unreadable\n");
+        return 1;
+      }
+      const formatRaw = flagString(flags, "--format") ?? "compact";
+      if (formatRaw !== "cards" && formatRaw !== "compact") {
+        throw new TypeError("format must be one of: cards, compact");
+      }
+      const categoriesRaw = flagString(flags, "--categories");
+      const result = queryTimelineRange(deps.cards, {
+        from,
+        to,
+        format: formatRaw,
+        categories: categoriesRaw ? categoriesRaw.split(",").filter(Boolean) : undefined,
+        includeDistractions: flags.get("--include-distractions") === true,
+        maxRangeDays: deps.qa.maxRangeDays,
+      });
+      io.stdout.write(`${JSON.stringify(result)}\n`);
+      return 0;
+    }
+    if (command === "search") {
+      const q = flagString(flags, "--query");
+      if (q === undefined) throw new TypeError("search requires --query");
+      const limitRaw = flagString(flags, "--limit");
+      const limit = limitRaw === undefined ? undefined : Number(limitRaw);
+      if (limitRaw !== undefined && !Number.isInteger(limit)) {
+        throw new RangeError("limit must be an integer from 1 to 50");
+      }
+      const result = queryTimelineSearch(deps.cards, {
+        query: q,
+        from: flagString(flags, "--from"),
+        to: flagString(flags, "--to"),
+        limit,
+      });
+      io.stdout.write(`${JSON.stringify(result)}\n`);
+      return result.ok ? 0 : 1;
+    }
+    throw new TypeError(`unknown command ${command} (valid: range, search)`);
+  } catch (err) {
+    io.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+}

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

@@ -0,0 +1,277 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { activityDayWindow } from "../digest.js";
+import { parseActivityConfig } from "../config.js";
+import {
+  DEFAULT_TIMELINE_CATEGORIES,
+  TIMELINE_RESERVED_IDLE,
+  TIMELINE_RESERVED_PAUSE,
+  TIMELINE_RESERVED_UNKNOWN,
+  sortTimelineCategories,
+  validateTimelineCategories,
+} from "./categories.js";
+import { classifyTimelineObservation } from "./classify.js";
+import { buildTimelineDay, serializeTimelineDay, TIMELINE_MERGE_GAP_MS } from "./build.js";
+import { applyTimelineCorrections, TimelineCorrectionStore } from "./corrections.js";
+import type { TimelineCategory, TimelineObservation } from "./types.js";
+
+function obs(overrides: Partial<TimelineObservation> & { id: number; capturedAtUtc: string }): TimelineObservation {
+  return {
+    machine: "workstation-a",
+    app: "Code",
+    windowTitle: "main.ts — editor",
+    contentHash: `hash-${overrides.id}`,
+    ...overrides,
+  };
+}
+
+const BASE_INPUT = {
+  date: "2026-06-01",
+  timezone: "UTC",
+  observations: [
+    obs({ id: 1, capturedAtUtc: "2026-06-01T09:00:00.000Z" }),
+    obs({ id: 2, capturedAtUtc: "2026-06-01T09:01:00.000Z" }),
+    obs({ id: 3, capturedAtUtc: "2026-06-01T09:02:00.000Z" }),
+    obs({ id: 4, capturedAtUtc: "2026-06-01T09:40:00.000Z" }),
+  ],
+};
+
+test("synthetic observations replay into byte-stable cards regardless of input order", () => {
+  const first = buildTimelineDay(BASE_INPUT);
+  const second = buildTimelineDay({ ...BASE_INPUT, observations: [...BASE_INPUT.observations].reverse() });
+  assert.equal(serializeTimelineDay(second), serializeTimelineDay(first));
+  // "Restart" isolation: a completely fresh call over equal content matches.
+  const third = buildTimelineDay(JSON.parse(JSON.stringify(BASE_INPUT)));
+  assert.equal(serializeTimelineDay(third), serializeTimelineDay(first));
+  assert.ok(first.cards.every((card) => card.id.startsWith("tlc_")));
+});
+
+test("adjacent compatible observations merge; key changes and long gaps split cards", () => {
+  const day = buildTimelineDay(BASE_INPUT);
+  const activity = day.cards.filter((card) => card.kind === "activity");
+  assert.equal(activity.length, 2, "2-min gaps merge, a 38-min gap splits");
+  assert.deepEqual(activity[0].evidenceIds, [1, 2, 3]);
+  // Dwell caps at 15 min past the LAST observation: [09:00, 09:17), [09:40, 09:55).
+  assert.equal(activity[0].startUtc, "2026-06-01T09:00:00.000Z");
+  assert.equal(activity[0].endUtc, "2026-06-01T09:17:00.000Z");
+  assert.equal(activity[1].startUtc, "2026-06-01T09:40:00.000Z");
+  assert.equal(activity[1].endUtc, "2026-06-01T09:55:00.000Z");
+  // The >15-min remainder is a derived idle card with no evidence.
+  const idle = day.cards.filter((card) => card.kind === "idle");
+  assert.equal(idle.length, 1);
+  assert.equal(idle[0].categoryId, TIMELINE_RESERVED_IDLE);
+  assert.deepEqual(idle[0].evidenceIds, []);
+  assert.equal(idle[0].startUtc, "2026-06-01T09:17:00.000Z");
+  assert.equal(idle[0].endUtc, "2026-06-01T09:40:00.000Z");
+
+  // Same cadence but a different window title: two cards, contiguous, no idle.
+  const keyed = buildTimelineDay({
+    ...BASE_INPUT,
+    observations: [
+      obs({ id: 1, capturedAtUtc: "2026-06-01T09:00:00.000Z" }),
+      obs({ id: 2, capturedAtUtc: "2026-06-01T09:01:00.000Z", windowTitle: "other.ts — editor" }),
+    ],
+  });
+  const cards = keyed.cards.filter((card) => card.kind === "activity");
+  assert.equal(cards.length, 2);
+  assert.equal(cards[0].endUtc, cards[1].startUtc, "dwell stops at the next observation");
+  assert.equal(keyed.cards.filter((card) => card.kind === "idle").length, 0);
+  assert.equal(TIMELINE_MERGE_GAP_MS, 120_000, "merge gap contract");
+});
+
+test("card dwell is clipped at the local day end (midnight)", () => {
+  const day = buildTimelineDay({
+    date: "2026-06-01",
+    timezone: "UTC",
+    observations: [obs({ id: 7, capturedAtUtc: "2026-06-01T23:59:00.000Z" })],
+  });
+  const card = day.cards[0];
+  assert.equal(card.startUtc, "2026-06-01T23:59:00.000Z");
+  assert.equal(card.endUtc, "2026-06-02T00:00:00.000Z", "15-min dwell must not cross midnight");
+  assert.equal(card.dayKey, "2026-06-01");
+});
+
+test("DST transition days bucket observations through the shifted window", () => {
+  // America/New_York springs forward 2026-03-08: the local day is 23 hours.
+  const window = activityDayWindow("2026-03-08", "America/New_York");
+  assert.equal(Date.parse(window.endUtc) - Date.parse(window.startUtc), 23 * 3_600_000);
+  const day = buildTimelineDay({
+    date: "2026-03-08",
+    timezone: "America/New_York",
+    observations: [
+      obs({ id: 11, capturedAtUtc: "2026-03-08T06:30:00.000Z" }),
+      obs({ id: 12, capturedAtUtc: "2026-03-08T06:31:00.000Z" }),
+    ],
+  });
+  assert.equal(day.cards.length, 1);
+  assert.equal(day.cards[0].dayKey, "2026-03-08");
+  assert.equal(day.startUtc, window.startUtc);
+  // Fall-back day is 25 hours.
+  const fallWindow = activityDayWindow("2026-11-01", "America/New_York");
+  assert.equal(Date.parse(fallWindow.endUtc) - Date.parse(fallWindow.startUtc), 25 * 3_600_000);
+});
+test("user pause closes cards, is emitted as its own kind, and wins over idle", () => {
+  const day = buildTimelineDay({
+    ...BASE_INPUT,
+    observations: [
+      obs({ id: 1, capturedAtUtc: "2026-06-01T10:00:00.000Z" }),
+      obs({ id: 2, capturedAtUtc: "2026-06-01T10:01:30.000Z" }),
+      obs({ id: 3, capturedAtUtc: "2026-06-01T11:00:00.000Z" }),
+    ],
+    pauses: [{ startUtc: "2026-06-01T10:30:00.000Z", endUtc: "2026-06-01T11:00:00.000Z", reason: "lunch" }],
+  });
+  const pause = day.cards.filter((card) => card.kind === "pause");
+  assert.equal(pause.length, 1);
+  assert.equal(pause[0].categoryId, TIMELINE_RESERVED_PAUSE);
+  assert.deepEqual(pause[0].evidenceIds, []);
+  assert.ok(pause[0].summary.includes("lunch"));
+  const before = day.cards.find((card) => card.kind === "activity" && card.evidenceIds.includes(1));
+  assert.equal(before?.endUtc, "2026-06-01T10:16:30.000Z", "dwell (15m from last obs) ends before the pause");
+  // Dwell stops short of the pause, so the 13.5-min remainder is one idle
+  // card; the pause wins over idle covering the same minutes.
+  const idle = day.cards.filter((card) => card.kind === "idle");
+  assert.equal(idle.length, 1);
+  assert.equal(idle[0].startUtc, "2026-06-01T10:16:30.000Z");
+  assert.equal(idle[0].endUtc, "2026-06-01T10:30:00.000Z");
+  // No idle overlaps the pause interval itself.
+  assert.ok(idle.every((card) => card.endUtc <= pause[0].startUtc || card.startUtc >= pause[0].endUtc));
+  // Overlapping pauses union into one interval.
+  const unioned = buildTimelineDay({
+    date: "2026-06-01",
+    timezone: "UTC",
+    pauses: [
+      { startUtc: "2026-06-01T10:00:00.000Z", endUtc: "2026-06-01T10:30:00.000Z" },
+      { startUtc: "2026-06-01T10:20:00.000Z", endUtc: "2026-06-01T11:00:00.000Z" },
+    ],
+    observations: [],
+  });
+  assert.equal(unioned.cards.length, 1);
+  assert.equal(unioned.cards[0].endUtc, "2026-06-01T11:00:00.000Z");
+  // A pause between two compatible observations still closes the card.
+  const split = buildTimelineDay({
+    date: "2026-06-01",
+    timezone: "UTC",
+    observations: [
+      obs({ id: 1, capturedAtUtc: "2026-06-01T09:00:00.000Z" }),
+      obs({ id: 2, capturedAtUtc: "2026-06-01T09:00:30.000Z" }),
+    ],
+    pauses: [{ startUtc: "2026-06-01T09:00:10.000Z", endUtc: "2026-06-01T09:00:20.000Z" }],
+  });
+  assert.equal(split.cards.filter((card) => card.kind === "activity").length, 2);
+});
+
+test("overlapping multi-machine tracks never merge across machines", () => {
+  const day = buildTimelineDay({
+    ...BASE_INPUT,
+    observations: [
+      obs({ id: 1, machine: "ws-a", capturedAtUtc: "2026-06-01T09:00:00.000Z", app: "Chrome", windowTitle: "Docs" }),
+      obs({ id: 2, machine: "ws-b", capturedAtUtc: "2026-06-01T09:00:30.000Z", app: "Chrome", windowTitle: "Docs" }),
+      obs({ id: 3, machine: "ws-a", capturedAtUtc: "2026-06-01T09:01:00.000Z", app: "Chrome", windowTitle: "Docs" }),
+    ],
+  });
+  const activity = day.cards.filter((card) => card.kind === "activity");
+  assert.equal(activity.length, 2);
+  assert.deepEqual(new Set(activity.map((card) => card.machine)), new Set(["ws-a", "ws-b"]));
+  // Global order is start-time first with a stable machine tie-break.
+  assert.ok(activity[0].startUtc <= activity[1].startUtc);
+  assert.equal(activity.find((card) => card.machine === "ws-a")?.evidenceIds.length, 2);
+});
+
+test("unclassified activity stays visible in system.unknown; domains outrank app names", () => {
+  const unknown = classifyTimelineObservation({ app: "MysteryTool", windowTitle: "untitled" }, DEFAULT_TIMELINE_CATEGORIES);
+  assert.deepEqual(unknown, { categoryId: TIMELINE_RESERVED_UNKNOWN, confidence: 0 });
+  const day = buildTimelineDay({
+    date: "2026-06-01",
+    timezone: "UTC",
+    observations: [obs({ id: 1, capturedAtUtc: "2026-06-01T09:00:00.000Z", app: "MysteryTool", windowTitle: "untitled" })],
+  });
+  assert.equal(day.cards[0].categoryId, TIMELINE_RESERVED_UNKNOWN);
+  assert.equal(day.cards[0].confidence, 0);
+  // A browser on github.com is development (domain signal) even though the
+  // app rule alone would say browsing.
+  const classified = classifyTimelineObservation(
+    { app: "Chrome", windowTitle: "feat: timeline", browserUrl: "https://github.com/org/repo" },
+    DEFAULT_TIMELINE_CATEGORIES,
+  );
+  assert.equal(classified.categoryId, "development");
+  assert.equal(classified.confidence, 0.85);
+});
+
+test("categories validate reserved/system rules and sort with equal-order tie-breaks", () => {
+  assert.throws(
+    () => validateTimelineCategories([{ id: "development", name: "x", color: "#3b82f6", description: "d", order: 1 }]),
+    /system\.unknown/,
+  );
+  assert.throws(
+    () =>
+      validateTimelineCategories([
+        ...DEFAULT_TIMELINE_CATEGORIES,
+        { id: "development", name: "dup", color: "#000000", description: "d", order: 5 },
+      ]),
+    /unique/,
+  );
+  assert.throws(
+    () => validateTimelineCategories(DEFAULT_TIMELINE_CATEGORIES.map((c) => (c.id === "development" ? { ...c, color: "blue" } : c))),
+    /#RRGGBB/,
+  );
+  assert.throws(
+    () => validateTimelineCategories(DEFAULT_TIMELINE_CATEGORIES.map((c) => (c.id === "development" ? { ...c, system: true } : c))),
+    /only reserved categories/,
+  );
+  const equalOrder: TimelineCategory[] = [
+    { id: "beta", name: "B", color: "#000001", description: "d", order: 50 },
+    { id: "alpha", name: "A", color: "#000002", description: "d", order: 50 },
+    ...DEFAULT_TIMELINE_CATEGORIES,
+  ];
+  validateTimelineCategories(equalOrder);
+  const sorted = sortTimelineCategories(equalOrder);
+  assert.ok(sorted.findIndex((c) => c.id === "alpha") < sorted.findIndex((c) => c.id === "beta"), "equal order tie-breaks by id");
+});
+
+test("manual corrections survive a rebuild and reset reverts the card", () => {
+  const memoryDir = mkdtempSync(path.join(tmpdir(), "remnic-timeline-test-"));
+  try {
+    const store = TimelineCorrectionStore.open(memoryDir);
+    const day = buildTimelineDay(BASE_INPUT);
+    const target = day.cards[0];
+    store.upsert({ cardId: target.id, categoryId: "communication", title: "Morning standup", editedAtUtc: "2026-06-01T12:00:00.000Z" });
+    assert.throws(() => store.upsert({ cardId: target.id, categoryId: "nope", editedAtUtc: "2026-06-01T12:00:00.000Z" }), /unknown category/);
+
+    // "Rebuild" — same evidence, fresh build call, corrections reapplied.
+    const rebuiltDay = buildTimelineDay(BASE_INPUT);
+    const rebuilt = applyTimelineCorrections(rebuiltDay.cards, store.list());
+    const corrected = rebuilt.find((card) => card.id === target.id);
+    assert.equal(corrected?.title, "Morning standup");
+    assert.equal(corrected?.categoryId, "communication");
+    assert.equal(corrected?.confidence, 1);
+    assert.equal(corrected?.manualEdit?.editedAtUtc, "2026-06-01T12:00:00.000Z");
+    const untouched = rebuilt.find((card) => card.id !== target.id);
+    assert.deepEqual(untouched, rebuiltDay.cards.find((card) => card.id === untouched?.id));
+
+    // Explicit reset restores the derived card byte-for-byte.
+    assert.equal(store.reset(target.id), true);
+    assert.equal(store.reset(target.id), false);
+    const afterReset = applyTimelineCorrections(buildTimelineDay(BASE_INPUT).cards, store.list());
+    assert.deepEqual(afterReset.find((card) => card.id === target.id), target);
+
+    // Corrections persist across close/reopen (process restart).
+    store.close();
+    const reopened = TimelineCorrectionStore.open(memoryDir);
+    assert.equal(reopened.list().length, 0);
+    reopened.close();
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("activity.timeline config gate defaults off and parses explicitly", () => {
+  assert.equal(parseActivityConfig(undefined).timeline.enabled, false);
+  assert.equal(parseActivityConfig({ timeline: { enabled: true } }).timeline.enabled, true);
+  assert.equal(parseActivityConfig({ timeline: { enabled: "false" } }).timeline.enabled, false);
+  assert.throws(() => parseActivityConfig({ timeline: "on" }), /activity\.timeline must be an object/);
+  assert.throws(() => parseActivityConfig({ timeline: { enabled: "maybe" } }), /activity\.timeline\.enabled must be a boolean/);
+});

package/src/activity/timeline/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Timeline-card layer over the #1899 activity store (issue #2049).
+ *
+ * A card is a deterministic, replayable *derived view*: it references snapshot
+ * evidence by store row id and content identity, never copying or re-storing
+ * it. All intervals are half-open [start, end) UTC; day bucketing reuses the
+ * DST-aware `activityDayWindow` from the digest layer, so timeline days and
+ * digests always agree on day bounds.
+ */
+
+/** Reference to one stored observation (subset of ActivitySnapshot; no text). */
+export interface TimelineObservation {
+  /** Store row id of the referenced snapshot. */
+  id: number;
+  machine: string;
+  /** UTC ISO-8601 capture instant. */
+  capturedAtUtc: string;
+  app: string;
+  windowTitle: string;
+  /** Browser tab URL, when the frontmost window is a known browser. */
+  browserUrl?: string;
+  /** Content hash of the referenced snapshot (identity, not re-stored text). */
+  contentHash: string;
+}
+
+/** User-declared pause, half-open [startUtc, endUtc) in UTC. Not idle. */
+export interface TimelinePause {
+  startUtc: string;
+  endUtc: string;
+  /** Free-form reason, kept verbatim on the derived pause card. */
+  reason?: string;
+}
+
+/** One category definition in the registry. */
+export interface TimelineCategory {
+  /** Stable ID (`system.*` is the reserved namespace). */
+  id: string;
+  name: string;
+  /** Hex color, `#RRGGBB`. */
+  color: string;
+  description: string;
+  /** Presentation order; equal orders tie-break by id. */
+  order: number;
+  /** Reserved system category (idle / pause / unknown). */
+  system?: boolean;
+  /** Marks the reserved idle category. */
+  idle?: boolean;
+}
+
+export type TimelineCardKind = "activity" | "idle" | "pause";
+
+/** Provenance stamped on a card when a manual correction was applied. */
+export interface TimelineManualEdit {
+  categoryId?: string;
+  title?: string;
+  editedAtUtc: string;
+}
+
+/** A persisted manual correction; keyed by stable card id, survives rebuilds. */
+export interface TimelineCorrection {
+  cardId: string;
+  categoryId?: string;
+  title?: string;
+  editedAtUtc: string;
+}
+
+/** Stable first/last evidence identity keys bracketing a card's sources. */
+export interface TimelineEvidenceRange {
+  firstKey: string;
+  lastKey: string;
+}
+
+export interface TimelineCard {
+  /** Stable content-derived id (never array position or wall-clock). */
+  id: string;
+  kind: TimelineCardKind;
+  title: string;
+  summary: string;
+  categoryId: string;
+  /** Classification confidence; manual corrections set it to 1. */
+  confidence: number;
+  /** Half-open [startUtc, endUtc) UTC bounds. */
+  startUtc: string;
+  endUtc: string;
+  /** Local day key (YYYY-MM-DD) this card belongs to. */
+  dayKey: string;
+  timezone: string;
+  /** Track the card was built on; null for machine-less pause cards. */
+  machine: string | null;
+  /** Store row ids of the source snapshots (empty for idle/pause). */
+  evidenceIds: number[];
+  /** First/last evidence identity keys (null for idle/pause). */
+  evidenceRange: TimelineEvidenceRange | null;
+  /** Present only when a manual correction was applied. */
+  manualEdit?: TimelineManualEdit;
+}
+
+/** One replayable local day of cards. */
+export interface TimelineDay {
+  formatVersion: number;
+  date: string;
+  timezone: string;
+  startUtc: string;
+  endUtc: string;
+  cards: TimelineCard[];
+}