@volter/world-runtime 2.0.0

package/dist/src/pack-facts.js

@@ -0,0 +1,98 @@
+// PACK FACTS OVERLAY — the world-runtime consumer of the generated pack-facts artifact
+// (packages/world-core/generated/pack-facts.json, compiled by scripts/pack-facts.ts
+// from each pack's `pack: TwinPack` descriptor).
+//
+// During the descriptor-first migration (adding-a-twin.md §3) (adding-a-twin.md §3 (the descriptor is the one home)), the
+// adoption tables here are the UNION of the legacy central maps and the pack declarations.
+// The overlay MUTATES the central tables at module init — every use-site keeps reading the
+// object it always read — and a fact declared in BOTH places throws: dual declaration is the
+// drift this migration exists to end, so it is loud everywhere, not just in a test.
+import factsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
+// world-runtime and core are sibling workspace packages; the artifact is committed,
+// so a missing file is a broken checkout (or an unbuilt generator change), never a soft state.
+// core's artifact, imported as a JSON module: the published runtime resolves it beside an installed
+// core, a bundle carries it, and no host needs a filesystem to read it
+export function packFacts() {
+    return factsDocument.packs;
+}
+const dual = (vendor, kind, key, holder) => new Error(`pack-facts: ${kind} "${key}" is declared BOTH on the ${vendor} pack descriptor AND in the central ${holder} table — ` +
+    `the migration rule is one home per fact. Delete the central entry (the descriptor wins).`);
+/** Overlay descriptor-declared npm SDK names onto the central SDK_TWINS map (project-inspect.ts). */
+/** The PyPI half of the SDK map, built the same way from each descriptor's `adoption.pypi`
+ *  (PEP 503 names). One name belongs to one pack; a second claim refuses at load. */
+export function overlayPypiTwins(pypiTwins) {
+    for (const [vendor, facts] of Object.entries(packFacts())) {
+        for (const raw of facts.adoption?.pypi ?? []) {
+            const name = normalizePypiName(raw);
+            if (Object.hasOwn(pypiTwins, name)) {
+                const holder = pypiTwins[name].vendor;
+                if (holder !== vendor)
+                    throw new Error(`pack-facts overlay: pypi package "${name}" is claimed by BOTH the "${holder}" and "${vendor}" packs' descriptors — one name, one pack`);
+                continue;
+            }
+            pypiTwins[name] = { vendor, twin: `@volter/twin-${vendor}` };
+        }
+    }
+}
+/** PEP 503: case-insensitive, runs of `-_.` collapse to one `-`. */
+export function normalizePypiName(name) {
+    return name.trim().toLowerCase().replace(/[-_.]+/g, '-');
+}
+export function overlaySdkTwins(sdkTwins) {
+    for (const [vendor, facts] of Object.entries(packFacts())) {
+        for (const sdk of facts.adoption?.sdks ?? []) {
+            // Object.hasOwn, not `in`: `in` walks the prototype chain, so a pathological name like
+            // 'constructor' would throw a bogus dual error. And when the holder is another PACK's
+            // overlay (two descriptors claiming one name), the right fix is different from a hand-
+            // table collision — say which it is (§9 round two L2, 2026-08-31).
+            if (Object.hasOwn(sdkTwins, sdk)) {
+                const holder = sdkTwins[sdk].vendor;
+                if (holder !== vendor) {
+                    throw new Error(`pack-facts overlay: npm sdk "${sdk}" is claimed by BOTH the "${holder}" and "${vendor}" packs' descriptors (or by ${holder} in the central SDK_TWINS table) — one home per fact: decide which pack owns the client and remove the other claim.`);
+                }
+                throw dual(vendor, 'sdk', sdk, 'SDK_TWINS');
+            }
+            sdkTwins[sdk] = { vendor, twin: `@volter/twin-${vendor}` };
+        }
+    }
+}
+/** Overlay descriptor-declared scopes/env stems/world ids onto covers.ts's central maps. */
+export function overlayCoversMaps(maps) {
+    for (const [vendor, facts] of Object.entries(packFacts())) {
+        for (const scope of facts.adoption?.scopes ?? []) {
+            if (scope in maps.scopeVendors)
+                throw dual(vendor, 'scope', scope, 'SDK_SCOPE_VENDORS');
+            maps.scopeVendors[scope] = vendor;
+        }
+        for (const stemRaw of facts.adoption?.envStems ?? []) {
+            const stem = stemRaw.toLowerCase();
+            if (stem in maps.envStemVendors)
+                throw dual(vendor, 'env stem', stem, 'ENV_STEM_VENDORS');
+            maps.envStemVendors[stem] = vendor;
+        }
+        const worldIds = facts.adoption?.worldIds ?? [];
+        if (worldIds.length > 0) {
+            if (vendor in maps.vendorWorldIds)
+                throw dual(vendor, 'world ids', vendor, 'VENDOR_WORLD_IDS');
+            maps.vendorWorldIds[vendor] = [vendor, ...worldIds];
+        }
+    }
+}
+/** Overlay descriptor-declared endpoint-env wiring for packs with no injectable host.
+ * Packs that also declare hosts are wired through the injector; init reads their optional
+ * endpoint templates directly from pack facts without misclassifying them as app-read-only. */
+export function overlayEndpointEnv(table) {
+    for (const [vendor, facts] of Object.entries(packFacts())) {
+        if (facts.endpointEnv === undefined)
+            continue;
+        if ((facts.hosts?.length ?? 0) > 0)
+            continue;
+        if (vendor in table)
+            throw dual(vendor, 'endpoint env', vendor, 'APP_READ_ENDPOINT_ENV');
+        table[vendor] = {
+            injectEnv: facts.endpointEnv.name,
+            ...(facts.endpointEnv.templates ? { injectEnvTemplates: facts.endpointEnv.templates } : {}),
+            note: facts.endpointEnv.note,
+        };
+    }
+}

