@volter/world-runtime 3.0.163 → 3.0.164

package/src/branch.ts

@@ -7,7 +7,7 @@
 // base running at once share the database port its definition names; run one at a time (the SDK does). `checkout <name>`
 // brings a stopped world back up from its own instance record, state intact.
 import { runInfrastructure } from './infra.ts';
-import { cpSync, existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { captureHistory, historyAtInstant, forkTwin, stateGeneration, withHistoryLocks, worldPaths, worldStateRoot } from '@volter/world-core/runtime';
@@ -49,7 +49,7 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
       const position = options.at?.positions?.[service] ?? options.at?.positions?.[state] ?? timed?.position;
       return { state, view, position, generation: stateGeneration(worldPaths(state, fromRoot).dir) };
     }) };
-  }));
+  }), { operation: 'capture' });
   // the base's managed databases (checked before the branch boots: its database would share the base's port)
   const databases = managedDatabases(from);
   if (databases.length && (options.at?.instant || options.at?.positions || options.at?.views)) {
@@ -83,23 +83,28 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
 }
 
 /** The base's containerless managed databases: each PGlite `pglite-<kind>-data`, MongoDB's
- *  `mongod-mongodb-data` (pglite-backing.ts), the redis twin's `redis-twin` tree (redis-backing.ts), and native PostgreSQL. A stopped World's
+ *  `mongod-mongodb-data` (pglite-backing.ts), the declared Redis/ClickHouse twin trees, and native PostgreSQL. A stopped World's
  *  hosts leave no pid file; a docker-backed World keeps its data under the container's volume, which a branch does not
  *  carry. */
 function managedDatabases(from: WorldInstance): string[] {
   const data = from.dirs.data;
   if (!existsSync(data)) return [];
-  const known = (name: string) => /^pglite-[a-z0-9_-]+-data$/.test(name) || name === 'mongod-mongodb-data' || name === 'native-postgres-data';
+  const known = (name: string) => /^pglite-[a-z0-9_-]+-data$/.test(name) || name === 'mongod-mongodb-data' || ['native-postgres-data', 'native-mariadb-data'].includes(name);
   if (readdirSync(data).some(name => name.endsWith('-data') && !known(name) && !from.services[name])) {
     throw new Error('volter-world branch: unrecognised storage; retain the original World');
   }
-  return readdirSync(data).filter((n) => /^pglite-[a-z0-9_-]+-data$/.test(n) || n === 'mongod-mongodb-data' || n === 'redis-twin' || n === 'native-postgres-data');
+  return readdirSync(data).filter((n) => /^pglite-[a-z0-9_-]+-data$/.test(n) || n === 'mongod-mongodb-data' || ['redis-twin', 'clickhouse-twin', 'native-postgres-data', 'native-mariadb-data'].includes(n));
 }
 
 /** The pid files of the hosts serving one managed database directory. */
 function hostPidFiles(data: string, db: string): string[] {
+  if (db === 'native-mariadb-data') return readdirSync(data).filter(name => /^native-mariadb\.(?:owner|starting)\.json(?:\.spawn\.json)?$/u.test(name)
+    || /^native-mariadb-tool-.*\.json(?:\.spawn\.json)?$/u.test(name)).map(name => join(data, name));
   if (db === 'native-postgres-data') return [join(data, 'native-postgres.owner.json')];
   if (db === 'redis-twin') return readdirSync(data).filter((n) => /^redis-twin-\d+\.pid$/.test(n)).map((n) => join(data, n));
+  if (db === 'clickhouse-twin') return [...new Set(readdirSync(data)
+    .filter(n => new RegExp(`^${db}-\\d+\\.pid(?:\\.spawn\\.json)?$`).test(n))
+    .map(n => join(data, n.replace(/\.spawn\.json$/, ''))))];
   return [join(data, `${db.slice(0, -'-data'.length)}.pid`)];
 }
 
