@volter/world-runtime 3.0.166 → 3.0.167

package/src/schema.ts

@@ -1,4 +1,5 @@
 import { errorMessage } from './error-message.ts';
+import { isScalarCredentialField } from './credential-door.ts';
 import { normalizeWorldNetwork, type WorldNetwork } from '@volter/world-core/network-policy';
 
 export type WorldServiceType = 'twin' | 'process' | 'external';
@@ -172,7 +173,7 @@ export type WorldServiceConfig = {
   /** The credential this twin issues the World's applications at boot (its pack's `credentialDoor`, copied by `init`):
    *  `up` POSTs `body` to `path` on the running twin and sets each name of `fill` whose value is `$issue:<this id>` to
    *  the answer's field `fill` names for it. */
-  issues?: { path: string; body: Record<string, unknown>; fill: Record<string, string> };
+  issues?: { path: string; body: Record<string, unknown>; fill: Record<string, string>; required?: string[] };
   /**
    * The twin PACKAGE this service boots from (`@volter/twin-<vendor>`), resolved from the world
    * root at boot by node's own `node_modules` walk (docs/concepts/worlds.md#the-config-and-the-running-world).
@@ -458,6 +459,9 @@ export type WorldInstance = {
   };
   services: Record<string, WorldServiceInstance>;
   env: Record<string, string>;
+  /** Required owners fixed at this boot; the digest binds their actual scalar responses in env without duplicating values.
+   * Omitted digest means issuance has not finished. Absent metadata is readable for cleanup, but not a live application declaration. */
+  requiredCredentials?: { version: 1; owners: Record<string, string>; valuesSha256?: string };
   /** Always written at boot; optional only so cleanup can read incomplete legacy records. */
   networkCeiling?: WorldNetwork | 'unrestricted';
   bootServices?: string[];
@@ -632,7 +636,7 @@ function assertLegacyWorldConfig(value: unknown, path: string): WorldConfig {
     if (service.branchState !== undefined && service.branchState !== 'unsupported') throw new Error(`Service ${service.id} branchState must be unsupported in ${path}`);
     const exports = [service.injectEnv, ...Object.keys(service.injectEnvTemplates ?? {}), ...Object.keys(service.cliRedirect ?? {}), ...(Array.isArray(service.external?.discover) ? service.external.discover.map(entry => entry?.as) : [])];
     if (exports.some(name => name !== undefined && !isEnvironmentName(name))) throw new Error(`Service ${service.id} bindings must name environment variables in ${path}`);
-    if (service.issues !== undefined && (!record(service.issues) || typeof service.issues.path !== 'string' || !record(service.issues.body) || !environmentMap(service.issues.fill))) throw new Error(`Service ${service.id} issues must define path, body and string→string fill in ${path}`);
+    if (service.issues !== undefined) readCredentialDoor(service.issues, service.id, path);
     if (service.env?.VOLTER_WORLD_NETWORK_POLICY !== undefined || exports.includes('VOLTER_WORLD_NETWORK_POLICY')) throw new Error(`Service ${service.id} cannot replace World network permission in ${path}`);
     if (!/^[a-z0-9][a-z0-9._-]*$/.test(service.id)) throw new Error(`Invalid service id "${service.id}" in ${path}`);
     if (ids.has(service.id)) throw new Error(`Duplicate service id "${service.id}" in ${path}`);
@@ -762,6 +766,7 @@ function assertLegacyWorldConfig(value: unknown, path: string): WorldConfig {
       }
     }
   }
+  assertRequiredCredentialBindings(config as WorldConfig, path);
   return config as WorldConfig;
 }
 
@@ -774,6 +779,67 @@ function assertKeys(value: Record<string, unknown>, allowed: string[], what: str
   if (unexpected.length) throw new Error(`${what} has unknown field(s) ${unexpected.join(', ')} in ${path}`);
 }
 
