@remnic/core 9.65.8 → 9.66.0

package/src/access-mcp.ts

@@ -45,7 +45,7 @@ import { applyToolOutputSchemas } from "./access-mcp-output-schemas.js";
 import { MCP_READ_ONLY_TOOL_SUFFIXES } from "./mcp-read-only-tools.js";
 import { MEETINGS_MCP_TOOLS } from "./meetings/mcp-tools.js";
 import { WEARABLES_MCP_TOOLS } from "./wearables/mcp-tools.js";
-import { WHO_KNOWS_MCP_TOOLS } from "./who-knows.js"; import { LOCATION_MCP_TOOLS } from "./location/mcp-tools.js";
+import { WHO_KNOWS_MCP_TOOLS } from "./who-knows.js"; import { LOCATION_MCP_TOOLS } from "./location/mcp-tools.js"; import { STANDUP_MCP_TOOLS } from "./standup/mcp-tools.js";
 import { PROMOTION_CANDIDATES_MCP_TOOLS } from "./memory-subject.js";
 import { EXTERNAL_WIKI_MCP_TOOLS } from "./external-wiki-mcp-tools.js";
 import { abortError, isAbortError } from "./abort-error.js";
@@ -192,7 +192,7 @@ export const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> =
   "engram.location_status": "location_status", "engram.location_check": "location_check", "engram.location_sync": "location_sync",
   "engram.location_backfill": "location_backfill", "engram.location_day": "location_day",
   "engram.transcript_day": "transcript_day", "engram.transcript_search": "transcript_search",
-  "engram.transcript_memories": "transcript_memories", "engram.meetings_list": "meetings_list", "engram.meetings_get": "meetings_get", "engram.meetings_build": "meetings_build",
+  "engram.transcript_memories": "transcript_memories", "engram.meetings_list": "meetings_list", "engram.meetings_get": "meetings_get", "engram.meetings_build": "meetings_build", "engram.standup": "standup",
   "engram.action_confidence": "action_confidence",
   "engram.chatgpt_memory_inspector": "chatgpt_memory_inspector",
   "engram.day_summary": "day_summary",
@@ -706,7 +706,7 @@ export class EngramMcpServer {
           additionalProperties: false,
         },
       },
-      ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS, ...WHO_KNOWS_MCP_TOOLS, ...PROMOTION_CANDIDATES_MCP_TOOLS, ...LOCATION_MCP_TOOLS,
+      ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS, ...WHO_KNOWS_MCP_TOOLS, ...PROMOTION_CANDIDATES_MCP_TOOLS, ...LOCATION_MCP_TOOLS, ...STANDUP_MCP_TOOLS,
       ...(service.supportPassportEnabled ? SUPPORT_PASSPORT_MCP_TOOLS : []),
       {
         name: "engram.action_confidence",

package/src/access-operations.ts

@@ -695,6 +695,7 @@ import "./support-passport/access-operations.js";
 import "./relay/mission-access.js";
 // Location sync surfaces (issue #2047).
 import "./location/access-operations.js";
+import "./standup/access-operations.js";
 
 export const REGISTERED_OPERATIONS = [
   memoryGetOperation.spec.name,

package/src/access-service-offline-file-content.test.ts

@@ -516,6 +516,69 @@ test("offline apply routes reject forged support-passport metadata and allow pub
   }
 });
 
