@remnic/core 9.65.8 → 9.66.1

package/src/activity/timeline/build.ts

@@ -0,0 +1,279 @@
+/**
+ * Deterministic timeline-card day builder (issue #2049).
+ *
+ * Semantics (all half-open [start, end), all UTC internally):
+ * - Observations are grouped per capture machine and sorted by
+ *   (canonical capture instant, contentHash) — never by array position.
+ * - Compatibility rule: two consecutive observations on one machine merge
+ *   into the same card iff they share the exact (app, windowTitle) pair.
+ * - Gap rule: a merge happens only when the inter-observation gap is
+ *   ≤ MERGE_GAP_MS (2 min). A card's end extends from its last observation
+ *   by at most MAX_DWELL_MS (15 min, matching the digest dwell cap), is
+ *   clipped by the next observation on the machine, by any user pause, and
+ *   by the local day end — so cards never overlap on a track.
+ * - Idle: any uncovered remainder between consecutive cards on a machine
+ *   track (which in practice means a gap > MAX_DWELL_MS) becomes a derived
+ *   idle card with no evidence. The day's leading/trailing uncovered ranges
+ *   are represented by the absence of cards, not by invented idle.
+ * - Pause: user-declared intervals are unioned, clipped to the day, emitted
+ *   as pause cards, and never overlapped by activity dwell or idle.
+ * - Nothing is invented for gaps: idle/pause cards carry no evidence and are
+ *   flagged by kind; an app/window match never claims user intent.
+ *
+ * Output is byte-stable: identical inputs produce identical
+ * `serializeTimelineDay()` bytes across runs and process restarts.
+ */
+
+import { createHash } from "node:crypto";
+
+import { activityDayWindow } from "../digest.js";
+import { DEFAULT_TIMELINE_CATEGORIES, TIMELINE_RESERVED_IDLE, TIMELINE_RESERVED_PAUSE, validateTimelineCategories } from "./categories.js";
+import { classifyTimelineObservation } from "./classify.js";
+import type { TimelineCard, TimelineCategory, TimelineDay, TimelineObservation, TimelinePause } from "./types.js";
+
+export const TIMELINE_FORMAT_VERSION = 1;
+
+/** Max inter-observation gap that still merges into one card. */
+export const TIMELINE_MERGE_GAP_MS = 120_000;
+/** Max dwell attributed past a card's last observation (digest parity). */
+export const TIMELINE_MAX_DWELL_MS = 15 * 60_000;
+
+export interface TimelineBuildInput {
+  /** Local day, YYYY-MM-DD. */
+  date: string;
+  timezone: string;
+  /** Stored observations for the day (e.g. from ActivityStore.listSnapshotsForDay). */
+  observations: readonly TimelineObservation[];
+  /** User-declared pauses (UTC, half-open); may overlap and extend past the day. */
+  pauses?: readonly TimelinePause[];
+  /** Registry override; validated. Defaults to the built-in registry. */
+  categories?: readonly TimelineCategory[];
+}
+
+/** Canonical UTC ISO instant, or the raw string when unparseable (dropped later). */
+function canonicalMs(iso: string): number {
+  const parsed = Date.parse(iso);
+  return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+
+function isoOf(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+/** Content identity of one observation: machine + instant + content hash. */
+function evidenceKeyOf(observation: TimelineObservation): string {
+  return `${observation.machine}|${isoOf(canonicalMs(observation.capturedAtUtc))}|${observation.contentHash}`;
+}
+
+function stableCardId(identity: string): string {
+  return `tlc_${createHash("sha256").update(identity, "utf8").digest("hex").slice(0, 16)}`;
+}
+
+function formatDurationMinutes(ms: number): string {
+  return `${Math.round(ms / 60_000)}m`;
+}
+
+/** Union overlapping/adjacent [start,end) intervals; returns sorted, disjoint ms pairs. */
+function unionIntervals(intervals: readonly (readonly [number, number])[]): Array<[number, number]> {
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const merged: Array<[number, number]> = [];
+  for (const interval of sorted) {
+    const last = merged[merged.length - 1];
+    if (last !== undefined && interval[0] <= last[1]) {
+      last[1] = Math.max(last[1], interval[1]);
+    } else {
+      merged.push([interval[0], interval[1]]);
+    }
+  }
+  return merged;
+}
+
+/** Remove [cutStart,cutEnd) from [start,end); returns the remaining pieces. */
+function subtractInterval(start: number, end: number, cutStart: number, cutEnd: number): Array<[number, number]> {
+  if (cutEnd <= start || cutStart >= end) return [[start, end]];
+  const pieces: Array<[number, number]> = [];
+  if (cutStart > start) pieces.push([start, cutStart]);
+  if (cutEnd < end) pieces.push([cutEnd, end]);
+  return pieces;
+}
+
+interface MergedObservations {
+  machine: string;
+  observations: TimelineObservation[];
+}
+
+/** Per-machine merge pass: compatibility + gap rules (see module doc). */
+function mergeTrack(
+  machine: string,
+  track: TimelineObservation[],
+  pauses: readonly (readonly [number, number])[],
+): MergedObservations[] {
+  const cards: MergedObservations[] = [];
+  let current: TimelineObservation[] = [];
+  const pauseStartsAfter = (fromMs: number, toMs: number): boolean =>
+    pauses.some(([ps, pe]) => ps >= fromMs && ps < toMs && pe > ps);
+  for (const observation of track) {
+    const last = current[current.length - 1];
+    if (last !== undefined) {
+      const gap = canonicalMs(observation.capturedAtUtc) - canonicalMs(last.capturedAtUtc);
+      const sameKey = observation.app === last.app && observation.windowTitle === last.windowTitle;
+      const pauseBetween = pauseStartsAfter(canonicalMs(last.capturedAtUtc), canonicalMs(observation.capturedAtUtc));
+      if (!sameKey || gap > TIMELINE_MERGE_GAP_MS || pauseBetween) {
+        cards.push({ machine, observations: current });
+        current = [];
+      }
+    }
+    current.push(observation);
+  }
+  if (current.length > 0) cards.push({ machine, observations: current });
+  return cards;
+}
+
+/** Build one replayable local day of timeline cards. Pure; throws on bad input. */
+export function buildTimelineDay(input: TimelineBuildInput): TimelineDay {
+  const categories = input.categories ?? DEFAULT_TIMELINE_CATEGORIES;
+  validateTimelineCategories(categories);
+  const window = activityDayWindow(input.date, input.timezone);
+  const dayStartMs = Date.parse(window.startUtc);
+  const dayEndMs = Date.parse(window.endUtc);
+
+  // Observations: canonicalize, drop instants outside the day window.
+  const observations = input.observations
+    .filter((observation) => Number.isFinite(canonicalMs(observation.capturedAtUtc)))
+    .filter((observation) => {
+      const ms = canonicalMs(observation.capturedAtUtc);
+      return ms >= dayStartMs && ms < dayEndMs;
+    });
+
+  // Pauses: validate instants, clip to the day, union overlaps.
+  for (const pause of input.pauses ?? []) {
+    const startMs = canonicalMs(pause.startUtc);
+    const endMs = canonicalMs(pause.endUtc);
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || startMs >= endMs) {
+      throw new RangeError("timeline pause must be a valid half-open [startUtc, endUtc) interval");
+    }
+  }
+  const pauseIntervals = unionIntervals(
+    (input.pauses ?? [])
+      .map((pause) => [canonicalMs(pause.startUtc), canonicalMs(pause.endUtc)] as const)
+      .map(([startMs, endMs]) => [Math.max(startMs, dayStartMs), Math.min(endMs, dayEndMs)] as const)
+      .filter(([startMs, endMs]) => endMs > startMs),
+  );
+
+  // Group per machine; sort by (instant, contentHash) — position-independent.
+  const tracks = new Map<string, TimelineObservation[]>();
+  for (const observation of observations) {
+    const track = tracks.get(observation.machine) ?? [];
+    track.push(observation);
+    tracks.set(observation.machine, track);
+  }
+  for (const track of tracks.values()) {
+    track.sort(
+      (a, b) => canonicalMs(a.capturedAtUtc) - canonicalMs(b.capturedAtUtc) || (a.contentHash < b.contentHash ? -1 : a.contentHash > b.contentHash ? 1 : 0),
+    );
+  }
+
+  const cards: TimelineCard[] = [];
+  const machines = [...tracks.keys()].sort();
+  for (const machine of machines) {
+    const track = tracks.get(machine) ?? [];
+    const merged = mergeTrack(machine, track, pauseIntervals);
+    // [startMs, endMs] per merged card, reused by the idle pass below.
+    const trackIntervals: Array<[number, number]> = [];
+    for (let index = 0; index < merged.length; index++) {
+      const group = merged[index];
+      const first = group.observations[0];
+      const last = group.observations[group.observations.length - 1];
+      const startMs = canonicalMs(first.capturedAtUtc);
+      const lastMs = canonicalMs(last.capturedAtUtc);
+      const nextObsMs = index + 1 < merged.length ? canonicalMs(merged[index + 1].observations[0].capturedAtUtc) : Number.POSITIVE_INFINITY;
+      const pauseStartMs = pauseIntervals.find(([ps]) => ps > lastMs)?.[0] ?? Number.POSITIVE_INFINITY;
+      const endMs = Math.max(lastMs, Math.min(lastMs + TIMELINE_MAX_DWELL_MS, nextObsMs, pauseStartMs, dayEndMs));
+      trackIntervals.push([startMs, endMs]);
+      const evidenceIds = group.observations.map((observation) => observation.id);
+      const classification = classifyTimelineObservation(first, categories);
+      cards.push({
+        id: stableCardId(`activity|${machine}|${evidenceKeyOf(first)}|${evidenceKeyOf(last)}`),
+        kind: "activity",
+        title: first.windowTitle.length > 0 ? first.windowTitle : first.app,
+        summary: `${first.app} · ${machine} · ${evidenceIds.length} obs · ${formatDurationMinutes(endMs - startMs)}`,
+        categoryId: classification.categoryId,
+        confidence: classification.confidence,
+        startUtc: isoOf(startMs),
+        endUtc: isoOf(endMs),
+        dayKey: input.date,
+        timezone: input.timezone,
+        machine,
+        evidenceIds,
+        evidenceRange: { firstKey: evidenceKeyOf(first), lastKey: evidenceKeyOf(last) },
+      });
+    }
+
+    // Idle: uncovered remainders between consecutive cards on this track,
+    // pauses removed (a pause wins over idle covering the same minutes).
+    for (let index = 0; index + 1 < trackIntervals.length; index++) {
+      const gapStart = trackIntervals[index][1];
+      const gapEnd = trackIntervals[index + 1][0];
+      if (gapEnd <= gapStart) continue;
+      let pieces: Array<[number, number]> = [[gapStart, gapEnd]];
+      for (const [pauseStart, pauseEnd] of pauseIntervals) {
+        pieces = pieces.flatMap(([start, end]) => subtractInterval(start, end, pauseStart, pauseEnd));
+      }
+      for (const [start, end] of pieces) {
+        cards.push({
+          id: stableCardId(`idle|${machine}|${isoOf(start)}|${isoOf(end)}`),
+          kind: "idle",
+          title: "Idle",
+          summary: `${formatDurationMinutes(end - start)} gap on ${machine}`,
+          categoryId: TIMELINE_RESERVED_IDLE,
+          confidence: 1,
+          startUtc: isoOf(start),
+          endUtc: isoOf(end),
+          dayKey: input.date,
+          timezone: input.timezone,
+          machine,
+          evidenceIds: [],
+          evidenceRange: null,
+        });
+      }
+    }
+  }
+
+  for (const [pauseStart, pauseEnd] of pauseIntervals) {
+    const reason = (input.pauses ?? []).find((pause) => canonicalMs(pause.startUtc) === pauseStart)?.reason;
+    cards.push({
+      id: stableCardId(`pause|${isoOf(pauseStart)}|${isoOf(pauseEnd)}`),
+      kind: "pause",
+      title: "Paused",
+      summary: reason === undefined ? `${formatDurationMinutes(pauseEnd - pauseStart)} user pause` : `${formatDurationMinutes(pauseEnd - pauseStart)} user pause — ${reason}`,
+      categoryId: TIMELINE_RESERVED_PAUSE,
+      confidence: 1,
+      startUtc: isoOf(pauseStart),
+      endUtc: isoOf(pauseEnd),
+      dayKey: input.date,
+      timezone: input.timezone,
+      machine: null,
+      evidenceIds: [],
+      evidenceRange: null,
+    });
+  }
+
+  cards.sort((a, b) => a.startUtc < b.startUtc ? -1 : a.startUtc > b.startUtc ? 1 : a.endUtc < b.endUtc ? -1 : a.endUtc > b.endUtc ? 1 : (a.machine ?? "") < (b.machine ?? "") ? -1 : (a.machine ?? "") > (b.machine ?? "") ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+  return {
+    formatVersion: TIMELINE_FORMAT_VERSION,
+    date: input.date,
+    timezone: input.timezone,
+    startUtc: window.startUtc,
+    endUtc: window.endUtc,
+    cards,
+  };
+}
+
+/**
+ * Canonical byte-stable serialization. Card objects are constructed in a
+ * fixed field order, so `JSON.stringify` output is stable across runs.
+ */
+export function serializeTimelineDay(day: TimelineDay): string {
+  return JSON.stringify(day);
+}

package/src/activity/timeline/categories.ts

@@ -0,0 +1,111 @@
+/**
+ * Timeline category registry (issue #2049): ordered definitions with stable
+ * IDs, names, colors, descriptions, and system/idle flags. Reserved system
+ * categories (`system.*`) must always be present; unknown activity stays
+ * visible in `system.unknown` rather than being silently reassigned.
+ */
+
+import type { TimelineCategory } from "./types.js";
+
+export const TIMELINE_RESERVED_UNKNOWN = "system.unknown";
+export const TIMELINE_RESERVED_IDLE = "system.idle";
+export const TIMELINE_RESERVED_PAUSE = "system.pause";
+
+const COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+
+function isTimelineCategoryId(id: string): boolean {
+  const parts = id.split(".");
+  if (parts.length === 0) return false;
+  for (const part of parts) {
+    if (part.length === 0) return false;
+    const first = part.charCodeAt(0);
+    if (first < 97 || first > 122) return false;
+    for (let i = 1; i < part.length; i += 1) {
+      const code = part.charCodeAt(i);
+      const ok = (code >= 97 && code <= 122) || (code >= 48 && code <= 57) || code === 45;
+      if (!ok) return false;
+    }
+  }
+  return true;
+}
+
+
+/**
+ * Default registry. User category orders step by 10 so a corrected registry
+ * can insert between without renumbering; system categories sort last.
+ */
+export const DEFAULT_TIMELINE_CATEGORIES: readonly TimelineCategory[] = [
+  { id: "development", name: "Development", color: "#3b82f6", description: "Editors, terminals, IDEs, and code forges.", order: 10 },
+  { id: "communication", name: "Communication", color: "#f59e0b", description: "Mail, chat, and meetings.", order: 20 },
+  { id: "browsing", name: "Browsing", color: "#6366f1", description: "Web browsing without a more specific domain match.", order: 30 },
+  { id: "documents", name: "Documents", color: "#10b981", description: "Writing, notes, and PDFs.", order: 40 },
+  { id: "design", name: "Design & Media", color: "#ec4899", description: "Design, audio, and video tools.", order: 50 },
+  { id: "data", name: "Data & Analysis", color: "#84cc16", description: "Spreadsheets, dashboards, and databases.", order: 60 },
+  { id: "admin", name: "Admin", color: "#64748b", description: "File managers, settings, and system utilities.", order: 70 },
+  { id: "entertainment", name: "Entertainment", color: "#ef4444", description: "Video, music, and games.", order: 80 },
+  { id: TIMELINE_RESERVED_UNKNOWN, name: "Uncategorized", color: "#9ca3af", description: "Activity with no matching classification signal. Kept visible, never silently reassigned.", order: 990, system: true },
+  { id: TIMELINE_RESERVED_IDLE, name: "Idle", color: "#d1d5db", description: "Derived gap between cards where no activity was observed.", order: 991, system: true, idle: true },
+  { id: TIMELINE_RESERVED_PAUSE, name: "Paused", color: "#a78bfa", description: "User-declared pause interval.", order: 992, system: true },
+];
+
+/**
+ * Validate a registry: unique well-formed ids, non-empty names, hex colors,
+ * integer orders, reserved categories present and correctly flagged, and the
+ * `system.` namespace reserved. Throws with the offending key path.
+ */
+export function validateTimelineCategories(categories: readonly TimelineCategory[]): void {
+  if (!Array.isArray(categories) || categories.length === 0) {
+    throw new RangeError("timeline categories must be a non-empty array");
+  }
+  const seen = new Set<string>();
+  for (const category of categories) {
+    if (typeof category.id !== "string" || !isTimelineCategoryId(category.id)) {
+      throw new RangeError(`timeline category id must be dotted kebab-case: ${String(category.id)}`);
+    }
+    if (seen.has(category.id)) {
+      throw new RangeError(`timeline category id must be unique: ${category.id}`);
+    }
+    seen.add(category.id);
+    if (typeof category.name !== "string" || category.name.length === 0) {
+      throw new RangeError(`timeline category ${category.id}: name must be a non-empty string`);
+    }
+    if (typeof category.color !== "string" || !COLOR_PATTERN.test(category.color)) {
+      throw new RangeError(`timeline category ${category.id}: color must be #RRGGBB`);
+    }
+    if (typeof category.description !== "string" || category.description.length === 0) {
+      throw new RangeError(`timeline category ${category.id}: description must be a non-empty string`);
+    }
+    if (!Number.isInteger(category.order)) {
+      throw new RangeError(`timeline category ${category.id}: order must be an integer`);
+    }
+    const isReserved = category.id === TIMELINE_RESERVED_UNKNOWN || category.id === TIMELINE_RESERVED_IDLE || category.id === TIMELINE_RESERVED_PAUSE;
+    if (isReserved && category.system !== true) {
+      throw new RangeError(`timeline category ${category.id} is reserved and must set system: true`);
+    }
+    if (!isReserved) {
+      if (category.id.startsWith("system.")) {
+        throw new RangeError(`timeline category id namespace "system." is reserved: ${category.id}`);
+      }
+      if (category.system === true || category.idle === true) {
+        throw new RangeError(`timeline category ${category.id}: only reserved categories may set system/idle flags`);
+      }
+    }
+  }
+  const idle = categories.find((category) => category.id === TIMELINE_RESERVED_IDLE);
+  if (idle !== undefined && idle.idle !== true) {
+    throw new RangeError(`timeline category ${TIMELINE_RESERVED_IDLE} must set idle: true`);
+  }
+  for (const reserved of [TIMELINE_RESERVED_UNKNOWN, TIMELINE_RESERVED_IDLE, TIMELINE_RESERVED_PAUSE]) {
+    if (!categories.some((category) => category.id === reserved)) {
+      throw new RangeError(`timeline categories must include the reserved "${reserved}" category`);
+    }
+  }
+}
+
+/**
+ * Deterministic presentation order: by `order`, then by id as the equal-order
+ * tie-breaker, so two categories sharing an order never swap between runs.
+ */
+export function sortTimelineCategories(categories: readonly TimelineCategory[]): TimelineCategory[] {
+  return [...categories].sort((a, b) => a.order - b.order || (a.id < b.id ? -1 : a.id > b.id ? 1 : 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,8 @@
+/** 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";
+export * from "./query.js";
+export * from "./journal-recap.js";