@volter/twin 0.1.0

package/src/status.ts

@@ -0,0 +1,58 @@
+// world status (the twins architecture notes → "Status"). The operator safety
+// dashboard: it makes the four state classes impossible to confuse — queued
+// deliveries, canonical observed events, local transaction commits, and push/apply
+// records — plus drift, conflicts, and stale bases. Pure read over the kernel
+// ledgers; deterministic.
+import { listActions, pendingActions } from './actions.ts';
+import { isFork, forkDivergence } from './fork.ts';
+import { pendingConflicts } from './plan.ts';
+import { unconfirmedPushes } from './pushLedger.ts';
+import { queueCounts } from './queueLifecycle.ts';
+import type { QueueCounts } from './queueLifecycle.ts';
+import { isBaseStale, readLocalRef, readRemoteRef } from './refs.ts';
+import type { WorldRemoteRef } from './refs.ts';
+
+export type WorldStatus = {
+  service: string;
+  remote: WorldRemoteRef | null;
+  queue: QueueCounts;
+  local: { unpushed: number; reverted: number };
+  push: { unconfirmed: number };
+  drift: { created: number; changed: number } | null;
+  conflicts: Array<{ actionId: string; reason: string }>;
+  staleBase: boolean | null;
+};
+
+export function worldStatus(
+  service: string,
+  opts: { root?: string; forkId?: string; provider?: string; refName?: string } = {},
+): WorldStatus {
+  const { root, forkId, provider, refName = 'main' } = opts;
+  const actions = listActions(service, root);
+  const remote = provider ? readRemoteRef(service, provider, refName, root) : null;
+  const local = forkId ? readLocalRef(service, forkId, root) : null;
+  const drift = isFork(service, root ?? '') ? (() => { const d = forkDivergence(service, root ?? ''); return { created: d.created.length, changed: d.changed.length }; })() : null;
+  return {
+    service,
+    remote,
+    queue: queueCounts(service, root),
+    local: { unpushed: pendingActions(service, root).length, reverted: actions.filter((a) => a.op === 'revert').length },
+    push: { unconfirmed: unconfirmedPushes(service, root).length },
+    drift,
+    conflicts: pendingConflicts(service, root),
+    staleBase: local ? isBaseStale(local, root) : null,
+  };
+}
+
+/** Render the status as the operator text block the doc shows. */
+export function formatStatus(s: WorldStatus): string {
+  const lines: string[] = [];
+  lines.push(s.remote ? `remote/${s.remote.provider}/${s.remote.name} at ${s.remote.cursor ?? s.remote.eventId ?? '(no checkpoint)'}` : 'remote: (no ref recorded)');
+  lines.push(`queue: ${s.queue.queued} queued, ${s.queue.committed} committed, ${s.queue.ignored} ignored, ${s.queue.superseded} superseded, ${s.queue.poisoned} poisoned`);
+  lines.push(`local: ${s.local.unpushed} unpushed transactions, ${s.local.reverted} reverted`);
+  lines.push(`push: ${s.push.unconfirmed} provider_accepted/attempted awaiting observed confirmation`);
+  if (s.drift) lines.push(`drift: ${s.drift.created} created, ${s.drift.changed} changed since fork base`);
+  lines.push(`conflicts: ${s.conflicts.length}${s.conflicts.length ? ` (${s.conflicts.map((c) => c.actionId).join(', ')})` : ''}`);
+  if (s.staleBase !== null) lines.push(`base: ${s.staleBase ? 'STALE — rebase before push' : 'current'}`);
+  return lines.join('\n');
+}

package/src/storage.ts

