@volter/world-runtime 3.0.38 → 3.0.40

package/dist/src/cli-commands.js

@@ -57,10 +57,10 @@ function printHelp() {
                                                   # emission. Exit 0 = ready to \`up\`; exit 1 = the honest worklist.
                                                   # 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] [--root <repo>]
+  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--json] [--root <repo>]
   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] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
+  volter-world down <name> [--grace-ms <ms>] [--purge] [--if-instance <token>] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
                                                                           # --purge: after teardown, delete the instance dir (and per-service twin data) too — see docs/concepts/data-and-keys.md
   volter-world status <name> [--json] [--root <repo>]
   volter-world consumers retire <world> [--consumer <id>] [--root <repo>] [--json]  # resolve attachments whose runner, command and process group are gone
@@ -94,14 +94,15 @@ function printHelp() {
                                                   # fails loudly with the registration recipe. A world that boots
                                                   # the app itself declares an "app" service (type "process") —
                                                   # its URL answers without any registration
-  volter-world log <name> [service...] [--no-follow] [--json] [--requests] [--root <repo>]   # the log of changes (alias: tail)
+  volter-world log <name> [service...] [--no-follow] [--json] [--requests] [--logs] [--root <repo>]   # the log of changes (alias: tail)
                                                   # merged, occurredAt-ordered feed of the twins' action ledgers — one
                                                   # \`HH:MM:SS.mmm <service> <operation> <subjectId>\` line per action;
                                                   # follows until Ctrl-C (--no-follow: dump and exit; --json: raw JSONL;
                                                   # --requests: also merge the request journals — reads/404s,
                                                   # plus WHICH credential arrived in WHICH header/query param, named +
                                                   # fingerprinted, never the value — kept by every twin and link
-                                                  # unless VOLTER_TWIN_REQUEST_JOURNAL=0)
+                                                  # unless VOLTER_TWIN_REQUEST_JOURNAL=0; --logs: also read the services'
+                                                  # process output verbatim, labeled stdout — not shape-only journals)
   volter-world seed <world> [--entry <file>] [--cwd <dir>] [--json] [--root <repo>]
                                                   # pull from the placeholder remote: the seed entry runs with every twin's
                                                   # window open, so the defaults land as observed state (diff empty, nothing pending)
@@ -282,9 +283,18 @@ export async function main() {
         if (graceArg && !(Number(graceArg) >= 0))
             throw new Error(`volter-world down: invalid --grace-ms "${graceArg}" (want a non-negative number)`);
         const purge = rest.includes('--purge');
+        if (rest.some(arg => arg === '--if-created-at' || arg.startsWith('--if-created-at=')))
+            throw new Error('volter-world down: use --if-instance with the token returned by your own boot');
+        // absent flag: no ownership expectation (optionValue's '' fallback would read as an empty, refused token)
+        const ifInstance = rest.some(arg => arg === '--if-instance' || arg.startsWith('--if-instance='));
+        const expectedInstance = ifInstance ? optionValue(rest, '--if-instance') : undefined;
+        if (ifInstance
+            && (!expectedInstance || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(expectedInstance)))
+            throw new Error('volter-world down: invalid --if-instance token');
         const result = await downWorld(subject, root, {
             ...(graceArg ? { graceMs: Number(graceArg) } : {}),
             ...(purge ? { purge: true } : {}),
+            ...(expectedInstance === undefined ? {} : { expectedInstance }),
         });
         process.stdout.write(result.externalErrors.length ? `World ${result.name}: teardown incomplete; lifecycle evidence retained\n`
             : `Stopped world ${result.name}${result.stopped.length ? `: ${result.stopped.join(', ')}` : ''}\n`);
@@ -297,6 +307,8 @@ export async function main() {
                 process.stderr.write(`External teardown failed: ${message}\n`);
         }
         if (result.purged) {
+            for (const message of result.externalAbandoned ?? [])
+                process.stdout.write(`Surrendered unavailable backend record (external stop unverified): ${message}\n`);
             process.stdout.write(`Purged instance data: ${result.purged}\n`);
         }
         else if (purge && result.externalErrors.length) {
@@ -657,6 +669,7 @@ export async function main() {
             follow: !rest.includes('--no-follow'),
             json: rest.includes('--json'),
             requests: rest.includes('--requests'),
+            logs: rest.includes('--logs'),
             signal: controller.signal,
         });
         return;
@@ -664,10 +677,13 @@ export async function main() {
     if (cmd === 'seed' || cmd === 'reset') {
         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;
         const entry = optionValue(rest, '--entry') || undefined;
         const cwd = optionValue(rest, '--cwd') || undefined;
         const json = rest.includes('--json');
-        const outcome = cmd === 'seed' ? await seedWorld(subject, { root, ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) }) : await resetWorld(subject, { root, ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) });
+        const outcome = cmd === 'seed' ? await seedWorld(subject, { root, ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) }) : await resetWorld(subject, { root, ...(envFile ? { envFile } : {}), ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) });
         if (json)
             process.stdout.write(`${JSON.stringify({ world: outcome.world, entry: outcome.entry, exitCode: outcome.exitCode, observed: outcome.observed }, null, 2)}\n`);
         else
