@volter/twin-world 0.1.0 → 0.1.2

package/src/changeset.ts

@@ -0,0 +1,416 @@
+// `volter-world mark` / `diff` / `changeset` — the WORLD-side verbs over the changeset
+// primitive (docs/OPERATIONAL_VCS.md v0). Thin, exactly like `covers` and `tail` are thin: all
+// the state logic (markers, deltas, content hashing, replay) lives in @volter/twin's
+// control-plane, beside the `actions.jsonl` ledgers it reads. What lives HERE is the only thing
+// the control plane cannot know — where a world keeps its twins' data, and where a world keeps
+// its own marks and changesets.
+//
+// Discovery mirrors `tail.ts`: a world service's ledgers are
+// `<data>/<service>/<state-dir>/world/<state-service>/actions.jsonl`, and one world service may
+// record under more than one state service. Re-discovered on every call, because a twin's ledger
+// dir does not exist until its first action.
+//
+// STORAGE. Marks and changesets are the world's own artifacts, so they live in the world's state
+// dir beside `instance.json`: `.volter/worlds/<world>/{marks,changesets}/<name>.json`. That makes
+// a changeset share its world's lifecycle — `down --purge` takes the twin data AND the changesets
+// cut from it, which is the honest coupling (a changeset whose ledgers were purged is a fossil).
+// `changeset show|replay|list` take a bare name because a changeset is world-scoped but
+// world-PORTABLE: they scan every world's changeset dir, and an ambiguous name is a loud error
+// asking for `--world`, never a silent pick.
+//
+// Read-only over the twins' data at rest, like `tail` — except `replay`, which is the one verb
+// here that WRITES, and it writes only through the control plane's kernel write path.
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  approveChangeset,
+  buildChangeset,
+  captureMarker,
+  changesetHashMatches,
+  changesetReadiness,
+  diffLedgers,
+  normalizeChangeset,
+  replayChangeset,
+  runChangesetVerifiers,
+  stateDirName,
+  withVerification,
+  worldBootMarker,
+  assertSafeChangesetName,
+  assertMarkerBelongsTo,
+  CHANGESET_KIND,
+  MARKER_KIND,
+  WORLD_BOOT_MARKER_ID,
+} from '@volter/twin';
+import type { Changeset, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, LedgerDelta, LedgerRef, ReplayReport, ReplayTarget, WorldMarker } from '@volter/twin';
+import { instanceDir, listWorlds, statusWorld } from './runtime.ts';
+import type { WorldInstance } from './schema.ts';
+
+export type WorldRootOptions = { root?: string };
+
+function resolveRoot(root?: string): string {
+  return resolve(root ?? process.cwd());
+}
+
+/** The world instance, or a loud error that names what this repo actually has. `statusWorld`'s
+ *  own "not found" is correct but bare; a verb an operator reaches for by name should say which
+ *  names exist. */
+function requireWorld(name: string, root: string): WorldInstance {
+  try {
+    return statusWorld(name, root);
+  } catch (error) {
+    if (!/World instance not found/.test(String((error as Error).message))) throw error;
+    const known = listWorlds(root).map((world) => world.name);
+    throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — boot it with \`volter-world up <config> --env-file <path> --name ${name}\``);
+  }
+}
+
+/** Every state service a world service currently records actions under (often exactly one). */
+function stateServicesFor(controlRoot: string): string[] {
+  const stateRoot = join(controlRoot, stateDirName(), 'world');
+  if (!existsSync(stateRoot)) return [];
+  return readdirSync(stateRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(stateRoot, entry.name, 'actions.jsonl')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/** Every action ledger in a world, as control-plane ledger references. */
+export function worldLedgers(name: string, root?: string): LedgerRef[] {
+  const resolvedRoot = resolveRoot(root);
+  const instance = requireWorld(name, resolvedRoot);
+  const ledgers: LedgerRef[] = [];
+  for (const service of Object.keys(instance.services).sort()) {
+    const controlRoot = join(instance.dirs.data, service);
+    for (const stateService of stateServicesFor(controlRoot)) {
+      ledgers.push({ service, stateService, controlRoot });
+    }
+  }
+  return ledgers;
+}
+
+// ── marks ──────────────────────────────────────────────────────────────────────────────────────
+
+export function worldMarksDir(name: string, root?: string): string {
+  return join(instanceDir(resolveRoot(root), name), 'marks');
+}
+
+export function worldChangesetsDir(name: string, root?: string): string {
+  return join(instanceDir(resolveRoot(root), name), 'changesets');
+}
+
+/** `mark-<compact-utc>-<rand>` — sortable by name, collision-free within a millisecond. */
+function defaultMarkerId(now: Date): string {
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+  return `mark-${stamp}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+/** Capture a cross-service base marker for `world` and persist it. */
+export function markWorld(name: string, options: WorldRootOptions & { id?: string; now?: Date } = {}): WorldMarker {
+  const root = resolveRoot(options.root);
+  requireWorld(name, root);
+  const now = options.now ?? new Date();
+  const id = options.id ?? defaultMarkerId(now);
+  assertSafeChangesetName(id, 'marker');
+  const marker = captureMarker({ id, world: name, ledgers: worldLedgers(name, root), createdAt: now.toISOString() });
+  const dir = worldMarksDir(name, root);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${id}.json`), `${JSON.stringify(marker, null, 2)}\n`);
+  return marker;
+}
+
+/** Every mark recorded in a world, oldest first. */
+export function listWorldMarks(name: string, root?: string): WorldMarker[] {
+  const dir = worldMarksDir(name, root);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((file) => file.endsWith('.json'))
+    .map((file) => readMarkerFile(join(dir, file)))
+    .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.id < b.id ? -1 : 1));
+}
+
+function readMarkerFile(path: string): WorldMarker {
+  const marker = JSON.parse(readFileSync(path, 'utf8')) as WorldMarker;
+  if (marker.kind !== MARKER_KIND) throw new Error(`${path}: not a world marker (kind=${JSON.stringify(marker.kind)})`);
+  return marker;
+}
+
+/**
+ * The base a diff/changeset is taken against:
+ *   explicit `--base <id>` → that mark (which must belong to THIS world),
+ *   otherwise the world's most recent mark,
+ *   otherwise `world-boot` — position 0 on every ledger, i.e. everything this world recorded.
+ *
+ * `--base world-boot` is spellable explicitly, so "show me the whole session" never requires
+ * deleting marks.
+ */
+export function resolveBaseMarker(name: string, options: WorldRootOptions & { base?: string } = {}): WorldMarker {
+  const root = resolveRoot(options.root);
+  const instance = requireWorld(name, root);
+  const boot = (): WorldMarker => worldBootMarker(name, instance.createdAt);
+  if (options.base === WORLD_BOOT_MARKER_ID) return boot();
+  if (options.base) {
+    // A marker id may address a mark in ANOTHER world — read it wherever it lives so the
+    // cross-world case fails with "captured in world X, not Y" rather than "no such mark".
+    const found = findMarkerAnywhere(root, options.base);
+    if (!found) {
+      const known = listWorldMarks(name, root).map((mark) => mark.id);
+      throw new Error(`No marker "${options.base}" (world "${name}" has: ${known.length ? known.join(', ') : 'no marks yet — run `volter-world mark ' + name + '`'})`);
+    }
+    assertMarkerBelongsTo(found, name);
+    return found;
+  }
+  const marks = listWorldMarks(name, root);
+  return marks.length ? marks[marks.length - 1]! : boot();
+}
+
+/** Look for a marker id in every world under `root` — the seam that makes a wrong-world base a
+ *  precise error instead of a confusing "not found". */
+function findMarkerAnywhere(root: string, id: string): WorldMarker | null {
+  for (const world of listWorlds(root)) {
+    const path = join(worldMarksDir(world.name, root), `${id}.json`);
+    if (existsSync(path)) return readMarkerFile(path);
+  }
+  return null;
+}
+
+// ── diff ───────────────────────────────────────────────────────────────────────────────────────
+
+/** The world's ledger delta since `base` (default: the last mark, else world-boot). */
+export function diffWorld(name: string, options: WorldRootOptions & { base?: string } = {}): LedgerDelta {
+  const root = resolveRoot(options.root);
+  const base = resolveBaseMarker(name, { root, ...(options.base === undefined ? {} : { base: options.base }) });
+  return diffLedgers({ world: name, ledgers: worldLedgers(name, root), base });
+}
+
+// ── changesets ─────────────────────────────────────────────────────────────────────────────────
+
+export type ChangesetLocation = { changeset: Changeset; world: string; path: string };
+
+/** Freeze the current delta into `<world>/changesets/<name>.json`. */
+export function createWorldChangeset(
+  world: string,
+  name: string,
+  options: WorldRootOptions & { base?: string; verifiers?: ChangesetVerifier[]; now?: Date; overwrite?: boolean } = {},
+): Changeset {
+  const root = resolveRoot(options.root);
+  assertSafeChangesetName(name);
+  const dir = worldChangesetsDir(world, root);
+  const path = join(dir, `${name}.json`);
+  if (existsSync(path) && !options.overwrite) {
+    throw new Error(`Changeset "${name}" already exists in world "${world}" (${path}) — pick another name, or pass --force to replace it`);
+  }
+  const delta = diffWorld(world, { root, ...(options.base === undefined ? {} : { base: options.base }) });
+  const changeset = buildChangeset({
+    name,
+    world,
+    base: delta.base.id,
+    actions: delta.actions,
+    ...(options.verifiers ? { verifiers: options.verifiers } : {}),
+    ...(options.now ? { createdAt: options.now.toISOString() } : {}),
+  });
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, `${JSON.stringify(changeset, null, 2)}\n`);
+  return changeset;
+}
+
+function readChangesetFile(path: string): Changeset {
+  const changeset = JSON.parse(readFileSync(path, 'utf8')) as Changeset;
+  if (changeset.kind !== CHANGESET_KIND) throw new Error(`${path}: not a changeset (kind=${JSON.stringify(changeset.kind)})`);
+  // a v0 object lacks the v1 lifecycle fields on disk; filling them is hash-neutral
+  return normalizeChangeset(changeset);
+}
+
+/** Persist a changeset back where it was found — verify/approve write THROUGH this, so the
+ *  object on disk is always the object the verbs returned. */
+function writeChangesetFile(path: string, changeset: Changeset): void {
+  writeFileSync(path, `${JSON.stringify(changeset, null, 2)}\n`);
+}
+
+/** Every changeset in every world under `root` (or one world with `world`), newest first. */
+export function listWorldChangesets(options: WorldRootOptions & { world?: string } = {}): ChangesetLocation[] {
+  const root = resolveRoot(options.root);
+  const worldNames = options.world ? [options.world] : listWorlds(root).map((world) => world.name);
+  const found: ChangesetLocation[] = [];
+  for (const world of worldNames) {
+    const dir = worldChangesetsDir(world, root);
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir).filter((entry) => entry.endsWith('.json')).sort()) {
+      const path = join(dir, file);
+      found.push({ changeset: readChangesetFile(path), world, path });
+    }
+  }
+  return found.sort((a, b) => (a.changeset.createdAt > b.changeset.createdAt ? -1 : a.changeset.createdAt < b.changeset.createdAt ? 1 : 0));
+}
+
+/** Resolve a bare changeset name across worlds. Ambiguity is an error, never a guess. */
+export function findWorldChangeset(name: string, options: WorldRootOptions & { world?: string } = {}): ChangesetLocation {
+  const root = resolveRoot(options.root);
+  assertSafeChangesetName(name);
+  const matches = listWorldChangesets({ root, ...(options.world ? { world: options.world } : {}) }).filter((entry) => entry.changeset.name === name);
+  if (matches.length === 1) return matches[0]!;
+  if (matches.length > 1) {
+    throw new Error(`Changeset "${name}" exists in more than one world (${matches.map((m) => m.world).sort().join(', ')}) — disambiguate with --world <name>`);
+  }
+  const known = listWorldChangesets({ root, ...(options.world ? { world: options.world } : {}) });
+  const scope = options.world ? `world "${options.world}"` : `${root}`;
+  throw new Error(`No changeset "${name}" in ${scope} (have: ${known.length ? known.map((entry) => `${entry.changeset.name} [${entry.world}]`).join(', ') : 'none — create one with `volter-world changeset create <world> <name>`'})`);
+}
+
+// ── replay ─────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Which state service a replayed action lands in for a given target world service:
+ * the changeset's own state service when the target already records under it (or records
+ * nothing yet — a fresh world, the CI case), the target's single existing state service when
+ * it uses a different name, and a loud error when the target records under several and none of
+ * them is the one the changeset names (there is no correct guess there).
+ */
+function resolveTargetStateService(into: string, service: string, controlRoot: string, wanted: string): string {
+  const existing = stateServicesFor(controlRoot);
+  if (existing.length === 0 || existing.includes(wanted)) return wanted;
+  if (existing.length === 1) return existing[0]!;
+  throw new Error(`World "${into}" service "${service}" records actions under multiple state services (${existing.join(', ')}) and none is "${wanted}" — cannot decide where to replay`);
+}
+
+/** The replay targets a changeset needs inside an existing world (services the world lacks are
+ *  left out — `replayChangeset` reports them loudly by name). */
+function worldReplayTargets(changeset: Changeset, into: string, root: string): { targets: ReplayTarget[]; available: string[]; dataDir: string } {
+  const instance = requireWorld(into, root);
+  const available = Object.keys(instance.services).sort();
+  const targets: ReplayTarget[] = [];
+  for (const service of [...new Set(changeset.actions.map((entry) => entry.service))]) {
+    if (!instance.services[service]) continue; // reported as a missing twin by replayChangeset
+    const controlRoot = join(instance.dirs.data, service);
+    const wanted = changeset.actions.find((entry) => entry.service === service)!.stateService;
+    targets.push({ service, stateService: resolveTargetStateService(into, service, controlRoot, wanted), controlRoot });
+  }
+  return { targets, available, dataDir: instance.dirs.data };
+}
+
+/** Replay a changeset into `into`'s twins, through the control plane's kernel write path. */
+export async function replayWorldChangeset(
+  name: string,
+  options: WorldRootOptions & { into: string; world?: string },
+): Promise<ReplayReport> {
+  const root = resolveRoot(options.root);
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  const { targets, available } = worldReplayTargets(located.changeset, options.into, root);
+  return replayChangeset(located.changeset, { into: options.into, targets, available });
+}
+
+// ── verify / approve / status — the operational-PR contract (v1) ───────────────────────────────
+
+export type VerifyWorldOutcome = {
+  changeset: Changeset;
+  verification: ChangesetVerification;
+  report: ReplayReport;
+  world: string;
+  path: string;
+};
+
+/** The label a throwaway verify target reports as `into` — not a world name on purpose. */
+export const EPHEMERAL_VERIFY_TARGET = 'ephemeral';
+
+/**
+ * `volter-world changeset verify <name> --into <world> | --ephemeral`: replay the changeset
+ * into a clean target, run its verifiers against the post-replay projected state, and record
+ * the outcome ON the object as `verification` — REPLACING any prior run (the record carries
+ * its own provenance: when, into what, against which body hash and world digest). The body
+ * hash never moves: verification is about-the-body metadata, like approvals.
+ *
+ * `--ephemeral` builds a throwaway replay target (fresh empty ledgers per twin, no world
+ * booted), verifies against it, and removes it — the zero-setup CI check. `--into` verifies
+ * inside an existing world, whose twins must cover the changeset AND its verifiers.
+ */
+export async function verifyWorldChangeset(
+  name: string,
+  options: WorldRootOptions & { into?: string; ephemeral?: boolean; world?: string; now?: Date },
+): Promise<VerifyWorldOutcome> {
+  const root = resolveRoot(options.root);
+  if (Boolean(options.into) === Boolean(options.ephemeral)) {
+    throw new Error('volter-world changeset verify: pass exactly one of --into <world> (verify inside an existing world) or --ephemeral (a throwaway replay target)');
+  }
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  const changeset = located.changeset;
+  if (!changesetHashMatches(changeset)) {
+    throw new Error(`Refusing to verify changeset "${name}": its stored contentHash does not match its body — the object drifted after authoring, and a verification would launder that drift`);
+  }
+
+  const intoLabel = options.into ?? EPHEMERAL_VERIFY_TARGET;
+  let scratch: string | null = null;
+  let targets: ReplayTarget[];
+  let available: string[] | undefined;
+  if (options.into) {
+    const resolved = worldReplayTargets(changeset, options.into, root);
+    targets = resolved.targets;
+    available = resolved.available;
+    // a verifier may check a twin the actions never touched — it still needs a real target
+    for (const verifier of changeset.verifiers) {
+      if (targets.some((target) => target.service === verifier.service)) continue;
+      if (!available.includes(verifier.service)) {
+        throw new Error(`Cannot verify changeset "${name}" in world "${options.into}": verifier "${verifier.id}" checks twin "${verifier.service}", which that world does not have (world "${options.into}" has: ${available.join(', ') || 'no services'})`);
+      }
+      const controlRoot = join(resolved.dataDir, verifier.service);
+      targets.push({ service: verifier.service, stateService: resolveTargetStateService(options.into, verifier.service, controlRoot, verifier.service), controlRoot });
+    }
+  } else {
+    scratch = mkdtempSync(join(tmpdir(), 'volter-world-verify-'));
+    const pairs = new Map<string, ReplayTarget>();
+    for (const entry of changeset.actions) {
+      pairs.set(`${entry.service} ${entry.stateService}`, { service: entry.service, stateService: entry.stateService, controlRoot: join(scratch, entry.service) });
+    }
+    for (const verifier of changeset.verifiers) {
+      if (![...pairs.values()].some((target) => target.service === verifier.service)) {
+        pairs.set(`${verifier.service} ${verifier.service}`, { service: verifier.service, stateService: verifier.service, controlRoot: join(scratch, verifier.service) });
+      }
+    }
+    targets = [...pairs.values()];
+  }
+
+  try {
+    const report = await replayChangeset(changeset, { into: intoLabel, targets, ...(available ? { available } : {}) });
+    const at = (options.now ?? new Date()).toISOString();
+    const verification = runChangesetVerifiers(changeset, targets, { at, into: intoLabel });
+    const updated = withVerification(changeset, verification);
+    writeChangesetFile(located.path, updated);
+    return { changeset: updated, verification, report, world: located.world, path: located.path };
+  } finally {
+    if (scratch) rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+export type ApproveWorldOutcome = {
+  changeset: Changeset;
+  approval: ChangesetApproval;
+  world: string;
+  path: string;
+};
+
+/** `volter-world changeset approve <name> --as <principal>`: append an approval bound to the
+ *  current body hash. The control plane refuses a drifted object loudly. */
+export function approveWorldChangeset(
+  name: string,
+  options: WorldRootOptions & { principal: string; note?: string; world?: string; now?: Date },
+): ApproveWorldOutcome {
+  const root = resolveRoot(options.root);
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  const { changeset, approval } = approveChangeset(located.changeset, {
+    principal: options.principal,
+    ...(options.note ? { note: options.note } : {}),
+    ...(options.now ? { at: options.now.toISOString() } : {}),
+  });
+  writeChangesetFile(located.path, changeset);
+  return { changeset, approval, world: located.world, path: located.path };
+}
+
+/** `volter-world changeset status <name>`: the apply-readiness gate, recomputed from the
+ *  object. Truth only — pushing is v2's job. */
+export function statusWorldChangeset(
+  name: string,
+  options: WorldRootOptions & { world?: string } = {},
+): ChangesetReadiness {
+  const root = resolveRoot(options.root);
+  const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+  return changesetReadiness(located.changeset);
+}