@volter/world-runtime 3.0.163 → 3.0.165

package/dist/src/schema.d.ts

@@ -336,6 +336,7 @@ export type WorldDatabasePrepare = {
     command: string[];
     cwd: string;
     inputs: string[];
+    with?: 'world';
 };
 /**
  * SETTINGS FOR THE PERSON DEVELOPING THE APP AGAINST THIS WORLD (runtime.development). A World that sets any of

package/dist/src/schema.js

@@ -86,8 +86,8 @@ function assertExternalServiceConfig(service, path) {
             if (!mapping.as || typeof mapping.as !== 'string') {
                 throw new Error(`External service "${id}" discover entry must define string "as" in ${path}`);
             }
-            if (mapping.protocol !== undefined && !['postgres', 'mysql', 'mongodb', 'redis', 'http'].includes(mapping.protocol)) {
-                throw new Error(`External service "${id}" discover "${mapping.as}" protocol must be postgres, mysql, mongodb, redis or http in ${path}`);
+            if (mapping.protocol !== undefined && !['postgres', 'mysql', 'mongodb', 'redis', 'http', 'clickhouse'].includes(mapping.protocol)) {
+                throw new Error(`External service "${id}" discover "${mapping.as}" protocol must be postgres, mysql, mongodb, redis, http or clickhouse in ${path}`);
             }
             const hasJson = typeof mapping.jsonPath === 'string';
             const hasPattern = typeof mapping.pattern === 'string';
@@ -505,7 +505,9 @@ function normalizeV2(value, path) {
     if (databasePrepare !== undefined) {
         if (!record(databasePrepare))
             throw new Error(`runtime.database.prepare must be an object in ${path}`);
-        assertKeys(databasePrepare, ['command', 'cwd', 'inputs'], 'runtime.database.prepare', path);
+        assertKeys(databasePrepare, ['command', 'cwd', 'inputs', 'with'], 'runtime.database.prepare', path);
+        if (databasePrepare.with !== undefined && databasePrepare.with !== 'world')
+            throw new Error(`runtime.database.prepare.with must be "world" where it is given in ${path}`);
         const strings = (value) => Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string' && item !== '');
         if (!strings(databasePrepare.command))
             throw new Error(`runtime.database.prepare.command must be a non-empty argv in ${path}`);

package/dist/src/served-world.js

@@ -2075,7 +2075,7 @@ export class WorldDoors {
             const views = {};
             const vendors = Object.keys(this.up().services);
             withHistoryLocks(vendors.map((vendor) => worldPaths(this.stateOf(vendor), this.controlRoot(vendor)).dir), () => { for (const vendor of vendors)
-                views[vendor] = historyAtInstant(this.stateOf(vendor), instant, this.controlRoot(vendor)); });
+                views[vendor] = historyAtInstant(this.stateOf(vendor), instant, this.controlRoot(vendor)); }, { operation: 'capture' });
             return Response.json({ world: this.served, at: new Date(Date.parse(instant)).toISOString(), views });
         }
         // THE WORLD'S MARKS (`GET marks`, `POST marks { note? }`): where its changes count from. A World seeded through its
@@ -2099,7 +2099,7 @@ export class WorldDoors {
                 const passed = delta.actions.filter((a) => !received.has(a.action.id)).length;
                 const mark = markWorld(this.name, { root: this.worldRoot, ...(typeof body.note === 'string' && body.note.trim() ? { note: body.note } : {}) });
                 return { mark, passed };
-            });
+            }, { operation: 'capture' });
             return Response.json({ world: this.served, mark, passed }, { status: 201 });
         }
         if (kind === 'map' && !name && request.method === 'GET')
@@ -3188,7 +3188,7 @@ export async function landChangeset(name, worldRoot, instance, changeset, expect
             }
             landedByTwin.set(twin, ids);
         }
-    });
+    }, { operation: 'action append' });
     for (const [twin, landedIds] of landedByTwin) {
         const controlRoot = join(instance.dirs.data, twin);
         const state = stateOf(twin);

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

@@ -0,0 +1,47 @@
+import { type PackFacts } from './pack-facts.js';
+import { type HostLaunch, type InfraService } from './pglite-backing.js';
+/** A managed-infrastructure kind a twin may serve (the kinds pack facts admit in `managedService`). */
+export type ManagedKind = NonNullable<PackFacts['managedService']>['kind'];
+/** What only a kind's protocol can answer, and the kind's name as a person reads it in a message. */
+export interface ManagedProtocol {
+    name: string;
+    /** Ownership may use the kernel boot answer, bound to this child by a retained nonce. */
+    bootProof?: true;
+    /** Whether a server of this protocol answers on the port at all: one that does before this World's starts is another process's. */
+    answers(port: number): Promise<boolean>;
+    /** Whether the server answering on the port is the process `pid` (architecture D9). */
+    serves(port: number, pid: number, service?: InfraService, boot?: string): Promise<boolean>;
+}
+export interface TwinServedBacking extends ManagedProtocol {
+    /** The vendor id of the pack that declares the kind, and the word its messages use in lower case. */
+    id: string;
+    /** The pack's package. */
+    package: string;
+    /** The directory under the World's data that holds the service's state, and the stem of its pid file and log. */
+    directory: string;
+    facts: PackFacts;
+}
+/** The directory of a kind's state under the World's data. */
+export declare const managedDirectory: (kind: ManagedKind) => string;
+/** The twin that serves a kind: the one pack whose facts declare it (pack-facts refuses two for a kind), with the
+ *  kind's protocol. Undefined where no pack declares the kind; the kind then keeps its own backing.
+ *
+ *  Facts are read in two places. The kernel's own table holds the packs it was built with. A pack it was not built
+ *  with carries its own facts (`generated/pack-facts.json`, architecture, "The catalog: where twins come from"), and
+ *  the catalog overlays those for a World's SELECTED twins only; a pack that serves a managed service is selected by
+ *  nobody (it is no service of world.json), so its declaration is read here from the package itself, installed
+ *  above one of `from`. Only the declaration is read: nothing of that file is overlaid on the kernel's tables. */
+export declare function managedTwin(kind: ManagedKind, protocol: ManagedProtocol, from?: readonly string[], originalInputs?: boolean): TwinServedBacking | undefined;
+/** The twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export declare function twinBackingCli(kind: TwinServedBacking, from: string[]): string | undefined;
+/** Where the service's state lives: the World's tree for the service, under the World's data. */
+export declare const twinBackingRoot: (kind: TwinServedBacking, dataDir: string) => string;
+export declare function originalInputArguments(kind: TwinServedBacking, service: InfraService, config: string): string[];
+export declare function twinBackingUp(kind: TwinServedBacking, services: InfraService[], dataDir: string, cli: string, launch?: HostLaunch): Promise<void>;
+/** Whether these services stand now as their status would prove them, asked now: for each port, the pid recorded is
+ *  the child this process started, that child has not closed and is alive, and the port is served by it (`serves`,
+ *  asked again here, as status asks it). A service it did not start here, or any doubt (an error asking), is not held,
+ *  and the caller's own status runs instead. */
+export declare function twinBackingHeld(kind: TwinServedBacking, services: InfraService[], dataDir: string): Promise<boolean>;
+export declare function twinBackingStatus(kind: TwinServedBacking, services: InfraService[], dataDir: string): Promise<number>;
+export declare function twinBackingDown(kind: TwinServedBacking, services: InfraService[], dataDir: string): Promise<void>;