@@ -684,7 +700,7 @@ export async function main() {
         const envFile = optionValue(rest, '--env-out') || undefined;
         const { instance, forked } = await branchWorld(subject, name, { root, forceEnvOutput: rest.includes('--force'), ...(envFile ? { envFile } : {}) });
         if (rest.includes('--json'))
-            process.stdout.write(`${JSON.stringify({ name: instance.name, base: subject, forked }, null, 2)}\n`);
+            process.stdout.write(`${JSON.stringify({ name: instance.name, instance: instance.instance, createdAt: instance.createdAt, base: subject, forked }, null, 2)}\n`);
         else {
             process.stdout.write(`Branched world ${name} from ${subject}\n${Object.entries(forked).map(([s, states]) => `  ${s}: mirror forked (${states.join(', ')})`).join('\n')}\n`);
             printReady(instance);
@@ -696,7 +712,7 @@ export async function main() {
             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 }, null, 2)}\n`);
+            process.stdout.write(`${JSON.stringify({ name: instance.name, instance: instance.instance, createdAt: instance.createdAt }, null, 2)}\n`);
         else
             printReady(instance);
         return;
@@ -1109,7 +1125,7 @@ export async function main() {
             throw new Error('volter-world run: missing required --env-out=<path>');
         const name = optionValue(worldArgs, '--name') || undefined;
         const mode = optionValue(worldArgs, '--mode', 'local');
-        const result = await runWorld(subject, rest.slice(split + 1), { root, name, mode, envFile, forceEnvOutput: worldArgs.includes('--force'), owner: ownerOption(worldArgs), keep: worldArgs.includes('--keep'), verbose: worldArgs.includes('--verbose') });
+        const result = await runWorld(subject, rest.slice(split + 1), { root, cwd: process.cwd(), name, mode, envFile, forceEnvOutput: worldArgs.includes('--force'), owner: ownerOption(worldArgs), keep: worldArgs.includes('--keep'), verbose: worldArgs.includes('--verbose') });
         if (result.exitCode !== 0) {
             const detail = result.outcome.error ? `could not start (${result.outcome.error})`
                 : result.outcome.signal ? `was terminated by ${result.outcome.signal}`
@@ -1164,7 +1180,7 @@ export async function main() {
         if (!subject)
             throw new Error('volter-world unshare: missing world name');
         const service = optionValue(rest, '--service') || undefined;
-        const result = unshareWorld(subject, { root, service });
+        const result = await unshareWorld(subject, { root, service });
         process.stdout.write(`Unshared world ${subject}${service ? `/${service}` : ''}\n`);
         if (result.escalated.length)
             process.stdout.write(`Escalated to SIGKILL (tunnel ignored SIGTERM past the grace): ${result.escalated.join(', ')}\n`);

package/dist/src/cli.js

@@ -2,11 +2,12 @@
 // 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 { 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("./cli-commands.js").then(({ main }) => main());
 run.catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.stderr.write(`${errorMessage(error)}\n`);
     process.exit(1);
 });

package/dist/src/command-lifetime.d.mts

@@ -0,0 +1,12 @@
+import type { ChildProcess } from 'node:child_process';
+import type { SpawnIdentity } from './process-receipt.js';
+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): {
+  identity: Promise<SpawnIdentity | undefined>;
+  cancel(signal: NodeJS.Signals): void;
+  readonly forwarded: NodeJS.Signals | undefined;
+  finish(): Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+};

package/dist/src/command-lifetime.d.ts

@@ -1,15 +1 @@
-import type { ChildProcess } from 'node:child_process';
-export declare const COMMAND_GRACE_MS = 5000;
-export declare const commandProcessGroup: boolean;
-export declare 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 declare function commandLifetime(child: ChildProcess, abort?: AbortSignal, preserveOnSuccess?: boolean): {
-    cancel: (value: NodeJS.Signals) => void;
-    readonly forwarded: NodeJS.Signals | undefined;
-    finish(): Promise<{
-        code: number | null;
-        signal: NodeJS.Signals | null;
-    }>;
-};
+export { COMMAND_GRACE_MS, COMMAND_CONFIRM_MS, commandProcessGroup, CommandRetirementError, commandLifetime } from './command-lifetime.mjs';

package/dist/src/command-lifetime.js

@@ -1,98 +1 @@
-import { offSignal } from "./signals.js";
-import { survivingOwnedGroups } from "./process-groups.js";
-export const COMMAND_GRACE_MS = 5_000;
-export const commandProcessGroup = process.platform !== 'win32';
-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) {
-    let forwarded;
-    let code = null;
-    let exitSignal = null;
-    let exited = false;
-    let closed = false;
-    let deadline = 0;
-    let escalated = false;
-    let timer;
-    let resolveFinished;
-    let rejectFinished;
-    const finished = new Promise((resolve, reject) => { resolveFinished = resolve; rejectFinished = reject; });
-    finished.catch(() => { });
-    const signal = (value) => {
-        if (!child.pid)
-            return;
-        try {
-            if (commandProcessGroup)
-                process.kill(-child.pid, value);
-            else
-                child.kill(value);
-        }
-        catch { /* retirement is proved below, never inferred from signal delivery */ }
-    };
-    const alive = () => {
-        if (!child.pid)
-            return false;
-        return survivingOwnedGroups([child.pid]).length > 0;
-    };
-    const detach = () => {
-        if (timer)
-            clearInterval(timer);
-        offSignal('SIGINT', onInt);
-        offSignal('SIGTERM', onTerm);
-        abort?.removeEventListener('abort', onAbort);
-    };
-    const check = () => {
-        if (exited && closed && ((preserveOnSuccess && code === 0 && !forwarded) || !alive())) {
-            detach();
-            resolveFinished();
-            return;
-        }
-        if (deadline && Date.now() >= deadline) {
-            if (!escalated) {
-                escalated = true;
-                signal('SIGKILL');
-                deadline = Date.now() + 1_000;
-            }
-            else {
-                detach();
-                child.stdout?.destroy();
-                child.stderr?.destroy();
-                rejectFinished(new CommandRetirementError('Command retirement could not be confirmed; ownership and cleanup evidence retained'));
-            }
-        }
-    };
-    const watch = () => {
-        if (!deadline)
-            deadline = Date.now() + COMMAND_GRACE_MS;
-        timer ??= setInterval(check, 20);
-        check();
-    };
-    const cancel = (value) => { forwarded ??= value; signal(value); watch(); };
-    const onInt = () => cancel('SIGINT');
-    const onTerm = () => cancel('SIGTERM');
-    const onAbort = () => cancel(abort?.reason === 'SIGINT' ? 'SIGINT' : 'SIGTERM');
-    process.on('SIGINT', onInt);
-    process.on('SIGTERM', onTerm);
-    abort?.addEventListener('abort', onAbort, { once: true });
-    if (abort?.aborted)
-        onAbort();
-    child.once('exit', (value, signalValue) => {
-        code = value;
-        exitSignal = signalValue;
-        exited = true;
-        if (!(preserveOnSuccess && code === 0 && !forwarded))
-            signal('SIGTERM');
-        watch();
-    });
-    child.once('error', () => { if (!child.pid) {
-        exited = true;
-        watch();
-    } });
-    child.once('close', () => { closed = true; check(); });
-    return {
-        cancel,
-        get forwarded() { return forwarded; },
-        async finish() { await finished; return { code, signal: exitSignal }; },
-    };
-}
+export { COMMAND_GRACE_MS, COMMAND_CONFIRM_MS, commandProcessGroup, CommandRetirementError, commandLifetime } from './command-lifetime.mjs';

package/dist/src/command-lifetime.mjs

@@ -0,0 +1,90 @@
+import { offSignal } from './signals.mjs';
+import { survivingOwnedGroups } from './process-groups.mjs';
+import { childIdentity, signalOwnedProcess, signalChild } from './process-signal.mjs';
+
+export const COMMAND_GRACE_MS = 5_000;
+export const COMMAND_CONFIRM_MS = 1_000;
+export const commandProcessGroup = process.platform !== 'win32';
+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) {
+  const identity = child.pid && commandProcessGroup ? childIdentity(child) : Promise.resolve(undefined);
+  let signalFailure;
+  let pendingSignals = 0;
+  let forwarded;
+  let code = null;
+  let exitSignal = null;
+  let exited = false;
+  let closed = false;
+  let deadline = 0;
+  let escalated = false;
+  let timer;
+  let resolveFinished;
+  let rejectFinished;
+  const finished = new Promise((resolve, reject) => { resolveFinished = resolve; rejectFinished = reject; });
+  finished.catch(() => {});
+  const signal = (value) => {
+    if (!child.pid) return;
+    try {
+      if (signalChild(child, value, commandProcessGroup)) return;
+      if (!commandProcessGroup || !alive()) return;
+      // The leader has exited: this is now retained numeric group ownership.
+      pendingSignals++;
+      void identity.then(birth => signalOwnedProcess(birth, value, true))
+        .catch(error => { signalFailure = error; })
+        .finally(() => { pendingSignals--; check(); });
+    } catch (error) { signalFailure = error; }
+  };
+  const alive = () => {
+    if (!child.pid) return false;
+    return survivingOwnedGroups([child.pid]).length > 0;
+  };
+  const detach = () => {
+    if (timer) clearInterval(timer);
+    offSignal('SIGINT', onInt);
+    offSignal('SIGTERM', onTerm);
+    abort?.removeEventListener('abort', onAbort);
+  };
+  const check = () => {
+    if (pendingSignals) return;
+    if (exited && closed && ((preserveOnSuccess && code === 0 && !forwarded) || !alive())) {
+      detach(); resolveFinished(); return;
+    }
+    if (deadline && Date.now() >= deadline) {
+      if (!escalated) { escalated = true; signal('SIGKILL'); deadline = Date.now() + COMMAND_CONFIRM_MS; }
+      else {
+        detach();
+        child.stdout?.destroy(); child.stderr?.destroy();
+        rejectFinished(new CommandRetirementError('Command retirement could not be confirmed; ownership and cleanup evidence retained', { cause: signalFailure }));
+      }
+    }
+  };
+  const watch = () => {
+    if (!deadline) deadline = Date.now() + COMMAND_GRACE_MS;
+    timer ??= setInterval(check, 20);
+    check();
+  };
+  const cancel = (value) => { forwarded ??= value; signal(value); watch(); };
+  const onInt = () => cancel('SIGINT');
+  const onTerm = () => cancel('SIGTERM');
+  const onAbort = () => cancel(abort?.reason === 'SIGINT' ? 'SIGINT' : 'SIGTERM');
+  process.on('SIGINT', onInt);
+  process.on('SIGTERM', onTerm);
+  abort?.addEventListener('abort', onAbort, { once: true });
+  if (abort?.aborted) onAbort();
+  child.once('exit', (value, signalValue) => {
+    code = value; exitSignal = signalValue; exited = true;
+    if (!(preserveOnSuccess && code === 0 && !forwarded)) signal('SIGTERM');
+    watch();
+  });
+  child.once('error', () => { if (!child.pid) { exited = true; watch(); } });
+  child.once('close', () => { closed = true; check(); });
+  return {
+    identity,
+    cancel,
+    get forwarded() { return forwarded; },
+    async finish() { await finished; await identity; return { code, signal: exitSignal }; },
+  };
+}

package/dist/src/configs.js

@@ -29,7 +29,7 @@ export function writeWorldConfig(path, config) {
     getActiveWorldStore().write(path, `${JSON.stringify(document, null, 2)}\n`);
 }
 const LEGACY_TOP_LEVEL = new Set(['id', 'description', 'bare', 'remotes', 'resources', 'isolation', 'env', 'stripEnv', 'services', 'share', 'actors', 'fixtures', 'catalog', 'network']);
-const LEGACY_SERVICE = new Set(['id', 'type', 'package', 'command', 'args', 'cwd', 'port', 'portReason', 'env', 'controlPlane', 'injectEnv', 'injectEnvTemplates', 'root', 'rootArg', 'portArg', 'cliRedirect', 'ready', 'preload', 'external', 'colocate', 'version']);
+const LEGACY_SERVICE = new Set(['id', 'type', 'package', 'command', 'args', 'cwd', 'port', 'portReason', 'env', 'controlPlane', 'branchState', 'injectEnv', 'injectEnvTemplates', 'root', 'rootArg', 'portArg', 'cliRedirect', 'ready', 'preload', 'external', 'colocate', 'version']);
 const LEGACY_NESTED = {
     bare: new Set(['name']), resources: new Set(['memoryMiB', 'writableStorageMiB']), catalog: new Set(['sha', 'protocol']),
     root: new Set(['url', 'deploy', 'refresh', 'scope']), refresh: new Set(['every', 'webhook']),

package/dist/src/console-apart.js

@@ -4,6 +4,7 @@
 // console on a listener of its own: the console's shell and bundle, and the host's `/-/` doors
 // forwarded to the host — never a twin's path, so no twin-served script ever runs on this origin.
 // The console opens a World's pages (a vendor's screens) on the Worlds' origin, which it is told.
+import { errorMessage } from "./error-message.js";
 import { serveHttp } from '@volter/world-core/runtime';
 export const CONSOLE_BASE = '/-/console';
 /** Serve `mount` on its own listener; doors under `/-/` go to `upstream` (the Worlds' origin). */
@@ -62,8 +63,8 @@ export async function serveConsoleFor(target, opts = {}) {
         mount = (await import('@volter/world-console')).createConsole();
     }
     catch (error) {
-        if (error instanceof Error && /Cannot find (module|package)/.test(error.message))
-            throw new Error('the console is not installed: add @volter/world-console beside @volter/world');
+        if (error instanceof Error && /Cannot find (module|package)/.test(errorMessage(error)))
+            throw new Error('the console is not installed: add @volter/world-console beside @volter/world', { cause: error });
         throw error;
     }
     const hostname = opts.hostname ?? '127.0.0.1';

package/dist/src/covers.d.ts

@@ -1,4 +1,4 @@
-import { type WorldSelection, type WorldUsage } from './schema.js';
+import { type WorldSelection, type WorldServiceConfig, type WorldServiceInstance, type WorldUsage } from './schema.js';
 export type CoverageStatus = 'covered' | 'missing' | 'uninterceptable' | 'unknown-sdk' | 'acknowledged' | 'excluded';
 export type CoverageRow = {
     /** vendor key for mapped vendors; the raw dep/env name for unknown-sdk rows */
@@ -118,6 +118,7 @@ export type WorldTwinId = {
     interceptable: boolean;
 };
 type WorldTwinInventory = {
+    services: Array<WorldServiceConfig | WorldServiceInstance>;
     source: 'instance' | 'config';
     path: string;
     /** normalized identifier → id record (e.g. 'stripe' → { label: 'stripe (service)', … }) */
@@ -177,7 +178,7 @@ export type RepoVendorSignals = {
  * 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): RepoVendorSignals;
+export declare function detectRepoVendors(repoPath: string, services?: Array<WorldServiceConfig | WorldServiceInstance>): RepoVendorSignals;
 export declare function coverWorld(world: string, repoPath: string, options?: CoverageOptions): CoverageReport;
 export declare function formatCoverageReport(report: CoverageReport): string;
 export {};

package/dist/src/covers.js

@@ -21,11 +21,13 @@
 //             coverage. An external-service-shaped dep/env var with no vendor mapping →
 //             unknown-sdk → exit 1 by default (`--allow-unknown` downgrades to a warning:
 //             unknowns still print, but stop failing the proof).
+import { errorMessage } from "./error-message.js";
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { vendorOfPackModule } from '@volter/world-core/runtime';
 import { loadWorldConfig } from "./configs.js";
+import { VENDOR_SERVER_BACKINGS } from "./backings.js";
 import { injectableVendorKeys, loadInject, twinUrlVendorFor } from "./inject-map.js";
 import { connectionProtocol, projectConnections, projectDependencies, projectManifestDirs, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from "./project-inspect.js";
 import { overlayCoversMaps, packFacts } from "./pack-facts.js";
@@ -247,16 +249,54 @@ export function registryAcknowledgedReason(name) {
         return null;
     return entries[0].reason;
 }
-function declaredTwin(services) {
+/** Identity comes from the registered wrapper, not an arbitrary process with the vendor's name. */
+function serverBacking(service) {
+    const backing = VENDOR_SERVER_BACKINGS[service.id];
+    if (!backing || service.type !== backing.service.type)
+        return undefined;
+    // an instance records the whole argv in `command`; a config splits it into `command` and `args`
+    const command = Array.isArray(service.command) ? service.command : [service.command, ...(('args' in service ? service.args : undefined) ?? [])];
+    if (!command[0] || basename(command[0]) !== backing.service.command || command[1] !== backing.service.args?.[0])
+        return undefined;
+    return backing;
+}
+function addBackingIds(ids, services, effectiveEnv) {
+    for (const service of services) {
+        const backing = serverBacking(service);
+        if (backing) {
+            const template = backing.facts.endpointEnv.templates[backing.facts.endpointEnv.name];
+            const instance = 'pid' in service;
+            const values = instance ? service.env : service.injectEnvTemplates ?? {};
+            const endpoint = instance && service.url && service.port ? template?.replaceAll('${host}', new URL(service.url).hostname)
+                .replaceAll('${port}', String(service.port)).replaceAll('${url}', service.url) : undefined;
+            const routed = template !== undefined && (instance
+                ? endpoint !== undefined && Object.entries(values).some(([name, value]) => value === endpoint && effectiveEnv?.[name] === value)
+                : service.port !== undefined && Object.values(values).includes(template));
+            addId(ids, normalizeId(service.id), `${service.id} (server backing)`, routed);
+        }
+        // A protocol already proved owned by this service can satisfy its declared native driver.
+        // HTTP-only siblings of the same vendor retain their independent interface obligations.
+        for (const binding of serviceConnections([service], effectiveEnv).values()) {
+            for (const [vendor, facts] of Object.entries(packFacts())) {
+                if (facts.transport === 'raw-tcp' && facts.managedService?.scheme === binding.protocol) {
+                    addId(ids, normalizeId(vendor), `${binding.label}; managed ${facts.managedService.kind} backing`, true);
+                }
+            }
+        }
+    }
+}
+function declaredTwin(services, effectiveEnv) {
     const declared = new Map();
     for (const service of services) {
-        if (service.type !== undefined && service.type !== 'twin')
+        if (service.type !== undefined && service.type !== 'twin' && !serverBacking(service))
             continue;
         const config = service;
         const identity = config.package?.match(/^@volter\/twin-(.+)$/)?.[1] ?? servicePackNames(config)[0] ?? service.id;
         const vendor = Object.keys(packFacts()).find((candidate) => worldIdsFor(candidate).includes(normalizeId(identity))) ?? identity;
         const ids = new Map();
-        addServiceIds(ids, service);
+        if (!serverBacking(service))
+            addServiceIds(ids, service);
+        addBackingIds(ids, [service], effectiveEnv);
         const match = [...worldIdsFor(vendor), vendor].map(normalizeId).map((id) => ids.get(id)).find(Boolean);
         declared.set(vendor, match ?? { label: `${service.id} (declared twin)`, interceptable: false });
     }
@@ -278,7 +318,16 @@ function servicePackNames(service) {
         ...(service.args ?? []),
         ...(service.colocate?.module ? [service.colocate.module] : []),
     ];
-    return commandParts.flatMap((part) => {
+    return commandParts.flatMap((argument, index) => {
+        // A shared host command is recorded on each service. Only that service's
+        // module identifies its pack; its neighbours' modules must not cover it.
+        let part = argument;
+        if (commandParts[index - 1] === '--spec') {
+            const [id, module] = argument.split('|');
+            if (id !== service.id || !module)
+                return [];
+            part = module;
+        }
         const fromPath = part.match(/(?:^|[/\\])twin-packs-p[23][/\\]([a-z0-9-]+)[/\\]/);
         const fromBin = part.match(/^world-([a-z0-9-]+)$/);
         const fromPkg = part.match(/(?:^|[/\\])@volter\/twin-([a-z0-9-]+)(?:[/\\]|$)/);
@@ -400,23 +449,27 @@ export function worldTwinInventory(world, root) {
         const status = statusWorld(world, root, { readOnly: true });
         const ids = new Map();
         for (const service of Object.values(status.services))
-            addServiceIds(ids, service);
+            if (!serverBacking(service))
+                addServiceIds(ids, service);
+        addBackingIds(ids, Object.values(status.services), status.env);
         for (const key of Object.keys(status.env)) {
             const stem = key.match(/^(.+)_TWIN_URL$/);
             // a bare env `*_TWIN_URL` var is only a REACHABLE twin when the injector reads it
             if (stem)
                 addId(ids, normalizeId(stem[1]), `env ${key}`, twinUrlVendorFor(key) !== null);
         }
-        return { source: 'instance', path: `${status.dirs.instance}/instance.json`, ids, connections: serviceConnections(Object.values(status.services), status.env), selection: status.selection, declared: declaredTwin(Object.values(status.services)) };
+        return { services: Object.values(status.services), source: 'instance', path: `${status.dirs.instance}/instance.json`, ids, connections: serviceConnections(Object.values(status.services), status.env), selection: status.selection, declared: declaredTwin(Object.values(status.services), status.env) };
     }
     catch (error) {
-        instanceError = error instanceof Error ? error.message : String(error);
+        instanceError = errorMessage(error);
     }
     try {
         const { path, config } = loadWorldConfig(world, root);
         const ids = new Map();
         for (const service of config.services)
-            addServiceIds(ids, service);
+            if (!serverBacking(service))
+                addServiceIds(ids, service);
+        addBackingIds(ids, config.services);
         const connections = serviceConnections(config.services);
         // a name the World's env leaves to a twin's credential door (`$issue:<service>`) is that twin's, whatever scheme the
         // issued value has: the twin that issues it serves it
@@ -424,10 +477,10 @@ export function worldTwinInventory(world, root) {
             if (value.startsWith(ISSUE_ENV_PREFIX))
                 connections.set(name, { protocol: 'issued', label: `${value.slice(ISSUE_ENV_PREFIX.length)} (${name}; issued)` });
         }
-        return { source: 'config', path, ids, connections, selection: config.selection, declared: declaredTwin(config.services) };
+        return { services: config.services, source: 'config', path, ids, connections, selection: config.selection, declared: declaredTwin(config.services) };
     }
     catch (error) {
-        const configError = error instanceof Error ? error.message : String(error);
+        const configError = errorMessage(error);
         throw new Error(`volter-world covers: world "${world}" not found as an instance or a config.\n` +
             `  instance: ${instanceError}\n  config: ${configError}`);
     }
@@ -464,7 +517,16 @@ function usesOf(signals) {
  * 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) {
+export function detectRepoVendors(repoPath, services = []) {
+    // Application aliases are names the selected backing actually injects, never global vendor adoption.
+    const backingEnvVendors = new Map();
+    for (const service of services) {
+        if (!serverBacking(service))
+            continue;
+        const bindings = 'pid' in service ? service.env : service.injectEnvTemplates;
+        for (const name of Object.keys(bindings ?? {}))
+            backingEnvVendors.set(name, service.id);
+    }
     const repo = resolve(repoPath);
     // the platform's own packages — the twins an app installed, the command, the runtime — are
     // never a vendor signal: an app that installed @volter/twin-slack did not gain a Slack dependency.
@@ -512,7 +574,7 @@ export function detectRepoVendors(repoPath) {
             detected.set('smtp', [...(detected.get('smtp') ?? []), `env: ${name}`]);
             continue;
         }
-        const vendor = envStemVendor(name, ENV_SUFFIX_BROAD);
+        const vendor = backingEnvVendors.get(name) ?? envStemVendor(name, ENV_SUFFIX_BROAD);
         if (vendor)
             detected.set(vendor, [...(detected.get(vendor) ?? []), `env: ${name}`]);
     }
@@ -535,6 +597,9 @@ export function detectRepoVendors(repoPath) {
         ...Object.values(SDK_TWINS).map((entry) => entry.vendor),
         ...Object.values(ENV_STEM_VENDORS),
         ...Object.keys(VENDOR_WORLD_IDS),
+        // a pack whose vendor is called only by its hosts (no SDK, no credential: Poly Haven's and ambientCG's public
+        // catalogs) is known by its descriptor's hosts, or a raw fetch matched to it would be dropped here
+        ...Object.entries(packFacts()).filter(([, facts]) => (facts.hosts ?? []).length).map(([vendor]) => vendor),
     ])
         knownVendorById.set(normalizeId(vendor), vendor);
     const canonicalVendor = (injectorKey) => {
@@ -632,7 +697,7 @@ export function detectRepoVendors(repoPath) {
         if (isSmtpEnvSignal(name))
             continue; // now a DETECTED vendor (above), no longer an unknown
         const stem = envVendorStem(name, ENV_SUFFIX_STRICT);
-        if (stem === null || envStemVendor(name, ENV_SUFFIX_STRICT) || ENV_STEM_IGNORE.has(stem))
+        if (stem === null || backingEnvVendors.has(name) || envStemVendor(name, ENV_SUFFIX_STRICT) || ENV_STEM_IGNORE.has(stem))
             continue;
         // The registry's notExternal suppressions apply to ENV STEMS too — the census adjudicated
         // 40 app-internal stems ("names no vendor") that this loop kept flagging because only the
@@ -654,7 +719,7 @@ export function coverWorld(world, repoPath, options = {}) {
     }
     const repo = resolve(repoPath);
     const inventory = worldTwinInventory(world, root);
-    const { detected, unknown: unknownSources, uses, unknownUses } = detectRepoVendors(repo);
+    const { detected, unknown: unknownSources, uses, unknownUses } = detectRepoVendors(repo, inventory.services);
     // 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
     // wiring is merely wrong (fix it, don't acknowledge it); no key at all means the pack is a
@@ -678,7 +743,14 @@ export function coverWorld(world, repoPath, options = {}) {
         // twin (no injector vendor, no app-read endpoint env) is a distinct, failing status.
         const candidates = worldIdsFor(vendor).filter((id) => inventory.ids.has(id));
         const matchId = candidates.find((id) => inventory.ids.get(id).interceptable) ?? candidates[0];
-        const match = matchId === undefined ? null : inventory.ids.get(matchId);
+        const managed = packFacts()[vendor]?.managedService;
+        // Only a booted, service-owned endpoint establishes a managed pack's reachable wire.
+        const managedBinding = inventory.source === 'instance' && managed
+            ? [...inventory.connections.values()].find(binding => binding.protocol === managed.scheme)
+            : undefined;
+        const match = matchId === undefined
+            ? managedBinding ? { label: managedBinding.label, interceptable: true } : null
+            : inventory.ids.get(matchId);
         let status = match === null ? 'missing' : match.interceptable ? 'covered' : 'uninterceptable';
         let ackRefused;
         if (acknowledge[vendor] !== undefined) {
@@ -755,9 +827,14 @@ export function coverWorld(world, repoPath, options = {}) {
             uninterceptable.push(vendor);
         rows.push({ vendor, detectedVia: ['declared in world'], twinInWorld: declared.label, status });
     }
-    for (const requirement of projectConnections(repo, new Set([...detected.values(), ...unknownSources.values()].flat().filter((source) => source.startsWith('env: ')).map((source) => source.slice(5))))) {
+    for (const requirement of projectConnections(repo, new Set([...detected.values(), ...unknownSources.values()].flat().filter((source) => source.startsWith('env: ')).map((source) => source.slice(5))), new Map([...inventory.connections].flatMap(([name, binding]) => binding.protocol && !['http', 'issued', 'incompatible'].includes(binding.protocol) ? [[name, binding.protocol]] : [])))) {
         const vendor = `${requirement.protocol ?? 'unknown-connection'}:${requirement.env ?? requirement.sources[0]}`;
-        if (inventory.selection !== undefined && !worldSelectionIncludes(inventory.selection, vendor, 'application')) {
+        const connectionNames = [vendor, ...(requirement.protocol ? [requirement.protocol] : [])];
+        const selectorMatches = (selector) => (selector.usage === undefined || selector.usage === 'application') &&
+            (selector.vendor === undefined || connectionNames.includes(selector.vendor));
+        const connectionSelected = inventory.selection === undefined ||
+            (inventory.selection.include.some(selectorMatches) && !inventory.selection.exclude.some(selectorMatches));
+        if (!connectionSelected) {
             excluded.push(vendor);
             rows.push({
                 vendor,

package/dist/src/error-message.d.mts

@@ -0,0 +1 @@
+export function errorMessage(error: unknown): string;

package/dist/src/error-message.d.ts

@@ -0,0 +1 @@
+export { errorMessage } from './error-message.mjs';

package/dist/src/error-message.js

@@ -0,0 +1,2 @@
+// The native Node hosts and typed runtime entrypoints use the same renderer.
+export { errorMessage } from './error-message.mjs';