package/dist/src/pglite-backing.d.ts

@@ -0,0 +1,21 @@
+export interface InfraService {
+    kind: string;
+    hostPort: number;
+}
+/** Parse the services out of world.infrastructure.yml. This is NOT a YAML
+ * parser: init's renderComposeFile emits a deterministic shape, and this
+ * reads exactly that shape back (service key at 2-space indent = the kind;
+ * the single loopback port mapping beneath it). Anything else is a malformed
+ * definition and fails loudly. */
+export declare function parseInfraDefinition(text: string): InfraService[];
+/** Endpoints of the declared infrastructure, published through external.discover. Only URLs
+ * whose protocol and loopback port match a declared service belong to this lifecycle. */
+export declare function infraConnections(services: InfraService[], env: Record<string, string | undefined>): Record<string, string>;
+/** The kinds this backing cannot serve, or [] when it can serve the world. */
+export declare function unsupportedKinds(services: InfraService[]): string[];
+export declare function pgliteUp(services: InfraService[], dataDir: string): Promise<void>;
+export declare function pgliteStatus(services: InfraService[], dataDir: string): Promise<{
+    ok: boolean;
+    ready: number;
+}>;
+export declare function pgliteDown(services: InfraService[], dataDir: string): Promise<void>;

package/dist/src/pglite-backing.js

