@nebutra/time-machine 0.1.1

package/README.md

@@ -0,0 +1,28 @@
+# @nebutra/time-machine
+
+Status: **WIP**
+
+Chronos product surface for founder-facing timeline views, branches, comparisons,
+annotations, and rollback dry-runs.
+
+## Boundary
+
+`time-machine` does not own historical truth. Event truth stays in
+`@nebutra/event-log`; this package projects it into product data and writes only
+annotation artifacts to `@nebutra/content-store`.
+
+## Commands
+
+```bash
+pnpm time-machine:doctor
+pnpm time-machine:quickstart
+pnpm time-machine:debug
+```
+
+## Current Closure
+
+- Timeline projection over event-log.
+- Branch creation through event-log.
+- Compare narrative over affected assets.
+- Rollback dry-run only.
+- Star annotations as content-store artifacts.

package/dist/chunk-AQ6XF75L.js

@@ -0,0 +1,172 @@
+// src/index.ts
+import { mkdir } from "fs/promises";
+import { join } from "path";
+import { appendCapabilityDebug, readCapabilityDebug } from "@nebutra/capability-kit/debug";
+import { ContentStore } from "@nebutra/content-store";
+import { CapabilityError } from "@nebutra/errors";
+import { EventLog } from "@nebutra/event-log";
+import { assetId } from "@nebutra/generation-context";
+function requireTenant(value) {
+  if (!value?.trim()) {
+    throw new CapabilityError("time-machine", "Time Machine requires tenant context", {
+      suggestion: "Pass tenantId when opening TimeMachine so timeline reads stay tenant-scoped.",
+      statusCode: 400
+    });
+  }
+  return value;
+}
+function nodeKind(event) {
+  if (event.traceId.includes("branch")) return "branch";
+  if (event.traceId.includes("decision")) return "decision";
+  if (event.traceId.includes("play")) return "play_completed";
+  return "milestone";
+}
+function toNode(event) {
+  return {
+    id: `node_${event.id}`,
+    eventId: event.id,
+    kind: nodeKind(event),
+    timestamp: event.at,
+    oneLineSummary: event.summary,
+    branchId: "main",
+    ...event.parent ? { parentNode: `node_${event.parent}` } : {},
+    affectedAssets: event.affected,
+    preview: { kind: "event-summary", text: event.summary }
+  };
+}
+function unique(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+var TimeMachine = class _TimeMachine {
+  #tenantId;
+  #debugRoot;
+  #contentStore;
+  #eventLog;
+  constructor(options) {
+    this.#tenantId = requireTenant(options.tenantId);
+    this.#debugRoot = options.debugRoot ?? process.cwd();
+    this.#contentStore = options.contentStore;
+    this.#eventLog = options.eventLog;
+  }
+  static async open(root = ".nebutra/time-machine", options = {}) {
+    const tenantId = options.tenantId ?? "local";
+    await mkdir(root, { recursive: true });
+    const contentStore = await ContentStore.open(join(root, "content"), { tenantId });
+    const eventLog = await EventLog.open(join(root, "event-log"), { tenantId });
+    return new _TimeMachine({ ...options, tenantId, contentStore, eventLog });
+  }
+  static async fromStores(options) {
+    if (options.root) await mkdir(options.root, { recursive: true });
+    return new _TimeMachine({
+      tenantId: options.tenantId,
+      contentStore: options.contentStore,
+      eventLog: options.eventLog,
+      ...(options.debugRoot ?? options.root) !== void 0 ? { debugRoot: options.debugRoot ?? options.root } : {}
+    });
+  }
+  async timelineView() {
+    const events = await this.#eventLog.timeline();
+    const nodes = events.map(toNode);
+    await this.#debug({ type: "timeline_view", tenantId: this.#tenantId, nodes: nodes.length });
+    return { tenantId: this.#tenantId, truthSource: "event-log", nodes };
+  }
+  async branchFrom(eventId, name) {
+    const branch = await this.#eventLog.branchFrom(eventId, name);
+    const result = {
+      branchId: assetId("branch", `${eventId}_${name}`),
+      name: branch.name,
+      fromEventId: branch.from,
+      createdAt: branch.at
+    };
+    await this.#debug({ type: "branch", tenantId: this.#tenantId, eventId, name });
+    return result;
+  }
+  async star(eventId, label = "starred") {
+    await this.#requireEvent(eventId);
+    const annotation = {
+      eventId,
+      starred: true,
+      label,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      truthSource: "event-log"
+    };
+    const path = `time-machine/annotations/${eventId}.json`;
+    await this.#contentStore.write(path, `${JSON.stringify(annotation, null, 2)}
+`);
+    await this.#eventLog.commit({
+      traceId: assetId("time_machine_annotation", eventId),
+      kind: "content_write",
+      affected: [path],
+      parent: eventId,
+      snapshot: { [path]: `${JSON.stringify(annotation, null, 2)}
+` }
+    });
+    await this.#debug({ type: "star", tenantId: this.#tenantId, eventId, label });
+    return { eventId, starred: true, label, path };
+  }
+  async compare(leftEventId, rightEventId) {
+    const left = await this.#requireEvent(leftEventId);
+    const right = await this.#requireEvent(rightEventId);
+    const changedAssets = unique([...left.affected, ...right.affected]);
+    const narrative = `Compared ${leftEventId} to ${rightEventId}: ${changedAssets.join(
+      ", "
+    )} changed.`;
+    await this.#debug({
+      type: "compare",
+      tenantId: this.#tenantId,
+      leftEventId,
+      rightEventId,
+      changedAssets
+    });
+    return { leftEventId, rightEventId, changedAssets, narrative };
+  }
+  async rollbackDryRun(eventId) {
+    const plan = await this.#eventLog.rollbackTo(eventId);
+    await this.#debug({
+      type: "rollback_dry_run",
+      tenantId: this.#tenantId,
+      eventId,
+      affected: plan.affected
+    });
+    return plan;
+  }
+  async doctor() {
+    const events = await this.#eventLog.timeline();
+    const report = {
+      capability: "time-machine",
+      ok: true,
+      checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      truthSource: "event-log",
+      features: ["timeline", "branch", "compare", "rollback-dry-run", "annotation"],
+      ...events.length === 0 ? { suggestion: "Commit at least one event to Chronos before opening the star-map view." } : {}
+    };
+    await this.#debug({ type: "doctor", tenantId: this.#tenantId, events: events.length });
+    return report;
+  }
+  async close() {
+    await this.#contentStore.close();
+  }
+  async #requireEvent(eventId) {
+    const event = (await this.#eventLog.timeline()).find((record) => record.id === eventId);
+    if (!event) {
+      throw new CapabilityError("time-machine", "Timeline event not found", {
+        suggestion: "Call timelineView and choose an event id from the current tenant.",
+        metadata: { eventId },
+        statusCode: 404
+      });
+    }
+    return event;
+  }
+  async #debug(entry) {
+    await appendCapabilityDebug("time-machine", entry, { root: this.#debugRoot });
+  }
+};
+async function readTimeMachineDebug(root = process.cwd(), limit = 20) {
+  return readCapabilityDebug("time-machine", { root, limit });
+}
+
+export {
+  TimeMachine,
+  readTimeMachineDebug
+};
+//# sourceMappingURL=chunk-AQ6XF75L.js.map

package/dist/chunk-AQ6XF75L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { mkdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { appendCapabilityDebug, readCapabilityDebug } from \"@nebutra/capability-kit/debug\";\nimport { ContentStore } from \"@nebutra/content-store\";\nimport { CapabilityError } from \"@nebutra/errors\";\nimport { EventLog, type EventRecord, type RollbackPlan } from \"@nebutra/event-log\";\nimport { assetId } from \"@nebutra/generation-context\";\n\nexport type TimelineNodeKind = \"milestone\" | \"decision\" | \"branch\" | \"play_completed\";\n\nexport interface TimelineNode {\n  readonly id: string;\n  readonly eventId: string;\n  readonly kind: TimelineNodeKind;\n  readonly timestamp: string;\n  readonly oneLineSummary: string;\n  readonly branchId: string;\n  readonly parentNode?: string;\n  readonly affectedAssets: readonly string[];\n  readonly preview: {\n    readonly kind: \"event-summary\";\n    readonly text: string;\n  };\n}\n\nexport interface TimelineView {\n  readonly tenantId: string;\n  readonly truthSource: \"event-log\";\n  readonly nodes: readonly TimelineNode[];\n}\n\nexport interface TimelineBranch {\n  readonly branchId: string;\n  readonly name: string;\n  readonly fromEventId: string;\n  readonly createdAt: string;\n}\n\nexport interface TimelineAnnotation {\n  readonly eventId: string;\n  readonly starred: true;\n  readonly label: string;\n  readonly path: string;\n}\n\nexport interface TimelineComparison {\n  readonly leftEventId: string;\n  readonly rightEventId: string;\n  readonly changedAssets: readonly string[];\n  readonly narrative: string;\n}\n\nexport interface TimeMachineDoctorReport {\n  readonly capability: \"time-machine\";\n  readonly ok: boolean;\n  readonly checkedAt: string;\n  readonly truthSource: \"event-log\";\n  readonly features: readonly string[];\n  readonly suggestion?: string;\n}\n\nexport interface TimeMachineOptions {\n  readonly tenantId?: string;\n  readonly root?: string;\n  readonly debugRoot?: string;\n  readonly contentStore?: ContentStore;\n  readonly eventLog?: EventLog;\n}\n\nfunction requireTenant(value: string | undefined): string {\n  if (!value?.trim()) {\n    throw new CapabilityError(\"time-machine\", \"Time Machine requires tenant context\", {\n      suggestion: \"Pass tenantId when opening TimeMachine so timeline reads stay tenant-scoped.\",\n      statusCode: 400,\n    });\n  }\n  return value;\n}\n\nfunction nodeKind(event: EventRecord): TimelineNodeKind {\n  if (event.traceId.includes(\"branch\")) return \"branch\";\n  if (event.traceId.includes(\"decision\")) return \"decision\";\n  if (event.traceId.includes(\"play\")) return \"play_completed\";\n  return \"milestone\";\n}\n\nfunction toNode(event: EventRecord): TimelineNode {\n  return {\n    id: `node_${event.id}`,\n    eventId: event.id,\n    kind: nodeKind(event),\n    timestamp: event.at,\n    oneLineSummary: event.summary,\n    branchId: \"main\",\n    ...(event.parent ? { parentNode: `node_${event.parent}` } : {}),\n    affectedAssets: event.affected,\n    preview: { kind: \"event-summary\", text: event.summary },\n  };\n}\n\nfunction unique(values: readonly string[]): string[] {\n  return [...new Set(values)].sort((left, right) => left.localeCompare(right));\n}\n\nexport class TimeMachine {\n  readonly #tenantId: string;\n  readonly #debugRoot: string;\n  readonly #contentStore: ContentStore;\n  readonly #eventLog: EventLog;\n\n  private constructor(\n    options: Required<Pick<TimeMachineOptions, \"tenantId\" | \"contentStore\" | \"eventLog\">> &\n      Pick<TimeMachineOptions, \"debugRoot\">,\n  ) {\n    this.#tenantId = requireTenant(options.tenantId);\n    this.#debugRoot = options.debugRoot ?? process.cwd();\n    this.#contentStore = options.contentStore;\n    this.#eventLog = options.eventLog;\n  }\n\n  static async open(\n    root = \".nebutra/time-machine\",\n    options: Omit<TimeMachineOptions, \"root\" | \"contentStore\" | \"eventLog\"> = {},\n  ): Promise<TimeMachine> {\n    const tenantId = options.tenantId ?? \"local\";\n    await mkdir(root, { recursive: true });\n    const contentStore = await ContentStore.open(join(root, \"content\"), { tenantId });\n    const eventLog = await EventLog.open(join(root, \"event-log\"), { tenantId });\n    return new TimeMachine({ ...options, tenantId, contentStore, eventLog });\n  }\n\n  static async fromStores(\n    options: Required<Pick<TimeMachineOptions, \"tenantId\" | \"contentStore\" | \"eventLog\">> &\n      Pick<TimeMachineOptions, \"root\" | \"debugRoot\">,\n  ): Promise<TimeMachine> {\n    if (options.root) await mkdir(options.root, { recursive: true });\n    return new TimeMachine({\n      tenantId: options.tenantId,\n      contentStore: options.contentStore,\n      eventLog: options.eventLog,\n      ...((options.debugRoot ?? options.root) !== undefined\n        ? { debugRoot: options.debugRoot ?? options.root }\n        : {}),\n    });\n  }\n\n  async timelineView(): Promise<TimelineView> {\n    const events = await this.#eventLog.timeline();\n    const nodes = events.map(toNode);\n    await this.#debug({ type: \"timeline_view\", tenantId: this.#tenantId, nodes: nodes.length });\n    return { tenantId: this.#tenantId, truthSource: \"event-log\", nodes };\n  }\n\n  async branchFrom(eventId: string, name: string): Promise<TimelineBranch> {\n    const branch = await this.#eventLog.branchFrom(eventId, name);\n    const result = {\n      branchId: assetId(\"branch\", `${eventId}_${name}`),\n      name: branch.name,\n      fromEventId: branch.from,\n      createdAt: branch.at,\n    };\n    await this.#debug({ type: \"branch\", tenantId: this.#tenantId, eventId, name });\n    return result;\n  }\n\n  async star(eventId: string, label = \"starred\"): Promise<TimelineAnnotation> {\n    await this.#requireEvent(eventId);\n    const annotation = {\n      eventId,\n      starred: true,\n      label,\n      createdAt: new Date().toISOString(),\n      truthSource: \"event-log\",\n    };\n    const path = `time-machine/annotations/${eventId}.json`;\n    await this.#contentStore.write(path, `${JSON.stringify(annotation, null, 2)}\\n`);\n    await this.#eventLog.commit({\n      traceId: assetId(\"time_machine_annotation\", eventId),\n      kind: \"content_write\",\n      affected: [path],\n      parent: eventId,\n      snapshot: { [path]: `${JSON.stringify(annotation, null, 2)}\\n` },\n    });\n    await this.#debug({ type: \"star\", tenantId: this.#tenantId, eventId, label });\n    return { eventId, starred: true, label, path };\n  }\n\n  async compare(leftEventId: string, rightEventId: string): Promise<TimelineComparison> {\n    const left = await this.#requireEvent(leftEventId);\n    const right = await this.#requireEvent(rightEventId);\n    const changedAssets = unique([...left.affected, ...right.affected]);\n    const narrative = `Compared ${leftEventId} to ${rightEventId}: ${changedAssets.join(\n      \", \",\n    )} changed.`;\n    await this.#debug({\n      type: \"compare\",\n      tenantId: this.#tenantId,\n      leftEventId,\n      rightEventId,\n      changedAssets,\n    });\n    return { leftEventId, rightEventId, changedAssets, narrative };\n  }\n\n  async rollbackDryRun(eventId: string): Promise<RollbackPlan> {\n    const plan = await this.#eventLog.rollbackTo(eventId);\n    await this.#debug({\n      type: \"rollback_dry_run\",\n      tenantId: this.#tenantId,\n      eventId,\n      affected: plan.affected,\n    });\n    return plan;\n  }\n\n  async doctor(): Promise<TimeMachineDoctorReport> {\n    const events = await this.#eventLog.timeline();\n    const report: TimeMachineDoctorReport = {\n      capability: \"time-machine\",\n      ok: true,\n      checkedAt: new Date().toISOString(),\n      truthSource: \"event-log\",\n      features: [\"timeline\", \"branch\", \"compare\", \"rollback-dry-run\", \"annotation\"],\n      ...(events.length === 0\n        ? { suggestion: \"Commit at least one event to Chronos before opening the star-map view.\" }\n        : {}),\n    };\n    await this.#debug({ type: \"doctor\", tenantId: this.#tenantId, events: events.length });\n    return report;\n  }\n\n  async close(): Promise<void> {\n    await this.#contentStore.close();\n  }\n\n  async #requireEvent(eventId: string): Promise<EventRecord> {\n    const event = (await this.#eventLog.timeline()).find((record) => record.id === eventId);\n    if (!event) {\n      throw new CapabilityError(\"time-machine\", \"Timeline event not found\", {\n        suggestion: \"Call timelineView and choose an event id from the current tenant.\",\n        metadata: { eventId },\n        statusCode: 404,\n      });\n    }\n    return event;\n  }\n\n  async #debug(entry: Record<string, unknown>): Promise<void> {\n    await appendCapabilityDebug(\"time-machine\", entry, { root: this.#debugRoot });\n  }\n}\n\nexport async function readTimeMachineDebug(root = process.cwd(), limit = 20): Promise<unknown[]> {\n  return readCapabilityDebug(\"time-machine\", { root, limit });\n}\n"],"mappings":"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","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,36 @@
+import {
+  TimeMachine,
+  readTimeMachineDebug
+} from "./chunk-AQ6XF75L.js";
+
+// src/cli.ts
+var command = process.argv[2] ?? "doctor";
+var root = process.env.TIME_MACHINE_ROOT ?? ".nebutra/time-machine";
+var tenantId = process.env.NEBUTRA_TENANT_ID ?? "local";
+if (command === "doctor") {
+  const machine = await TimeMachine.open(root, { tenantId });
+  try {
+    process.stdout.write(`${JSON.stringify(await machine.doctor(), null, 2)}
+`);
+  } finally {
+    await machine.close();
+  }
+} else if (command === "quickstart") {
+  const machine = await TimeMachine.open(root, { tenantId });
+  try {
+    process.stdout.write(`${JSON.stringify(await machine.timelineView(), null, 2)}
+`);
+  } finally {
+    await machine.close();
+  }
+} else if (command === "debug") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "time-machine", entries: await readTimeMachineDebug() }, null, 2)}
+`
+  );
+} else {
+  process.stderr.write(`Unknown time-machine command: ${command}
+`);
+  process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["import { readTimeMachineDebug, TimeMachine } from \"./index\";\n\nconst command = process.argv[2] ?? \"doctor\";\nconst root = process.env.TIME_MACHINE_ROOT ?? \".nebutra/time-machine\";\nconst tenantId = process.env.NEBUTRA_TENANT_ID ?? \"local\";\n\nif (command === \"doctor\") {\n  const machine = await TimeMachine.open(root, { tenantId });\n  try {\n    process.stdout.write(`${JSON.stringify(await machine.doctor(), null, 2)}\\n`);\n  } finally {\n    await machine.close();\n  }\n} else if (command === \"quickstart\") {\n  const machine = await TimeMachine.open(root, { tenantId });\n  try {\n    process.stdout.write(`${JSON.stringify(await machine.timelineView(), null, 2)}\\n`);\n  } finally {\n    await machine.close();\n  }\n} else if (command === \"debug\") {\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"time-machine\", entries: await readTimeMachineDebug() }, null, 2)}\\n`,\n  );\n} else {\n  process.stderr.write(`Unknown time-machine command: ${command}\\n`);\n  process.exitCode = 1;\n}\n"],"mappings":";;;;;;AAEA,IAAM,UAAU,QAAQ,KAAK,CAAC,KAAK;AACnC,IAAM,OAAO,QAAQ,IAAI,qBAAqB;AAC9C,IAAM,WAAW,QAAQ,IAAI,qBAAqB;AAElD,IAAI,YAAY,UAAU;AACxB,QAAM,UAAU,MAAM,YAAY,KAAK,MAAM,EAAE,SAAS,CAAC;AACzD,MAAI;AACF,YAAQ,OAAO,MAAM,GAAG,KAAK,UAAU,MAAM,QAAQ,OAAO,GAAG,MAAM,CAAC,CAAC;AAAA,CAAI;AAAA,EAC7E,UAAE;AACA,UAAM,QAAQ,MAAM;AAAA,EACtB;AACF,WAAW,YAAY,cAAc;AACnC,QAAM,UAAU,MAAM,YAAY,KAAK,MAAM,EAAE,SAAS,CAAC;AACzD,MAAI;AACF,YAAQ,OAAO,MAAM,GAAG,KAAK,UAAU,MAAM,QAAQ,aAAa,GAAG,MAAM,CAAC,CAAC;AAAA,CAAI;AAAA,EACnF,UAAE;AACA,UAAM,QAAQ,MAAM;AAAA,EACtB;AACF,WAAW,YAAY,SAAS;AAC9B,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,gBAAgB,SAAS,MAAM,qBAAqB,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EACnG;AACF,OAAO;AACL,UAAQ,OAAO,MAAM,iCAAiC,OAAO;AAAA,CAAI;AACjE,UAAQ,WAAW;AACrB;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { ContentStore } from '@nebutra/content-store';
+import { EventLog, RollbackPlan } from '@nebutra/event-log';
+
+type TimelineNodeKind = "milestone" | "decision" | "branch" | "play_completed";
+interface TimelineNode {
+    readonly id: string;
+    readonly eventId: string;
+    readonly kind: TimelineNodeKind;
+    readonly timestamp: string;
+    readonly oneLineSummary: string;
+    readonly branchId: string;
+    readonly parentNode?: string;
+    readonly affectedAssets: readonly string[];
+    readonly preview: {
+        readonly kind: "event-summary";
+        readonly text: string;
+    };
+}
+interface TimelineView {
+    readonly tenantId: string;
+    readonly truthSource: "event-log";
+    readonly nodes: readonly TimelineNode[];
+}
+interface TimelineBranch {
+    readonly branchId: string;
+    readonly name: string;
+    readonly fromEventId: string;
+    readonly createdAt: string;
+}
+interface TimelineAnnotation {
+    readonly eventId: string;
+    readonly starred: true;
+    readonly label: string;
+    readonly path: string;
+}
+interface TimelineComparison {
+    readonly leftEventId: string;
+    readonly rightEventId: string;
+    readonly changedAssets: readonly string[];
+    readonly narrative: string;
+}
+interface TimeMachineDoctorReport {
+    readonly capability: "time-machine";
+    readonly ok: boolean;
+    readonly checkedAt: string;
+    readonly truthSource: "event-log";
+    readonly features: readonly string[];
+    readonly suggestion?: string;
+}
+interface TimeMachineOptions {
+    readonly tenantId?: string;
+    readonly root?: string;
+    readonly debugRoot?: string;
+    readonly contentStore?: ContentStore;
+    readonly eventLog?: EventLog;
+}
+declare class TimeMachine {
+    #private;
+    private constructor();
+    static open(root?: string, options?: Omit<TimeMachineOptions, "root" | "contentStore" | "eventLog">): Promise<TimeMachine>;
+    static fromStores(options: Required<Pick<TimeMachineOptions, "tenantId" | "contentStore" | "eventLog">> & Pick<TimeMachineOptions, "root" | "debugRoot">): Promise<TimeMachine>;
+    timelineView(): Promise<TimelineView>;
+    branchFrom(eventId: string, name: string): Promise<TimelineBranch>;
+    star(eventId: string, label?: string): Promise<TimelineAnnotation>;
+    compare(leftEventId: string, rightEventId: string): Promise<TimelineComparison>;
+    rollbackDryRun(eventId: string): Promise<RollbackPlan>;
+    doctor(): Promise<TimeMachineDoctorReport>;
+    close(): Promise<void>;
+}
+declare function readTimeMachineDebug(root?: string, limit?: number): Promise<unknown[]>;
+
+export { TimeMachine, type TimeMachineDoctorReport, type TimeMachineOptions, type TimelineAnnotation, type TimelineBranch, type TimelineComparison, type TimelineNode, type TimelineNodeKind, type TimelineView, readTimeMachineDebug };