@@ -0,0 +1,632 @@
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import {
+  GenericWorldStateSchema,
+  WorldServiceEventSchema,
+} from './schemas.ts';
+import type {
+  AppendEventResult,
+  CommitQueuedEventsResult,
+  EnqueueEventResult,
+  GenericWorldState,
+  QueuedWorldServiceEvent,
+  WorldPaths,
+  WorldReducer,
+  WorldServiceEvent,
+} from './types.ts';
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function projectRoot(root?: string): string {
+  return resolve(root || process.env.PROJECT_ROOT || process.cwd());
+}
+
+/**
+ * Name of the per-project state directory holding world data
+ * (`<root>/<stateDir>/world/...`). Defaults to `.volter`; hosts that need a
+ * different directory set VOLTER_STATE_DIR. Every path in this package must
+ * go through worldStateRoot — never the literal.
+ */
+export function stateDirName(): string {
+  return process.env.VOLTER_STATE_DIR || '.volter';
+}
+
+export function worldStateRoot(root?: string): string {
+  return join(projectRoot(root), stateDirName(), 'world');
+}
+
+function assertServiceName(service: string): string {
+  if (!/^[A-Za-z0-9_-]+$/.test(service)) {
+    throw new Error(`Invalid world service name: ${service}`);
+  }
+  return service;
+}
+
+export function worldPaths(service: string, root?: string): WorldPaths {
+  const safeService = assertServiceName(service);
+  const resolvedRoot = projectRoot(root);
+  const dir = join(worldStateRoot(root), safeService);
+  return {
+    root: resolvedRoot,
+    service: safeService,
+    dir,
+    events: join(dir, 'events.jsonl'),
+    state: join(dir, 'state.json'),
+    resources: join(dir, 'resources'),
+    cursors: join(dir, 'cursors'),
+    ingests: join(dir, 'ingests'),
+    eventQueue: join(dir, 'event-queue.jsonl'),
+  };
+}
+
+function readJsonl<T>(path: string): T[] {
+  if (!existsSync(path)) return [];
+  const rows: T[] = [];
+  for (const [index, line] of readFileSync(path, 'utf8').split('\n').entries()) {
+    if (!line.trim()) continue;
+    try {
+      rows.push(JSON.parse(line) as T);
+    } catch (error) {
+      throw new Error(`${path}:${index + 1}: invalid JSONL row: ${(error as Error).message}`);
+    }
+  }
+  return rows;
+}
+
+/** Read + parse a whole-file JSON sidecar, citing the path on a parse failure (mirrors
+ *  readJsonl's `${path}:...` error shape). Callers own existence semantics — this parses a
+ *  file that is expected to exist; guard with existsSync first when absence is allowed. */
+export function readJsonFile<T>(path: string): T {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch (error) {
+    throw new Error(`${path}: invalid JSON: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Append `data` to `path`. When VOLTER_DURABLE=1, `fsyncSync` the file after the write so
+ * the appended record survives an OS crash / power loss — not just a process crash.
+ *
+ * Default (VOLTER_DURABLE unset) is OFF: `appendFileSync` is a completed write syscall, so a
+ * *process* crash after it returns still leaves the record on the log (the OS owns the page
+ * cache). The window this leaves open is a **kernel-panic / power loss** between the write
+ * landing in the page cache and the fs flushing it to stable storage — a torn or lost tail
+ * record. That crash window matters more once real pulled staging data lives in these files
+ * (purpose 2), so hosts that need durability opt in with VOLTER_DURABLE=1 at the cost of an
+ * fsync per append. See ARCHITECTURE.md D1.
+ */
+export function appendDurable(path: string, data: string): void {
+  const fd = openSync(path, 'a');
+  try {
+    appendFileSync(fd, data);
+    if (process.env.VOLTER_DURABLE === '1') fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Opt-in structured stderr logging for the audit trail (ARCHITECTURE-REVIEW-TODOS D3):
+ * one line per action-log append and per push-ledger row, so "who reviewed the change
+ * that caused this real write" is mechanically greppable from a single log stream via
+ * `correlationId`. Off by default — mirrors the VOLTER_DURABLE opt-in policy above: no
+ * always-on I/O, never on the default path. Set VOLTER_TWIN_LOG=1 to enable.
+ */
+export function twinLog(kind: string, details: Record<string, unknown>): void {
+  if (process.env.VOLTER_TWIN_LOG !== '1') return;
+  console.error(`[twin:${kind}]`, JSON.stringify(details));
+}
+
+function appendJsonl(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendDurable(path, `${JSON.stringify(value)}\n`);
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** How long a lock may live before an acquirer treats it as abandoned. Above the 10s
+ *  wait timeout so a live-but-slow holder is never reclaimed out from under itself. */
+const LOCK_STALE_MS = 60_000;
+
+type LockHolder = { pid: number; hostname: string; at: string };
+
+function readLockHolder(lockPath: string): LockHolder | null {
+  try {
+    return JSON.parse(readFileSync(lockPath, 'utf8')) as LockHolder;
+  } catch {
+    return null; // missing, empty (mid-write), or malformed
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // ESRCH → no such process (dead); EPERM → exists but not ours to signal (alive)
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/** A lock is stale when its holder is provably gone (same host + dead pid) or it has
+ *  outlived LOCK_STALE_MS. The age falls back to the lockfile's own mtime when the
+ *  `at` record is unreadable — so a writer that crashed between creating the lock and
+ *  recording itself is still eventually reclaimed, while a freshly-created (recent
+ *  mtime) empty lock is left alone, avoiding a race with the live writer. */
+function lockIsStale(lockPath: string): boolean {
+  const holder = readLockHolder(lockPath);
+  if (holder && holder.hostname === hostname() && Number.isInteger(holder.pid) && !pidAlive(holder.pid)) {
+    return true;
+  }
+  const recordedAt = holder && typeof holder.at === 'string' ? Date.parse(holder.at) : NaN;
+  let stamp = recordedAt;
+  if (!Number.isFinite(stamp)) {
+    try {
+      stamp = statSync(lockPath).mtimeMs;
+    } catch {
+      return false; // lock vanished — let the next openSync settle it
+    }
+  }
+  return Date.now() - stamp > LOCK_STALE_MS;
+}
+
+/** Run `fn` holding an exclusive cross-process file lock (the same primitive the event log
+ *  uses). Used to make read-then-append critical sections atomic across processes. The
+ *  lockfile records `{pid, hostname, at}`; a contender that finds a stale lock (dead pid or
+ *  age > LOCK_STALE_MS) reclaims it by atomically renaming it aside — so a crashed holder
+ *  can't wedge the world forever. Reclaim is race-safe: only the process that wins the
+ *  rename clears the stale inode, and the exclusive `wx` create still decides the winner. */
+export function withFileLock<T>(lockPath: string, fn: () => T): T {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  const started = Date.now();
+  let fd: number | null = null;
+  while (fd === null) {
+    try {
+      fd = openSync(lockPath, 'wx');
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'EEXIST') throw error;
+      if (lockIsStale(lockPath)) {
+        const holder = readLockHolder(lockPath);
+        const salvage = `${lockPath}.stale.${process.pid}.${Date.now()}`;
+        try {
+          renameSync(lockPath, salvage);
+        } catch (renameError) {
+          if ((renameError as NodeJS.ErrnoException).code === 'ENOENT') continue; // another contender reclaimed it
+          throw renameError;
+        }
+        console.warn(
+          `[world] reclaiming stale storage lock ${lockPath} (held by pid ${holder?.pid ?? '?'} on ${holder?.hostname ?? '?'} since ${holder?.at ?? 'unknown'})`,
+        );
+        try {
+          unlinkSync(salvage);
+        } catch { /* the moved-aside stale inode; safe to leave if unlink fails */ }
+        continue; // retry the exclusive create immediately
+      }
+      if (Date.now() - started > 10_000) {
+        throw new Error(`Timed out waiting for world storage lock: ${lockPath}`);
+      }
+      sleepSync(25);
+    }
+  }
+
+  // Record the holder so a later contender can detect staleness. Best-effort: a write
+  // failure here doesn't weaken exclusivity, only staleness diagnostics.
+  try {
+    writeFileSync(fd, `${JSON.stringify({ pid: process.pid, hostname: hostname(), at: new Date().toISOString() } satisfies LockHolder)}\n`);
+  } catch { /* ignore */ }
+
+  try {
+    return fn();
+  } finally {
+    closeSync(fd);
+    try {
+      unlinkSync(lockPath);
+    } catch { /* already reclaimed by a stale-lock sweep */ }
+  }
+}
+
+function writeJsonAtomic(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+export function listEvents(service: string, root?: string): WorldServiceEvent[] {
+  const paths = worldPaths(service, root);
+  return readJsonl<unknown>(paths.events).map((row) => WorldServiceEventSchema.parse(row));
+}
+
+// ── Append dedupe index ─────────────────────────────────────────────────────
+// appendEvent must check id/idempotencyKey uniqueness on every append; a full
+// re-read + zod parse of the log per append is O(N) and turns a relay run
+// into O(N·M). The index caches the id/key sets per events file, validated by
+// file size AND mtime: the log is append-only under the file lock, so a
+// matching size+mtime means the cache is current. Size alone is not enough —
+// an external rewrite that replaces the file with SAME-SIZE-but-different
+// content (e.g. a same-length id/key swap) is invisible to a size-only check
+// and would leave the cache silently wrong (stale ids "known", new ids not),
+// letting a genuine duplicate slip past dedup. mtime changes on any write
+// (rewrite or append), so size+mtime together catch both a length-changing
+// AND a length-preserving external rewrite; any such change forces a rebuild.
+// Rebuilds use plain JSON.parse of two fields — full schema validation stays
+// where it belongs (listEvents, and the event being appended).
+
+type EventsIndex = { size: number; mtimeMs: number; ids: Set<string>; keys: Set<string> };
+
+const eventsIndexCache = new Map<string, EventsIndex>();
+
+function eventsFileStamp(eventsPath: string): { size: number; mtimeMs: number } {
+  if (!existsSync(eventsPath)) return { size: 0, mtimeMs: 0 };
+  const stat = statSync(eventsPath);
+  return { size: stat.size, mtimeMs: stat.mtimeMs };
+}
+
+function eventsIndexFor(eventsPath: string): EventsIndex {
+  const { size, mtimeMs } = eventsFileStamp(eventsPath);
+  const cached = eventsIndexCache.get(eventsPath);
+  if (cached && cached.size === size && cached.mtimeMs === mtimeMs) return cached;
+  const index: EventsIndex = { size, mtimeMs, ids: new Set(), keys: new Set() };
+  for (const row of readJsonl<{ id?: unknown; idempotencyKey?: unknown }>(eventsPath)) {
+    if (typeof row.id === 'string') index.ids.add(row.id);
+    if (typeof row.idempotencyKey === 'string') index.keys.add(row.idempotencyKey);
+  }
+  eventsIndexCache.set(eventsPath, index);
+  return index;
+}
+
+/** Targeted fetch of one event row by id or idempotencyKey (rare duplicate path). */
+function findEventRow(eventsPath: string, id: string, idempotencyKey: string): WorldServiceEvent | null {
+  for (const row of readJsonl<{ id?: unknown; idempotencyKey?: unknown }>(eventsPath)) {
+    if (row.id === id || row.idempotencyKey === idempotencyKey) {
+      return WorldServiceEventSchema.parse(row);
+    }
+  }
+  return null;
+}
+
+function ensureEventDirs(paths: WorldPaths): void {
+  mkdirSync(paths.dir, { recursive: true });
+  mkdirSync(paths.resources, { recursive: true });
+  mkdirSync(paths.cursors, { recursive: true });
+  mkdirSync(paths.ingests, { recursive: true });
+}
+
+/** Exported so other modules that share a service's events log (e.g. egress.ts,
+ *  TWIN-58) can serialize their own critical sections on the SAME lock appendEvent
+ *  itself uses, instead of inventing a second, uncoordinated lockfile. */
+export function eventsLockPath(paths: WorldPaths): string {
+  return join(paths.dir, 'events.jsonl.lock');
+}
+
+/**
+ * The append body, assuming the caller already holds `eventsLockPath(paths)`. Split
+ * out so `commitQueuedEvents` can run a whole batch of appends (and the rebuild that
+ * follows them) under ONE lock acquisition instead of nesting a fresh `withFileLock`
+ * per row — `withFileLock` is not reentrant, so re-acquiring it from inside an
+ * already-held lock in the same process would just spin to its own timeout. Also
+ * exported for egress.ts (TWIN-58): performExternalWrite's ledger-check +
+ * intent-append span holds `eventsLockPath` itself, so it must append through this
+ * already-locked path rather than the public `appendEvent` (which would try to
+ * re-acquire the same lock and spin to its own timeout).
+ */
+export function appendEventLocked(parsed: WorldServiceEvent, paths: WorldPaths): AppendEventResult {
+  const index = eventsIndexFor(paths.events);
+  if (index.ids.has(parsed.id) || index.keys.has(parsed.idempotencyKey)) {
+    const duplicate = findEventRow(paths.events, parsed.id, parsed.idempotencyKey);
+    if (!duplicate) throw new Error(`World events index out of sync for ${paths.events}; delete nothing — rerun to rebuild`);
+    // observedAt (delivery time), occurredAt (poll-based connectors use
+    // poll-cycle time, not the resource's own timestamp), and external.url
+    // (a convenience pointer — provider URLs embed mutable title slugs,
+    // e.g. Linear) are metadata, not event identity: re-observations
+    // differing only there are duplicates, not conflicts.
+    // external.provider/id ARE identity.
+    const stripMetadata = (event: WorldServiceEvent) => {
+      const { observedAt: _observedAt, occurredAt: _occurredAt, external, ...content } = event;
+      if (!external) return content;
+      const { url: _url, ...externalIdentity } = external;
+      return { ...content, external: externalIdentity };
+    };
+    if (JSON.stringify(stripMetadata(duplicate)) !== JSON.stringify(stripMetadata(parsed))) {
+      throw new Error(
+        `Conflicting duplicate ${parsed.service} event: ${parsed.id} / ${parsed.idempotencyKey} conflicts with ${duplicate.id}`,
+      );
+    }
+    return { event: duplicate, appended: false, duplicateOf: duplicate.id };
+  }
+
+  appendJsonl(paths.events, parsed);
+  const stamp = eventsFileStamp(paths.events);
+  index.ids.add(parsed.id);
+  index.keys.add(parsed.idempotencyKey);
+  index.size = stamp.size;
+  index.mtimeMs = stamp.mtimeMs;
+  return { event: parsed, appended: true };
+}
+
+export function appendEvent(event: WorldServiceEvent, root?: string): AppendEventResult {
+  const parsed = WorldServiceEventSchema.parse(event);
+  const paths = worldPaths(parsed.service, root);
+  ensureEventDirs(paths);
+  return withFileLock(eventsLockPath(paths), () => appendEventLocked(parsed, paths));
+}
+
+function queuedEventId(event: WorldServiceEvent): string {
+  return `queue:${event.service}:${event.idempotencyKey}`;
+}
+
+export function listQueuedEvents(service: string, root?: string): QueuedWorldServiceEvent[] {
+  const paths = worldPaths(service, root);
+  return readJsonl<QueuedWorldServiceEvent>(paths.eventQueue);
+}
+
+export function enqueueEvent(
+  event: WorldServiceEvent,
+  options: { root?: string; source?: QueuedWorldServiceEvent['source']; receivedAt?: string; id?: string } = {},
+): EnqueueEventResult {
+  const parsed = WorldServiceEventSchema.parse(event);
+  const paths = worldPaths(parsed.service, options.root);
+  mkdirSync(paths.dir, { recursive: true });
+  mkdirSync(paths.ingests, { recursive: true });
+  const queued: QueuedWorldServiceEvent = {
+    id: options.id ?? queuedEventId(parsed),
+    service: parsed.service,
+    receivedAt: options.receivedAt ?? nowIso(),
+    source: options.source ?? 'listener',
+    event: parsed,
+  };
+
+  return withFileLock(join(paths.dir, 'event-queue.jsonl.lock'), () => {
+    const existing = readJsonl<QueuedWorldServiceEvent>(paths.eventQueue);
+    const duplicate = existing.find((candidate) => candidate.id === queued.id || candidate.event.idempotencyKey === queued.event.idempotencyKey);
+    if (duplicate) return { queued: duplicate, appended: false, duplicateOf: duplicate.id };
+    appendJsonl(paths.eventQueue, queued);
+    return { queued, appended: true };
+  });
+}
+
+/**
+ * Commit queued (webhook/listener) events into the canonical log, then rebuild the
+ * generic projection — spanning BOTH under the SAME events-lock acquisition (D7).
+ * Appending each event and rebuilding state.json are two separate durable writes;
+ * without a shared lock, a concurrent commit/append on another process could
+ * interleave between "this commit's last append" and "this commit's rebuild",
+ * so the rebuilt state.json would not correspond to exactly this commit's view of
+ * the log. Holding one lock across the whole sequence rules that out: no other
+ * appendEvent/commitQueuedEvents call for this service can run until both the
+ * appends AND the rebuild here have completed. (A single-process crash between the
+ * last durable append and the rebuild can still leave state.json one rebuild behind
+ * — that window is inherent to a two-file update with no WAL, and is unaffected by
+ * locking; it is closed by the next successful commit/rebuild, which always starts
+ * from the durably-appended log, so no event is ever lost, only state.json's
+ * projection is briefly stale.)
+ */
+export function commitQueuedEvents(
+  service: string,
+  options: { root?: string; limit?: number } = {},
+): CommitQueuedEventsResult {
+  const paths = worldPaths(service, options.root);
+  ensureEventDirs(paths);
+  const queued = listQueuedEvents(service, options.root).sort((a, b) => a.event.occurredAt.localeCompare(b.event.occurredAt) || a.receivedAt.localeCompare(b.receivedAt) || a.id.localeCompare(b.id));
+  const limit = options.limit ?? queued.length;
+
+  return withFileLock(eventsLockPath(paths), () => {
+    let committed = 0;
+    let skipped = 0;
+    const eventIds: string[] = [];
+    for (const row of queued.slice(0, limit)) {
+      const parsed = WorldServiceEventSchema.parse(row.event);
+      const result = appendEventLocked(parsed, paths);
+      if (result.appended) {
+        committed += 1;
+        eventIds.push(result.event.id);
+      } else {
+        skipped += 1;
+      }
+    }
+    if (committed > 0) rebuildGenericState(service, options.root);
+    return { service, queued: Math.min(queued.length, limit), committed, skipped, eventIds };
+  });
+}
+
+// NOTE: annotation read/write (listAnnotations/addAnnotation/createAnnotation) moved
+// to @volter/tracker/world-annotations — annotations are a tracker concern.
+
+export function genericWorldReducer(state: GenericWorldState, event: WorldServiceEvent): GenericWorldState {
+  const key = `${event.subject.type}:${event.subject.id}`;
+  return GenericWorldStateSchema.parse({
+    ...state,
+    eventCount: state.eventCount + 1,
+    latestEventId: event.id,
+    subjects: {
+      ...state.subjects,
+      [key]: {
+        type: event.subject.type,
+        id: event.subject.id,
+        latestEventId: event.id,
+        latestType: event.type,
+        updatedAt: event.occurredAt || event.observedAt,
+      },
+    },
+  });
+}
+
+export function emptyGenericState(service: string): GenericWorldState {
+  return {
+    version: 1,
+    service: assertServiceName(service),
+    rebuiltAt: nowIso(),
+    eventCount: 0,
+    subjects: {},
+  };
+}
+
+export function rebuildState<State>(
+  service: string,
+  initialState: State,
+  reducer: WorldReducer<State>,
+  root?: string,
+): State {
+  const paths = worldPaths(service, root);
+  const state = listEvents(service, root).reduce(reducer, initialState);
+  writeJsonAtomic(paths.state, state);
+  return state;
+}
+
+export function rebuildGenericState(service: string, root?: string): GenericWorldState {
+  return rebuildState(service, emptyGenericState(service), genericWorldReducer, root);
+}
+
+export function loadState<T = unknown>(service: string, root?: string): T | null {
+  const paths = worldPaths(service, root);
+  if (!existsSync(paths.state)) return null;
+  return readJsonFile<T>(paths.state);
+}
+
+export function createEvent(input: Omit<WorldServiceEvent, 'schemaVersion' | 'observedAt'> & {
+  schemaVersion?: number;
+  observedAt?: string;
+}): WorldServiceEvent {
+  return WorldServiceEventSchema.parse({
+    schemaVersion: 1,
+    observedAt: nowIso(),
+    ...input,
+  });
+}
+
+// ── Scrub: delete pulled data at rest (TWIN-45 dev/02a) ─────────────────────
+// `sync pull` (sync.ts) folds real, customer-shaped resources into a service's
+// event log + rebuilt state.json (see worldPaths); `scrub` is the honest
+// counterpart — plain `rm` of exactly that on-disk data, nothing cleverer (no
+// crypto-shredding; see docs/DATA_AT_REST.md). Two grains, matching what's
+// actually there: one service's dir, or the whole world dir. Both refuse to
+// touch a directory whose contents don't look like our own event-log shape,
+// unless the caller passes `force: true` — the directories scrub ever removes
+// are ALWAYS ones derived from worldPaths()/worldStateRoot() (never a raw path
+// from the caller), so this check is defense in depth against a wrong `root`
+// resolving somewhere unexpected, not a general path-safety mechanism.
+
+export type ScrubResult = {
+  /** The directory scrub targeted (may not have existed). */
+  target: string;
+  /** Every file actually removed, path relative to `target`, in no particular order. */
+  removed: string[];
+  /** One-line human summary, safe to print as-is. */
+  message: string;
+};
+
+/** Filenames/dirnames ANY control-plane src module ever writes inside a single
+ *  service's state dir (see worldPaths) — plus the lockfiles withFileLock creates
+ *  next to a log and the `.tmp`/`.stale.*` sidecars its atomic-write/reclaim paths
+ *  use. storage.ts itself only accounts for events.jsonl/event-queue.jsonl/
+ *  state.json/resources/cursors/ingests; the rest are written by other modules
+ *  that share the same service dir (actions.ts, pushLedger.ts, plan.ts, lease.ts,
+ *  refs.ts, fork.ts, queueLifecycle.ts) — this set MUST stay in sync with every
+ *  one of them so scrubService never demands --force for an ordinary twin. */
+const KNOWN_SERVICE_ENTRIES = new Set([
+  'events.jsonl',
+  'events.jsonl.lock',
+  'event-queue.jsonl',
+  'event-queue.jsonl.lock',
+  'state.json',
+  'resources',
+  'cursors',
+  'ingests',
+  // actions.ts: the local transaction-commit log + its lock.
+  'actions.jsonl',
+  'actions.jsonl.lock',
+  // pushLedger.ts: the push-phase ledger for real-vendor replication.
+  'push-ledger.jsonl',
+  // queueLifecycle.ts: the append-only status ledger over event-queue.jsonl rows.
+  'event-queue-status.jsonl',
+  // fork.ts: fork metadata (base snapshot + divergence baseline) for a fork root.
+  'fork-meta.json',
+  // plan.ts: one JSON file per apply plan, under plans/<planId>.json.
+  'plans',
+  // lease.ts: one JSON file per apply lease, under leases/<leaseId>.json.
+  'leases',
+  // refs.ts: remote/local checkpoint refs, under refs/remote/<provider>/<name>.json
+  // and refs/local/<forkId>.json.
+  'refs',
+]);
+
+function isKnownServiceEntry(name: string): boolean {
+  return KNOWN_SERVICE_ENTRIES.has(name) || name.endsWith('.tmp') || /\.stale\.\d+\.\d+$/.test(name);
+}
+
+/** A service dir "looks like" one of ours when every entry in it is something
+ *  storage.ts is known to create. A directory that doesn't exist yet trivially
+ *  looks fine (scrub will just no-op on it). */
+function looksLikeServiceStateDir(dir: string): boolean {
+  if (!existsSync(dir)) return true;
+  return readdirSync(dir).every((entry) => isKnownServiceEntry(entry));
+}
+
+/** The whole world dir "looks like" ours when every entry in it is itself a
+ *  directory that looks like a service state dir (each service gets one subdir
+ *  under worldStateRoot — see worldPaths). */
+function looksLikeWorldStateDir(dir: string): boolean {
+  if (!existsSync(dir)) return true;
+  return readdirSync(dir).every((entry) => {
+    const full = join(dir, entry);
+    return statSync(full).isDirectory() && looksLikeServiceStateDir(full);
+  });
+}
+
+/** Every file under `dir`, path relative to `dir`, depth-first. Used to report
+ *  exactly what scrub is about to remove before it removes it. */
+function listFilesRecursive(dir: string, base: string = dir): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFilesRecursive(full, base));
+    else out.push(full.slice(base.length + 1));
+  }
+  return out;
+}
+
+function scrubDir(
+  dir: string,
+  label: string,
+  looksLike: (d: string) => boolean,
+  options: { force?: boolean },
+): ScrubResult {
+  if (!existsSync(dir)) {
+    return { target: dir, removed: [], message: `nothing to scrub: ${label} (${dir}) does not exist` };
+  }
+  if (!options.force && !looksLike(dir)) {
+    throw new Error(
+      `world scrub: refusing to remove "${dir}" — it does not look like a world state directory ` +
+        `(unexpected contents). Pass --force (or { force: true }) to scrub it anyway.`,
+    );
+  }
+  const removed = listFilesRecursive(dir);
+  rmSync(dir, { recursive: true, force: true });
+  return { target: dir, removed, message: `scrubbed ${label}: removed ${removed.length} file(s) under ${dir}` };
+}
+
+/** Delete one service's pulled data at rest: its event log, queued events,
+ *  rebuilt state.json, and any resources/cursors/ingests sidecars — everything
+ *  `worldPaths(service)` points at. Refuses (unless `force`) when the dir holds
+ *  anything storage.ts didn't put there. */
+export function scrubService(service: string, options: { root?: string; force?: boolean } = {}): ScrubResult {
+  const paths = worldPaths(service, options.root);
+  return scrubDir(paths.dir, `service "${service}"`, looksLikeServiceStateDir, options);
+}
+
+/** Delete the ENTIRE world state dir (`<root>/<stateDir>/world`) — every
+ *  service's pulled data at once. Refuses (unless `force`) when any entry in it
+ *  isn't itself a recognizable per-service state dir. */
+export function scrubWorld(options: { root?: string; force?: boolean } = {}): ScrubResult {
+  const dir = worldStateRoot(options.root);
+  return scrubDir(dir, 'entire world state dir', looksLikeWorldStateDir, options);
+}
+