+/** Credential metadata is read completely before normalization or serialization can discard a field. */
+function readCredentialDoor(value: unknown, service: string, path: string): NonNullable<WorldServiceConfig['issues']> {
+  const what = `Service ${service} issues`;
+  if (!record(value)) throw new Error(`${what} must be an object in ${path}`);
+  assertKeys(value, ['path', 'body', 'fill', 'required'], what, path);
+  if (!Object.hasOwn(value, 'path') || typeof value.path !== 'string' || value.path === ''
+    || !Object.hasOwn(value, 'body') || !record(value.body)
+    || !Object.hasOwn(value, 'fill') || !record(value.fill)) {
+    throw new Error(`${what} must define non-empty path, object body and string→string fill in ${path}`);
+  }
+  const fill: Array<[string, string]> = [];
+  for (const [name, field] of Object.entries(value.fill)) {
+    if (!isEnvironmentName(name) || typeof field !== 'string') throw new Error(`${what} fill must map environment names to strings in ${path}`);
+    fill.push([name, field]);
+  }
+  const required: string[] = [];
+  if (Object.hasOwn(value, 'required')) {
+    if (!Array.isArray(value.required)) throw new Error(`${what} required must be an array in ${path}`);
+    const seen = new Set<string>();
+    for (const name of value.required) {
+      if (!isEnvironmentName(name) || seen.has(name)) throw new Error(`${what} required must contain unique environment names in ${path}`);
+      const field = value.fill[name];
+      if (!Object.hasOwn(value.fill, name) || typeof field !== 'string' || !isScalarCredentialField(field)) {
+        throw new Error(`${what} required ${name} must name its direct scalar fill in ${path}`);
+      }
+      seen.add(name); required.push(name);
+    }
+  }
+  return { path: value.path, body: value.body, fill: Object.fromEntries(fill),
+    ...(Object.hasOwn(value, 'required') ? { required } : {}) };
+}
+
+/** Required names belong to one twin's exact pending reference, with no competing output or local override. */
+export function assertRequiredCredentialBindings(config: WorldConfig, path: string): void {
+  const owners = new Map<string, string>();
+  for (const service of config.services) {
+    if (service.issues === undefined) continue;
+    const door = readCredentialDoor(service.issues, service.id, path);
+    if (door.required !== undefined && (service.type ?? 'twin') !== 'twin') {
+      throw new Error(`Service ${service.id} required credential bindings belong to a twin in ${path}`);
+    }
+    for (const name of door.required ?? []) {
+      if (owners.has(name)) throw new Error(`Required credential ${name} has competing issuers in ${path}`);
+      if (!Object.hasOwn(config.env ?? {}, name) || config.env?.[name] !== `${ISSUE_ENV_PREFIX}${service.id}`) {
+        throw new Error(`Required credential ${name} must be exactly ${ISSUE_ENV_PREFIX}${service.id} in ${path}`);
+      }
+      owners.set(name, service.id);
+    }
+  }
+  for (const service of config.services) {
+    const endpoints = new Set([service.injectEnv, ...Object.keys(service.injectEnvTemplates ?? {}),
+      ...Object.keys(service.cliRedirect ?? {}), ...(service.external?.discover ?? []).map(entry => entry.as)]);
+    for (const [name, owner] of owners) {
+      if (endpoints.has(name) || Object.hasOwn(service.env ?? {}, name)
+        || (service.id !== owner && Object.hasOwn(service.issues?.fill ?? {}, name))) {
+        throw new Error(`Required credential ${name} owned by ${owner} conflicts with service ${service.id} in ${path}`);
+      }
+    }
+  }
+}
+
 export const DEFAULT_WORLD_SELECTION: WorldSelection = {
   include: [{ usage: 'application' }],
   exclude: [],
@@ -810,7 +876,7 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
   assertKeys(source, ['package', 'version'], 'service.source', path);
   assertKeys(execution, ['process', 'colocate', 'lifecycle', 'cwd', 'environment', 'preload', 'controlPlane', 'branchState'], 'service.execution', path);
   assertKeys(endpoint, ['port', 'portReason', 'ready'], 'service.endpoint', path);
-  assertKeys(bindings, ['injectEnv', 'injectEnvTemplates', 'cliRedirect', 'discover'], 'service.bindings', path);
+  assertKeys(bindings, ['injectEnv', 'injectEnvTemplates', 'cliRedirect', 'discover', 'issues'], 'service.bindings', path);
   const process = execution.process === undefined ? {} : execution.process;
   const environment = execution.environment === undefined ? {} : execution.environment;
   if (!record(process) || !record(environment)) throw new Error(`Service execution process/environment must be objects in ${path}`);
@@ -867,6 +933,7 @@ function serviceV2ToLegacy(value: unknown, path: string): WorldServiceConfig {
     ...(bindings.injectEnv === undefined ? {} : { injectEnv: bindings.injectEnv as string }),
     ...(bindings.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: bindings.injectEnvTemplates as Record<string, string> }),
     ...(bindings.cliRedirect === undefined ? {} : { cliRedirect: bindings.cliRedirect as Record<string, string> }),
+    ...(!Object.hasOwn(bindings, 'issues') ? {} : { issues: readCredentialDoor(bindings.issues, value.id, path) }),
     ...(value.root === undefined ? {} : { root: value.root as WorldServiceConfig['root'] }),
     ...(external === undefined ? {} : { external }),
   };
