@volter/world-runtime 3.0.162 → 3.0.164

package/src/cli-commands.ts

@@ -1,26 +1,27 @@
+import type { statusWorld } from './runtime.ts';
 // Every volter-world command but `up` (./up-cli.ts), loaded by ./cli.ts only when one of them is asked for.
-import { sessionTrustEnv } from './ca-trust.ts';
+
 import { optionValue, ownerOption } from './cli-args.ts';
-import { printReady } from './up-cli.ts';
+
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve, resolve as resolvePath } from 'node:path';
-import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, writeWorldClock, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, recordCoverage, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
-import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core/runtime';
-import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from './serve.ts';
+
+
+
 import type { WorldManifest } from './attach.ts';
-import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from './runtime.ts';
-import { worldResourceReport } from './resources.ts';
-import { worldConsumers, worldUsage } from './consumers.ts';
-import { addAppHosts, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from './app-url.ts';
+
+
+
+
 import type { PrerequisiteId } from './index.ts';
-import { describeServiceEnd, describeWorldEvent, readServiceEnd, readWorldEvents } from './service-exit.ts';
-import { worldEventsPath } from './runtime.ts';
-import { resolveCatalog } from './catalog.ts';
-import { loadWorldConfig } from './configs.ts';
-import { vendorOfPackModule } from '@volter/world-core/runtime';
+
+
+
+
+
 
 
 
@@ -54,7 +55,7 @@ function acknowledgeOptions(args: string[], command: string): Record<string, str
 
 function printHelp(): void {
   process.stdout.write(`Usage:
-  volter-world init <name> --repo <path> [--out <dir>] [--force] [--allow-unknown] [--acknowledge vendor=reason]... [--json] [--root <repo>]
+  volter-world init <name> --repo <path> [--out <dir>] [--needs <needs.json>] [--force] [--allow-unknown] [--acknowledge vendor=reason]... [--json] [--root <repo>]
                                                   # the FRONT DOOR: detect the repo's vendors, EMIT a world config +
                                                   # env file OUTSIDE the repo (default <repo>/../<name>-pilot/, the
                                                   # repo is never written to), then run the coverage proof over the
@@ -62,6 +63,7 @@ function printHelp(): void {
                                                   # Deterministic: same repo + same pack catalog => identical bytes.
                                                   # init DIAGNOSES; it never boots — it prints the exact next commands
   volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--app-url <url>] [--in-process] [--json] [--root <repo>]
+  volter-world up <config> --env-out=<path> --in-process --attach-after-line [--name <name>] [--keep-state] [--app-url <url>] [--root <repo>] -- <command...>   # after its last boot line, waits for stdin "attach" before running the command
   volter-world outdated <world> [--json]            — each mounted twin: pinned / mounted / catalog-current version and protocol standing (R17)
   volter-world audit <world> [--json]               — each mounted twin's grade, as the catalog records it (R17)
   volter-world down <name> [--grace-ms <ms>] [--purge] [--if-instance <token>] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
@@ -184,6 +186,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'consumers') {
+    const { retireWorldConsumers } = await import('./runtime.ts');
     // `volter-world consumers retire <world> [--consumer <id>] [--root <repo>] [--json]`: the owner's
     // explicit resolution of attachments whose runner and command are provably gone.
     const args = rest.filter((arg): arg is string => arg !== undefined);
@@ -205,6 +208,9 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'resources' || cmd === 'prune') {
+    const { pruneWorlds, statusWorld } = await import('./runtime.ts');
+    const { worldResourceReport } = await import('./resources.ts');
+    const { worldConsumers, worldUsage } = await import('./consumers.ts');
     const args = [subject, ...rest].filter((arg): arg is string => arg !== undefined);
     const reportRoot = optionValue(args, '--root', process.cwd());
     // Destructive commands must reject typos, not silently broaden a target to all Worlds.
@@ -263,6 +269,7 @@ export async function main(): Promise<void> {
 
 
   if (cmd === 'down') {
+    const { downWorld } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world down: missing world name');
     const graceArg = optionValue(rest, '--grace-ms');
     if (graceArg && !(Number(graceArg) >= 0)) throw new Error(`volter-world down: invalid --grace-ms "${graceArg}" (want a non-negative number)`);
@@ -298,6 +305,8 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'events') {
+    const { statusWorld, worldEventsPath } = await import('./runtime.ts');
+    const { readWorldEvents, describeWorldEvent } = await import('./service-exit.ts');
     if (!subject) throw new Error('volter-world events: missing world name');
     const status = statusWorld(subject, root, { readOnly: true, light: true });
     const events = readWorldEvents(worldEventsPath(status.dirs.logs));
@@ -308,6 +317,9 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'status') {
+    const { statusWorld, worldEventsPath } = await import('./runtime.ts');
+    const { worldUsage } = await import('./consumers.ts');
+    const { readServiceEnd, describeServiceEnd, readWorldEvents, describeWorldEvent } = await import('./service-exit.ts');
     if (!subject) throw new Error('volter-world status: missing world name');
     const status = statusWorld(subject, root);
     const usage = worldUsage(root, subject);
@@ -364,6 +376,7 @@ export async function main(): Promise<void> {
   // `plan` and `review` retired 2026-09-05: the changeset verbs are the one review path (verify, approve, status, push).
 
   if (cmd === 'doctor') {
+    const { doctorWorld } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world doctor: missing world name');
     const report = await doctorWorld(subject, { root, verifyPublic: rest.includes('--verify-public') });
     if (rest.includes('--json')) {
@@ -377,6 +390,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'doctor-prereqs') {
+    const { checkPrerequisites, formatPrerequisiteChecks } = await import('./prerequisites.ts');
     const required = rest.flatMap((arg, index) => arg === '--require' ? [rest[index + 1]] : [])
       .filter(Boolean) as PrerequisiteId[];
     const checks = checkPrerequisites(required.length ? required : ['local-execution']);
@@ -392,6 +406,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'inspect-project') {
+    const { inspectProject, formatProjectInspection } = await import('./project-inspect.ts');
     const args = [...(subject ? [subject] : []), ...rest];
     const path = args.find((arg) => !arg.startsWith('--')) || process.cwd();
     const report = inspectProject(path);
@@ -400,6 +415,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'migrate-config') {
+    const { migrateWorldConfig } = await import('./configs.ts');
     if (!subject) throw new Error('volter-world migrate-config: missing config path or name');
     const migration = migrateWorldConfig(subject, root);
     if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(migration, null, 2)}\n`);
@@ -430,20 +446,26 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'init') {
+    const { initWorld, formatInitReport } = await import('./init.ts');
     if (!subject) throw new Error('volter-world init: missing world name (usage: volter-world init <name> --repo <path>)');
     const repo = optionValue(rest, '--repo');
     if (!repo) throw new Error('volter-world init: --repo <path> is required (the application repo to build the world for)');
     const out = optionValue(rest, '--out');
+    const needs = optionValue(rest, '--needs');
     const result = initWorld(subject, repo, {
       root,
       ...(out ? { out } : {}),
+      ...(needs ? { needs } : {}),
       force: rest.includes('--force'),
       allowUnknown: rest.includes('--allow-unknown'),
       acknowledge: acknowledgeOptions(rest, 'init'),
     });
     process.stdout.write(rest.includes('--json') ? `${JSON.stringify(result, null, 2)}\n` : formatInitReport(result));
     // Vendor coverage IS the exit code. App boot risks remain a separate, prominent report field.
-    if (!result.ok) process.exit(1);
+    // A World made from a stack's needs is the exception, and says so: it is made for the services the stack
+    // names, a vendor with no twin is its report and not its failure, and its maker goes by this exit alone.
+    if (!result.ok && needs) process.stdout.write('\nVENDOR COVERAGE: incomplete (the vendors above with no pack). With --needs that is reported and is not a failure: the World is written, exit 0.\n');
+    if (!result.ok && !needs) process.exit(1);
     return;
   }
 
@@ -451,9 +473,10 @@ export async function main(): Promise<void> {
   // twins this world mounted; `audit` is each one's grade as the catalog records it. Both read
   // instance.json and the committed artifacts — nothing is fetched.
   if (cmd === 'outdated' || cmd === 'audit') {
+    const { statusWorld } = await import('./runtime.ts');
     if (!subject) throw new Error(`volter-world ${cmd}: missing world name (usage: volter-world ${cmd} <world> [--json])`);
     const status = statusWorld(subject, root);
-    const rows = worldUpkeep(status, cmd, root);
+    const rows = await worldUpkeep(status, cmd, root);
     if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
     else {
       if (rows.length === 0) process.stdout.write(`World ${status.name}: no twin mounted with a resolved version — boot it once (up) so instance.json records what was mounted\n`);
@@ -463,6 +486,7 @@ export async function main(): Promise<void> {
     return;
   }
   if (cmd === 'covers') {
+    const { coverWorld, formatCoverageReport, recordCoverage } = await import('./covers.ts');
     if (!subject) throw new Error('volter-world covers: missing world name (usage: volter-world covers <world> --repo <path>)');
     const repo = optionValue(rest, '--repo');
     if (!repo) throw new Error('volter-world covers: --repo <path> is required (the application repo to prove coverage for)');
@@ -481,6 +505,8 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'clock') {
+    const { clockFile } = await import('./runtime.ts');
+    const { writeWorldClock } = await import('./clock.ts');
     // THE operator door for world time (physics): show / set <iso> / advance <duration> / shift <duration> / clear.
     // The clock every twin reads per request (kernel worldNow()), and every application process through the injector
     // (inject.cjs, WORLD TIME); a change takes effect live, no restarts. Its two forms (world-clock.cjs): `set` freezes
@@ -539,6 +565,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'urls') {
+    const { urlsWorld } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world urls: missing world name');
     const urls = urlsWorld(subject, root);
     if (rest.includes('--json')) {
@@ -553,6 +580,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'url') {
+    const { urlWorld } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world url: missing world name (usage: volter-world url <world> [service])');
     const [service] = positionalArgs(rest);
     const urls = urlWorld(subject, { root, ...(service === undefined ? {} : { service }) });
@@ -562,6 +590,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'app-url') {
+    const { setAppUrl, detectAppUrl, addAppHosts, readAppUrl, appUrlUnsetMessage } = await import('./app-url.ts');
     if (!subject) throw new Error('volter-world app-url: missing world name (usage: volter-world app-url <world> [--set <url>|--detect <pid|port>])');
     const set = optionValue(rest, '--set');
     const detect = optionValue(rest, '--detect');
@@ -592,6 +621,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'tail' || cmd === 'log') {
+    const { tailWorldActions } = await import('./tail.ts');
     if (!subject) throw new Error(`volter-world ${cmd}: missing world name (usage: volter-world log <world> [service...])`);
     const services = positionalArgs(rest);
     const controller = new AbortController();
@@ -610,6 +640,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'seed' || cmd === 'reset') {
+    const { seedWorld, resetWorld } = await import('./placeholder.ts');
     if (!subject) throw new Error(`volter-world ${cmd}: missing world name (usage: volter-world ${cmd} <world> [--entry <file>] [--cwd <dir>])`);
     if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file='))) throw new Error('--env-file is not an input for this command. Reset accepts --env-out=<new-output-path>.');
     const envFile = optionValue(rest, '--env-out') || undefined;
@@ -624,6 +655,8 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'branch') {
+    const { branchWorld } = await import('./branch.ts');
+    const { printReady } = await import('./up-cli.ts');
     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.');
     const [name] = positionalArgs(rest);
     if (!subject || !name) throw new Error('volter-world branch: usage: volter-world branch <world> <name> [--env-out=<path>]');
@@ -634,12 +667,15 @@ export async function main(): Promise<void> {
     return;
   }
   if (cmd === 'checkout') {
+    const { checkoutWorld } = await import('./branch.ts');
+    const { printReady } = await import('./up-cli.ts');
     if (!subject) throw new Error('volter-world checkout: missing world name');
     const instance = await checkoutWorld(subject, { root });
     if (rest.includes('--json')) process.stdout.write(`${JSON.stringify({ name: instance.name, instance: instance.instance, createdAt: instance.createdAt }, null, 2)}\n`); else printReady(instance);
     return;
   }
   if (cmd === 'fetch') {
+    const { fetchFromOrigin } = await import('./origin.ts');
     if (!subject) throw new Error('volter-world fetch: missing world name (usage: volter-world fetch <world> --key <key> [--origin <url> --namespace <org>/<world>] [--full])');
     const key = optionValue(rest, '--key') || process.env.VOLTER_TWINS_READ_KEY || process.env.VOLTER_TWINS_KEY || '';
     if (!key) throw new Error('volter-world fetch: --key <twins key> is required (the read key for a fetch, the admin key for --full)');
@@ -652,6 +688,7 @@ export async function main(): Promise<void> {
     return;
   }
   if (cmd === 'origin') {
+    const { worldOrigin } = await import('./origin.ts');
     if (!subject) throw new Error('volter-world origin: missing world name');
     const origin = worldOrigin(subject, root);
     if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(origin, null, 2)}\n`);
@@ -660,6 +697,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'mark') {
+    const { markWorld } = await import('./changeset.ts');
     if (!subject) throw new Error('volter-world mark: missing world name (usage: volter-world mark <world> [--id <marker>] [--note <text>])');
     const id = optionValue(rest, '--id');
     const note = optionValue(rest, '--note');
@@ -670,6 +708,8 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'diff') {
+    const { diffWorld } = await import('./changeset.ts');
+    const { formatLedgerDelta } = await import('@volter/world-core/runtime');
     if (!subject) throw new Error('volter-world diff: missing world name (usage: volter-world diff <world> [--base <marker>])');
     const base = optionValue(rest, '--base');
     const delta = diffWorld(subject, { root, ...(base ? { base } : {}) });
@@ -678,6 +718,8 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'changeset') {
+    const { parseVerifierExpression, formatChangeset, formatReplayReport, formatVerification, formatChangesetStatus, formatRebaseReport, formatApplication } = await import('@volter/world-core/runtime');
+    const { createWorldChangeset, findWorldChangeset, listWorldChangesets, replayWorldChangeset, verifyWorldChangeset, approveWorldChangeset, statusWorldChangeset, rebaseWorldChangeset, pushWorldChangeset } = await import('./changeset.ts');
     const CHANGESET_VALUE_FLAGS = ['--root', '--base', '--into', '--world', '--verifier', '--as', '--note'];
     const args = positionalArgs(rest, CHANGESET_VALUE_FLAGS);
     const world = optionValue(rest, '--world');
@@ -773,6 +815,8 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'list') {
+    const { listWorlds } = await import('./runtime.ts');
+    const { worldUsage } = await import('./consumers.ts');
     const listArgs = [subject, ...rest].filter((arg): arg is string => arg !== undefined);
     const listRoot = optionValue(listArgs, '--root', process.cwd());
     const worlds = listWorlds(listRoot).map(world => ({ ...world, usage: worldUsage(listRoot, world.name) }));
@@ -785,6 +829,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'env') {
+    const { attachWorld } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world env: missing world name');
     const split = rest.indexOf('--');
     if (split < 0) throw new Error('volter-world env: pass command after --');
@@ -793,6 +838,10 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'attach') {
+    // The local env attach, every app's CMD path, needs the World's ref and its runtime alone: the two load together,
+    // and the remote door (serve.ts) and the reflect front (reflect.ts, ca-trust.ts) load only on their own paths.
+    // All five were imported one after another first (S2 R16: Dub's attach, 225 bodies in 341 ms before its `next`).
+    const [{ resolveWorldRef, isRemoteWorldRef, worldManifest }, { withoutVaultSignIn, instanceDir, attachWorld }] = await Promise.all([import('./attach.ts'), import('./runtime.ts')]);
     // `subject` may be the ref, a flag, or the `--` separator — reassemble and split.
     const args = [subject, ...rest].filter((arg): arg is string => arg !== undefined);
     const split = args.indexOf('--');
@@ -807,6 +856,7 @@ export async function main(): Promise<void> {
       throw new Error('--owner is supported for local attach --via env commands');
     }
     if (isRemoteWorldRef(resolved.ref)) {
+      const { fetchRemoteManifest, remoteAttachEnv } = await import('./serve.ts');
       // remote world: fetch the manifest, synthesize the attach env, exec
       const attachToken = optionValue(head, '--token') || process.env.VOLTER_WORLD_TOKEN || undefined;
       const manifest = await fetchRemoteManifest(resolved.ref, attachToken === undefined ? {} : { token: attachToken });
@@ -849,6 +899,7 @@ export async function main(): Promise<void> {
       // gets the override — and everything else runs with the trust env and VOLTER_WORLD set, its DNS
       // being the caller's to point (a container's --dns, a resolver on the host).
       if (command.length === 0) throw new Error('volter-world attach: pass the command after --');
+      const [{ readReflectManifest, splitDockerComposeArgs, composeOverrideForReflect, dockerComposeWithOverride, ATTACHED_CA_PATH }, { sessionTrustEnv }] = await Promise.all([import('./reflect.ts'), import('./ca-trust.ts')]);
       const manifest = readReflectManifest(attachRoot, resolved.ref);
       if (!manifest) throw new Error(`volter-world attach --via reflect: no reflect front is running for world ${resolved.ref} — start one: volter-world reflect ${resolved.ref} --target-ip <ip> --port 443 --resolver-port 53`);
       const env: Record<string, string> = { ...withoutVaultSignIn(process.env) as Record<string, string>, VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
@@ -879,12 +930,15 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'manifest') {
+    const { worldManifest } = await import('./attach.ts');
     if (!subject) throw new Error('volter-world manifest: missing world name');
     process.stdout.write(`${JSON.stringify(worldManifest(subject, root), null, 2)}\n`);
     return;
   }
 
   if (cmd === 'reflect') {
+    const { reflectRoutesPath, startReflectFront, startReflectResolver, readReflectRoutes, writeReflectManifest, clearReflectManifest } = await import('./reflect.ts');
+    const { statusWorld, instanceDir } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world reflect: missing world name');
     const targetIp = optionValue(rest, '--target-ip');
     if (!targetIp) throw new Error('volter-world reflect: --target-ip <ip> is required (the address attachers reach the front at)');
@@ -918,6 +972,9 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'serve') {
+    const { startReflectFront } = await import('./reflect.ts');
+    const { statusWorld, instanceDir } = await import('./runtime.ts');
+    const { startManifestServer, advertiseWorldManifest, MANIFEST_PATH } = await import('./serve.ts');
     if (!subject) throw new Error('volter-world serve: missing world name');
     const advertise = optionValue(rest, '--advertise');
     if (!advertise) throw new Error('volter-world serve: --advertise <https-origin> is required (how attachers reach the door, e.g. https://worlds.corp:8443)');
@@ -956,6 +1013,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'route') {
+    const { reflectRoutesPath, readReflectRoutes, writeReflectRoutes } = await import('./reflect.ts');
     if (!subject) throw new Error('volter-world route: missing world name');
     const [verb, host] = rest.filter((arg) => !arg.startsWith('--'));
     const routesPath = reflectRoutesPath(root, subject);
@@ -974,17 +1032,21 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'activate') {
+    const { activateScript } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world activate: missing world name');
     process.stdout.write(activateScript(subject, root));
     return;
   }
 
   if (cmd === 'shell') {
+    const { shellWorld } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world shell: missing world name');
     process.exit(await shellWorld(subject, root));
   }
 
   if (cmd === 'run') {
+    const { runWorld } = await import('./runtime.ts');
+    const { readServiceEnd, describeServiceEnd } = await import('./service-exit.ts');
     if (!subject) throw new Error('volter-world run: missing config');
     const split = rest.indexOf('--');
     if (split < 0) throw new Error('volter-world run: pass command after --');
@@ -1013,6 +1075,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'share') {
+    const { shareWorldServices } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world share: missing world name');
     const service = optionValue(rest, '--service') || undefined;
     const verifyPath = rest.includes('--no-verify')
@@ -1044,6 +1107,7 @@ export async function main(): Promise<void> {
   }
 
   if (cmd === 'unshare') {
+    const { unshareWorld } = await import('./runtime.ts');
     if (!subject) throw new Error('volter-world unshare: missing world name');
     const service = optionValue(rest, '--service') || undefined;
     const result = await unshareWorld(subject, { root, service });
@@ -1059,7 +1123,10 @@ export async function main(): Promise<void> {
 /** The rows `outdated` / `audit` print. `outdated`: pinned vs mounted vs catalog-current version and the
  *  protocol standing; `audit`: each mounted twin's grade, from the catalog's record. `attention` marks a row the
  *  operator should act on (exit 1). */
-function worldUpkeep(status: ReturnType<typeof statusWorld>, kind: 'outdated' | 'audit', root: string): Array<{ id: string; line: string; attention: boolean }> {
+async function worldUpkeep(status: ReturnType<typeof statusWorld>, kind: 'outdated' | 'audit', root: string): Promise<Array<{ id: string; line: string; attention: boolean }>> {
+  const { resolveCatalog } = await import('./catalog.ts');
+  const { loadWorldConfig } = await import('./configs.ts');
+  const { vendorOfPackModule } = await import('@volter/world-core/runtime');
   const catalog = resolveCatalog(root);
   const config = loadWorldConfig(status.name, root).config;
   const out: Array<{ id: string; line: string; attention: boolean }> = [];

package/src/cli-load-clock.ts

@@ -0,0 +1,2 @@
+// Imported first by the CLI: measures only its modules, after the engine starts this first body.
+export const cliLoadStarted = performance.now();

package/src/cli.ts

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 // volter-world: each command loads only what it needs. `up` (./up-cli.ts) starts the World's owner process
 // before any other command's modules load; every other command is ./cli-commands.ts.
+import { cliLoadStarted } from './cli-load-clock.ts';
 import { optionValue } from './cli-args.ts';
 import { errorMessage } from './error-message.ts';
 
 const [cmd, subject, ...rest] = process.argv.slice(2);
 const run = cmd === 'up' && subject !== '--help' && subject !== '-h'
-  ? import('./up-cli.ts').then(({ upCommand }) => upCommand(subject, rest, optionValue(rest, '--root', process.cwd())))
+  ? import('./up-cli.ts').then(({ upCommand }) => {
+    process.stderr.write(`volter-world up: entry modules loaded in ${(performance.now() - cliLoadStarted).toFixed(1)} ms\n`);
+    return upCommand(subject, rest, optionValue(rest.includes('--attach-after-line') && rest.includes('--') ? rest.slice(0, rest.indexOf('--')) : rest, '--root', process.cwd()));
+  })
   : import('./cli-commands.ts').then(({ main }) => main());
 run.catch((error) => {
   process.stderr.write(`${errorMessage(error)}\n`);

package/src/clickhouse-backing.ts

@@ -0,0 +1,70 @@
+// ClickHouse's managed ownership questions: HTTP ping, this child's kernel boot answer,
+// and a native Hello/Ping. No SQL is executed by readiness.
+// Packet fields: clickhouse-docs/docs/native-protocol/{client,server,basics}.md;
+// revision54429 uses the reached clickhouse-driver0.2.10 layout retained with the pack.
+import { connect } from 'node:net';
+import { WORLD_BOOT_PATH } from '@volter/world-core/runtime';
+import type { ManagedProtocol } from './twin-backing.ts';
+import type { InfraService } from './infra-definition.ts';
+
+async function answer(port: number, path: string): Promise<string | undefined> {
+  const controller = new AbortController(), timer = setTimeout(() => controller.abort(), 1000);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}${path}`, { signal: controller.signal, redirect: 'error' });
+    if (!response.ok || !response.body) return undefined;
+    // This private proof contains a UUID boot nonce and a JavaScript-safe PID; ping is four bytes.
+    const reader = response.body.getReader(); let text = '', bytes = 0;
+    try { while (true) { const part = await reader.read(); if (part.done) break; bytes += part.value.length; if (bytes > 256) return undefined; text += new TextDecoder().decode(part.value); } }
+    finally { await reader.cancel().catch(() => undefined); }
+    return text;
+  } catch { return undefined; } finally { clearTimeout(timer); }
+}
+function number(value: number): number[] { const result: number[] = []; do { const byte = value % 128; value = Math.floor(value / 128); result.push(byte | (value ? 128 : 0)); } while (value); return result; }
+function string(value: string): number[] { const bytes = new TextEncoder().encode(value); return [...number(bytes.length), ...bytes]; }
+function nativeAnswers(service: InfraService): Promise<boolean> {
+  const port = service.sides?.native?.hostPort; if (!port) return Promise.resolve(false);
+  const users = service.configuration?.users as Record<string, string> | undefined;
+  const [user, password] = users && Object.hasOwn(users, 'default') ? ['default', users.default!] : Object.entries(users ?? { default: '' })[0] ?? [];
+  if (typeof user !== 'string' || typeof password !== 'string') return Promise.resolve(false);
+  const hello = Uint8Array.from([0, ...string('World ownership'), 1, 0, ...number(54429), ...string('default'), ...string(user), ...string(password)]);
+  return new Promise(resolve => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: 1000 }); let bytes = new Uint8Array(), phase = 'hello', settled = false;
+    const end = (valid: boolean) => { if (settled) return; settled = true; clearTimeout(timer); socket.destroy(); resolve(valid); };
+    // One complete ownership question has one deadline; incoming fragments never extend it.
+    const timer = setTimeout(() => end(false), 1000);
+    const missing = Symbol('incomplete');
+    socket.once('connect', () => socket.write(hello));
+    socket.on('data', chunk => {
+      // The declaring pack fixes its Hello name, timezone and display name;64KiB is beyond that packet domain.
+      if (bytes.length + chunk.length > 65536) { end(false); return; }
+      const joined = new Uint8Array(bytes.length + chunk.length); joined.set(bytes); joined.set(chunk, bytes.length); bytes = joined;
+      let at = 0;
+      const read = (): number => {
+        let value = 0n;
+        for (let shift = 0; shift < 70; shift += 7) { if (at >= bytes.length) throw missing; const byte = bytes[at++]!; value |= BigInt(byte & 127) << BigInt(shift); if (!(byte & 128)) { if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('Invalid native integer'); return Number(value); } }
+        throw new Error('Invalid native integer');
+      };
+      const text = (): string => { const length = read(); if (length > bytes.length - at) throw missing; const result = new TextDecoder().decode(bytes.subarray(at, at + length)); at += length; return result; };
+      try {
+        if (phase === 'hello') {
+          if (read() !== 0 || text() !== 'ClickHouse') { end(false); return; }
+          read(); read(); const revision = read(); if (revision !== 54429) { end(false); return; }
+          text(); text(); read(); bytes = bytes.slice(at); phase = 'pong'; socket.write(Uint8Array.of(4));
+          if (!bytes.length) return; at = 0;
+        }
+        end(read() === 4);
+      } catch (error) { if (error !== missing) end(false); }
+    });
+    socket.once('error', () => end(false)); socket.once('timeout', () => end(false)); socket.once('close', () => end(false));
+  });
+}
+export const CLICKHOUSE_PROTOCOL: ManagedProtocol = {
+  name: 'ClickHouse', bootProof: true,
+  async answers(port) { return await answer(port, '/ping') === 'Ok.\n'; },
+  async serves(port, pid, service, boot) {
+    if (!service || !boot || await answer(port, '/ping') !== 'Ok.\n') return false;
+    const body = await answer(port, WORLD_BOOT_PATH); if (!body) return false;
+    try { const held = JSON.parse(body); if (held.boot !== boot || held.pid !== pid) return false; } catch { return false; }
+    return nativeAnswers(service);
+  },
+};

package/src/command-lifetime.d.mts

@@ -4,7 +4,7 @@ export const COMMAND_GRACE_MS: number;
 export const COMMAND_CONFIRM_MS: number;
 export const commandProcessGroup: boolean;
 export class CommandRetirementError extends Error {}
-export function commandLifetime(child: ChildProcess, abort?: AbortSignal, preserveOnSuccess?: boolean): {
+export function commandLifetime(child: ChildProcess, abort?: AbortSignal, preserveOnSuccess?: boolean, graceMs?: number): {
   identity: Promise<SpawnIdentity | undefined>;
   cancel(signal: NodeJS.Signals): void;
   readonly forwarded: NodeJS.Signals | undefined;

package/src/command-lifetime.mjs

@@ -9,7 +9,10 @@ export class CommandRetirementError extends Error {}
 
 /** The child owns a private POSIX group. A bounded retirement requires both closed output and
  * a vanished group. Unknown retirement keeps the caller's ownership record and reservation. */
-export function commandLifetime(child, abort, preserveOnSuccess = false) {
+/** `graceMs` is how long a cancelled child is awaited before SIGKILL. A command gets the default; a STORE (a
+ *  database, a twin that holds state) is given its lifecycle's budget, since what it does between the signal and
+ *  its exit is write its state down, and a SIGKILL in the middle of that leaves a store nothing may take. */
+export function commandLifetime(child, abort, preserveOnSuccess = false, graceMs = COMMAND_GRACE_MS) {
   const identity = child.pid && commandProcessGroup ? childIdentity(child) : Promise.resolve(undefined);
   let signalFailure;
   let pendingSignals = 0;
@@ -62,7 +65,7 @@ export function commandLifetime(child, abort, preserveOnSuccess = false) {
     }
   };
   const watch = () => {
-    if (!deadline) deadline = Date.now() + COMMAND_GRACE_MS;
+    if (!deadline) deadline = Date.now() + graceMs;
     timer ??= setInterval(check, 20);
     check();
   };

package/src/configs.ts

@@ -1,6 +1,6 @@
 import { copyFileSync, constants, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
-import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime';
+import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime-state';
 import { assertWorldConfig, LEGACY_WORLD_SELECTION, worldConfigDocument, type WorldChangesetRules, type WorldConfig } from './schema.ts';
 
 export function resolveConfigPath(config: string, root = process.cwd()): string {

package/src/consumers.ts

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { join } from 'node:path';
-import { stateDirName, withFileLock } from '@volter/world-core/runtime';
+import { stateDirName, withFileLock } from '@volter/world-core/runtime-state';
 
 export type WorldConsumer = {
   id: string;

package/src/covers.ts

@@ -627,6 +627,8 @@ export function worldTwinInventory(world: string, root: string): WorldTwinInvent
 export type CoverageOptions = {
   root?: string;
   allowUnknown?: boolean;
+  /** Application environment names already read from its declared stack. */
+  declaredEnvironmentNames?: readonly string[];
   /**
    * vendor → reason: vendors the operator ACKNOWLEDGES need no twin in this world — e.g. an SDK
    * used verifier-only (svix's Webhook verifies incoming signatures locally and never calls out).
@@ -685,11 +687,11 @@ function usesOf(signals: Map<string, string[]>): Map<string, Array<{ usage: Worl
 
 /** Detect every vendor (and every unmapped external-service-shaped signal) an application repo
  * betrays: mapped npm dependencies across the root + all workspace members, vendor-shaped env
- * names in committed `.env*` files, the SMTP/raw-protocol signal, and literal vendor URLs passed
+ * names in committed `.env*` files or its declared stack, the SMTP/raw-protocol signal, and literal vendor URLs passed
  * directly to fetch in production source. URL attribution reads the injector's VENDOR_HOSTS table
  * rather than re-encoding host rules here. Insertion order follows the sorted dependency, env-name,
  * and source lists, so callers that preserve it are deterministic. */
-export function detectRepoVendors(repoPath: string, services: Array<WorldServiceConfig | WorldServiceInstance> = []): RepoVendorSignals {
+export function detectRepoVendors(repoPath: string, services: Array<WorldServiceConfig | WorldServiceInstance> = [], declaredEnvironmentNames: readonly string[] = []): RepoVendorSignals {
   // Application aliases are names the selected backing actually injects, never global vendor adoption.
   const backingEnvVendors = new Map<string, string>();
   for (const service of services) {
@@ -703,7 +705,10 @@ export function detectRepoVendors(repoPath: string, services: Array<WorldService
   // A Volter package a pack names as its vendor's SDK is one (`@volter/identity`, the Volter identity
   // service's client, is the volteridentity twin's), as any vendor's SDK is.
   const dependencies = projectDependencies(repo).filter((dep) => Object.hasOwn(SDK_TWINS, dep) || (!dep.startsWith('@volter/') && !dep.startsWith('pypi:volter')));
-  const envNames = projectEnvNames(repo);
+  for (const name of declaredEnvironmentNames) {
+    if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error('Declared vendor environment name must be an identifier');
+  }
+  const envNames = [...new Set([...projectEnvNames(repo), ...declaredEnvironmentNames])].sort();
   const npmRegistries = projectNpmRegistries(repo);
 
   // vendor → detection sources
@@ -871,7 +876,7 @@ export function coverWorld(world: string, repoPath: string, options: CoverageOpt
   const repo = resolve(repoPath);
   const inventory = worldTwinInventory(world, root);
 
-  const { detected, unknown: unknownSources, uses, unknownUses } = detectRepoVendors(repo, inventory.services);
+  const { detected, unknown: unknownSources, uses, unknownUses } = detectRepoVendors(repo, inventory.services, options.declaredEnvironmentNames);
 
   // Does ANY injector vendor key exist for this vendor? Decides whether an UNINTERCEPTABLE
   // finding is acknowledgeable: a key that exists means the twin COULD be intercepted and the