@remnic/core 9.65.8 → 9.66.0

package/src/activity/timeline/classify.ts

@@ -0,0 +1,110 @@
+/**
+ * Deterministic first-pass timeline classification (issue #2049).
+ *
+ * Signal-only: application name, browser domain, and window-title keywords.
+ * No LLM, no scoring, no intent inference — an app/window match says what was
+ * on screen, never that the user meant it. First matching rule (in declared
+ * order: domain, then app, then title) wins; no match stays visible in the
+ * reserved `system.unknown` category with confidence 0.
+ */
+
+import type { TimelineCategory, TimelineObservation } from "./types.js";
+import { TIMELINE_RESERVED_UNKNOWN } from "./categories.js";
+
+const DOMAIN_CONFIDENCE = 0.85;
+const APP_CONFIDENCE = 0.9;
+const TITLE_CONFIDENCE = 0.7;
+const UNKNOWN_CONFIDENCE = 0;
+
+interface ClassificationRule {
+  categoryId: string;
+  /** Substring matches against the browser URL host (most specific signal). */
+  domains?: readonly string[];
+  /** Substring matches against the application name. */
+  apps?: readonly string[];
+  /** Substring matches against the window title (weakest signal). */
+  titles?: readonly string[];
+}
+
+/**
+ * Ordered rules. Domain rules come first (a browser on github.com is
+ * development even though the app is Chrome), then app rules, then title
+ * keywords. Order is part of the contract: inserting a rule changes only
+ * classifications below it.
+ */
+const RULES: readonly ClassificationRule[] = [
+  { categoryId: "development", domains: ["github.com", "gitlab.com", "stackoverflow.com", "linear.app", "atlassian.net"] },
+  { categoryId: "communication", domains: ["mail.google.com", "gmail.com", "outlook.com", "outlook.office.com", "slack.com"] },
+  { categoryId: "design", domains: ["figma.com", "canva.com"] },
+  { categoryId: "documents", domains: ["docs.google.com", "notion.so", "dropbox.com"] },
+  { categoryId: "entertainment", domains: ["youtube.com", "netflix.com", "spotify.com"] },
+  { categoryId: "data", domains: ["metabase", "tableau", "grafana"] },
+
+  { categoryId: "development", apps: ["code", "cursor", "neovim", "vim", "emacs", "xcode", "intellij", "terminal", "iterm", "warp", "wezterm", "kitty", "alacritty", "zed", "sublime", "datagrip"] },
+  { categoryId: "communication", apps: ["slack", "discord", "teams", "mail", "outlook", "thunderbird", "messages", "signal", "whatsapp", "telegram", "zoom", "facetime", "meet"] },
+  { categoryId: "design", apps: ["figma", "sketch", "photoshop", "illustrator", "indesign", "premiere", "after effects", "davinci", "blender", "ableton", "logic pro", "final cut"] },
+  { categoryId: "documents", apps: ["word", "pages", "notion", "obsidian", "notes", "typora", "bear", "preview", "acrobat"] },
+  { categoryId: "data", apps: ["excel", "numbers", "sheets", "tableau"] },
+  { categoryId: "admin", apps: ["finder", "settings", "system preferences", "activity monitor", "files", "explorer"] },
+  { categoryId: "entertainment", apps: ["spotify", "music", "youtube", "vlc", "quicktime", "steam", "netflix", "podcast", "tv"] },
+  { categoryId: "browsing", apps: ["chrome", "safari", "firefox", "edge", "arc", "brave", "browser"] },
+
+  { categoryId: "development", titles: ["pull request", "merge conflict", "terminal —", "repository"] },
+  { categoryId: "communication", titles: ["inbox"] },
+  { categoryId: "data", titles: ["spreadsheet", "pivot table"] },
+];
+
+export interface TimelineClassification {
+  categoryId: string;
+  confidence: number;
+}
+
+/**
+ * Classify one observation. Throws if a rule targets a category missing from
+ * the registry (configuration error must fail loudly, not fall back silently).
+ */
+export function classifyTimelineObservation(
+  observation: Pick<TimelineObservation, "app" | "windowTitle" | "browserUrl">,
+  categories: readonly TimelineCategory[],
+): TimelineClassification {
+  const app = observation.app.toLowerCase();
+  const title = observation.windowTitle.toLowerCase();
+  const domain = observation.browserUrl === undefined ? "" : hostOf(observation.browserUrl);
+  for (const rule of RULES) {
+    if (rule.domains !== undefined && domain !== "" && rule.domains.some((pattern) => domain.includes(pattern))) {
+      return checkedRule(rule, DOMAIN_CONFIDENCE, categories);
+    }
+  }
+  for (const rule of RULES) {
+    if (rule.apps !== undefined && rule.apps.some((pattern) => app.includes(pattern))) {
+      return checkedRule(rule, APP_CONFIDENCE, categories);
+    }
+  }
+  for (const rule of RULES) {
+    if (rule.titles !== undefined && rule.titles.some((pattern) => title.includes(pattern))) {
+      return checkedRule(rule, TITLE_CONFIDENCE, categories);
+    }
+  }
+  return { categoryId: TIMELINE_RESERVED_UNKNOWN, confidence: UNKNOWN_CONFIDENCE };
+}
+
+/** Verify the rule's target exists in the registry before returning it. */
+function checkedRule(
+  rule: ClassificationRule,
+  confidence: number,
+  categories: readonly TimelineCategory[],
+): TimelineClassification {
+  if (!categories.some((category) => category.id === rule.categoryId)) {
+    throw new RangeError(`timeline classification rule targets unknown category: ${rule.categoryId}`);
+  }
+  return { categoryId: rule.categoryId, confidence };
+}
+
+/** Lowercased hostname of a URL, or "" when unparseable (never throws). */
+function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname.toLowerCase();
+  } catch {
+    return url.toLowerCase();
+  }
+}