@@ -984,6 +1051,7 @@ export function assertWorldConfig(value: unknown, path: string): WorldConfig {
     return normalizeV2(value, path);
   }
   const legacy = assertLegacyWorldConfig(value, path);
+  if (legacy.services.some(service => service.issues?.required !== undefined)) throw new Error(`Required credential bindings require a format-2 World manifest in ${path}`);
   return { ...legacy, manifestVersion: 1 };
 }
 
@@ -1021,6 +1089,7 @@ function serviceToV2(service: WorldServiceConfig): Record<string, unknown> {
     ...(service.ready === undefined ? {} : { ready: service.ready }),
   };
   const bindings = {
+    ...(service.issues === undefined ? {} : { issues: readCredentialDoor(service.issues, service.id, 'World serialization') }),
     ...(service.injectEnv === undefined ? {} : { injectEnv: service.injectEnv }),
     ...(service.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: service.injectEnvTemplates }),
     ...(service.cliRedirect === undefined ? {} : { cliRedirect: service.cliRedirect }),
@@ -1044,6 +1113,7 @@ function serviceToV2(service: WorldServiceConfig): Record<string, unknown> {
 
 /** Serialize normalized intent as the committed format-2 manifest. */
 export function worldConfigDocument(config: WorldConfig, selection: WorldSelection = config.selection ?? DEFAULT_WORLD_SELECTION): WorldManifestV2 & Record<string, unknown> {
+  assertLegacyWorldConfig({ ...config, manifestVersion: 2 }, 'World serialization');
   return {
     schemaVersion: WORLD_SCHEMA_VERSION,
     metadata: { id: config.id, ...(config.description === undefined ? {} : { description: config.description }) },

package/src/serve.ts

@@ -8,7 +8,8 @@
 import { timingSafeEqual } from 'node:crypto';
 import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
 import { deriveWorldManifest, type WorldManifest } from './attach.ts';
-import { statusWorld } from './runtime.ts';
+import { refuseRequiredCredentialTransport, statusWorld } from './runtime.ts';
+import { errorMessage } from './error-message.ts';
 import { worldAttachmentNetworkEnv, worldStrictEgress } from '@volter/world-core/network-policy';
 
 export const MANIFEST_PATH = '/.well-known/volter-world';
@@ -16,7 +17,9 @@ export const MANIFEST_PATH = '/.well-known/volter-world';
 /** The manifest a REMOTE attacher sees: every vendor behind the one advertised
  * door. The serving side keeps routing against its own loopback env. */
 export function advertiseWorldManifest(name: string, root: string, advertisedOrigin: string): WorldManifest {
-  const local = deriveWorldManifest(name, statusWorld(name, root).env);
+  const status = statusWorld(name, root);
+  refuseRequiredCredentialTransport(status, 'remote WorldManifest publication');
+  const local = deriveWorldManifest(name, status.env);
   const vendors: Record<string, string> = {};
   // /__vendor/<id> keeps the fetch flow routable through the one door (the
   // injector's fetch patch rewrites URLs wholesale and loses the vendor Host);
@@ -57,8 +60,15 @@ export async function startManifestServer(options: ManifestServerOptions): Promi
       response.end('volter-world: GET ' + MANIFEST_PATH + '\n');
       return;
     }
+    let body: string;
+    try { body = `${JSON.stringify(options.manifest(), null, 2)}\n`; }
+    catch (error) {
+      response.writeHead(503, { 'content-type': 'text/plain' });
+      response.end(`World manifest unavailable: ${errorMessage(error)}\n`);
+      return;
+    }
     response.writeHead(200, { 'content-type': 'application/json' });
-    response.end(`${JSON.stringify(options.manifest(), null, 2)}\n`);
+    response.end(body);
   });
   await new Promise<void>((resolveListen, reject) => {
     server.once('error', reject);
@@ -81,18 +91,26 @@ export async function fetchRemoteManifest(ref: string, options: { token?: string
   const response = await fetch(url, options.token === undefined ? undefined : { headers: { authorization: `Bearer ${options.token}` } });
   if (!response.ok) throw new Error(`remote world manifest: ${url} → ${response.status}`);
   const manifest = (await response.json()) as WorldManifest;
-  if (typeof manifest.name !== 'string' || typeof manifest.vendors !== 'object' || manifest.vendors === null) {
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)
+    || typeof manifest.name !== 'string' || typeof manifest.vendors !== 'object' || manifest.vendors === null) {
     throw new Error(`remote world manifest: ${url} returned no manifest`);
   }
+  refuseRequiredRemoteManifest(manifest);
   return manifest;
 }
 
+/** Required credentials have no approved remote transport; their field must never be silently ignored. */
+function refuseRequiredRemoteManifest(manifest: WorldManifest): void {
+  if (Object.hasOwn(manifest, 'requiredCredentials')) throw new Error('Remote WorldManifest required credential transport is unsupported; refusing attachment');
+}
+
 /** The env a remote env-attachment exports: vendor twin URLs (the advertised
  * door), suggested fake credentials, CA trust, and the injector preload. */
 export function remoteAttachEnv(
   manifest: WorldManifest,
   options: { caFile?: string; injectPath: string; worldRef?: string; callerEnv?: Readonly<Record<string, string | undefined>> },
 ): Record<string, string> {
+  refuseRequiredRemoteManifest(manifest);
   const env: Record<string, string> = { ...manifest.env,
     ...worldAttachmentNetworkEnv(options.worldRef ?? manifest.name, manifest.network, options.callerEnv ?? process.env, worldStrictEgress(manifest.env)),
   };

package/src/served-world.ts

@@ -53,6 +53,7 @@ import { describeActionFields, resourceBlobFile } from '@volter/world-core/runti
 import { worldLedgers } from './changeset.ts';
 import { clockFile, downWorld, instanceDir, isWorldOrigin, listWorlds, readWorldBootRecord, statusWorld, upWorld } from './runtime.ts';
 import { assertChangesetRules, type WorldChangesetRules, type WorldInstance } from './schema.ts';
+import { forwardableHeaders } from './forwardable-headers.ts';
 
 export const TOKEN_HEADER = 'x-volter-token';
 /** The header the injector carries a hosted World's token in (inject.cjs, VOLTER_TWINS_KEY). */
@@ -194,7 +195,7 @@ function configRefFor(worldRoot: string, name: string): string {
 /** A world mounted by a host. `token`/`readToken` read the CURRENT tokens (rotate changes them);
  *  `twins()` names the world's twins once booted; `rotate()` mints both tokens anew — the old die
  *  with the call — and keeps them beside the world like `boot` does. */
-export type MountedWorld = { maxRequestBodySize: number; name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; /** the same site at its local address, its framed pages carrying the board's picture script (localSite) */ localSite: (request: Request, host: string) => Promise<Response>; /** WorldDoors.pagesPass */ pagesPass: (scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => string | null; branchBoard: (frame?: string) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
+export type MountedWorld = { maxRequestBodySize: number; name: string; served: string; root: string; readonly token: string; readonly readToken: string; /** whether its boot has finished: until then its twins are not known */ ready: () => boolean; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; /** the same site at its local address, its framed pages carrying the board's picture script (localSite) */ localSite: (request: Request, host: string) => Promise<Response>; /** WorldDoors.pagesPass */ pagesPass: (scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => string | null; branchBoard: (frame?: string) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
 /** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
 /** What a content-plane pass, and the session it opens, carry: its scope; the control session that asked (the content
  *  session ends with it; none when the World's token asked); the person; the console that frames it; and whether it
@@ -244,7 +245,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
       if (!target) return null;
       // the body as bytes, none when empty: an empty body streamed is sent chunked with no last chunk (Bun 1.2), and the
       // twin's server reads the next request on the connection as its continuation (HPE_INVALID_CHUNK_SIZE)
-      return async (request) => { const at = new URL(request.url); const body = request.body ? new Uint8Array(await request.arrayBuffer()) : undefined; return fetch(`${target.replace(/\/+$/, '')}${at.pathname}${at.search}`, { method: request.method, headers: request.headers, ...(body?.byteLength ? { body } : {}), redirect: 'manual' } as RequestInit); };
+      return async (request) => { const at = new URL(request.url); const body = request.body ? new Uint8Array(await request.arrayBuffer()) : undefined; return fetch(`${target.replace(/\/+$/, '')}${at.pathname}${at.search}`, { method: request.method, headers: forwardableHeaders(request.headers), ...(body?.byteLength ? { body } : {}), redirect: 'manual' } as RequestInit); };
     },
   };
   const world = new WorldDoors(name, worldRoot, configRef, served, host, held('token') ?? mintToken('tok_'), held('token.read') ?? mintToken('tok_r_'));
@@ -255,6 +256,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     name, served, root: worldRoot,
     maxRequestBodySize: Math.max(1024 * 1024 * 1024, ...loadWorldConfig(configRef, worldRoot).config.services.map((service) => packFacts()[service.package?.replace(/^@volter\/twin-/, '') ?? service.id]?.maxRequestBodySize ?? 0)),
     get token() { return world.token; }, get readToken() { return world.readToken; },
+    ready: () => host.ready(),
     twins: () => world.twins(),
     rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
     handle: (request) => world.handle(request),
@@ -1209,7 +1211,7 @@ export class WorldDoors {
       const reads = request.method === 'GET' || request.method === 'HEAD';
       const enforced = browser && grant?.scope === 'read' && await this.enforcesRead(vendor, twin, url.origin);
       if (browser && grant?.scope === 'read' && !reads && !enforced) return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
-      const headers = browser ? new Headers(request.headers) : new Headers();
+      const headers = browser ? forwardableHeaders(request.headers) : new Headers();
       for (const key of [TOKEN_HEADER, TWINS_KEY_HEADER, CALLER_HEADER, ORIGINAL_PATH_HEADER, READ_ONLY_HEADER, 'host', TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, TWIN_SITE_HEADER]) headers.delete(key);
       for (const name of ['accept', 'accept-language', 'if-none-match', 'range', 'user-agent']) { const v = request.headers.get(name); if (v !== null) headers.set(name, v); }
       if (browser) {
@@ -1421,7 +1423,7 @@ export class WorldDoors {
     // (a Slack read over POST passes, a post is refused); a twin that cannot enforce that gets reads only
     const enforced = scope === 'read' && (await this.enforcesRead(vendor!, twin, url.origin));
     if (scope === 'read' && !reads && !enforced) return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
-    const headers = new Headers(request.headers); headers.delete(TOKEN_HEADER); headers.delete(TWINS_KEY_HEADER); headers.delete('host');
+    const headers = forwardableHeaders(request.headers); headers.delete(TOKEN_HEADER); headers.delete(TWINS_KEY_HEADER); headers.delete('host');
     // who made it is the World's word, never the caller's: the twin's request journal records it. The World is a hop of
     // the request's trace: the caller's trace-id goes on (or a new one), under a parent-id the World mints, which the
     // request's log entries carry, so each entry is joined to its caller by an id no caller chose
@@ -1507,7 +1509,7 @@ export class WorldDoors {
   private async forward(request: Request, url: URL, rest: string, name: string, origin: string): Promise<Response> {
     // what leaves for the vendor before the seal is applied: no World token in any header it can arrive
     // under (an SDK's own `Authorization: Bearer` included), no cookie, no routing headers of this World
-    const caller = new Headers(request.headers);
+    const caller = forwardableHeaders(request.headers);
     for (const h of [TOKEN_HEADER, TWINS_KEY_HEADER, TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, CALLER_HEADER, 'host', 'x-forwarded-host', 'x-forwarded-proto', 'cookie']) caller.delete(h);
     // a secret this World minted (`tok_…`, live, revoked or expired) or one that opens it never leaves
     const authorization = caller.get('authorization');

package/src/service-command.ts

@@ -1,29 +1,51 @@
-// Process services run without a shell. On Windows npm's Bun command is a .cmd
-// shim, whose native package executable must be selected before Node spawns it.
+// Process services run without a shell. On Windows a bare command name is found the way a shell would find it, and an
+// npm command shim (`.cmd`, which Node's shell-free spawn cannot execute) runs as what it launches: its package's
+// script under Node, or the native executable of npm's Bun.
 import { readFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 
 const file = (path: string): boolean => {
   try { return statSync(path).isFile(); } catch { return false; }
 };
 
-/** Resolve only the known npm Bun layout, never execute or interpret a command
- *  script. Keep explicit paths, other commands and non-Windows behavior intact. */
-export function serviceExecutable(command: string, env: NodeJS.ProcessEnv): string {
-  if (process.platform !== 'win32' || command.toLowerCase() !== 'bun') return command;
+/** npm's Bun package: `bun.cmd` beside `node_modules/bun/bin/bun.exe`. */
+function npmBun(directory: string): string | undefined {
+  const installed = resolve(directory, 'node_modules', 'bun');
+  const executable = join(installed, 'bin', 'bun.exe');
+  if (!file(executable)) return undefined;
+  try {
+    const manifest = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8')) as { name?: unknown; bin?: { bun?: unknown } };
+    if (manifest.name === 'bun' && manifest.bin?.bun === 'bin/bun.exe') return executable;
+  } catch { /* An incomplete installation follows the ordinary spawn-error path. */ }
+  return undefined;
+}
+
+/** The script an npm cmd-shim launches (`"%dp0%\node_modules\<package>\bin\<tool>.js" %*`), when it names one under
+ *  its own directory. Only the shim's text is read; nothing in it is executed. */
+function shimScript(shim: string): string | undefined {
+  let text: string;
+  try { text = readFileSync(shim, 'utf8'); } catch { return undefined; }
+  const match = /"%dp0%\\([^"%]+\.[cm]?js)"\s+%\*/i.exec(text) ?? /"%~dp0\\([^"%]+\.[cm]?js)"\s+%\*/i.exec(text);
+  if (!match) return undefined;
+  const script = resolve(shim, '..', match[1]!);
+  return file(script) ? script : undefined;
+}
+
+/** The program and arguments a service command runs as. Explicit paths, commands with an extension and every
+ *  non-Windows command keep their meaning; a command that cannot be resolved is spawned as given, and fails through
+ *  the ordinary recorded spawn error. */
+export function serviceInvocation(command: string, args: string[], env: NodeJS.ProcessEnv): { command: string; args: string[] } {
+  if (process.platform !== 'win32' || !command || isAbsolute(command) || /[\\/]/.test(command) || /\.[a-z0-9]+$/i.test(command)) return { command, args };
   const path = Object.entries(env).find(([key]) => key.toUpperCase() === 'PATH')?.[1] ?? '';
-  const directories = [process.cwd(), ...path.split(';').map((value) => value.replace(/^"(.*)"$/, '$1'))];
+  const directories = [process.cwd(), ...path.split(';').filter(Boolean).map((value) => value.replace(/^"(.*)"$/, '$1'))];
   for (const directory of directories) {
-    const native = resolve(directory, 'bun.exe');
-    if (file(native)) return native;
-    if (!file(resolve(directory, 'bun.cmd'))) continue;
-    const installed = resolve(directory, 'node_modules', 'bun');
-    const executable = join(installed, 'bin', 'bun.exe');
-    if (!file(executable)) continue;
-    try {
-      const manifest = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8')) as { name?: unknown; bin?: { bun?: unknown } };
-      if (manifest.name === 'bun' && manifest.bin?.bun === 'bin/bun.exe') return executable;
-    } catch { /* An incomplete installation follows the ordinary spawn-error path. */ }
+    const native = resolve(directory, `${command}.exe`);
+    if (file(native)) return { command: native, args };
+    const shim = resolve(directory, `${command}.cmd`);
+    if (!file(shim)) continue;
+    if (command.toLowerCase() === 'bun') { const bun = npmBun(directory); if (bun) return { command: bun, args }; }
+    const script = shimScript(shim);
+    if (script) return { command: process.execPath, args: [script, ...args] };
   }
-  return command;
+  return { command, args };
 }

package/src/service-environment.ts

@@ -0,0 +1,21 @@
+/** The recorder's environment and its child's are computed here so the boot gate sees the exact final names. */
+export function recorderEnvironment(env: NodeJS.ProcessEnv, service: string, log: string, logDir: string, events: string): NodeJS.ProcessEnv {
+  const out: NodeJS.ProcessEnv = { ...env, VOLTER_WORLD_SERVICE_ID: service, VOLTER_WORLD_SERVICE_LOG: log,
+    VOLTER_WORLD_SERVICE_LOG_DIR: logDir, VOLTER_WORLD_EVENTS: events };
+  if (out.NODE_OPTIONS !== undefined) {
+    out.VOLTER_WORLD_SERVICE_NODE_OPTIONS = out.NODE_OPTIONS;
+    delete out.NODE_OPTIONS;
+  }
+  return out;
+}
+
+/** Restore the injector for the real child and omit only the recorder's existing private transport names. */
+export function recordedApplicationEnvironment(recorded: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const out: NodeJS.ProcessEnv = { ...recorded };
+  if (out.VOLTER_WORLD_SERVICE_NODE_OPTIONS !== undefined) {
+    out.NODE_OPTIONS = out.VOLTER_WORLD_SERVICE_NODE_OPTIONS;
+    delete out.VOLTER_WORLD_SERVICE_NODE_OPTIONS;
+  }
+  for (const key of ['VOLTER_WORLD_EVENTS', 'VOLTER_WORLD_SERVICE_LOG_MAX']) delete out[key];
+  return out;
+}

package/src/service-recorder.ts

@@ -17,19 +17,18 @@
 // The World's NODE_OPTIONS (the injector) is for the service, not this parent: it arrives renamed and is restored.
 import { signalChild } from './process-signal.mjs';
 import { errorMessage } from './error-message.ts';
-import { serviceExecutable } from './service-command.ts';
+import { serviceInvocation } from './service-command.ts';
+import { recordedApplicationEnvironment } from './service-environment.ts';
 import { spawn } from 'node:child_process';
 import { constants } from 'node:os';
 import { appendFileSync, closeSync, fstatSync, openSync, readSync, statSync, truncateSync, writeFileSync } from 'node:fs';
 
 const [command = '', ...args] = process.argv.slice(2);
-const env = { ...process.env };
-if (env.VOLTER_WORLD_SERVICE_NODE_OPTIONS !== undefined) { env.NODE_OPTIONS = env.VOLTER_WORLD_SERVICE_NODE_OPTIONS; delete env.VOLTER_WORLD_SERVICE_NODE_OPTIONS; }
-const service = env.VOLTER_WORLD_SERVICE_ID;
-const logPath = env.VOLTER_WORLD_SERVICE_LOG;
-const eventsPath = env.VOLTER_WORLD_EVENTS;
-const cap = Number(env.VOLTER_WORLD_SERVICE_LOG_MAX) > 0 ? Number(env.VOLTER_WORLD_SERVICE_LOG_MAX) : 64 * 1024 * 1024;
-for (const key of ['VOLTER_WORLD_EVENTS', 'VOLTER_WORLD_SERVICE_LOG_MAX']) delete env[key];
+const env = recordedApplicationEnvironment(process.env);
+const service = process.env.VOLTER_WORLD_SERVICE_ID;
+const logPath = process.env.VOLTER_WORLD_SERVICE_LOG;
+const eventsPath = process.env.VOLTER_WORLD_EVENTS;
+const cap = Number(process.env.VOLTER_WORLD_SERVICE_LOG_MAX) > 0 ? Number(process.env.VOLTER_WORLD_SERVICE_LOG_MAX) : 64 * 1024 * 1024;
 
 /** The log's size and whether its last byte ends a line (a record never lands inside a service's line). */
 const logEnd = (): { size: number; atLineStart: boolean } => {
@@ -49,7 +48,8 @@ const record = (entry: Record<string, unknown>, then?: () => void): void => {
 };
 
 const started = Date.now();
-const child = spawn(serviceExecutable(command, env), args, { windowsHide: true, stdio: 'inherit', env });
+const invocation = serviceInvocation(command, args, env);
+const child = spawn(invocation.command, invocation.args, { windowsHide: true, stdio: 'inherit', env });
 if (child.pid !== undefined) record({ event: 'world.service.started', pid: child.pid, parentPid: process.pid });
 
 /** The log's last `bytes` (from a line start) as the rotation `<log>.1`: however far a runaway writer overshot the cap,