@volter/world-runtime 3.0.163 → 3.0.164

package/dist/src/cli-commands.js

@@ -1,24 +1,10 @@
 // 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.js";
 import { optionValue, ownerOption } from "./cli-args.js";
-import { printReady } from "./up-cli.js";
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } 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, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
-import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core/runtime';
-import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from "./serve.js";
-import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from "./runtime.js";
-import { worldResourceReport } from "./resources.js";
-import { worldConsumers, worldUsage } from "./consumers.js";
-import { addAppHosts, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from "./app-url.js";
-import { describeServiceEnd, describeWorldEvent, readServiceEnd, readWorldEvents } from "./service-exit.js";
-import { worldEventsPath } from "./runtime.js";
-import { resolveCatalog } from "./catalog.js";
-import { loadWorldConfig } from "./configs.js";
-import { vendorOfPackModule } from '@volter/world-core/runtime';
 /** The non-flag args, skipping each value-taking flag's value (so `--root <path>` never
  * masquerades as a positional service id). */
 function positionalArgs(args, valueFlags = ['--root']) {
@@ -50,7 +36,7 @@ function acknowledgeOptions(args, command) {
 }
 function printHelp() {
     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
@@ -58,6 +44,7 @@ function printHelp() {
                                                   # 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)
@@ -177,6 +164,7 @@ export async function main() {
         return;
     }
     if (cmd === 'consumers') {
+        const { retireWorldConsumers } = await import("./runtime.js");
         // `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 !== undefined);
@@ -206,6 +194,9 @@ export async function main() {
         return;
     }
     if (cmd === 'resources' || cmd === 'prune') {
+        const { pruneWorlds, statusWorld } = await import("./runtime.js");
+        const { worldResourceReport } = await import("./resources.js");
+        const { worldConsumers, worldUsage } = await import("./consumers.js");
         const args = [subject, ...rest].filter((arg) => arg !== undefined);
         const reportRoot = optionValue(args, '--root', process.cwd());
         // Destructive commands must reject typos, not silently broaden a target to all Worlds.
@@ -277,6 +268,7 @@ export async function main() {
         return;
     }
     if (cmd === 'down') {
+        const { downWorld } = await import("./runtime.js");
         if (!subject)
             throw new Error('volter-world down: missing world name');
         const graceArg = optionValue(rest, '--grace-ms');
@@ -321,6 +313,8 @@ export async function main() {
         return;
     }
     if (cmd === 'events') {
+        const { statusWorld, worldEventsPath } = await import("./runtime.js");
+        const { readWorldEvents, describeWorldEvent } = await import("./service-exit.js");
         if (!subject)
             throw new Error('volter-world events: missing world name');
         const status = statusWorld(subject, root, { readOnly: true, light: true });
@@ -335,6 +329,9 @@ export async function main() {
         return;
     }
     if (cmd === 'status') {
+        const { statusWorld, worldEventsPath } = await import("./runtime.js");
+        const { worldUsage } = await import("./consumers.js");
+        const { readServiceEnd, describeServiceEnd, readWorldEvents, describeWorldEvent } = await import("./service-exit.js");
         if (!subject)
             throw new Error('volter-world status: missing world name');
         const status = statusWorld(subject, root);
@@ -397,6 +394,7 @@ export async function main() {
     }
     // `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.js");
         if (!subject)
             throw new Error('volter-world doctor: missing world name');
         const report = await doctorWorld(subject, { root, verifyPublic: rest.includes('--verify-public') });
@@ -413,6 +411,7 @@ export async function main() {
         return;
     }
     if (cmd === 'doctor-prereqs') {
+        const { checkPrerequisites, formatPrerequisiteChecks } = await import("./prerequisites.js");
         const required = rest.flatMap((arg, index) => arg === '--require' ? [rest[index + 1]] : [])
             .filter(Boolean);
         const checks = checkPrerequisites(required.length ? required : ['local-execution']);
@@ -429,6 +428,7 @@ export async function main() {
         return;
     }
     if (cmd === 'inspect-project') {
+        const { inspectProject, formatProjectInspection } = await import("./project-inspect.js");
         const args = [...(subject ? [subject] : []), ...rest];
         const path = args.find((arg) => !arg.startsWith('--')) || process.cwd();
         const report = inspectProject(path);
@@ -436,6 +436,7 @@ export async function main() {
         return;
     }
     if (cmd === 'migrate-config') {
+        const { migrateWorldConfig } = await import("./configs.js");
         if (!subject)
             throw new Error('volter-world migrate-config: missing config path or name');
         const migration = migrateWorldConfig(subject, root);
@@ -469,22 +470,29 @@ export async function main() {
         return;
     }
     if (cmd === 'init') {
+        const { initWorld, formatInitReport } = await import("./init.js");
         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)
+        // 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;
     }
@@ -492,10 +500,11 @@ export async function main() {
     // 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.js");
         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 {
@@ -509,6 +518,7 @@ export async function main() {
         return;
     }
     if (cmd === 'covers') {
+        const { coverWorld, formatCoverageReport, recordCoverage } = await import("./covers.js");
         if (!subject)
             throw new Error('volter-world covers: missing world name (usage: volter-world covers <world> --repo <path>)');
         const repo = optionValue(rest, '--repo');
@@ -532,6 +542,8 @@ export async function main() {
         return;
     }
     if (cmd === 'clock') {
+        const { clockFile } = await import("./runtime.js");
+        const { writeWorldClock } = await import("./clock.js");
         // 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
@@ -604,6 +616,7 @@ export async function main() {
         return;
     }
     if (cmd === 'urls') {
+        const { urlsWorld } = await import("./runtime.js");
         if (!subject)
             throw new Error('volter-world urls: missing world name');
         const urls = urlsWorld(subject, root);
@@ -619,6 +632,7 @@ export async function main() {
         return;
     }
     if (cmd === 'url') {
+        const { urlWorld } = await import("./runtime.js");
         if (!subject)
             throw new Error('volter-world url: missing world name (usage: volter-world url <world> [service])');
         const [service] = positionalArgs(rest);
@@ -631,6 +645,7 @@ export async function main() {
         return;
     }
     if (cmd === 'app-url') {
+        const { setAppUrl, detectAppUrl, addAppHosts, readAppUrl, appUrlUnsetMessage } = await import("./app-url.js");
         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');
@@ -667,6 +682,7 @@ export async function main() {
         return;
     }
     if (cmd === 'tail' || cmd === 'log') {
+        const { tailWorldActions } = await import("./tail.js");
         if (!subject)
             throw new Error(`volter-world ${cmd}: missing world name (usage: volter-world log <world> [service...])`);
         const services = positionalArgs(rest);
@@ -685,6 +701,7 @@ export async function main() {
         return;
     }
     if (cmd === 'seed' || cmd === 'reset') {
+        const { seedWorld, resetWorld } = await import("./placeholder.js");
         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=')))
@@ -702,6 +719,8 @@ export async function main() {
         return;
     }
     if (cmd === 'branch') {
+        const { branchWorld } = await import("./branch.js");
+        const { printReady } = await import("./up-cli.js");
         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);
@@ -718,6 +737,8 @@ export async function main() {
         return;
     }
     if (cmd === 'checkout') {
+        const { checkoutWorld } = await import("./branch.js");
+        const { printReady } = await import("./up-cli.js");
         if (!subject)
             throw new Error('volter-world checkout: missing world name');
         const instance = await checkoutWorld(subject, { root });
@@ -728,6 +749,7 @@ export async function main() {
         return;
     }
     if (cmd === 'fetch') {
+        const { fetchFromOrigin } = await import("./origin.js");
         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 || '';
@@ -749,6 +771,7 @@ export async function main() {
         return;
     }
     if (cmd === 'origin') {
+        const { worldOrigin } = await import("./origin.js");
         if (!subject)
             throw new Error('volter-world origin: missing world name');
         const origin = worldOrigin(subject, root);
@@ -759,6 +782,7 @@ export async function main() {
         return;
     }
     if (cmd === 'mark') {
+        const { markWorld } = await import("./changeset.js");
         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');
@@ -771,6 +795,8 @@ export async function main() {
         return;
     }
     if (cmd === 'diff') {
+        const { diffWorld } = await import("./changeset.js");
+        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');
@@ -779,6 +805,8 @@ export async function main() {
         return;
     }
     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.js");
         const CHANGESET_VALUE_FLAGS = ['--root', '--base', '--into', '--world', '--verifier', '--as', '--note'];
         const args = positionalArgs(rest, CHANGESET_VALUE_FLAGS);
         const world = optionValue(rest, '--world');
@@ -893,6 +921,8 @@ export async function main() {
         throw new Error(`volter-world changeset: unknown subcommand ${JSON.stringify(subject ?? '')} (want create|show|list|replay|verify|approve|status|rebase|push)`);
     }
     if (cmd === 'list') {
+        const { listWorlds } = await import("./runtime.js");
+        const { worldUsage } = await import("./consumers.js");
         const listArgs = [subject, ...rest].filter((arg) => arg !== undefined);
         const listRoot = optionValue(listArgs, '--root', process.cwd());
         const worlds = listWorlds(listRoot).map(world => ({ ...world, usage: worldUsage(listRoot, world.name) }));
@@ -907,6 +937,7 @@ export async function main() {
         return;
     }
     if (cmd === 'env') {
+        const { attachWorld } = await import("./runtime.js");
         if (!subject)
             throw new Error('volter-world env: missing world name');
         const split = rest.indexOf('--');
@@ -916,6 +947,10 @@ export async function main() {
         process.exit(exitCode);
     }
     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.js"), import("./runtime.js")]);
         // `subject` may be the ref, a flag, or the `--` separator — reassemble and split.
         const args = [subject, ...rest].filter((arg) => arg !== undefined);
         const split = args.indexOf('--');
@@ -930,6 +965,7 @@ export async function main() {
             throw new Error('--owner is supported for local attach --via env commands');
         }
         if (isRemoteWorldRef(resolved.ref)) {
+            const { fetchRemoteManifest, remoteAttachEnv } = await import("./serve.js");
             // 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 });
@@ -975,6 +1011,7 @@ export async function main() {
             // 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.js"), import("./ca-trust.js")]);
             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`);
@@ -1007,12 +1044,15 @@ export async function main() {
         process.exit(await attachWorld(resolved.ref, command, attachRoot, { cwd: process.cwd(), owner: ownerOption(head), verbose: head.includes('--verbose') }));
     }
     if (cmd === 'manifest') {
+        const { worldManifest } = await import("./attach.js");
         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.js");
+        const { statusWorld, instanceDir } = await import("./runtime.js");
         if (!subject)
             throw new Error('volter-world reflect: missing world name');
         const targetIp = optionValue(rest, '--target-ip');
@@ -1047,6 +1087,9 @@ export async function main() {
         return;
     }
     if (cmd === 'serve') {
+        const { startReflectFront } = await import("./reflect.js");
+        const { statusWorld, instanceDir } = await import("./runtime.js");
+        const { startManifestServer, advertiseWorldManifest, MANIFEST_PATH } = await import("./serve.js");
         if (!subject)
             throw new Error('volter-world serve: missing world name');
         const advertise = optionValue(rest, '--advertise');
@@ -1088,6 +1131,7 @@ export async function main() {
         return;
     }
     if (cmd === 'route') {
+        const { reflectRoutesPath, readReflectRoutes, writeReflectRoutes } = await import("./reflect.js");
         if (!subject)
             throw new Error('volter-world route: missing world name');
         const [verb, host] = rest.filter((arg) => !arg.startsWith('--'));
@@ -1111,17 +1155,21 @@ export async function main() {
         return;
     }
     if (cmd === 'activate') {
+        const { activateScript } = await import("./runtime.js");
         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.js");
         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.js");
+        const { readServiceEnd, describeServiceEnd } = await import("./service-exit.js");
         if (!subject)
             throw new Error('volter-world run: missing config');
         const split = rest.indexOf('--');
@@ -1155,6 +1203,7 @@ export async function main() {
         process.exit(result.exitCode);
     }
     if (cmd === 'share') {
+        const { shareWorldServices } = await import("./runtime.js");
         if (!subject)
             throw new Error('volter-world share: missing world name');
         const service = optionValue(rest, '--service') || undefined;
@@ -1187,6 +1236,7 @@ export async function main() {
         return;
     }
     if (cmd === 'unshare') {
+        const { unshareWorld } = await import("./runtime.js");
         if (!subject)
             throw new Error('volter-world unshare: missing world name');
         const service = optionValue(rest, '--service') || undefined;
@@ -1201,7 +1251,10 @@ export async function main() {
 /** 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, kind, root) {
+async function worldUpkeep(status, kind, root) {
+    const { resolveCatalog } = await import("./catalog.js");
+    const { loadWorldConfig } = await import("./configs.js");
+    const { vendorOfPackModule } = await import('@volter/world-core/runtime');
     const catalog = resolveCatalog(root);
     const config = loadWorldConfig(status.name, root).config;
     const out = [];

package/dist/src/cli-load-clock.d.ts

@@ -0,0 +1 @@
+export declare const cliLoadStarted: number;

package/dist/src/cli-load-clock.js

@@ -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/dist/src/cli.js

@@ -1,11 +1,15 @@
 #!/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.js";
 import { optionValue } from "./cli-args.js";
 import { errorMessage } from "./error-message.js";
 const [cmd, subject, ...rest] = process.argv.slice(2);
 const run = cmd === 'up' && subject !== '--help' && subject !== '-h'
-    ? import("./up-cli.js").then(({ upCommand }) => upCommand(subject, rest, optionValue(rest, '--root', process.cwd())))
+    ? import("./up-cli.js").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.js").then(({ main }) => main());
 run.catch((error) => {
     process.stderr.write(`${errorMessage(error)}\n`);

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

@@ -0,0 +1,2 @@
+import type { ManagedProtocol } from './twin-backing.js';
+export declare const CLICKHOUSE_PROTOCOL: ManagedProtocol;

package/dist/src/clickhouse-backing.js

@@ -0,0 +1,145 @@
+// 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';
+async function answer(port, path) {
+    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) { const result = []; do {
+    const byte = value % 128;
+    value = Math.floor(value / 128);
+    result.push(byte | (value ? 128 : 0));
+} while (value); return result; }
+function string(value) { const bytes = new TextEncoder().encode(value); return [...number(bytes.length), ...bytes]; }
+function nativeAnswers(service) {
+    const port = service.sides?.native?.hostPort;
+    if (!port)
+        return Promise.resolve(false);
+    const users = service.configuration?.users;
+    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) => { 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 = () => {
+                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 = () => { 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 = {
+    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/dist/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/dist/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/dist/src/configs.js

@@ -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 } from "./schema.js";
 export function resolveConfigPath(config, root = process.cwd()) {
     const candidates = config.includes('/') || config.endsWith('.json')

package/dist/src/consumers.js

@@ -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 const CONSUMER_HEARTBEAT_MS = 5000;
 const STALE_MS = 30_000;
 export function checkedOwner(owner) {

package/dist/src/covers.d.ts

@@ -142,6 +142,8 @@ export declare function worldTwinInventory(world: string, root: string): WorldTw
 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).
@@ -179,11 +181,11 @@ export type RepoVendorSignals = {
 };
 /** 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 declare function detectRepoVendors(repoPath: string, services?: Array<WorldServiceConfig | WorldServiceInstance>): RepoVendorSignals;
+export declare function detectRepoVendors(repoPath: string, services?: Array<WorldServiceConfig | WorldServiceInstance>, declaredEnvironmentNames?: readonly string[]): RepoVendorSignals;
 export declare function coverWorld(world: string, repoPath: string, options?: CoverageOptions): CoverageReport;
 /**
  * The report as the data `init` keeps in the config (`discovery.coverage`): the same rows `formatCoverageReport`