package/src/activity/timeline/corrections.ts

@@ -0,0 +1,145 @@
+/**
+ * Timeline correction store (issue #2049): manual card/category edits that
+ * survive day rebuilds. Corrections are keyed by the card's stable
+ * content-derived id, so rebuilding the same evidence reproduces the same
+ * card ids and re-applies the edit; an explicit `reset()` reverts a card to
+ * its derived values. Corrections are user edits, not evidence — they live in
+ * their own small SQLite file, never in the #1899 snapshot store.
+ */
+
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+
+import { openBetterSqlite3, type BetterSqlite3Database } from "../../runtime/better-sqlite.js";
+import { DEFAULT_TIMELINE_CATEGORIES, validateTimelineCategories } from "./categories.js";
+import type { TimelineCard, TimelineCategory, TimelineCorrection } from "./types.js";
+
+export function timelineCorrectionDatabasePath(memoryDir: string): string {
+  return path.join(memoryDir, "state", "activity-timeline.sqlite");
+}
+
+interface CorrectionRow {
+  card_id: string;
+  category_id: string | null;
+  title: string | null;
+  edited_at_utc: string;
+}
+
+function rowToCorrection(row: CorrectionRow): TimelineCorrection {
+  return {
+    cardId: row.card_id,
+    categoryId: row.category_id ?? undefined,
+    title: row.title ?? undefined,
+    editedAtUtc: row.edited_at_utc,
+  };
+}
+
+export class TimelineCorrectionStore {
+  private readonly db: BetterSqlite3Database;
+
+  constructor(db: BetterSqlite3Database) {
+    this.db = db;
+  }
+
+  static open(memoryDir: string): TimelineCorrectionStore {
+    mkdirSync(path.join(memoryDir, "state"), { recursive: true });
+    const db = openBetterSqlite3(timelineCorrectionDatabasePath(memoryDir));
+    db.pragma("journal_mode = WAL");
+    db.pragma("busy_timeout = 5000");
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS timeline_corrections (
+        card_id       TEXT PRIMARY KEY,
+        category_id   TEXT,
+        title         TEXT,
+        edited_at_utc TEXT NOT NULL
+      );
+    `);
+    return new TimelineCorrectionStore(db);
+  }
+
+  /**
+   * Persist one correction. `categoryId`, when set, must exist in `categories`
+   * (defaults to the built-in registry) — an unknown category is a malformed
+   * edit and must fail rather than silently strand the card.
+   */
+  upsert(correction: TimelineCorrection, categories: readonly TimelineCategory[] = DEFAULT_TIMELINE_CATEGORIES): void {
+    validateTimelineCategories(categories);
+    if (typeof correction.cardId !== "string" || correction.cardId.length === 0) {
+      throw new RangeError("timeline correction requires a non-empty cardId");
+    }
+    if (typeof correction.editedAtUtc !== "string" || Number.isNaN(Date.parse(correction.editedAtUtc))) {
+      throw new RangeError("timeline correction requires a valid editedAtUtc instant");
+    }
+    if ((correction.categoryId === undefined && correction.title === undefined) || (correction.title !== undefined && correction.title.length === 0)) {
+      throw new RangeError("timeline correction must set a categoryId and/or a non-empty title");
+    }
+    if (correction.categoryId !== undefined && !categories.some((category) => category.id === correction.categoryId)) {
+      throw new RangeError(`timeline correction targets unknown category: ${correction.categoryId}`);
+    }
+    this.db
+      .prepare(
+        `INSERT INTO timeline_corrections (card_id, category_id, title, edited_at_utc)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(card_id) DO UPDATE SET category_id = excluded.category_id, title = excluded.title, edited_at_utc = excluded.edited_at_utc`,
+      )
+      .run(correction.cardId, correction.categoryId ?? null, correction.title ?? null, correction.editedAtUtc);
+  }
+
+  get(cardId: string): TimelineCorrection | undefined {
+    const row = this.db.prepare("SELECT card_id, category_id, title, edited_at_utc FROM timeline_corrections WHERE card_id = ?").get(cardId);
+    return row === undefined ? undefined : rowToCorrection(row as CorrectionRow);
+  }
+
+  /** All corrections ordered by card id (deterministic listing). */
+  list(): TimelineCorrection[] {
+    return this.db
+      .prepare("SELECT card_id, category_id, title, edited_at_utc FROM timeline_corrections ORDER BY card_id ASC")
+      .all()
+      .map((row) => rowToCorrection(row as CorrectionRow));
+  }
+
+  /** Explicitly reset a card to its derived values; true when a correction existed. */
+  reset(cardId: string): boolean {
+    return this.db.prepare("DELETE FROM timeline_corrections WHERE card_id = ?").run(cardId).changes > 0;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+/**
+ * Apply corrections to built cards. Overrides title/category, sets confidence
+ * to 1 (a human confirmed it), and stamps manual-edit provenance. Uncorrected
+ * cards pass through untouched, so serialization stays byte-stable for them.
+ */
+export function applyTimelineCorrections(
+  cards: readonly TimelineCard[],
+  corrections: readonly TimelineCorrection[],
+): TimelineCard[] {
+  const byCardId = new Map(corrections.map((correction) => [correction.cardId, correction]));
+  return cards.map((card) => {
+    const correction = byCardId.get(card.id);
+    if (correction === undefined) return card;
+    return {
+      id: card.id,
+      kind: card.kind,
+      title: correction.title ?? card.title,
+      summary: card.summary,
+      categoryId: correction.categoryId ?? card.categoryId,
+      confidence: 1,
+      startUtc: card.startUtc,
+      endUtc: card.endUtc,
+      dayKey: card.dayKey,
+      timezone: card.timezone,
+      machine: card.machine,
+      evidenceIds: card.evidenceIds,
+      evidenceRange: card.evidenceRange,
+      manualEdit: {
+        ...(correction.categoryId !== undefined ? { categoryId: correction.categoryId } : {}),
+        ...(correction.title !== undefined ? { title: correction.title } : {}),
+        editedAtUtc: correction.editedAtUtc,
+      },
+    };
+  });
+}

package/src/activity/timeline/index.ts

@@ -0,0 +1,6 @@
+/** Public entry for the timeline-card layer (issue #2049). */
+export * from "./types.js";
+export * from "./categories.js";
+export * from "./classify.js";
+export * from "./build.js";
+export * from "./corrections.js";

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[];
+}

package/src/activity/types.ts

@@ -96,6 +96,11 @@ export interface ActivitySourceConfig {
   token?: string;
 }
 
+/** Opt-in timeline-card derivation settings (issue #2049). Default off. */
+export interface ActivityTimelineConfig {
+  enabled: boolean;
+}
+
 /** Opt-in activity synchronization + trust-gated extraction settings. */
 export interface ActivityConfig {
   enabled: boolean;
@@ -114,4 +119,5 @@ export interface ActivityConfig {
   minImportance: ImportanceLevel;
   /** `0` means no count cap. */
   maxMemoriesPerDay: number;
+  timeline: ActivityTimelineConfig;
 }