+test("offline apply rejects JSON-escaped support-passport markers (#2387)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-access-escaped-marker-"));
+  try {
+    const storage = new StorageManager(root);
+    await storage.ensureDirectories();
+    const { service } = createManifestService({ root, storage });
+    // The raw frontmatter text never contains the literal marker substring;
+    // only JSON.parse of the structured-attribute value reconstructs it.
+    const escaped = Buffer.from([
+      "---",
+      "id: escaped-marker",
+      "category: fact",
+      `structuredAttributes: {"support\\u002dpassport-owner":"${"a".repeat(64)}"}`,
+      "---",
+      "Ordinary-looking body",
+    ].join("\n"));
+
+    const chunkPath = "facts/2026-08-13/escaped-chunk.md";
+    await assert.rejects(
+      () => service.offlineSyncApplyFileContent({
+        sourceId: "peer",
+        path: chunkPath,
+        sha256: sha256(escaped),
+        bytes: escaped.length,
+        mtimeMs: 0,
+        offset: 0,
+        content: escaped,
+      }),
+      (error) => error instanceof EngramAccessInputError && /private support-passport record/.test(error.message),
+    );
+    await assert.rejects(() => readFile(path.join(root, chunkPath)));
+
+    const changesetPath = "facts/2026-08-13/escaped-changeset.md";
+    await assert.rejects(
+      () => service.offlineSyncApply({
+        returnCurrentFiles: false,
+        changeset: {
+          format: OFFLINE_SYNC_CHANGESET_FORMAT,
+          schemaVersion: 1,
+          createdAt: new Date().toISOString(),
+          sourceId: "peer",
+          includeTranscripts: true,
+          changes: [{
+            type: "upsert",
+            path: changesetPath,
+            file: {
+              path: changesetPath,
+              sha256: sha256(escaped),
+              bytes: escaped.length,
+              mtimeMs: 0,
+              contentBase64: escaped.toString("base64"),
+            },
+          }],
+        },
+      }),
+      (error) => error instanceof EngramAccessInputError && /private support-passport record/.test(error.message),
+    );
+    await assert.rejects(() => readFile(path.join(root, changesetPath)));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test("offline apply-file-content reports invalid metadata as input errors", async () => {
   const service = createOfflineService();
   await assert.rejects(

package/src/access-surface-catalog.ts

@@ -71,6 +71,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "meetings_list", operation: "meetings_list" },
   { tool: "meetings_get", operation: "meetings_get" },
   { tool: "meetings_build", operation: "meetings_build" },
+  { tool: "standup", operation: "standup" },
   { tool: "action_confidence", operation: "action_confidence" },
   { tool: "chatgpt_memory_inspector", operation: "chatgpt_memory_inspector" },
   { tool: "day_summary", operation: "day_summary" },
@@ -234,6 +235,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "GET", pathname: "/engram/v1/meetings", operation: "meetings_list" },
   { method: "POST", pathname: "/engram/v1/meetings/build", operation: "meetings_build" },
   { method: "GET", pathname: "/engram/v1/meetings/:id", operation: "meetings_get" },
+  { method: "GET", pathname: "/engram/v1/standup", operation: "standup" },
   { method: "POST", pathname: "/engram/v1/observe", operation: "observe" },
   { method: "POST", pathname: "/engram/v1/lcm/search", operation: "lcm_search" },
   { method: "POST", pathname: "/engram/v1/lcm/compaction/flush", operation: "lcm_compaction_flush" },

package/src/activity/config.test.ts

@@ -17,6 +17,7 @@ test("parseActivityConfig defaults to an inert, search-only configuration", () =
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
+    timeline: { enabled: false },
   });
   assert.deepEqual(parseActivityConfig(undefined), defaultActivityConfig());
 });

package/src/activity/config.ts

@@ -1,7 +1,7 @@
 import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
 import { assertValidTimezone } from "./digest.js";
 import type { ImportanceLevel } from "../types.js";
-import type { ActivityConfig, ActivityExtractionMode, ActivitySourceConfig } from "./types.js";
+import type { ActivityConfig, ActivityExtractionMode, ActivitySourceConfig, ActivityTimelineConfig } from "./types.js";
 
 const EXTRACTION_MODES: readonly ActivityExtractionMode[] = ["off", "smart"];
 const IMPORTANCE_LEVELS: readonly ImportanceLevel[] = ["critical", "high", "normal", "low", "trivial"];
@@ -22,6 +22,7 @@ export function defaultActivityConfig(): ActivityConfig {
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
+    timeline: { enabled: false },
   };
 }
 
@@ -182,5 +183,24 @@ export function parseActivityConfig(raw: unknown): ActivityConfig {
     minConfidence: parseUnitInterval(config.minConfidence, "minConfidence", defaults.minConfidence),
     minImportance: minImportance as ImportanceLevel,
     maxMemoriesPerDay,
+    timeline: parseTimelineConfig(config.timeline),
   };
 }
+
+/**
+ * Parse the `activity.timeline.*` block. `enabled` is the master gate for
+ * timeline-card derivation (issue #2049); default false. A non-object block
+ * is malformed and must fail rather than silently disabling the layer.
+ */
+function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
+  if (raw === undefined) return { enabled: false };
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline must be an object");
+  }
+  const timeline = raw as Record<string, unknown>;
+  const enabledValue = coerceBooleanLike(timeline.enabled, "activity.timeline.enabled");
+  if (timeline.enabled !== undefined && enabledValue === undefined) {
+    throw new TypeError("activity.timeline.enabled must be a boolean");
+  }
+  return { enabled: enabledValue ?? false };
+}

package/src/activity/index.ts

@@ -14,4 +14,5 @@ export * from "./runner.js";
 export * from "./scheduler.js";
 export * from "./config.js";
 export * from "./reindex.js";
+export * from "./timeline/index.js";
 export * from "./memory-gen.js";

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