@volter/world-core 2.0.0

package/dist/src/world-store.d.ts

@@ -0,0 +1,168 @@
+/** Metadata a caller needs about a stored path. `isDirectory` distinguishes a JSON
+ *  sidecar from a per-service subdir (validate/scrub walk on it); `size`+`mtimeMs`
+ *  drive the append-dedupe index's cache-validity check in storage.ts. */
+export type WorldStat = {
+    size: number;
+    mtimeMs: number;
+    isDirectory: boolean;
+    isSymbolicLink?: boolean;
+};
+/**
+ * The synchronous persistence seam. Every path is an ABSOLUTE key the caller already
+ * computed (via `worldPaths`/`worldStateRoot`); the store treats it as an opaque key,
+ * so a single active store partitions cleanly by `root` (the root is embedded in the
+ * key) and no per-root wiring is needed.
+ */
+export interface WorldStore {
+    /** Whole-file read; `null` when the path does not exist. */
+    read(path: string): string | null;
+    /** File content split on `\n` (blank lines and the trailing empty included, so a
+     *  caller can report 1-based row numbers); `[]` when the path does not exist. */
+    readLines(path: string): string[];
+    /** Raw append of exactly `data` (the caller owns any trailing newline). On the fs
+     *  backend this is the VOLTER_DURABLE-aware durable append. Does NOT create parents —
+     *  call `mkdir` first, matching the historical `appendDurable` contract. */
+    append(path: string, data: string): void;
+    /** Non-atomic whole-file write, creating parent dirs. Matches the plain
+     *  `writeFileSync` sidecar writers (cursors, refs, leases, plans, fork-meta). `secret` makes the
+     *  file owner-only (0600 in a 0700 directory) where the backend has permissions. */
+    write(path: string, data: string, options?: {
+        secret?: boolean;
+    }): void;
+    /** Atomic whole-file write (write-temp-then-rename on fs), creating parent dirs.
+     *  Used where a reader must never observe a half-written document (state.json). `secret` makes
+     *  the file owner-only where the backend has permissions. */
+    writeAtomic(path: string, data: string, options?: {
+        secret?: boolean;
+    }): void;
+    /** Does the path exist? */
+    exists(path: string): boolean;
+    /** Recursively remove the path (force; a missing path is not an error). */
+    remove(path: string): void;
+    /** Ensure a directory (and parents) exists. A no-op on backends with implicit dirs. */
+    mkdir(dirPath: string): void;
+    /** Immediate child names of a directory; `[]` when it does not exist. */
+    list(dirPath: string): string[];
+    /** Metadata for a path, or `null` when it does not exist. */
+    stat(path: string): WorldStat | null;
+    /** The file from byte `start` to its end, decoded as UTF-8 (`start` must fall on a character boundary: a line's
+     *  start in a log); `null` when the path does not exist. Optional: a reader of an append-only log uses it to read
+     *  only what was appended, and reads the whole file on a store without it. */
+    readRange?(path: string, start: number): string | null;
+    /** Resolve filesystem aliases for durable ownership; absent on opaque-key stores. */
+    canonicalPath?(path: string): string;
+    /** Run `fn` holding an exclusive lock on `lockPath`, releasing it afterwards. The fs
+     *  backend uses the historical cross-process reclaimable file lock; an in-memory,
+     *  single-instance backend is a synchronous pass-through. */
+    withLock<T>(lockPath: string, fn: () => T, options?: {
+        retainLiveOwner?: boolean;
+    }): T;
+}
+/**
+ * The default store: a thin, faithful pass-through to `node:fs`. Every method preserves
+ * the exact behavior the kernel had before the seam existed — the durable append
+ * (VOLTER_DURABLE), the atomic write (temp + rename), and the reclaimable cross-process
+ * file lock — so the existing twins and the conformance suite are unaffected.
+ */
+export declare class FsWorldStore implements WorldStore {
+    read(path: string): string | null;
+    readLines(path: string): string[];
+    readRange(path: string, start: number): string | null;
+    append(path: string, data: string): void;
+    write(path: string, data: string, options?: {
+        secret?: boolean;
+    }): void;
+    writeAtomic(path: string, data: string, options?: {
+        secret?: boolean;
+    }): void;
+    exists(path: string): boolean;
+    remove(path: string): void;
+    mkdir(dirPath: string): void;
+    list(dirPath: string): string[];
+    canonicalPath(path: string): string;
+    stat(path: string): WorldStat | null;
+    /** Run `fn` holding an exclusive cross-process file lock. 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. (Moved verbatim from storage.ts `withFileLock`.) */
+    withLock<T>(lockPath: string, fn: () => T, options?: {
+        retainLiveOwner?: boolean;
+    }): T;
+}
+/**
+ * An in-memory store. Files are entries in a `Map<path, string>`; directories are
+ * synthesized from the key set (a path is a directory when it is a strict prefix of a
+ * file key). `withLock` is a synchronous pass-through — a single in-process instance has
+ * no concurrent writers to serialize, so the read-then-append critical sections the
+ * kernel guards are already atomic under the single-threaded event loop.
+ *
+ * This is the portability proof: point the active store here and the entire kernel — and
+ * the clerk twin on top of it — runs with the filesystem untouched.
+ */
+export declare class MemoryWorldStore implements WorldStore {
+    /** path → content, and path → version stamp driving `stat().mtimeMs`. */
+    private readonly files;
+    private readonly versions;
+    /** path → UTF-8 byte size, kept as content changes so `stat` never re-encodes a growing log. */
+    private readonly sizes;
+    /** The stamp of this store's most recent mutation (0 = never mutated). A serverless
+     *  entry snapshots this before running the sync kernel and flushes ONLY when it moved —
+     *  read-only requests (the common case) then skip the durable write entirely. */
+    private lastMutation;
+    mutationStamp(): number;
+    /** Paths whose content changed strictly after `stamp` — the DELTA-FLUSH primitive
+     *  (runtime contract R11b): a serverless entry records `mutationStamp()` at hydration,
+     *  runs the sync kernel, then persists ONLY these paths (plus removals, which the caller
+     *  detects by diffing its hydrated path set against `entries()` — a removed path has no
+     *  version to report). O(paths) scan, O(delta) write. */
+    changedSince(stamp: number): string[];
+    private bump;
+    read(path: string): string | null;
+    readLines(path: string): string[];
+    append(path: string, data: string): void;
+    write(path: string, data: string): void;
+    writeAtomic(path: string, data: string): void;
+    exists(path: string): boolean;
+    remove(path: string): void;
+    mkdir(_dirPath: string): void;
+    list(dirPath: string): string[];
+    stat(path: string): WorldStat | null;
+    withLock<T>(_lockPath: string, fn: () => T): T;
+    /** Test/inspection helper: a plain snapshot of every stored file. Not part of the
+     *  `WorldStore` contract — used by `flushFrom` and by tests asserting no fs was touched. */
+    entries(): Record<string, string>;
+}
+/** The store the kernel currently persists through: the request's scoped store, else the
+ *  module-global one (`FsWorldStore` by default). */
+export declare function getActiveWorldStore(): WorldStore;
+/** Swap the active store. A serverless/DO/test entry sets a `MemoryWorldStore` (or a
+ *  backend-backed store) here before running the sync kernel, and restores the previous
+ *  one afterwards. Returns the store that was active, so callers can restore it. */
+export declare function setActiveWorldStore(store: WorldStore): WorldStore;
+/** Run `fn` with `store` active, restoring the previous store afterwards (even on
+ *  throw). ASYNC-AWARE: when `fn` returns a promise, the restore happens after it
+ *  SETTLES — the first version restored at `fn`'s return, i.e. at an async callback's
+ *  FIRST await, un-scoping the rest of the request (both serverless pack lanes hit this
+ *  independently and hand-rolled the same try/finally, 2026-09-01).
+ *
+ *  CONCURRENCY: where the runtime has AsyncLocalStorage the scope is per async context, so
+ *  unserialized requests for different worlds interleave without bleeding stores. Only a runtime
+ *  without it (a browser bundle) falls back to the module-global swap, which is safe only when
+ *  store-scoped work is serialized. */
+export declare function withWorldStore<T>(store: WorldStore, fn: () => Promise<T>): Promise<T>;
+export declare function withWorldStore<T>(store: WorldStore, fn: () => T): T;
+/** A durable, async source of a world snapshot (path → content). */
+export interface HydrationSource {
+    load(): Promise<Record<string, string>>;
+}
+/** A durable, async sink for a world snapshot (path → content). */
+export interface HydrationSink {
+    save(snapshot: Record<string, string>): Promise<void>;
+}
+/** Fill `store` from an async durable `source` before the sync kernel runs. */
+export declare function hydrateInto(store: MemoryWorldStore, source: HydrationSource): Promise<void>;
+/** Persist `store`'s current contents back to an async durable `sink` after the sync
+ *  kernel has run. */
+export declare function flushFrom(store: MemoryWorldStore, sink: HydrationSink): Promise<void>;