package/dist/index.js

@@ -0,0 +1,9 @@
+import {
+  TimeMachine,
+  readTimeMachineDebug
+} from "./chunk-AQ6XF75L.js";
+export {
+  TimeMachine,
+  readTimeMachineDebug
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/examples/branch.ts

@@ -0,0 +1,22 @@
+import { EventLog } from "@nebutra/event-log";
+import { TimeMachine } from "../src/index";
+
+const root = ".nebutra/time-machine-branch-example";
+const tenantId = "local";
+const eventLog = await EventLog.open(`${root}/event-log`, { tenantId });
+const eventId = await eventLog.commit({
+  traceId: "demo_decision",
+  kind: "content_write",
+  affected: ["company/BRAND.md"],
+  parent: null,
+  snapshot: { "company/BRAND.md": "name: Loop\npalette: blue\n" },
+});
+const machine = await TimeMachine.open(root, { tenantId });
+
+try {
+  process.stdout.write(
+    `${JSON.stringify(await machine.branchFrom(eventId, "purple version"), null, 2)}\n`,
+  );
+} finally {
+  await machine.close();
+}

package/examples/doctor.ts

@@ -0,0 +1,9 @@
+import { TimeMachine } from "../src/index";
+
+const machine = await TimeMachine.open(".nebutra/time-machine-example", { tenantId: "local" });
+
+try {
+  process.stdout.write(`${JSON.stringify(await machine.doctor(), null, 2)}\n`);
+} finally {
+  await machine.close();
+}

package/examples/quickstart.ts

@@ -0,0 +1,10 @@
+import { TimeMachine } from "../src/index";
+
+const machine = await TimeMachine.open(".nebutra/time-machine-example", { tenantId: "local" });
+
+try {
+  const view = await machine.timelineView();
+  process.stdout.write(`${JSON.stringify(view, null, 2)}\n`);
+} finally {
+  await machine.close();
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nebutra/time-machine",
+  "version": "0.1.1",
+  "description": "Chronos product surface for timeline browsing, branching, comparison, and rollback previews",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "status": "wip",
+    "productionReady": false,
+    "surface": "ecosystem-product",
+    "requires": [
+      "@nebutra/event-log for append-only truth",
+      "@nebutra/content-store for annotation artifacts",
+      "@nebutra/capability-kit for debug and doctor surfaces"
+    ],
+    "gaps": [
+      "GUI star-map layout is represented as a data contract until the dashboard surface is wired",
+      "Rollback apply remains intentionally absent; only dry-run plans are exposed",
+      "Large binary media diffing is represented as metadata until sandbox diff workers are available"
+    ],
+    "featureId": "time-machine",
+    "category": "ai",
+    "summary": "Founder-facing view over event-log history without owning event truth"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@nebutra/capability-kit": "0.2.0",
+    "@nebutra/content-store": "0.1.0",
+    "@nebutra/errors": "0.1.0",
+    "@nebutra/event-log": "0.1.0",
+    "@nebutra/generation-context": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/time-machine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/time-machine"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/plays/timeline_view/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: timeline_view
+kind: play
+version: 1.0.0
+description: Build a founder-facing timeline view from event-log history
+required_skills:
+  - event_log.timeline
+  - content_store.write
+sub_agents:
+  - role: timeline_curator
+    allowed_skills: [event_log.timeline, content_store.write]
+depends_on_plays: []
+---
+
+## What this play does
+
+Reads Chronos event history and produces a founder-facing star-map timeline.
+
+## Boundaries
+
+- Event truth stays in event-log.
+- Rollback is dry-run only until the user explicitly confirms a higher-layer apply flow.
+- Branches are experiments, not destructive rewrites.

package/src/cli.ts

@@ -0,0 +1,28 @@
+import { readTimeMachineDebug, TimeMachine } from "./index";
+
+const command = process.argv[2] ?? "doctor";
+const root = process.env.TIME_MACHINE_ROOT ?? ".nebutra/time-machine";
+const tenantId = process.env.NEBUTRA_TENANT_ID ?? "local";
+
+if (command === "doctor") {
+  const machine = await TimeMachine.open(root, { tenantId });
+  try {
+    process.stdout.write(`${JSON.stringify(await machine.doctor(), null, 2)}\n`);
+  } finally {
+    await machine.close();
+  }
+} else if (command === "quickstart") {
+  const machine = await TimeMachine.open(root, { tenantId });
+  try {
+    process.stdout.write(`${JSON.stringify(await machine.timelineView(), null, 2)}\n`);
+  } finally {
+    await machine.close();
+  }
+} else if (command === "debug") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "time-machine", entries: await readTimeMachineDebug() }, null, 2)}\n`,
+  );
+} else {
+  process.stderr.write(`Unknown time-machine command: ${command}\n`);
+  process.exitCode = 1;
+}

package/src/index.test.ts

@@ -0,0 +1,85 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ContentStore } from "@nebutra/content-store";
+import { EventLog } from "@nebutra/event-log";
+import { afterEach, describe, expect, it } from "vitest";
+import { readTimeMachineDebug, TimeMachine } from "./index";
+
+let root: string | undefined;
+let machine: TimeMachine | undefined;
+
+afterEach(async () => {
+  if (machine) await machine.close();
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+  machine = undefined;
+});
+
+async function seed(): Promise<{ runtime: TimeMachine; first: string; second: string }> {
+  root = await mkdtemp(join(tmpdir(), "time-machine-"));
+  const tenantId = "tenant_a";
+  const contentStore = await ContentStore.open(join(root, "content"), { tenantId });
+  const eventLog = await EventLog.open(join(root, "event-log"), { tenantId });
+  const first = await eventLog.commit({
+    traceId: "brand",
+    kind: "content_write",
+    affected: ["company/BRAND.md"],
+    parent: null,
+    snapshot: { "company/BRAND.md": "name: Loop\npalette: blue\n" },
+  });
+  const second = await eventLog.commit({
+    traceId: "film",
+    kind: "content_write",
+    affected: ["company/film_60s.mp4", "company/BRAND.md"],
+    parent: first,
+    snapshot: { "company/BRAND.md": "name: Loop\npalette: purple\n" },
+  });
+  machine = await TimeMachine.fromStores({
+    tenantId,
+    root,
+    contentStore,
+    eventLog,
+  });
+  return { runtime: machine, first, second };
+}
+
+describe("time-machine", () => {
+  it("projects event-log records into a founder timeline without owning truth", async () => {
+    const { runtime, first, second } = await seed();
+
+    const view = await runtime.timelineView();
+
+    expect(view.nodes.map((node) => node.eventId)).toEqual([first, second]);
+    expect(view.nodes[0]).toMatchObject({
+      kind: "milestone",
+      branchId: "main",
+      affectedAssets: ["company/BRAND.md"],
+    });
+    expect(view.truthSource).toBe("event-log");
+  });
+
+  it("branches, stars, compares, and keeps rollback as dry-run only", async () => {
+    const { runtime, first, second } = await seed();
+
+    const branch = await runtime.branchFrom(first, "purple version");
+    const annotation = await runtime.star(first, "first brand");
+    const comparison = await runtime.compare(first, second);
+    const rollback = await runtime.rollbackDryRun(first);
+
+    expect(branch).toMatchObject({ name: "purple version", fromEventId: first });
+    expect(annotation.path).toBe(`time-machine/annotations/${first}.json`);
+    expect(comparison.changedAssets).toContain("company/film_60s.mp4");
+    expect(comparison.narrative).toContain("company/BRAND.md");
+    expect(rollback.dryRun).toBe(true);
+    expect(rollback.suggestion).toContain("Review");
+  });
+
+  it("records debug entries through capability-kit helpers", async () => {
+    const { runtime } = await seed();
+
+    await runtime.doctor();
+
+    await expect(readTimeMachineDebug(root)).resolves.toEqual(expect.any(Array));
+  });
+});