package/dist/src/twin-backing.js

@@ -0,0 +1,343 @@
+// A World's managed service SERVED BY A TWIN: the lifecycle every such service shares, whatever protocol the twin
+// speaks. The twin's own cli is started detached on the loopback port the definition declares, its state under the
+// World's data (so it branches, checkpoints and rolls back with the World's tree); the child is recorded by pid and
+// birth, proven to be the one answering on the port, and retired by TERM then KILL with its receipts kept until
+// retirement is confirmed.
+//
+// Which pack serves a kind is the pack's own declaration (`managedService` in its facts; architecture, "The
+// descriptor"), found here by managedTwin: no pack and no vendor is named in the runtime. Every such pack is started
+// the same way, by its bin: `serve --port <the definition's port> --root <the service's tree>`.
+//
+// What the runtime does hold per kind is its ManagedProtocol: the two questions only the kind's protocol can answer
+// (does anything of this protocol answer on the port; is the one answering this child, architecture D9).
+// redis-backing.ts holds Redis's.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { commandLifetime, COMMAND_CONFIRM_MS } from "./command-lifetime.js";
+import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, signalOwnedProcess } from "./process-receipt.js";
+import { spawn } from 'node:child_process';
+import { survivingOwnedGroups, worldEvent } from "./process-groups.js";
+import { errorMessage } from "./error-message.js";
+import { findInstalledPackage, packCli, packFactsFile, twinPackageName } from "./catalog.js";
+import { installedVendorPacks, vendorPackageDir } from '@volter/world-core/runtime';
+import { packFacts } from "./pack-facts.js";
+import { takePreparedStore } from "./pglite-backing.js";
+import { bindOriginalInputState, preflightOriginalInputState, readOriginalInputSnapshot, verifyOriginalInputState } from "./original-inputs.js";
+/** The directory of a kind's state under the World's data. */
+export const managedDirectory = (kind) => `${kind}-twin`;
+/** The twin that serves a kind: the one pack whose facts declare it (pack-facts refuses two for a kind), with the
+ *  kind's protocol. Undefined where no pack declares the kind; the kind then keeps its own backing.
+ *
+ *  Facts are read in two places. The kernel's own table holds the packs it was built with. A pack it was not built
+ *  with carries its own facts (`generated/pack-facts.json`, architecture, "The catalog: where twins come from"), and
+ *  the catalog overlays those for a World's SELECTED twins only; a pack that serves a managed service is selected by
+ *  nobody (it is no service of world.json), so its declaration is read here from the package itself, installed
+ *  above one of `from`. Only the declaration is read: nothing of that file is overlaid on the kernel's tables. */
+export function managedTwin(kind, protocol, from = [], originalInputs = false) {
+    const built = Object.entries(packFacts()).find(([, facts]) => facts.managedService?.kind === kind)?.[0];
+    const installed = built && !originalInputs ? undefined : installedDeclaring(kind, from);
+    if (originalInputs && !installed)
+        return undefined;
+    if (built && installed && built !== installed.vendor)
+        throw new Error(`Installed managed ${kind} pack conflicts with the built-in declaration`);
+    const vendor = originalInputs ? installed?.vendor : built ?? installed?.vendor;
+    return vendor === undefined ? undefined : { ...protocol, id: vendor, package: twinPackageName(vendor), directory: managedDirectory(kind), facts: installed?.facts ?? packFacts()[built] };
+}
+/** The installed pack whose own facts declare the kind, by vendor id; two that do are refused by name, as the
+ *  kernel's table refuses two. */
+function installedDeclaring(kind, from) {
+    const found = new Map();
+    for (const dir of from) {
+        for (const [vendor, pack] of installedVendorPacks(dir)) {
+            const file = packFactsFile(pack);
+            if (file === undefined)
+                continue;
+            let own;
+            try {
+                own = JSON.parse(readFileSync(file, 'utf8')).packs?.[vendor];
+            }
+            catch {
+                continue;
+            }
+            if (own?.managedService?.kind === kind)
+                found.set(vendor, own);
+        }
+    }
+    if (found.size > 1)
+        throw new Error(`two installed packs declare the ${kind} kind (managedService): ${[...found.keys()].sort().join(', ')}`);
+    const entry = [...found.entries()][0];
+    return entry ? { vendor: entry[0], facts: entry[1] } : undefined;
+}
+const hosts = new Map();
+const READY_TIMEOUT_MS = 60_000;
+/** The twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export function twinBackingCli(kind, from) {
+    for (const dir of from) {
+        const found = vendorPackageDir(dir, kind.id) ?? findInstalledPackage(dir, kind.package);
+        const cli = found === undefined ? undefined : packCli(found);
+        if (cli !== undefined && existsSync(cli))
+            return cli;
+    }
+    return undefined;
+}
+const pidPath = (kind, dataDir, service) => join(dataDir, `${kind.directory}-${service.hostPort}.pid`);
+/** Where the service's state lives: the World's tree for the service, under the World's data. */
+export const twinBackingRoot = (kind, dataDir) => join(dataDir, kind.directory);
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return false;
+        throw error;
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function portOccupied(port) {
+    return new Promise(resolve => {
+        const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+        const end = (occupied) => { socket.destroy(); resolve(occupied); };
+        socket.once('connect', () => end(true));
+        socket.once('error', () => end(false));
+        socket.once('timeout', () => end(false));
+        socket.once('close', () => end(false));
+    });
+}
+function sideArguments(kind, service) {
+    const args = [];
+    for (const [name, side] of Object.entries(service.sides ?? {})) {
+        const declared = kind.facts.sidePorts?.find(port => port.name === name);
+        if (!declared || !/^--[a-z][a-z-]*$/.test(declared.flag))
+            throw new Error(`${kind.name} installed pack does not declare side listener ${name}`);
+        args.push(declared.flag, String(side.hostPort));
+    }
+    return args;
+}
+export function originalInputArguments(kind, service, config) {
+    if (!service.originalInputs)
+        return [];
+    const input = kind.facts.managedService?.originalInputs;
+    if (!input || input.version !== 1 || input.manifestArg !== '--original-inputs' || input.rootArg !== '--original-root' || input.digestArg !== '--original-inputs-sha256'
+        || !Array.isArray(input.paths) || !input.paths.length)
+        throw new Error(`${kind.name} installed pack has no original-input consumer`);
+    const read = readOriginalInputSnapshot(dirname(config), service.originalInputs);
+    if (read.snapshot.manifest.family !== service.kind || input.paths.some(path => !read.snapshot.manifest.roots.includes(path)))
+        throw new Error(`${kind.name} original-input source differs from its consumer`);
+    return [input.manifestArg, join(read.root, read.reference.manifest), input.rootArg, read.root, input.digestArg, read.reference.sha256];
+}
+export async function twinBackingUp(kind, services, dataDir, cli, launch = {}) {
+    const config = (launch.env ?? process.env).VOLTER_WORLD_CONFIG;
+    if (services.some(service => service.originalInputs) && !config)
+        throw new Error('Original-input services require their World configuration path');
+    // Authenticate every source before changing any existing host or persistent store.
+    const originals = new Map(services.map(service => [service, service.originalInputs ? originalInputArguments(kind, service, config) : []]));
+    for (const service of services)
+        if (service.originalInputs)
+            preflightOriginalInputState(twinBackingRoot(kind, dataDir), service.originalInputs);
+    for (const service of services) {
+        const pidFile = pidPath(kind, dataDir, service);
+        if (hosts.has(pidFile) || existsSync(pidFile) || existsSync(spawnReceiptPath(pidFile))) {
+            await twinBackingDown(kind, [service], dataDir);
+        }
+        // a port that already answers is another process's (another World's twin, the vendor's own server): serving there would
+        // hand this World's app someone else's state, so it is refused, never taken as ready
+        if (await kind.answers(service.hostPort))
+            throw new Error(`port ${service.hostPort} already serves ${kind.name} for another process`);
+        const sides = sideArguments(kind, service);
+        for (const side of Object.values(service.sides ?? {}))
+            if (await portOccupied(side.hostPort))
+                throw new Error(`${kind.name} side port ${side.hostPort} already belongs to another listener`);
+        if (service.configuration && kind.facts.managedService?.configurationArg !== '--configuration')
+            throw new Error(`${kind.name} installed pack does not declare operator configuration`);
+        const root = twinBackingRoot(kind, dataDir);
+        // What a prepare step run with the World up wrote to this service (a queue's registered jobs in Redis) is the
+        // World's prepared state as its cluster is (architecture, "A step may need the World"): the staged root is
+        // placed here before the twin first serves an empty one, whichever pack's twin it is.
+        const env = launch.env ?? process.env;
+        const taken = takePreparedStore(env.VOLTER_WORLD_CONFIG, env, kind.directory, root);
+        if (taken.note)
+            launch.note?.(taken.note);
+        mkdirSync(root, { recursive: true });
+        if (service.originalInputs)
+            bindOriginalInputState(root, service.originalInputs);
+        const configurationFile = service.configuration ? join(root, `operator-${service.hostPort}.json`) : undefined;
+        if (configurationFile)
+            publishProcessReceipt(configurationFile, JSON.stringify(service.configuration) + '\n');
+        const boot = kind.bootProof ? randomUUID() : undefined;
+        const log = join(dataDir, `${kind.directory}-${service.hostPort}.log`);
+        mkdirSync(dirname(log), { recursive: true });
+        // a real fd, not a pipe: the server outlives this process untethered
+        const logFd = openSync(log, 'a');
+        // the runtime this runs on: Bun runs the pack's TypeScript as it is; Node (volter-world-infra's shebang) needs
+        // type transformation, not only stripping (the kernel declares constructor parameter properties)
+        const runtime = typeof globalThis.Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
+        let held;
+        try {
+            try {
+                const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root,
+                    ...(service.replicaSet ? ['--replica-set', service.replicaSet] : []), ...sides, ...(configurationFile ? ['--configuration', configurationFile] : []), ...originals.get(service)], {
+                    env: { ...(launch.env ?? process.env), ...(boot ? { VOLTER_WORLD_BOOT_ID: boot } : {}) }, detached: true, windowsHide: true, stdio: ['ignore', logFd, logFd],
+                });
+                // Retain BEFORE descriptor close, birth capture or either publication can fail.
+                held = { child, lifetime: commandLifetime(child, launch.signal, false, READY_TIMEOUT_MS), closed: false, ...(boot ? { boot } : {}) };
+                const observed = held;
+                child.once('close', () => { observed.closed = true; });
+                child.on('error', () => { }); // lifetime joins spawn failure and close
+                hosts.set(pidFile, held);
+            }
+            finally {
+                closeSync(logFd);
+            }
+            if (!held.child.pid)
+                throw new Error(`${kind.name} child did not start`);
+            const identity = await held.lifetime.identity;
+            if (!identity?.start)
+                throw new Error(`${kind.name} birth capture failed; retiring held child`);
+            publishProcessReceipt(spawnReceiptPath(pidFile), JSON.stringify({ ...identity, ...(boot ? { boot } : {}) }) + '\n');
+            publishProcessReceipt(pidFile, `${held.child.pid}\n`);
+            const deadline = Date.now() + READY_TIMEOUT_MS;
+            while (!alive(held.child.pid) || !(await kind.serves(service.hostPort, held.child.pid, service, boot))) {
+                if (!alive(held.child.pid))
+                    throw new Error(`${kind.id} exited before serving — see ${log}`);
+                launch.signal?.throwIfAborted();
+                if (Date.now() > deadline)
+                    throw new Error(`${kind.id} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+                await sleep(25);
+            }
+            launch.signal?.throwIfAborted();
+            held.child.unref();
+        }
+        catch (error) {
+            if (held) {
+                try {
+                    await twinBackingDown(kind, [service], dataDir);
+                }
+                catch (cleanup) {
+                    throw new AggregateError([error, cleanup], `${kind.name} startup and retirement failed; ownership retained`);
+                }
+            }
+            throw error;
+        }
+    }
+}
+/** Whether these services stand now as their status would prove them, asked now: for each port, the pid recorded is
+ *  the child this process started, that child has not closed and is alive, and the port is served by it (`serves`,
+ *  asked again here, as status asks it). A service it did not start here, or any doubt (an error asking), is not held,
+ *  and the caller's own status runs instead. */
+export async function twinBackingHeld(kind, services, dataDir) {
+    for (const service of services) {
+        try {
+            const pidFile = pidPath(kind, dataDir, service);
+            const held = hosts.get(pidFile);
+            if (!held?.child.pid || held.closed || !existsSync(pidFile))
+                return false;
+            const pid = Number(readFileSync(pidFile, 'utf8').trim());
+            if (pid !== held.child.pid || !alive(pid) || !(await kind.serves(service.hostPort, pid, service)))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+export async function twinBackingStatus(kind, services, dataDir) {
+    let ready = 0;
+    for (const service of services) {
+        if (service.originalInputs) {
+            try {
+                verifyOriginalInputState(twinBackingRoot(kind, dataDir), service.originalInputs);
+            }
+            catch (error) {
+                process.stderr.write(`${errorMessage(error)}\n`);
+                continue;
+            }
+        }
+        const pidFile = pidPath(kind, dataDir, service);
+        if (!existsSync(pidFile))
+            continue;
+        const recorded = readProcessReceipt(pidFile, text => {
+            const pid = Number(text.trim());
+            if (!Number.isInteger(pid) || pid <= 0)
+                throw new Error(`Invalid ${kind.name} ownership PID`);
+            return pid;
+        });
+        const identity = kind.bootProof ? readSpawnReceipt(pidFile) : undefined;
+        if (recorded.error || identity?.error) {
+            process.stderr.write(`${errorMessage(recorded.error ?? identity.error)}\n`);
+            continue;
+        }
+        const pid = recorded.value;
+        if (!pid)
+            continue;
+        const boot = identity?.value?.boot;
+        if (kind.bootProof && (identity?.value?.pid !== pid || typeof boot !== 'string' || !boot))
+            continue;
+        if (alive(pid) && await kind.serves(service.hostPort, pid, service, typeof boot === 'string' ? boot : undefined))
+            ready += 1;
+    }
+    return ready;
+}
+export async function twinBackingDown(kind, services, dataDir) {
+    for (const service of services) {
+        const pidFile = pidPath(kind, dataDir, service);
+        const recorded = readProcessReceipt(pidFile, text => {
+            const pid = Number(text.trim());
+            if (!Number.isInteger(pid) || pid <= 0)
+                throw new Error(`Invalid ${kind.name} ownership PID`);
+            return pid;
+        });
+        const identity = readSpawnReceipt(pidFile);
+        const held = hosts.get(pidFile);
+        if (recorded.error || identity.error)
+            process.stderr.write(`${errorMessage(new AggregateError([recorded.error, identity.error].filter(Boolean), `${kind.name} ownership uncertain; retrying established ownership`))}\n`);
+        if (held) {
+            const retired = () => held.closed && (!held.child.pid || !survivingOwnedGroups([held.child.pid]).length);
+            if (!retired()) {
+                held.child.ref();
+                held.lifetime.cancel('SIGTERM');
+                try {
+                    await held.lifetime.finish();
+                }
+                catch (error) {
+                    if (!retired())
+                        throw error;
+                }
+            }
+        }
+        else {
+            if (!recorded.present && !identity.present)
+                continue;
+            const pid = identity.value?.pid ?? recorded.value;
+            if (!pid)
+                throw new AggregateError([recorded.error, identity.error].filter(Boolean), `${kind.name} ownership uncertain; receipts retained`);
+            if (recorded.value && identity.value && recorded.value !== identity.value.pid)
+                throw new Error(`${kind.name} ownership receipts disagree; retirement refused; receipts retained`);
+            const live = () => survivingOwnedGroups([pid]).length > 0;
+            // A STORE IS AWAITED AT ITS STOP on the lifecycle's own budget, not a command's grace: between the signal and
+            // its exit it writes its state down, and a SIGKILL in the middle of that leaves a root nothing may take.
+            // Its stop, its exit and the time between are events in the World's log; a kill is said as a kill.
+            const stopAsked = Date.now();
+            for (const [signal, limit] of [['SIGTERM', READY_TIMEOUT_MS], ['SIGKILL', COMMAND_CONFIRM_MS]]) {
+                if (!live())
+                    break;
+                worldEvent({ event: signal === 'SIGTERM' ? 'world.service.stop' : 'world.service.killed', service: kind.name, by: 'down', signal, to: 'group', pid, ...(signal === 'SIGKILL' ? { afterMs: Date.now() - stopAsked, doing: 'its stop had not ended within the lifecycle budget' } : {}) });
+                await signalOwnedProcess(identity.value, signal, true, 'down');
+                const deadline = Date.now() + limit;
+                while (live() && Date.now() < deadline)
+                    await sleep(20);
+            }
+            if (!live())
+                worldEvent({ event: 'world.service.exited', service: kind.name, by: 'down', pid, shutdownMs: Date.now() - stopAsked });
+            if (live())
+                throw new Error(`${kind.name} retirement unconfirmed; receipts retained`);
+        }
+        rmSync(pidFile, { force: true });
+        rmSync(spawnReceiptPath(pidFile), { force: true });
+        hosts.delete(pidFile);
+    }
+}

package/dist/src/up-cli.js

@@ -3,8 +3,16 @@
 // the process starts (a browser tab's engine compiles every module it loads), those modules were most of the
 // CLI's time before the owner process began.
 import { optionValue, ownerOption } from "./cli-args.js";
-import { superviseWorldUp } from "./up-task.js";
 export async function upCommand(subject, rest, root) {
+    const split = rest.indexOf('--');
+    const command = split < 0 ? [] : rest.slice(split + 1);
+    if (split >= 0)
+        rest = rest.slice(0, split);
+    const attachAfterLine = rest.includes('--attach-after-line');
+    if (attachAfterLine && !rest.includes('--in-process'))
+        throw new Error('volter-world up: --attach-after-line requires --in-process');
+    if (attachAfterLine && command.length === 0)
+        throw new Error('volter-world up: --attach-after-line requires a command after --');
     if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file=')))
         throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
     if (!subject)
@@ -35,19 +43,64 @@ export async function upCommand(subject, rest, root) {
     // where there is none, it costs a whole Node start before the boot and its own end after it (Rallly run 35: 611 ms
     // from the owner's "returning" to its reply reaching this process). The caller's SIGINT or SIGTERM still cancels the
     // boot, which rolls back.
-    const instance = rest.includes('--in-process') ? await upInProcess(subject, options) : await superviseWorldUp(subject, options);
+    const instance = rest.includes('--in-process') ? await upInProcess(subject, options) : await (await import("./up-task.js")).superviseWorldUp(subject, options);
+    // An instrument: what this process does between the boot's return and its last line, each part timed. A second
+    // stood between "returning: the World is up" and the ready text with nothing naming it (LibreChat and Dub, in a
+    // browser tab); the parts are the app-url module's load, the World's status read, the record's locked write, and
+    // the ready text.
+    const returned = Date.now();
+    let tail = '';
     if (appUrl !== undefined) {
         const { setAppUrl } = await import("./app-url.js");
-        setAppUrl(instance.name, appUrl, { root });
+        const loaded = Date.now();
+        const timings = {};
+        setAppUrl(instance.name, appUrl, { root, timings });
         process.stderr.write(`volter-world up ${instance.name}: app url recorded: ${appUrl}\n`);
+        tail = `app-url module loaded in ${loaded - returned} ms, status read in ${timings.statusMs ?? '?'} ms, record written in ${timings.writeMs ?? '?'} ms, `;
     }
+    const printing = Date.now();
     if (rest.includes('--json'))
         process.stdout.write(JSON.stringify(instance, null, 2) + '\n');
     else
         printReady(instance, !keepState);
+    process.stderr.write(`volter-world up ${instance.name}: after the boot returned: ${tail}ready text in ${Date.now() - printing} ms, ${Date.now() - returned} ms in all\n`);
+    if (attachAfterLine) {
+        await waitForAttachLine();
+        const { attachWorld } = await import("./runtime.js");
+        process.exit(await attachWorld(instance.name, command, root, { cwd: process.cwd(), owner: ownerOption(rest), verbose: rest.includes('--verbose'), instance }));
+    }
+}
+/** Read only the admission line; the command inherits the same stdin afterward. */
+function waitForAttachLine() {
+    return new Promise((resolve, reject) => {
+        let line = '';
+        const cleanup = () => { process.stdin.off('readable', readable); process.stdin.off('end', ended); process.stdin.off('error', failed); };
+        const failed = (error) => { cleanup(); reject(error); };
+        const ended = () => failed(new Error('volter-world up: stdin ended before the attach line'));
+        const readable = () => {
+            let byte;
+            while ((byte = process.stdin.read(1)) !== null) {
+                if (byte[0] === 10) {
+                    cleanup();
+                    if (line.replace(/\r$/, '') !== 'attach')
+                        reject(new Error('volter-world up: expected stdin line "attach"'));
+                    else
+                        resolve();
+                    return;
+                }
+                line += byte.toString();
+            }
+        };
+        process.stdin.on('readable', readable);
+        process.stdin.once('end', ended);
+        process.stdin.once('error', failed);
+        readable();
+    });
 }
 async function upInProcess(configId, options) {
+    const loading = performance.now();
     const { upWorld } = await import("./runtime.js");
+    process.stderr.write(`volter-world up: runtime modules loaded in ${(performance.now() - loading).toFixed(1)} ms\n`);
     const abort = new AbortController();
     const cancel = (signal) => abort.abort(signal);
     process.on('SIGINT', cancel);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.163",
+  "version": "3.0.165",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -70,7 +70,7 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.155",
+    "@volter/world-core": "3.0.156",
     "@volter/world-console": "3.0.151"
   },
   "dependencies": {
@@ -80,7 +80,7 @@
     "@volter/browser-runtime": "0.1.104",
     "@volter/browser-sandboxes": "0.1.84",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.155",
+    "@volter/world-core": "3.0.156",
     "modern-screenshot": "4.7.0",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",

package/src/ancestry.ts

@@ -2,7 +2,7 @@
 // carry parent-side pins, including clones across checkouts, without a global World registry.
 import { existsSync, readdirSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
-import { assertStateRemovable, readBranchMeta, stateDirName, withAncestryLock, withStateRemoval, getActiveWorldStore, worldPaths, worldStateRoot } from '@volter/world-core/runtime';
+import { assertStateRemovable, readBranchMeta, stateDirName, withAncestryLock, withStateRemoval, getActiveWorldStore, worldPaths, worldStateRoot } from '@volter/world-core/runtime-state';
 
 function checkWorldAncestry(root: string, path: string): void {
   const base = join(root, stateDirName(), 'worlds');
@@ -28,7 +28,7 @@ function checkWorldAncestry(root: string, path: string): void {
 }
 
 export function assertWorldStateRemovable(root: string, path: string): void {
-  withAncestryLock(() => { checkWorldAncestry(root, path); assertStateRemovable(path); });
+  withAncestryLock(() => { checkWorldAncestry(root, path); assertStateRemovable(path); }, { operation: 'removal preflight' });
 }
 
 export function removeWorldState<T>(root: string, path: string, remove: () => T): T {

package/src/app-url.ts

@@ -21,7 +21,7 @@
 // instance it described.
 import { errorMessage } from './error-message.ts';
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { withFileLock } from '@volter/world-core/runtime';
+import { withFileLock } from '@volter/world-core/runtime-state';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import net from 'node:net';
@@ -113,11 +113,18 @@ function assertHttpUrl(url: string): URL {
 /** Record `url` as the app endpoint of the RUNNING/booted instance `name`. The instance must
  * exist (a record for a world that was never upped would describe nothing); the app itself is
  * deliberately NOT probed — the booter declaring "this is where I put the app" is the truth. */
-export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string; app?: string } = {}): AppUrlRecord {
+export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string; app?: string; /** An instrument: filled with how long the World's status and the record's write each took. */ timings?: { statusMs?: number; writeMs?: number } } = {}): AppUrlRecord {
   const root = options.root ?? process.cwd();
   const app = appName(options.app);
+  const began = Date.now();
   const status = statusWorld(name, root); // throws "World instance not found" — the loud path
+  const statusRead = Date.now();
+  if (options.timings) options.timings.statusMs = statusRead - began;
   assertHttpUrl(url);
+  try { return setAppUrlEntry(root, name, app, url, status, options); }
+  finally { if (options.timings) options.timings.writeMs = Date.now() - statusRead; }
+}
+function setAppUrlEntry(root: string, name: string, app: string, url: string, status: ReturnType<typeof statusWorld>, options: { via?: Exclude<AppUrlSource, 'service'>; detail?: string }): AppUrlRecord {
   return writeEntry(root, name, app, (file) => {
     // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
     const hosts = entryOf(file, app)?.hosts;