package/dist/src/world-store.js

@@ -0,0 +1,475 @@
+// WORLD STORE — the transport seam for the control-plane's persistence.
+//
+// The kernel's on-disk surface is a CLOSED SET of synchronous primitives: JSONL
+// append-logs (read-all-rows / append-row), whole-file JSON sidecars
+// (read/write/exists/remove), directory listing, and atomic-write + cross-process
+// file-lock. `WorldStore` names exactly that set, and nothing more. Route the whole
+// kernel through it and the twin persists through ANY backend — the local
+// filesystem today (`FsWorldStore`, the default), an in-memory Map for tests and
+// serverless proofs (`MemoryWorldStore`), a Durable Object / KV / redis tomorrow —
+// without touching a line of twin business logic.
+//
+// The interface is SYNCHRONOUS on purpose. The kernel's internals (append-then-
+// project, read-then-append critical sections) are synchronous, and `clerk-twin.ts`'s
+// request handler is a pure sync function keyed by `root`. Making the store async
+// would ripple `await` through every one of those call sites and change the handler's
+// shape — precisely the blast radius this seam exists to avoid. An async backend is
+// handled at a SEPARATE persistence boundary: `hydrate()` the durable source into a
+// sync store, run the sync kernel, `flush()` back out. See `hydrateInto`/`flushFrom`.
+//
+// NOT part of this store, deliberately: `rateBudget.ts`'s ledger. That is a
+// client-side guard on REAL vendor calls, keyed by CREDENTIAL and living in the user's
+// home dir (NOT under the project state root) — it is not twin persistence and never
+// runs on the serve path. Its bespoke inode-identity lock and reservation semantics
+// cannot be expressed through this generic seam without weakening them, so it stays on
+// `node:fs`. See its module header.
+import { appendFileSync, chmodSync, closeSync, existsSync, fsyncSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { hostname } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+// ── FsWorldStore — the DEFAULT, byte-identical to the historical node:fs behavior ────
+let fsAtomicSequence = 0;
+/** 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;
+function readLockHolder(lockPath) {
+    try {
+        return JSON.parse(readFileSync(lockPath, 'utf8'));
+    }
+    catch {
+        return null; // missing, empty (mid-write), or malformed
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH → no such process (dead); EPERM → exists but not ours to signal (alive)
+        return error.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, retainLiveOwner = false) {
+    const holder = readLockHolder(lockPath);
+    if (holder && holder.hostname === hostname() && Number.isInteger(holder.pid) && !pidAlive(holder.pid)) {
+        return true;
+    }
+    if (retainLiveOwner)
+        return false;
+    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;
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * The default store: a thin, faithful pass-through to `node:fs`. Every method preserves
+ * the exact behavior the kernel had before the seam existed — the durable append
+ * (VOLTER_DURABLE), the atomic write (temp + rename), and the reclaimable cross-process
+ * file lock — so the existing twins and the conformance suite are unaffected.
+ */
+export class FsWorldStore {
+    read(path) {
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, 'utf8');
+    }
+    readLines(path) {
+        if (!existsSync(path))
+            return [];
+        return readFileSync(path, 'utf8').split('\n');
+    }
+    readRange(path, start) {
+        let fd;
+        try {
+            fd = openSync(path, 'r');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        try {
+            const size = fstatSync(fd).size;
+            if (start >= size)
+                return '';
+            const buffer = Buffer.allocUnsafe(size - start);
+            let read = 0;
+            while (read < buffer.length) {
+                const n = readSync(fd, buffer, read, buffer.length - read, start + read);
+                if (n === 0)
+                    break;
+                read += n;
+            }
+            return buffer.toString('utf8', 0, read);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    append(path, data) {
+        // Historical appendDurable: a completed append syscall survives a process crash;
+        // fsync additionally survives kernel-panic/power-loss when VOLTER_DURABLE=1.
+        const fd = openSync(path, 'a');
+        try {
+            appendFileSync(fd, data);
+            if (process.env.VOLTER_DURABLE === '1')
+                fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    write(path, data, options = {}) {
+        if (!options.secret) {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, data);
+            return;
+        }
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, data, { mode: 0o600 });
+        chmodSync(path, 0o600);
+    }
+    writeAtomic(path, data, options = {}) {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.${Date.now()}.${fsAtomicSequence++}.tmp`;
+        try {
+            writeFileSync(tmp, data, options.secret ? { mode: 0o600 } : undefined);
+            renameSync(tmp, path);
+            if (options.secret)
+                chmodSync(path, 0o600);
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+    }
+    exists(path) {
+        return existsSync(path);
+    }
+    remove(path) {
+        rmSync(path, { recursive: true, force: true });
+    }
+    mkdir(dirPath) {
+        mkdirSync(dirPath, { recursive: true });
+    }
+    list(dirPath) {
+        if (!existsSync(dirPath))
+            return [];
+        return readdirSync(dirPath);
+    }
+    canonicalPath(path) {
+        const absolute = resolve(path);
+        try {
+            return realpathSync(absolute);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT' || dirname(absolute) === absolute)
+                throw error;
+            return join(this.canonicalPath(dirname(absolute)), basename(absolute));
+        }
+    }
+    stat(path) {
+        if (!existsSync(path))
+            return null;
+        const s = statSync(path);
+        return { size: s.size, mtimeMs: s.mtimeMs, isDirectory: s.isDirectory(), ...(lstatSync(path).isSymbolicLink() ? { isSymbolicLink: true } : {}) };
+    }
+    /** Run `fn` holding an exclusive cross-process file lock. 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. (Moved verbatim from storage.ts `withFileLock`.) */
+    withLock(lockPath, fn, options = {}) {
+        mkdirSync(dirname(lockPath), { recursive: true });
+        const started = Date.now();
+        let fd = null;
+        while (fd === null) {
+            try {
+                fd = openSync(lockPath, 'wx');
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== 'EEXIST')
+                    throw error;
+                if (lockIsStale(lockPath, options.retainLiveOwner)) {
+                    // Serialize reclaimers, then re-read: a contender's earlier stale observation
+                    // must never rename another contender's newly acquired, live lock.
+                    const recoveryPath = `${lockPath}.recovery`;
+                    let recovery;
+                    try {
+                        recovery = openSync(recoveryPath, 'wx');
+                    }
+                    catch (error) {
+                        if (error.code !== 'EEXIST')
+                            throw error;
+                        if (Date.now() - started > 10_000)
+                            throw new Error(`Lock recovery is active or interrupted: ${recoveryPath}. Inspect its owner before removing the recovery record.`);
+                        sleepSync(25);
+                        continue;
+                    }
+                    try {
+                        writeFileSync(recovery, JSON.stringify({ pid: process.pid, hostname: hostname() }));
+                        if (lockIsStale(lockPath, options.retainLiveOwner)) {
+                            const holder = readLockHolder(lockPath);
+                            const salvage = `${lockPath}.stale.${process.pid}.${Date.now()}`;
+                            try {
+                                renameSync(lockPath, salvage);
+                                console.warn(`[world] reclaiming stale storage lock ${lockPath} (held by pid ${holder?.pid ?? '?'} on ${holder?.hostname ?? '?'})`);
+                                unlinkSync(salvage);
+                            }
+                            catch (error) {
+                                if (error.code !== 'ENOENT')
+                                    throw error;
+                            }
+                        }
+                    }
+                    finally {
+                        closeSync(recovery);
+                        unlinkSync(recoveryPath);
+                    }
+                    continue;
+                }
+                if (Date.now() - started > 10_000) {
+                    const holder = readLockHolder(lockPath);
+                    const since = holder && typeof holder.at === 'string' ? Date.parse(holder.at) : NaN;
+                    throw new Error(`Timed out waiting for world storage lock: ${lockPath}${holder ? ` (held by pid ${holder.pid} on ${holder.hostname}${Number.isFinite(since) ? ` for ${Date.now() - since}ms` : ''})` : ''}`);
+                }
+                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() })}\n`);
+        }
+        catch { /* ignore */ }
+        const acquired = Date.now();
+        try {
+            return fn();
+        }
+        finally {
+            // Every World on the machine waits on some of these locks; a long hold stalls them all.
+            const heldMs = Date.now() - acquired;
+            if (heldMs > 2_000)
+                console.warn(`[world] held storage lock ${lockPath} for ${heldMs}ms (pid ${process.pid})\n${new Error().stack?.split('\n').slice(2, 8).join('\n') ?? ''}`);
+            const held = fstatSync(fd);
+            closeSync(fd);
+            try {
+                const current = lstatSync(lockPath);
+                if (held.dev === current.dev && held.ino === current.ino)
+                    unlinkSync(lockPath);
+            }
+            catch { /* already reclaimed by a stale-lock sweep */ }
+        }
+    }
+}
+// ── MemoryWorldStore — a Map-backed store; the proof a non-fs transport works ─────────
+// A process-global, strictly-increasing stamp source shared by every MemoryWorldStore, so
+// no two writes (across instances or requests) ever collide on `stat().mtimeMs`. See `bump`.
+let memoryStoreClock = 0;
+const byteLength = (text) => new TextEncoder().encode(text).length;
+/**
+ * An in-memory store. Files are entries in a `Map<path, string>`; directories are
+ * synthesized from the key set (a path is a directory when it is a strict prefix of a
+ * file key). `withLock` is a synchronous pass-through — a single in-process instance has
+ * no concurrent writers to serialize, so the read-then-append critical sections the
+ * kernel guards are already atomic under the single-threaded event loop.
+ *
+ * This is the portability proof: point the active store here and the entire kernel — and
+ * the clerk twin on top of it — runs with the filesystem untouched.
+ */
+export class MemoryWorldStore {
+    /** path → content, and path → version stamp driving `stat().mtimeMs`. */
+    files = new Map();
+    versions = new Map();
+    /** path → UTF-8 byte size, kept as content changes so `stat` never re-encodes a growing log. */
+    sizes = new Map();
+    /** The stamp of this store's most recent mutation (0 = never mutated). A serverless
+     *  entry snapshots this before running the sync kernel and flushes ONLY when it moved —
+     *  read-only requests (the common case) then skip the durable write entirely. */
+    lastMutation = 0;
+    mutationStamp() {
+        return this.lastMutation;
+    }
+    /** Paths whose content changed strictly after `stamp` — the DELTA-FLUSH primitive
+     *  (runtime contract R11b): a serverless entry records `mutationStamp()` at hydration,
+     *  runs the sync kernel, then persists ONLY these paths (plus removals, which the caller
+     *  detects by diffing its hydrated path set against `entries()` — a removed path has no
+     *  version to report). O(paths) scan, O(delta) write. */
+    changedSince(stamp) {
+        const changed = [];
+        for (const [path, version] of this.versions) {
+            if (version > stamp && this.files.has(path))
+                changed.push(path);
+        }
+        return changed.sort();
+    }
+    bump(path) {
+        // Draw the stamp from a PROCESS-GLOBAL monotonic counter, not a per-instance one.
+        // storage.ts's append-dedupe cache is keyed by path and validated by (size, mtimeMs),
+        // and it persists across requests in a Worker isolate while a fresh MemoryWorldStore is
+        // created per request (the hydrate→sync-kernel→flush shape). A per-instance counter
+        // resets to 0 each request, so two instances could present the SAME (size, mtimeMs) for
+        // one path with DIFFERENT content — serving a stale index (dedupe bypass) or a false
+        // conflict. A global counter makes every write across every instance a distinct,
+        // strictly-increasing stamp, so a cross-instance collision is impossible.
+        this.lastMutation = memoryStoreClock += 1;
+        this.versions.set(path, this.lastMutation);
+    }
+    read(path) {
+        return this.files.has(path) ? this.files.get(path) : null;
+    }
+    readLines(path) {
+        const content = this.files.get(path);
+        return content === undefined ? [] : content.split('\n');
+    }
+    append(path, data) {
+        this.files.set(path, (this.files.get(path) ?? '') + data);
+        this.sizes.set(path, (this.sizes.get(path) ?? 0) + byteLength(data));
+        this.bump(path);
+    }
+    write(path, data) {
+        this.files.set(path, data);
+        this.sizes.set(path, byteLength(data));
+        this.bump(path);
+    }
+    writeAtomic(path, data) {
+        // Atomic by nature in a single process: the assignment is indivisible, so no reader
+        // ever observes a partial document.
+        this.files.set(path, data);
+        this.sizes.set(path, byteLength(data));
+        this.bump(path);
+    }
+    exists(path) {
+        if (this.files.has(path))
+            return true;
+        // A directory "exists" when some file lives under it.
+        const prefix = path.endsWith('/') ? path : `${path}/`;
+        for (const key of this.files.keys())
+            if (key.startsWith(prefix))
+                return true;
+        return false;
+    }
+    remove(path) {
+        let removedAny = false;
+        if (this.files.delete(path)) {
+            this.versions.delete(path);
+            this.sizes.delete(path);
+            removedAny = true;
+        }
+        const prefix = path.endsWith('/') ? path : `${path}/`;
+        for (const key of [...this.files.keys()]) {
+            if (key.startsWith(prefix)) {
+                this.files.delete(key);
+                this.versions.delete(key);
+                this.sizes.delete(key);
+                removedAny = true;
+            }
+        }
+        // A pure removal is a mutation too: without this, a request that only deletes state
+        // would read as clean and the delta-flush would never persist the removal (R11b).
+        if (removedAny)
+            this.lastMutation = memoryStoreClock += 1;
+    }
+    mkdir(_dirPath) {
+        // Directories are implicit in the key set; nothing to do.
+    }
+    list(dirPath) {
+        const prefix = dirPath.endsWith('/') ? dirPath : `${dirPath}/`;
+        const children = new Set();
+        for (const key of this.files.keys()) {
+            if (!key.startsWith(prefix))
+                continue;
+            const rest = key.slice(prefix.length);
+            const slash = rest.indexOf('/');
+            children.add(slash === -1 ? rest : rest.slice(0, slash));
+        }
+        return [...children];
+    }
+    stat(path) {
+        const content = this.files.get(path);
+        if (content !== undefined) {
+            return { size: this.sizes.get(path) ?? byteLength(content), mtimeMs: this.versions.get(path) ?? 0, isDirectory: false };
+        }
+        if (this.exists(path)) {
+            return { size: 0, mtimeMs: 0, isDirectory: true };
+        }
+        return null;
+    }
+    withLock(_lockPath, fn) {
+        return fn();
+    }
+    /** Test/inspection helper: a plain snapshot of every stored file. Not part of the
+     *  `WorldStore` contract — used by `flushFrom` and by tests asserting no fs was touched. */
+    entries() {
+        return Object.fromEntries(this.files);
+    }
+}
+// ── the active store (the injection point) ───────────────────────────────────────────
+let activeStore = new FsWorldStore();
+const scope = (() => {
+    try {
+        const hooks = globalThis.process?.getBuiltinModule?.('node:async_hooks');
+        return hooks?.AsyncLocalStorage ? new hooks.AsyncLocalStorage() : null;
+    }
+    catch {
+        return null;
+    }
+})();
+/** The store the kernel currently persists through: the request's scoped store, else the
+ *  module-global one (`FsWorldStore` by default). */
+export function getActiveWorldStore() {
+    return scope?.getStore() ?? activeStore;
+}
+/** Swap the active store. A serverless/DO/test entry sets a `MemoryWorldStore` (or a
+ *  backend-backed store) here before running the sync kernel, and restores the previous
+ *  one afterwards. Returns the store that was active, so callers can restore it. */
+export function setActiveWorldStore(store) {
+    const previous = activeStore;
+    activeStore = store;
+    return previous;
+}
+export function withWorldStore(store, fn) {
+    if (scope)
+        return scope.run(store, fn);
+    const previous = setActiveWorldStore(store);
+    let result;
+    try {
+        result = fn();
+    }
+    catch (error) {
+        setActiveWorldStore(previous);
+        throw error;
+    }
+    if (result instanceof Promise) {
+        return result.finally(() => setActiveWorldStore(previous));
+    }
+    setActiveWorldStore(previous);
+    return result;
+}
+/** Fill `store` from an async durable `source` before the sync kernel runs. */
+export async function hydrateInto(store, source) {
+    const snapshot = await source.load();
+    for (const [path, content] of Object.entries(snapshot))
+        store.write(path, content);
+}
+/** Persist `store`'s current contents back to an async durable `sink` after the sync
+ *  kernel has run. */
+export async function flushFrom(store, sink) {
+    await sink.save(store.entries());
+}

package/dist/src/worldConfig.d.ts

@@ -0,0 +1,9 @@
+export type WorldServiceConfig = {
+    provider?: string;
+    tool?: string;
+    pollLimit?: number;
+} & Record<string, unknown>;
+export type WorldConfig = {
+    services: Record<string, WorldServiceConfig>;
+} & Record<string, unknown>;
+export declare function loadWorldConfig(root?: string): WorldConfig;

package/dist/src/worldConfig.js

@@ -0,0 +1,17 @@
+// World service config — generic per-service settings for the twin runtime
+// (`.volter/world/config.json`). Kept deliberately small + open: the index
+// signature lets a service carry arbitrary extra config that downstream tools
+// define. (The tracker's annotation adapter defines + reads `annotationPolicy` and
+// `browseUrlTemplate` on top of this — those are verification concerns, not the
+// twin's, so they are NOT typed here.)
+import { join } from 'node:path';
+import { worldStateRoot } from "./storage.js";
+import { getActiveWorldStore } from "./world-store.js";
+export function loadWorldConfig(root) {
+    const path = join(worldStateRoot(root), 'config.json');
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null)
+        return { services: {} };
+    const parsed = JSON.parse(raw);
+    return { ...parsed, services: parsed.services ?? {} };
+}