@@ -107,7 +112,19 @@ function hostPidFiles(data: string, db: string): string[] {
  *  port: the base must be stopped first (`volter world branch` stops it, as a branch replaces its base). */
 function refuseLiveDatabases(from: WorldInstance, dbs: string[]): void {
   for (const db of dbs) {
+    if (db === 'native-mariadb-data' && (existsSync(join(from.dirs.data, db, 'server.pid')) || existsSync(join(from.dirs.data, db, 'server.sock'))))
+      throw new Error(`volter-world branch: ${from.name}'s managed MariaDB retains PID/socket files; verified down is required`);
+    if (db === 'native-mariadb-data') {
+      const stamp = join(from.dirs.data, db, '.world-policy.json');
+      if (!existsSync(stamp) || !lstatSync(stamp).isFile() || existsSync(join(from.dirs.data, db, '.world-initializing.json')))
+        throw new Error(`volter-world branch: ${from.name}'s MariaDB has incomplete initialization; original data retained`);
+    }
     for (const pidFile of hostPidFiles(from.dirs.data, db)) {
+      // Successful managed-twin down removes both receipts. A partial publication or an
+      // uncertain retirement must finish there before branch copies this store.
+      if (db === 'clickhouse-twin' || db === 'native-mariadb-data') {
+        throw new Error(`volter-world branch: ${from.name}'s managed ${db} retains ownership receipts; stop ${from.name} before copying its store`);
+      }
       const recorded = existsSync(pidFile) ? readFileSync(pidFile, 'utf8').trim() : '';
       const pid = db === 'native-postgres-data' && recorded ? JSON.parse(recorded).pid : Number(recorded);
       let live = false;
@@ -121,6 +138,7 @@ function refuseLiveDatabases(from: WorldInstance, dbs: string[]): void {
 function requireMatchingBackings(source: string[], child: string[]): void {
   const kinds = {
     postgres: ['native-postgres-data', 'pglite-postgres-data'],
+    mysql: ['native-mariadb-data'],
     mongodb: ['mongod-mongodb-data'],
   };
   for (const [kind, formats] of Object.entries(kinds)) {
@@ -158,15 +176,15 @@ async function branchManagedDatabases(from: WorldInstance, instance: WorldInstan
   const infrastructure = config.services.find((service) => service.type === 'external' && (service.external?.up[0] === 'volter-world-infra' || service.id === 'infrastructure'));
   if (!infrastructure) throw new Error(`volter-world branch: ${instance.name}'s managed databases have no declared infrastructure service`);
   const launch = { env: externalServiceEnv(infrastructure, instance.dirs, instance.env, config.stripEnv) };
-  if (dbs.includes('native-postgres-data')) {
+  if (dbs.some(directory => ['native-postgres-data', 'native-mariadb-data', 'clickhouse-twin'].includes(directory))) {
     const io = { out: (text: string) => process.stdout.write(text), err: (text: string) => process.stderr.write(text) };
-    if (await runInfrastructure('down', launch.env, io) !== 0) throw new Error('managed native database branch could not stop its new backing');
+    if (await runInfrastructure('down', launch.env, io) !== 0) throw new Error('managed database branch could not stop its new backing');
     for (const db of dbs) {
       const to = join(instance.dirs.data, db);
       rmSync(to, { recursive: true, force: true });
       cpSync(join(from.dirs.data, db), to, { recursive: true });
     }
-    if (await runInfrastructure('up', launch.env, io) !== 0) throw new Error('managed native database branch could not resume its copied backing');
+    if (await runInfrastructure('up', launch.env, io) !== 0) throw new Error('managed database branch could not resume its copied backing');
     return;
   }
   const redisCli = dbs.includes('redis-twin') && redis.length ? redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(instance.configPath)]) : undefined;

package/src/browser-files.ts

@@ -0,0 +1,15 @@
+import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime-state';
+import { dirname, join } from 'node:path';
+
+/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
+export const browsersDir = (data: string): string => join(dirname(data), 'browser-records');
+
+/** Empty Worlds need no browser validators or cookie/load machinery. A prior
+ * projection still loads the ordinary materializer to remove stale files. */
+export async function materializeWorldBrowserFiles(data: string, root: string, name: string, main = name): Promise<void> {
+  const store = getActiveWorldStore();
+  if (!store.list(browsersDir(data)).some(file => file.endsWith('.json'))
+    && store.read(join(root, stateDirName(), 'browsers', '.source.json')) === null) return;
+  const { materializeBrowserFiles } = await import('./browsers.ts');
+  materializeBrowserFiles(data, root, name, main);
+}

package/src/browsers.ts

@@ -1,11 +1,11 @@
-import { assertBrowserName, validateBrowserState, type BrowserState } from '@volter/world-core';
-import { getActiveWorldStore, stateDirName, type WorldStore } from '@volter/world-core/runtime';
+import { assertBrowserName, validateBrowserState, type BrowserState } from '@volter/world-core/browser-state';
+import { getActiveWorldStore, stateDirName, type WorldStore } from '@volter/world-core/runtime-state';
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
 
 export type WorldBrowser = { name: string; state: BrowserState; version: string };
-/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
-export const browsersDir = (data: string): string => join(dirname(data), 'browser-records');
+import { browsersDir } from './browser-files.ts';
+export { browsersDir } from './browser-files.ts';
 const path = (data: string, name: string): string => { assertBrowserName(name); return join(browsersDir(data), `${name}.json`); };
 const records = new WeakMap<WorldStore, Map<string, { version: string; text: string; record: WorldBrowser }>>();
 export function worldBrowser(data: string, name: string): WorldBrowser | null {

package/src/catalog.ts

@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join, resolve } from 'node:path';
 import { overlayPackFacts, type PackFacts } from './pack-facts.ts';
-import { installedPackageDir, installedVendorPacks, isDerivedPack, packRepository } from '@volter/world-core/runtime';
+import { installedPackageDir, installedVendorPacks, isDerivedPack, packRepository } from '@volter/world-core/runtime-state';
 
 export const TWIN_PACKAGE_PREFIX = '@volter/twin-';
 
@@ -156,7 +156,7 @@ export function packFactsFile(dir: string): string | undefined {
 
 /** The catalog for a World root: its pack repository (or the one beside its platform checkout), merged with installed
  *  packages. Only the selected packs' own facts are overlaid on the kernel's. */
-export function resolveCatalog(root: string, options: { sources?: Readonly<Record<string, string>>; vendors?: readonly string[] } = {}): Catalog {
+export function resolveCatalog(root: string, options: { sources?: Readonly<Record<string, string>>; vendors?: readonly string[]; mayBeEmpty?: boolean } = {}): Catalog {
   const resolved = resolve(root);
   const installed = installedCatalog(resolved, options);
   const repo = packRepository(resolved);
@@ -165,7 +165,8 @@ export function resolveCatalog(root: string, options: { sources?: Readonly<Recor
     const file = packFactsFile(catalog.packDir(vendor)!);
     if (file) overlayPackFactsFile(file);
   }
-  if (catalog.vendors().length === 0) {
+  // A World whose application runs beside infrastructure alone has no twin to find (`init --needs`, architecture).
+  if (catalog.vendors().length === 0 && !options.mayBeEmpty) {
     throw new Error(
       `No twins found for ${resolved}: no pack repository and no \`@volter/twin-<vendor>\` package installed above it. `
       + `Install the twins your app needs (e.g. \`bun add -d @volter/twin-stripe\`) and run init again.`,

package/src/changeset.ts

@@ -641,7 +641,7 @@ export function rebaseWorldChangeset(name: string, options: WorldRootOptions & {
   const moved = [...new Set(located.changeset.actions.map((e) => e.service))].map((service) => ({ st: located.changeset.actions.find((e) => e.service === service)?.stateService ?? service, controlRoot: join(inst.dirs.data, service) }));
   withHistoryLocks(moved.map(({ st, controlRoot }) => worldPaths(st, controlRoot).dir), () => {
     for (const { st, controlRoot } of moved) rebaseBranch(st, controlRoot, { origin: Boolean(readBranchMeta(st, controlRoot)?.origin) });
-  });
+  }, { operation: 'branch-pointer adjustment' });
   if (!changesetHashMatches(located.changeset)) throw new Error(`Refusing to rebase changeset "${name}": its stored contentHash does not match its body — the object drifted after authoring`);
   const instance = requireWorld(located.world, root);
   const targets: RebaseTarget[] = [...new Set(located.changeset.actions.map((entry) => entry.service))].map((service) => ({ service, stateService: located.changeset.actions.find((entry) => entry.service === service)!.stateService, controlRoot: join(instance.dirs.data, service) }));

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`);