@@ -0,0 +1,158 @@
+// The containerless backing for World-managed infrastructure: PGlite hosts
+// (see pglite-host.ts) instead of docker compose. Selected by
+// `volter-world-infra` when no container runtime is available (or by
+// explicit VOLTER_WORLD_INFRA_BACKING=pglite); the world config, definition
+// file, injected env, and declared-service contract are byte-identical either
+// way — backing is private, exactly as the boundary comment in
+// infra-cli.ts promises.
+//
+// Capability is stated, not stretched: this backing serves POSTGRES services
+// only. A definition declaring mysql/redis without a container runtime is
+// refused with the kinds named, never half-booted.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+/** Parse the services out of world.infrastructure.yml. This is NOT a YAML
+ * parser: init's renderComposeFile emits a deterministic shape, and this
+ * reads exactly that shape back (service key at 2-space indent = the kind;
+ * the single loopback port mapping beneath it). Anything else is a malformed
+ * definition and fails loudly. */
+export function parseInfraDefinition(text) {
+    const services = [];
+    let current = null;
+    let inServices = false;
+    for (const line of text.split(/\r?\n/)) {
+        if (/^services:\s*$/.test(line)) {
+            inServices = true;
+            continue;
+        }
+        if (!inServices)
+            continue;
+        const service = line.match(/^ {2}([a-z][a-z0-9_-]*):\s*$/);
+        if (service) {
+            current = service[1];
+            continue;
+        }
+        const port = line.match(/^ {6}- "127\.0\.0\.1:(\d+):\d+"\s*$/);
+        if (port && current) {
+            services.push({ kind: current, hostPort: Number(port[1]) });
+            current = null;
+        }
+    }
+    return services;
+}
+/** Endpoints of the declared infrastructure, published through external.discover. Only URLs
+ * whose protocol and loopback port match a declared service belong to this lifecycle. */
+export function infraConnections(services, env) {
+    const connections = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        try {
+            const url = new URL(value);
+            if (url.hostname !== '127.0.0.1')
+                continue;
+            const kind = url.protocol === 'postgresql:' ? 'postgres' : url.protocol.slice(0, -1);
+            if (services.some((service) => service.kind === kind && service.hostPort === Number(url.port)))
+                connections[name] = value;
+        }
+        catch { /* not an infrastructure endpoint */ }
+    }
+    return connections;
+}
+const HOST = join(import.meta.dir, 'pglite-host.mjs');
+const READY_TIMEOUT_MS = 60_000;
+function pidPath(dataDir, kind) {
+    return join(dataDir, `pglite-${kind}.pid`);
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function listening(port) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: '127.0.0.1', port, timeout: 1000 }, () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('error', () => resolve(false));
+        socket.on('timeout', () => { socket.destroy(); resolve(false); });
+    });
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The kinds this backing cannot serve, or [] when it can serve the world. */
+export function unsupportedKinds(services) {
+    return [...new Set(services.filter((s) => s.kind !== 'postgres').map((s) => s.kind))];
+}
+export async function pgliteUp(services, dataDir) {
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service.kind);
+        if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim())))
+            continue;
+        const serviceData = join(dataDir, `pglite-${service.kind}-data`);
+        mkdirSync(serviceData, { recursive: true });
+        const log = join(dataDir, `pglite-${service.kind}.log`);
+        mkdirSync(dirname(log), { recursive: true });
+        // a real fd, not a pipe: the host must outlive this process untethered
+        const logFd = openSync(log, 'a');
+        const child = spawn('node', [HOST, '--port', String(service.hostPort), '--data', serviceData], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+        });
+        child.unref();
+        closeSync(logFd);
+        writeFileSync(pidFile, `${child.pid}\n`);
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        while (!(await listening(service.hostPort))) {
+            if (!alive(child.pid)) {
+                throw new Error(`pglite ${service.kind} exited before serving — see ${log}`);
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`pglite ${service.kind} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+            }
+            await sleep(200);
+        }
+    }
+}
+export async function pgliteStatus(services, dataDir) {
+    let ready = 0;
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service.kind);
+        if (!existsSync(pidFile))
+            continue;
+        const pid = Number(readFileSync(pidFile, 'utf8').trim());
+        if (alive(pid) && await listening(service.hostPort))
+            ready += 1;
+    }
+    return { ok: ready === services.length && services.length > 0, ready };
+}
+export async function pgliteDown(services, dataDir) {
+    for (const service of services) {
+        const pidFile = pidPath(dataDir, service.kind);
+        if (!existsSync(pidFile))
+            continue;
+        const pid = Number(readFileSync(pidFile, 'utf8').trim());
+        if (alive(pid)) {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch { /* already gone */ }
+            const deadline = Date.now() + 5000;
+            while (alive(pid) && Date.now() < deadline)
+                await sleep(100);
+            if (alive(pid)) {
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch { /* raced */ }
+            }
+        }
+        rmSync(pidFile, { force: true });
+    }
+}

package/dist/src/pglite-host.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// One managed-infrastructure postgres service, served without a container:
+// PGlite (real Postgres compiled to WASM) behind a pg-gateway wire-protocol
+// front. Spawned by `volter-world-infra` when the pglite backing is
+// selected; never operated directly (the same contract as the compose file).
+//
+// Plain .mjs under node, deliberately: PGlite's WASM init does not complete
+// under bun, and under node its create() promise only progresses while
+// something holds the event loop — an interval carries the init, and the TCP
+// server starts listening only once the backend is ready, so a port that
+// answers is a port that serves.
+//
+// PGlite is a SINGLE-SESSION backend, so this host serializes connections
+// with a transaction-affinity lock: a connection acquires the global lock at
+// its first protocol message and keeps it for as long as the backend reports
+// an open transaction (ReadyForQuery status != 'I'). Without the hold, two
+// pooled clients interleave into one session and a ROLLBACK on one swallows
+// the other's writes. A connection that dies mid-transaction is rolled back
+// before the lock is released.
+//
+// Identity is aliased, not faked: trust auth accepts the world's declared
+// user/password/database, but the backend is PGlite's single `postgres`
+// database — apps that introspect current_database() will see that. Worlds
+// accept this; an app needing true multi-database Postgres needs the
+// container backing.
+import net from 'node:net';
+import { mkdirSync } from 'node:fs';
+import { PGlite } from '@electric-sql/pglite';
+import { fromNodeSocket } from 'pg-gateway/node';
+
+function arg(name) {
+  const index = process.argv.indexOf(name);
+  const value = index >= 0 ? process.argv[index + 1] : undefined;
+  if (!value) {
+    process.stderr.write(`pglite-host: ${name} is required\n`);
+    process.exit(2);
+  }
+  return value;
+}
+
+const port = Number(arg('--port'));
+const dataDir = arg('--data');
+if (!Number.isInteger(port) || port < 1 || port > 65535) {
+  process.stderr.write('pglite-host: --port must be 1-65535\n');
+  process.exit(2);
+}
+
+mkdirSync(dataDir, { recursive: true });
+// stdio may be a log fd whose reader is gone; never die on a status line
+process.stdout.on('error', () => {});
+process.stderr.on('error', () => {});
+// PGlite's create() only progresses while something holds the event loop;
+// listening starts AFTER readiness so "port answers" means "serves queries"
+const initKeepAlive = setInterval(() => {}, 500);
+const dbReady = PGlite.create({ dataDir });
+dbReady.catch((error) => {
+  process.stderr.write(`pglite-host: backend failed to start: ${error?.message ?? error}\n`);
+  process.exit(1);
+});
+
+// ---- transaction-affinity lock ---------------------------------------------
+let holder = null;
+const waiters = [];
+async function acquire(token) {
+  while (holder !== null && holder !== token) {
+    await new Promise((resolve) => waiters.push(resolve));
+  }
+  holder = token;
+}
+function release(token) {
+  if (holder !== token) return;
+  holder = null;
+  const next = waiters.shift();
+  if (next) next();
+}
+
+/** The transaction status of the LAST ReadyForQuery ('Z') message in a raw
+ * protocol response, or null when the response carries none (mid-pipeline:
+ * the sender keeps the lock). 'I' = idle, 'T' = in transaction, 'E' = failed
+ * transaction. */
+function lastReadyStatus(response) {
+  let status = null;
+  let offset = 0;
+  while (offset + 5 <= response.length) {
+    const type = response[offset];
+    const length = (response[offset + 1] << 24) | (response[offset + 2] << 16)
+      | (response[offset + 3] << 8) | response[offset + 4];
+    if (length < 4) break; // malformed; stop scanning rather than loop
+    if (type === 0x5a /* 'Z' */ && offset + 5 < response.length) {
+      status = String.fromCharCode(response[offset + 5]);
+    }
+    offset += 1 + length;
+  }
+  return status;
+}
+
+const server = net.createServer(async (socket) => {
+  const token = {};
+  let holding = false;
+  socket.on('close', () => {
+    if (!holding) return;
+    // the client vanished inside its transaction: roll it back, then let the
+    // next connection in — never leak a half-open transaction into a stranger
+    void dbReady
+      .then((db) => db.query('ROLLBACK'))
+      .catch(() => {})
+      .then(() => {
+        holding = false;
+        release(token);
+      });
+  });
+  socket.on('error', () => { /* close handler owns cleanup */ });
+  await fromNodeSocket(socket, {
+    serverVersion: '18.3 (PGlite)',
+    auth: { method: 'trust' },
+    async onMessage(data, { isAuthenticated }) {
+      if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
+      const db = await dbReady;
+      await acquire(token);
+      holding = true;
+      const response = await db.execProtocolRaw(data);
+      const status = lastReadyStatus(response);
+      if (status === 'I') {
+        holding = false;
+        release(token);
+      }
+      return response;
+    },
+  });
+});
+
+void dbReady.then(() => {
+  clearInterval(initKeepAlive);
+  server.listen(port, '127.0.0.1', () => {
+    process.stdout.write(`pglite-host serving postgres wire protocol on 127.0.0.1:${port}\n`);
+  });
+});
+
+for (const signal of ['SIGTERM', 'SIGINT']) {
+  process.on(signal, () => {
+    server.close(() => {
+      void dbReady.then((db) => db.close()).finally(() => process.exit(0));
+    });
+    // a hung close must not make `down` hang the world
+    setTimeout(() => process.exit(0), 3000).unref();
+  });
+}

package/dist/src/placeholder.d.ts

@@ -0,0 +1,20 @@
+import type { WorldInstance } from './schema.js';
+export type SeedWorldOptions = {
+    root?: string;
+    entry?: string;
+    cwd?: string;
+};
+export type SeedWorldOutcome = {
+    world: string;
+    entry: string;
+    exitCode: number;
+    observed: Record<string, number>;
+};
+/** The seed entry `init` emits beside the world config, unless the caller names one. */
+export declare function seedEntryFor(instance: WorldInstance, entry?: string): string;
+/** Pull from the placeholder: every twin's window open around the seed entry. */
+export declare function seedWorld(name: string, options?: SeedWorldOptions): Promise<SeedWorldOutcome>;
+/** Back to the defaults: down with purge, up from the same config and env file, seed. */
+export declare function resetWorld(name: string, options?: SeedWorldOptions): Promise<SeedWorldOutcome & {
+    instance: WorldInstance;
+}>;

package/dist/src/placeholder.js

@@ -0,0 +1,100 @@
+// `volter-world seed <world>` and `volter-world reset <world>` — the placeholder remote's verbs
+// (docs/concepts/the-model.md#a-branch-is-a-position-not-a-copy, "default data"). `seed` opens every twin's placeholder-pull window,
+// runs the world's seed entry under the world env (the pack defaults and your story, through each
+// vendor's own API), and closes the windows: the seed lands as the placeholder's observed state,
+// `diff` reads empty, nothing is pending. `reset` is a pull from the placeholder again — down
+// with purge, up, seed — so a world returns to its defaults at any time; local work you want to
+// keep is a fork, taken before.
+import { materializeRoots } from "./root.js";
+import { loadWorldConfig } from "./configs.js";
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { beginPlaceholderPull, endPlaceholderPull, listEvents, PLACEHOLDER_REMOTE, worldStateRoot } from '@volter/world-core';
+import { downWorld, runWithWorldEnv, saveWorldInstance, statusWorld, upWorld } from "./runtime.js";
+/** The seed entry `init` emits beside the world config, unless the caller names one. */
+export function seedEntryFor(instance, entry) {
+    const path = resolve(entry ?? join(dirname(instance.configPath), 'seed.ts'));
+    if (!existsSync(path))
+        throw new Error(`No seed entry at ${path} — \`volter-world init\` writes one beside the world config (seed.ts); pass --entry <file> to name another`);
+    return path;
+}
+/** Placeholder rows under one world service's root, summed across every state service the twin
+ *  records under (slack records under `chat`): every state dir with an events log, whether or not
+ *  an actions log exists yet (a placeholder-only twin has none). */
+function placeholderCount(controlRoot) {
+    const stateRoot = worldStateRoot(controlRoot);
+    if (!existsSync(stateRoot))
+        return 0;
+    let n = 0;
+    for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !existsSync(join(stateRoot, entry.name, 'events.jsonl')))
+            continue;
+        try {
+            n += listEvents(entry.name, controlRoot).filter((e) => e.data?.remote === PLACEHOLDER_REMOTE).length;
+        }
+        catch { /* unreadable ledger: not counted */ }
+    }
+    return n;
+}
+/** Pull from the placeholder: every twin's window open around the seed entry. */
+export async function seedWorld(name, options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    const instance = statusWorld(name, root);
+    const entry = seedEntryFor(instance, options.entry);
+    const services = Object.keys(instance.services).sort();
+    const at = new Date().toISOString();
+    for (const service of services)
+        beginPlaceholderPull(service, join(instance.dirs.data, service), at);
+    let exitCode = 1;
+    try {
+        // The runtime that is running runs the seed: Bun, or Node with its TypeScript type stripping
+        // (`--experimental-strip-types`, accepted from Node 22.6 and on by default since 23.6). Never
+        // `bun` by name: the published runtime supports Node alone, and the tab's engine has no Bun.
+        if (typeof Bun === 'undefined' && /\.[cm]?ts$/.test(entry)) {
+            const [major, minor] = process.versions.node.split('.').map(Number);
+            if (major < 22 || (major === 22 && minor < 6))
+                throw new Error(`${entry} is TypeScript: seeding it under Node needs Node 22.6 or newer (type stripping), or Bun; this is Node ${process.versions.node}`);
+        }
+        const runner = typeof Bun !== 'undefined' ? ['bun', entry] : [process.execPath, '--experimental-strip-types', '--no-warnings', entry];
+        exitCode = await runWithWorldEnv(name, runner, root, { cwd: options.cwd ?? dirname(entry) });
+    }
+    finally {
+        for (const service of services)
+            endPlaceholderPull(service, join(instance.dirs.data, service));
+    }
+    const observed = {};
+    for (const service of services)
+        observed[service] = placeholderCount(join(instance.dirs.data, service));
+    return { world: name, entry, exitCode, observed };
+}
+/** Back to the defaults: down with purge, up from the same config and env file, seed. */
+export async function resetWorld(name, options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    const before = statusWorld(name, root);
+    // A world whose twins ship no default data has no seed entry: back to the defaults is back to
+    // empty, and that is a reset too — not an error.
+    const entry = existsSync(resolve(options.entry ?? join(dirname(before.configPath), 'seed.ts'))) ? seedEntryFor(before, options.entry) : null;
+    const stopped = await downWorld(name, root, { purge: true });
+    if (!stopped.purged || stopped.externalErrors.length)
+        throw new Error(`World reset refused: teardown did not purge the old instance (${stopped.externalErrors.join('; ')})`);
+    // a world booted from a config PATH re-ups from that path; one booted by id, by id
+    const booted = await upWorld(existsSync(before.configPath) ? before.configPath : before.config, { name, root, mode: before.mode, envFile: before.envFile });
+    // the origin belongs to the branch, not to its running state (git: a reset keeps the remote);
+    // the cursors do not — the mirror is gone, so the next fetch starts from the beginning
+    const instance = before.origin === undefined ? booted : { ...booted, origin: { url: before.origin.url, namespace: before.origin.namespace, ...(before.origin.clonedAt ? { clonedAt: before.origin.clonedAt } : {}) } };
+    if (before.origin !== undefined)
+        saveWorldInstance(instance);
+    // the roots reach the twins' state after the default data, so the seed runs simulated (as a fresh `up` does)
+    const rooted = () => materializeRoots(loadWorldConfig(existsSync(before.configPath) ? before.configPath : before.config, root).config, booted.dirs.data, root);
+    if (entry === null) {
+        rooted();
+        return { world: name, entry: '', exitCode: 0, observed: {}, instance };
+    }
+    try {
+        const seeded = await seedWorld(name, { root, entry, ...(options.cwd ? { cwd: options.cwd } : {}) });
+        return { ...seeded, instance };
+    }
+    finally {
+        rooted();
+    }
+}

