@remnic/core 9.65.7 → 9.66.0

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;
 }

package/src/cli/okf-commands.ts

@@ -1,6 +1,8 @@
+import path from "node:path";
 import type { Orchestrator } from "../orchestrator.js";
 import type { CliCommand } from "../cli.js";
 import { runOkfCliCommand } from "../okf/cli.js";
+import { exportOkfBundle, parseIncludeStatus } from "../transfer/export-okf.js";
 
 export function registerOkfCommands(cmd: CliCommand, orchestrator: Orchestrator): void {
   const okfCmd = cmd.command("okf").description("OKF v0.1 conformance (lint, sweep)");
@@ -9,6 +11,7 @@ export function registerOkfCommands(cmd: CliCommand, orchestrator: Orchestrator)
       memoryDir: orchestrator.config.memoryDir,
       conformanceEnabled: orchestrator.config.okf.conformanceEnabled,
       sweepEnabled: orchestrator.config.okf.sweepEnabled,
+      indexFilesEnabled: orchestrator.config.okf.indexFilesEnabled,
     });
     if (code !== 0) process.exitCode = code;
   };
@@ -21,3 +24,45 @@ export function registerOkfCommands(cmd: CliCommand, orchestrator: Orchestrator)
     await forward(["sweep", ...(options.json === true ? ["--json"] : [])]);
   });
 }
+
+export function registerExportOkfCommand(exportCmd: CliCommand, orchestrator: Orchestrator): void {
+  exportCmd
+    .command("okf")
+    .description("Export a portable OKF v0.1 knowledge bundle")
+    .requiredOption("--out <path>", "Output directory")
+    .option("--namespace <ns>", "Namespace to export")
+    .option("--include-status <status>", "Repeatable status allow-list (default: active)")
+    .option("--include-categories <categories>", "Comma-separated category allow-list")
+    .option("--exclude-tags <tags>", "Comma-separated tags to drop")
+    .option("--include-profile", "Include profile.md (default off)")
+    .option("--include-wearables", "Include wearable day transcripts (default off)")
+    .option("--log", "Write log.md from the lifecycle ledger")
+    .option("--force", "Replace a non-empty output directory")
+    .action(async (...args: unknown[]) => {
+      const options = (args[0] ?? {}) as Record<string, unknown>;
+      const out = options.out ? String(options.out) : "";
+      if (!out) throw new Error("Missing --out");
+      const includeStatus = parseIncludeStatus(options.includeStatus);
+      const namespace = options.namespace ? String(options.namespace) : "";
+      const memoryDir = namespace
+        ? path.join(orchestrator.config.memoryDir, "namespaces", namespace)
+        : orchestrator.config.memoryDir;
+      const result = await exportOkfBundle({
+        memoryDir,
+        outDir: out,
+        includeStatus,
+        includeCategories: options.includeCategories ? String(options.includeCategories).split(",") : undefined,
+        excludeTags: options.excludeTags ? String(options.excludeTags).split(",") : undefined,
+        includeProfile: options.includeProfile === true,
+        includeWearables: options.includeWearables === true,
+        includeLog: options.log === true,
+        force: options.force === true,
+      });
+      if (result.plaintextWarning) {
+        console.log("PLAINTEXT EXPORT: the OKF bundle is unencrypted.");
+      }
+      console.log(
+        `OKF export: ${result.exported} concepts, ${result.excluded} excluded`,
+      );
+    });
+}

package/src/cli.ts

@@ -15,7 +15,7 @@ import { utcDayRange } from "./transcript.js";
 import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerMeetingsCommands } from "./cli/meetings-commands.js";
-import { registerOkfCommands } from "./cli/okf-commands.js";
+import { registerExportOkfCommand, registerOkfCommands } from "./cli/okf-commands.js";
 import { registerSkillsCommands } from "./cli/skills-commands.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
 import { registerCreationLedgerCommands } from "./cli/creation-ledger-commands.js";
@@ -4367,7 +4367,7 @@ export function registerCli(
             return;
           }
           console.log("OK");
-        });
+        }); registerExportOkfCommand(exportCmd, orchestrator);
 
       const importCmd = cmd
         .command("import")