@volter/world-core 2.0.0

package/dist/src/state-system.d.ts

@@ -0,0 +1,70 @@
+import type { TwinAuthStrategy } from './executor.js';
+import { type TwinAction } from './actions.js';
+import type { PerformAction } from './head.js';
+import type { RemoteExecute } from './remote-execute.js';
+import type { TwinResource } from './serve.js';
+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 declare function rootPath(service: string, root?: string): string;
+export declare function readRoot(service: string, root?: string): RootConfig | null;
+export declare function writeRoot(service: string, config: RootConfig, root?: string): void;
+export declare function clearRoot(service: string, root?: string): void;
+/** 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>;
+};
+/** 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 declare function registerStateSystem(service: string, a: StateSystemAdapters): void;
+export declare function stateSystemFor(service: string): StateSystemAdapters | undefined;
+export declare function clearStateSystems(): void;
+export declare function registerAuthStrategy(service: string, a: TwinAuthStrategy): void;
+export declare function authStrategyFor(service: string): TwinAuthStrategy | undefined;
+/** 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 declare function runChecks(checks: Check[], entry: TwinAction, tree: TwinResource[]): Promise<CheckVerdict>;
+/** 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 declare const NO_SECRETS_CHECK: Check;

package/dist/src/state-system.js

@@ -0,0 +1,90 @@
+// 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 { worldPaths } from "./storage.js";
+import { getActiveWorldStore } from "./world-store.js";
+export function rootPath(service, root) {
+    return join(dirname(worldPaths(service, root).events), 'root.json');
+}
+export function readRoot(service, root) {
+    const raw = getActiveWorldStore().read(rootPath(service, root));
+    return raw === null ? null : JSON.parse(raw);
+}
+export function writeRoot(service, config, root) {
+    const path = rootPath(service, root);
+    getActiveWorldStore().mkdir(dirname(path));
+    getActiveWorldStore().writeAtomic(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+export function clearRoot(service, root) {
+    const path = rootPath(service, root);
+    if (getActiveWorldStore().exists(path))
+        getActiveWorldStore().remove(path);
+}
+const adapters = new Map();
+/** 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, a) { adapters.set(service, a); }
+export function stateSystemFor(service) { return adapters.get(service); }
+export function clearStateSystems() { 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();
+export function registerAuthStrategy(service, a) { authStrategies.set(service, a); }
+export function authStrategyFor(service) { return authStrategies.get(service); }
+/** Run every check over one entry; the first failure is the verdict. */
+export async function runChecks(checks, entry, tree) {
+    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 = {
+    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, path) => {
+            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/dist/src/storage.d.ts

@@ -0,0 +1,101 @@
+import type { AppendEventResult, GenericWorldState, WorldPaths, WorldReducer, WorldServiceEvent } from './types.js';
+/**
+ * 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 declare function stateDirName(): string;
+export declare function worldStateRoot(root?: string): string;
+export declare function observeWorldPaths(observer: (service: string, root: string | undefined) => void): void;
+export declare function worldPaths(service: string, root?: string): WorldPaths;
+/** 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 declare function readJsonFile<T>(path: string): T;
+/**
+ * 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 declare function appendDurable(path: string, data: string): void;
+/**
+ * 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 declare function twinLog(kind: string, details: Record<string, unknown>): void;
+/** 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 declare function withFileLock<T>(lockPath: string, fn: () => T): T;
+/** 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 declare function listEvents(service: string, root?: string): WorldServiceEvent[];
+/** 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 declare function eventsLockPath(paths: WorldPaths): string;
+/**
+ * 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 declare function projectionLockPath(paths: WorldPaths): string;
+/**
+ * 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 declare function appendEvent(event: WorldServiceEvent, root?: string): AppendEventResult;
+export declare function genericWorldReducer(state: GenericWorldState, event: WorldServiceEvent): GenericWorldState;
+export declare function emptyGenericState(service: string): GenericWorldState;
+export declare function rebuildState<State>(service: string, initialState: State, reducer: WorldReducer<State>, root?: string): State;
+export declare function rebuildGenericState(service: string, root?: string): GenericWorldState;
+export declare function loadState<T = unknown>(service: string, root?: string): T | null;
+export declare function createEvent(input: Omit<WorldServiceEvent, 'schemaVersion' | 'observedAt'> & {
+    schemaVersion?: number;
+    observedAt?: string;
+}): WorldServiceEvent;
+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;
+};
+/** 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 declare function scrubService(service: string, options?: {
+    root?: string;
+    force?: boolean;
+}): ScrubResult;
+/** 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 declare function scrubWorld(options?: {
+    root?: string;
+    force?: boolean;
+}): ScrubResult;

package/dist/src/storage.js

@@ -0,0 +1,337 @@
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { assertNotBeingRemoved, withAncestryLock, withStateRemoval } from "./ancestry.js";
+import { appendParentEntry, toEntry } from "./log.js";
+import { GenericWorldStateSchema, WorldServiceEventSchema, } from "./schemas.js";
+import { getActiveWorldStore } from "./world-store.js";
+import { parentEntries, toEvent } from "./log.js";
+function nowIso() {
+    return new Date().toISOString();
+}
+function projectRoot(root) {
+    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() {
+    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) {
+    return join(projectRoot(root), stateDirName(), 'world');
+}
+function assertServiceName(service) {
+    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;
+export function observeWorldPaths(observer) {
+    worldPathsObserver = observer;
+}
+export function worldPaths(service, root) {
+    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(path) {
+    const rows = [];
+    for (const [index, line] of getActiveWorldStore().readLines(path).entries()) {
+        if (!line.trim())
+            continue;
+        try {
+            rows.push(JSON.parse(line));
+        }
+        catch (error) {
+            throw new Error(`${path}:${index + 1}: invalid JSONL row: ${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(path) {
+    try {
+        const raw = getActiveWorldStore().read(path);
+        if (raw === null)
+            throw new Error('no such file');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${path}: invalid JSON: ${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, data) {
+    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, details) {
+    if (process.env.VOLTER_TWIN_LOG !== '1')
+        return;
+    console.error(`[twin:${kind}]`, JSON.stringify(details));
+}
+function appendJsonl(path, value) {
+    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(lockPath, fn) {
+    return withAncestryLock(() => { assertNotBeingRemoved(dirname(lockPath)); return getActiveWorldStore().withLock(lockPath, fn); });
+}
+function writeJsonAtomic(path, value) {
+    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, root) {
+    return parentEntries(service, root).map(toEvent);
+}
+function ensureEventDirs(paths) {
+    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) {
+    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) {
+    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, root) {
+    const parsed = WorldServiceEventSchema.parse(event);
+    const paths = worldPaths(parsed.service, root);
+    ensureEventDirs(paths);
+    const { appended } = appendParentEntry(toEntry(parsed), root);
+    return { event: parsed, appended };
+}
+export function genericWorldReducer(state, event) {
+    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) {
+    return {
+        version: 1,
+        service: assertServiceName(service),
+        rebuiltAt: nowIso(),
+        eventCount: 0,
+        subjects: {},
+    };
+}
+export function rebuildState(service, initialState, reducer, root) {
+    const paths = worldPaths(service, root);
+    const state = listEvents(service, root).reduce(reducer, initialState);
+    writeJsonAtomic(paths.state, state);
+    return state;
+}
+export function rebuildGenericState(service, root) {
+    return rebuildState(service, emptyGenericState(service), genericWorldReducer, root);
+}
+export function loadState(service, root) {
+    const paths = worldPaths(service, root);
+    if (!getActiveWorldStore().exists(paths.state))
+        return null;
+    return readJsonFile(paths.state);
+}
+export function createEvent(input) {
+    return WorldServiceEventSchema.parse({
+        schemaVersion: 1,
+        observedAt: nowIso(),
+        ...input,
+    });
+}
+/** 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) {
+    // 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) {
+    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) {
+    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, base = dir) {
+    const store = getActiveWorldStore();
+    if (!store.exists(dir))
+        return [];
+    const out = [];
+    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, label, looksLike, options) {
+    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, options = {}) {
+    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 = {}) {
+    const dir = worldStateRoot(options.root);
+    return scrubDir(dir, 'entire world state dir', looksLikeWorldStateDir, options);
+}

package/dist/src/twin-fetch.d.ts

@@ -0,0 +1,64 @@
+/** The header a host sets when it mounts a twin under a path (a served World's wire:
+ *  `/<org>/<world>/<vendor>`), the reverse-proxy convention; with it the host sets
+ *  `x-forwarded-host` and `x-forwarded-proto` to where the World is reached. */
+export declare const TWIN_PREFIX_HEADER = "x-forwarded-prefix";
+/** Where this twin is reached for this request: the request's origin plus the path a host mounted
+ *  the twin under. A pack mints every live URL it hands back (an upload target, a file link, a
+ *  callback) from this, never from the bare origin, so the URL works behind a served World. */
+export declare function twinPublicBase(request: Request): string;
+/** A twin's BYTE-STREAM door: a pack whose clients speak a TCP protocol (SMTP, the MySQL wire) serves
+ *  it over whatever carries the bytes — a local listener's socket, or a WebSocket to a hosted World.
+ *  The pack owns framing and protocol; the host owns the transport. `open` greets through the sink;
+ *  `data` hands the connection bytes in arrival order; `settled` resolves when every byte handed so
+ *  far has been answered; `close` is the peer going away. */
+export type TwinStreamSink = {
+    write(bytes: Uint8Array): void;
+    end(): void;
+};
+export type TwinStreamConnection = {
+    data(chunk: Uint8Array): void;
+    settled(): Promise<void>;
+    close(): void;
+};
+export type TwinStream = (sink: TwinStreamSink, peer: string) => TwinStreamConnection;
+export type TwinFetchHandlerResult = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/** The common handler request shape. Extra vendor fields ride `handlerOptions` (static,
+ *  per instance) and `extras` (derived per request); handlers ignore keys they don't
+ *  declare, so the union is safe to pass wholesale. */
+export type TwinFetchHandlerRequest = {
+    method: string;
+    path: string;
+    body: string;
+    headers: Record<string, string>;
+    readOnly: boolean;
+    occurredAt: string;
+    root?: string;
+} & Record<string, unknown>;
+export interface TwinFetchAdapterConfig {
+    root?: string;
+    readOnly?: boolean;
+    /** The keyless GET /twin body — a value (stateful packs: statefulTwinManifest(...)) or
+     *  a thunk (generative packs build theirs around the scenario engine). */
+    manifest: unknown | (() => unknown);
+    /** GET /twin/scenario body (thunk) — scenario-carrying packs only. */
+    scenarioStatus?: () => unknown;
+    /** THE STORE DOOR (R5c, mirror purity R3): named, deterministic projections over stored
+     *  state, served at `GET /twin/store/<name>` and listed in the manifest as `stores`. A
+     *  mirror reads twin state ONLY through this door — never by importing the handler or a
+     *  `-twin-internal` module — so the vendor API lacking a listing endpoint (resend has no
+     *  list-emails) no longer breeds a bespoke `/_twin/*` route per mirror. Keyed in the skin
+     *  like every state read (only bare `GET /twin` is keyless). */
+    stores?: Record<string, () => unknown | Promise<unknown>>;
+    /** Per-request vendor extras (header threading: stripe-version, notion-version, …). */
+    extras?: (request: Request, url: URL) => Record<string, unknown>;
+    /** Static per-instance handler options (e.g. rateLimitPerSecond). */
+    handlerOptions?: Record<string, unknown>;
+    /** Extra response headers on every non-door reply (e.g. stripe's request-id, and
+     *  postmark's `connection: close` Bun-socket workaround — inert under workerd). */
+    responseHeaders?: Record<string, string>;
+}
+export declare function createTwinFetchFromHandler(handler: (request: TwinFetchHandlerRequest) => TwinFetchHandlerResult | Promise<TwinFetchHandlerResult>, config: TwinFetchAdapterConfig): (request: Request) => Promise<Response>;