@volter/world-core 2.0.0

package/src/shared-blob-index.ts

@@ -0,0 +1,108 @@
+// A disposable lookup cache, not a byte store. Only owning World files retain payloads.
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, ftruncateSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, rmSync, writeFileSync, type Stats } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+const MAX_BUCKET_BYTES = 128 * 1024;
+const MAX_ENTRIES = 32;
+const MAX_PATHS = 4;
+type Index = Record<string, string[]>;
+
+function privateFile(stat: Stats): boolean {
+  return stat.isFile() && stat.nlink === 1 && (!process.getuid || stat.uid === process.getuid()) && (stat.mode & 0o077) === 0;
+}
+
+function privateDirectory(root: string): boolean {
+  try {
+    const stat = lstatSync(root);
+    return stat.isDirectory() && (stat.mode & 0o077) === 0 && (!process.getuid || stat.uid === process.getuid());
+  } catch { return false; }
+}
+
+function readIndex(file: string): Index {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+    const stat = fstatSync(fd);
+    if (!privateFile(stat) || stat.size > MAX_BUCKET_BYTES) return {};
+    const parsed: unknown = JSON.parse(readFileSync(fd, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    const index: Index = {};
+    for (const [key, paths] of Object.entries(parsed).slice(-MAX_ENTRIES)) {
+      if (!/^\d+:[a-f0-9]{64}$/.test(key) || !Array.isArray(paths)) continue;
+      index[key] = paths.filter((path): path is string => typeof path === 'string' && path.length <= 4096 && isAbsolute(path)).slice(0, MAX_PATHS);
+    }
+    return index;
+  } catch { return {}; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function digestFile(file: string, size: number): string | null {
+  const fd = openSync(file, 'r');
+  try {
+    const hash = createHash('sha256');
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    let remaining = size;
+    while (remaining > 0) {
+      const length = readSync(fd, buffer, 0, Math.min(buffer.length, remaining), null);
+      if (!length) return null;
+      hash.update(buffer.subarray(0, length));
+      remaining -= length;
+    }
+    if (readSync(fd, buffer, 0, 1, null)) return null;
+    return hash.digest('hex');
+  } finally { closeSync(fd); }
+}
+
+export function sharedBlobIndex(root: string, destinationDevice: number, digest: string): {
+  reuse(temporary: string, size: number): boolean;
+  record(key: string): void;
+} {
+  // 256 buckets with bounded entries/bytes keep metadata bounded across roots and devices.
+  const file = join(root, `${digest.slice(0, 2)}.json`);
+  const entry = `${destinationDevice}:${digest}`;
+  return {
+    reuse(temporary, size) {
+      if (!privateDirectory(root)) return false;
+      for (const candidate of readIndex(file)[entry] ?? []) {
+        try {
+          const source = lstatSync(candidate);
+          if (!source.isFile() || source.dev !== destinationDevice || source.size !== size
+            || (process.getuid && source.uid !== process.getuid())) continue;
+          linkSync(candidate, temporary);
+          // Check the actual linked file, not a source path that could have been replaced.
+          const linked = lstatSync(temporary);
+          if (linked.isFile() && linked.dev === destinationDevice && linked.size === size
+            && (!process.getuid || linked.uid === process.getuid()) && digestFile(temporary, size) === digest) return true;
+        } catch { /* A cache miss, stale path, unsupported link, or corrupt candidate. */ }
+        rmSync(temporary, { force: true });
+      }
+      return false;
+    },
+    record(key) {
+      try {
+        const path = resolve(key);
+        if (path.length > 4096) return;
+        const index = readIndex(file);
+        const paths = [path, ...(index[entry] ?? []).filter((old) => old !== path)].slice(0, MAX_PATHS);
+        delete index[entry];
+        index[entry] = paths;
+        let text = JSON.stringify(index);
+        while (Object.keys(index).length > MAX_ENTRIES || Buffer.byteLength(text) > MAX_BUCKET_BYTES) {
+          delete index[Object.keys(index)[0]!];
+          text = JSON.stringify(index);
+        }
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        if (!privateDirectory(root)) return;
+        // A torn/concurrent index update is just a cache miss. Writing the bounded
+        // bucket directly avoids retaining metadata temp files after SIGKILL.
+        const fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0), 0o600);
+        try {
+          if (!privateFile(fstatSync(fd))) return;
+          ftruncateSync(fd, 0);
+          writeFileSync(fd, text);
+        } finally { closeSync(fd); }
+      } catch { /* Index storage is optional: the World already owns its complete bytes. */ }
+    },
+  };
+}

package/src/state-system.ts

@@ -0,0 +1,115 @@
+// THE STATE SYSTEM (docs/concepts/the-model.md): what a write does at the
+// head of a twin's log, and how the tree is kept current. Two implementations of one interface,
+// bound per twin per world:
+//   simulated — apply appends the entry and the tree is the projection; refresh is nothing. That
+//               is every twin with no root, and every line of the write path as it stands.
+//   real      — the twin has a ROOT: the vendor's real account. Apply performs the entry against
+//               the vendor with the sealed credential (the pack's perform adapter over the kernel
+//               executor) and lands the receipt on the parent log; refresh fills the parent log
+//               from the vendor (the pack's refresh adapter). Reads never egress.
+// The binding is a file in the twin's state dir (`root.json`), written by `volter twin <vendor>
+// root`, read here — no env var, no pack code. The adapters come from the pack's descriptor
+// (protocol 2 `stateSystem`) or its anchored exports, registered by whoever mounts the twin.
+// CHECKS run before any entry is performed: a check that fails lands the entry as `refused` with
+// its reason and the deploy stops there. Checks are the world's files; the runtime loads them.
+import { dirname, join } from 'node:path';
+import type { TwinAuthStrategy } from './executor.ts';
+import { pushablePendingActions, type TwinAction } from './actions.ts';
+import type { PerformAction } from './head.ts';
+import type { RemoteExecute } from './remote-execute.ts';
+import { readTree } from './log.ts';
+import type { TwinResource } from './serve.ts';
+import { worldPaths } from './storage.ts';
+import { getActiveWorldStore } from './world-store.ts';
+
+export type DeployPolicy = 'auto' | 'gated' | 'hold';
+
+/** A twin's root: the vendor's real account. Key-free; the credential is sealed elsewhere. */
+export type RootConfig = {
+  /** the vendor's API, or the one resource the account is (`https://api.github.com/repos/o/r`) */
+  url: string;
+  deploy: DeployPolicy;
+  /** the world's override of the pack's refresh posture: an interval, and the least time between on-demand refreshes */
+  refresh?: { every?: string; webhook?: boolean; atMost?: string };
+  /** the one resource the account is, under `url` — `repos/acme/web` for GitHub — when the vendor's
+   *  adapters need it named; the adapters see `url/scope` as their origin */
+  scope?: string;
+};
+
+export function rootPath(service: string, root?: string): string {
+  return join(dirname(worldPaths(service, root).events), 'root.json');
+}
+export function readRoot(service: string, root?: string): RootConfig | null {
+  const raw = getActiveWorldStore().read(rootPath(service, root));
+  return raw === null ? null : (JSON.parse(raw) as RootConfig);
+}
+export function writeRoot(service: string, config: RootConfig, root?: string): void {
+  const path = rootPath(service, root);
+  getActiveWorldStore().mkdir(dirname(path));
+  getActiveWorldStore().writeAtomic(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+export function clearRoot(service: string, root?: string): void {
+  const path = rootPath(service, root);
+  if (getActiveWorldStore().exists(path)) getActiveWorldStore().remove(path);
+}
+
+/** The pack's half of the real state system. `perform` applies one entry against the vendor;
+ *  `refresh` observes the vendor into the parent log (it folds through the kernel — a pack never
+ *  writes a root log by hand); `ingest` folds one signed webhook. All over the kernel executor. */
+export type StateSystemAdapters = {
+  perform?: PerformAction;
+  refresh?: (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string }) => Promise<unknown>;
+  ingest?: (request: Request, ctx: { root?: string; secret?: string }) => Response | Promise<Response>;
+};
+
+const adapters = new Map<string, StateSystemAdapters>();
+/** Register a twin's adapters (the mounting host does this from the pack's descriptor or its
+ *  anchored exports). Replaces any earlier registration for the service. */
+export function registerStateSystem(service: string, a: StateSystemAdapters): void { adapters.set(service, a); }
+export function stateSystemFor(service: string): StateSystemAdapters | undefined { return adapters.get(service); }
+export function clearStateSystems(): void { adapters.clear(); authStrategies.clear(); }
+
+/** HOW EACH VENDOR AUTHENTICATES, registered from the pack's descriptor by `registerPack` — the
+ *  same shape as the adapters above, and it lives here rather than in the pack registry so the
+ *  head can read it without importing one (there is no cycle to argue about). Absent means header
+ *  replacement, which is what the executor has always done. */
+const authStrategies = new Map<string, TwinAuthStrategy>();
+export function registerAuthStrategy(service: string, a: TwinAuthStrategy): void { authStrategies.set(service, a); }
+export function authStrategyFor(service: string): TwinAuthStrategy | undefined { return authStrategies.get(service); }
+
+/** A check: deterministic, sees the entry and the tree, answers pass or fail with a reason. */
+/** A check may answer at once or later: a hosted World runs its checks in an isolate of their own,
+ *  reached over RPC. */
+export type CheckResult = { ok: true } | { ok: false; reason: string };
+export type Check = { name: string; run: (entry: TwinAction, tree: TwinResource[]) => CheckResult | Promise<CheckResult> };
+export type CheckVerdict = { name: string; reason: string } | null;
+
+/** Run every check over one entry; the first failure is the verdict. */
+export async function runChecks(checks: Check[], entry: TwinAction, tree: TwinResource[]): Promise<CheckVerdict> {
+  for (const check of checks) {
+    const result = await check.run(entry, tree);
+    if (!result.ok) return { name: check.name, reason: result.reason };
+  }
+  return null;
+}
+
+/** The one check every world ships: no credential-shaped string leaves for a vendor. Looks at
+ *  every string field of the entry (and its projection), so a token in a message body, a title or
+ *  a description is caught wherever the vendor would have put it. */
+export const NO_SECRETS_CHECK: Check = {
+  name: 'no-secrets',
+  run(entry) {
+    const CREDENTIAL = /\b(?:sk|pk|rk)[_-](?:live|test|prod)[_-][A-Za-z0-9]{8,}|\bxox[abprs]-[A-Za-z0-9-]{10,}|\bgh[pousr]_[A-Za-z0-9]{20,}|\bAKIA[0-9A-Z]{16}\b|\bsk-[A-Za-z0-9]{20,}|\bsk-(?:proj|ant)-[A-Za-z0-9_-]{16,}|-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+    const hit = (value: unknown, path: string): string | null => {
+      if (typeof value === 'string') return CREDENTIAL.test(value) ? path : null;
+      if (Array.isArray(value)) { for (const [i, v] of value.entries()) { const h = hit(v, `${path}[${i}]`); if (h) return h; } return null; }
+      if (value && typeof value === 'object') { for (const [k, v] of Object.entries(value)) { const h = hit(v, path ? `${path}.${k}` : k); if (h) return h; } return null; }
+      return null;
+    };
+    const where = hit(entry.fields, '') ?? hit(entry.projection, 'projection') ?? hit(entry.input, 'input');
+    return where === null ? { ok: true } : { ok: false, reason: `a credential-shaped string in ${where}` };
+  },
+};
+
+// DEPLOY and the deployable set live in head.ts (`performEntries`, `deployableEntries`): the same
+// code performs a wire write at an `auto` head, a pushed changeset and `volter world deploy`.

package/src/storage.ts

@@ -0,0 +1,407 @@
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { assertNotBeingRemoved, withAncestryLock, withStateRemoval } from './ancestry.ts';
+import { appendParentEntry, toEntry } from './log.ts';
+import {
+  GenericWorldStateSchema,
+  WorldServiceEventSchema,
+} from './schemas.ts';
+import { getActiveWorldStore } from './world-store.ts';
+import { parentEntries, toEvent } from './log.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 {
+  const name = process.env.VOLTER_STATE_DIR || '.volter';
+  if (isAbsolute(name) || name.split(/[\\/]/).includes('..')) throw new Error('VOLTER_STATE_DIR must be a relative directory without .. segments');
+  return name;
+}
+
+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;
+}
+
+/**
+ * IDENTITY SEAM for the request journal (serve.ts). `worldPaths` is the single funnel every
+ * state read/write in every pack goes through, so it is also the one place a twin says, in its
+ * own words, WHO it is (`service`) and WHERE its state lives (`root`) — the two things an HTTP
+ * layer that only sees `Bun.serve({fetch})` cannot know. serve.ts installs an observer here so
+ * the journal it writes lands beside that twin's `actions.jsonl` instead of guessing a root.
+ * Nothing else may use this: it is a one-slot observability hook, never a control seam.
+ */
+let worldPathsObserver: ((service: string, root: string | undefined) => void) | undefined;
+
+export function observeWorldPaths(observer: (service: string, root: string | undefined) => void): void {
+  worldPathsObserver = observer;
+}
+
+export function worldPaths(service: string, root?: string): WorldPaths {
+  const safeService = assertServiceName(service);
+  worldPathsObserver?.(safeService, root);
+  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[] {
+  const rows: T[] = [];
+  for (const [index, line] of getActiveWorldStore().readLines(path).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 {
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null) throw new Error('no such file');
+    return JSON.parse(raw) 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 docs/contributing/architecture.md D1.
+ */
+export function appendDurable(path: string, data: string): void {
+  getActiveWorldStore().append(path, data);
+}
+
+/**
+ * Opt-in structured stderr logging for the audit trail (the July 2026 architecture review, row 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 {
+  const store = getActiveWorldStore();
+  store.mkdir(dirname(path));
+  store.append(path, `${JSON.stringify(value)}\n`);
+}
+
+/** Run `fn` holding an exclusive cross-process lock, via the active store. On the fs
+ *  store this is the reclaimable file lock the event log uses; on an in-memory,
+ *  single-instance store it is a synchronous pass-through. Used to make read-then-append
+ *  critical sections atomic. Public so world-runtime can guard concurrent `upWorld`
+ *  claims of one instance dir with the SAME lock semantics the event log uses (TWIN-36). */
+export function withFileLock<T>(lockPath: string, fn: () => T): T {
+  return withAncestryLock(() => { assertNotBeingRemoved(dirname(lockPath)); return getActiveWorldStore().withLock(lockPath, fn); });
+}
+
+function writeJsonAtomic(path: string, value: unknown): void {
+  getActiveWorldStore().writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/** The parent log as a protocol 1 pack reads it: every entry the branch inherited or landed, as
+ *  observed rows (log.ts `toEvent`). A branched world sees its base world's logs to the branch
+ *  position first. */
+export function listEvents(service: string, root?: string): WorldServiceEvent[] {
+  return parentEntries(service, root).map(toEvent);
+}
+
+function ensureEventDirs(paths: WorldPaths): void {
+  const store = getActiveWorldStore();
+  store.mkdir(paths.dir);
+  store.mkdir(paths.resources);
+  store.mkdir(paths.cursors);
+  store.mkdir(paths.ingests);
+}
+
+/** 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');
+}
+
+/**
+ * Serializes mutations that can change a service's projected state, regardless of whether the
+ * durable row lands in events.jsonl or actions.jsonl. The per-log locks still protect their own
+ * append/dedupe mechanics; this outer lock makes a projection-based decision linearizable against
+ * connector observations as well as local actions.
+ */
+export function projectionLockPath(paths: WorldPaths): string {
+  return join(paths.dir, 'projection.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 appendEvent(event: WorldServiceEvent, root?: string): AppendEventResult {
+  const parsed = WorldServiceEventSchema.parse(event);
+  const paths = worldPaths(parsed.service, root);
+  ensureEventDirs(paths);
+  const { appended } = appendParentEntry(toEntry(parsed as unknown as Record<string, unknown>), root);
+  return { event: parsed, appended };
+}
+
+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 (!getActiveWorldStore().exists(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/concepts/data-and-keys.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, and connector-owned coordination) — 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([
+  'ancestry.json', 'history-format.json', 'views', 'origin.jsonl', 'origin-head.json',
+  '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',
+  // Vendor connectors may keep private, non-secret workflow leases and monotone observation clocks
+  // here when an async provider span must be serialized across processes.
+  'connector-workflows',
+]);
+
+function isKnownServiceEntry(name: string): boolean {
+  // log.ts: the branch pointer and the checkpoint
+  if (name === 'branch.json' || name === 'checkpoints') return true;
+  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 {
+  const store = getActiveWorldStore();
+  if (!store.exists(dir)) return true;
+  return store.list(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 {
+  const store = getActiveWorldStore();
+  if (!store.exists(dir)) return true;
+  return store.list(dir).every((entry) => {
+    const full = join(dir, entry);
+    return (store.stat(full)?.isDirectory ?? false) && 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[] {
+  const store = getActiveWorldStore();
+  if (!store.exists(dir)) return [];
+  const out: string[] = [];
+  for (const name of store.list(dir)) {
+    const full = join(dir, name);
+    if (store.stat(full)?.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 {
+  const store = getActiveWorldStore();
+  if (!store.exists(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);
+  withStateRemoval(dir, () => store.remove(dir));
+  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);
+}