package/dist/src/prerequisites.d.ts

@@ -0,0 +1,21 @@
+export type PrerequisiteId = 'local-execution';
+export type PrerequisiteCheck = {
+    id: PrerequisiteId;
+    ok: boolean;
+    label: string;
+    message: string;
+    guidance: string[];
+    details?: Record<string, string>;
+};
+type RunResult = {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+type Runner = (cmd: string, args: string[]) => RunResult;
+/** Private implementation probe behind the public World capability name. Its implementation and
+ * diagnostics never become instructions for application agents. */
+export declare function checkLocalExecution(runner?: Runner): PrerequisiteCheck;
+export declare function checkPrerequisites(ids: PrerequisiteId[], runner?: Runner): PrerequisiteCheck[];
+export declare function formatPrerequisiteChecks(checks: PrerequisiteCheck[]): string;
+export {};

package/dist/src/prerequisites.js

@@ -0,0 +1,49 @@
+import { spawnSync } from 'node:child_process';
+const realRunner = (cmd, args) => {
+    const result = spawnSync(cmd, args, { encoding: 'utf8' });
+    return {
+        status: result.status,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+    };
+};
+/** Private implementation probe behind the public World capability name. Its implementation and
+ * diagnostics never become instructions for application agents. */
+export function checkLocalExecution(runner = realRunner) {
+    const info = runner('docker', ['info']);
+    if (info.status === 0) {
+        return {
+            id: 'local-execution',
+            ok: true,
+            label: 'Local execution',
+            message: 'Local execution capacity is available.',
+            guidance: [],
+        };
+    }
+    return {
+        id: 'local-execution',
+        ok: false,
+        label: 'Local execution',
+        message: 'Local execution capacity is unavailable.',
+        guidance: [
+            'Run the World through `volter-world up`, then use `volter-world doctor <world>` and its declared service log if startup still fails.',
+            'Do not start, inspect, or clean up a backing runtime separately; the declared World service owns it.',
+        ],
+    };
+}
+export function checkPrerequisites(ids, runner = realRunner) {
+    return ids.map((id) => {
+        if (id === 'local-execution')
+            return checkLocalExecution(runner);
+        throw new Error(`Unknown prerequisite: ${id}`);
+    });
+}
+export function formatPrerequisiteChecks(checks) {
+    return checks.flatMap((check) => {
+        const status = check.ok ? 'ok' : 'missing';
+        const lines = [`${status} ${check.label}: ${check.message}`];
+        if (!check.ok)
+            lines.push(...check.guidance.map((line) => `  ${line}`));
+        return lines;
+    }).join('\n');
+}

package/dist/src/process-groups.d.ts

@@ -0,0 +1,4 @@
+/** Inspect only groups already owned by the lifecycle. A dead leader does not prove that its
+ * descendants exited. Zombies hold no resources; unknown inspection remains live. This is
+ * retirement evidence, never an ownership token or a way to discover processes to kill. */
+export declare function survivingOwnedGroups(pids: number[]): number[];