@volter/world-runtime 3.0.37 → 3.0.39

package/dist/src/error-message.mjs

@@ -0,0 +1,10 @@
+/** Operator-facing failures include aggregate members and retained causes. */
+export function errorMessage(error, seen = new Set()) {
+  const message = error && typeof error === 'object' && 'message' in error ? String(error.message) : String(error);
+  if (seen.has(error)) return '[circular error]';
+  seen.add(error);
+  const details = error instanceof AggregateError ? Array.from(error.errors, member => errorMessage(member, seen)) : [];
+  if (error instanceof Error && error.cause !== undefined) details.push(`cause: ${errorMessage(error.cause, seen)}`);
+  seen.delete(error);
+  return [message, ...details.map(detail => detail.split('\n').map(line => `  ${line}`).join('\n'))].join('\n');
+}

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

@@ -0,0 +1,4 @@
+export function admitGuestArgv(argv: string[], runtime: string, root: string, cwd: string): { argv: string[]; cwd: string };
+export function guestCommandGap(message: string): Error & { code: string };
+export function guestEnvironment(env: Record<string, string>): Record<string, string>;
+export function guestEnvironment(env: Record<string, string | undefined>): Record<string, string | undefined>;

package/dist/src/guest-command.mjs

@@ -0,0 +1,26 @@
+// Declared execution limits reach packs as capability gaps, never vendor launch failures.
+export const guestCommandGap = message => Object.assign(new Error(message), { code: 'WORLD_MACHINE_CAPABILITY_GAP' });
+// Only World routing may restore Node preload/CA configuration after caller controls are stripped.
+export function guestEnvironment(env) {
+  return Object.fromEntries(Object.entries(env).filter(([key]) => !/^(NODE_|LD_|DYLD_|SUBSTRATE_|OPENSSL_CONF$|OPENSSL_MODULES$)/i.test(key)));
+}
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { resolve, relative, isAbsolute } from 'node:path';
+// Interim admission list: the image's Node runtime and an ordinary JS file inside its folder.
+export function admitGuestArgv(argv, runtime, root, cwd) {
+  if (runtime !== 'node' || !Array.isArray(argv) || argv.length < 2 || !argv.every(value => typeof value === 'string' && !value.includes('\0')) || argv[0] !== 'node') {
+    throw guestCommandGap(`unsupported guest command ${Array.isArray(argv) ? argv[0] : '(invalid argv)'}; admitted program: node with an image entry file`);
+  }
+  if (argv[1].startsWith('-')) throw guestCommandGap('unsupported Node option/eval; guest command requires an image entry file');
+  const folder = realpathSync(root);
+  const within = path => {
+    const real = realpathSync(path), rest = relative(folder, real);
+    if (rest === '..' || rest.startsWith('../') || isAbsolute(rest)) throw guestCommandGap('guest command path leaves its folder');
+    return real;
+  };
+  const directory = within(cwd);
+  if (!statSync(directory).isDirectory()) throw guestCommandGap('guest command cwd is not a directory');
+  const entry = resolve(directory, argv[1]);
+  if (!existsSync(entry) || !/\.(?:mjs|cjs|js)$/.test(entry) || !statSync(within(entry)).isFile()) throw guestCommandGap('guest command needs an ordinary JS entry file in its folder');
+  return { argv: ['node', within(entry), ...argv.slice(2)], cwd: directory };
+}

package/dist/src/guest-control.d.mts

@@ -0,0 +1 @@
+export function guestControl<T>(operation: (signal: AbortSignal) => Promise<T>, label: string, signal?: AbortSignal, budget?: number): Promise<T>;

package/dist/src/guest-control.mjs

@@ -0,0 +1,17 @@
+import { COMMAND_GRACE_MS } from './command-lifetime.mjs';
+// Runtime teardown contract: existing 5000 ms grace, not a new vendor default.
+export function guestControl(operation, label, signal, budget = COMMAND_GRACE_MS) {
+  const controller = new AbortController();
+  const abort = () => controller.abort(signal.reason);
+  if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(() => controller.abort(new Error(`${label} exceeded ${budget} ms runtime control budget; ownership retained`)), budget);
+  let rejectAbort;
+  const failed = new Promise((_, reject) => { rejectAbort = reject; });
+  const cancelled = () => rejectAbort(controller.signal.reason);
+  controller.signal.addEventListener('abort', cancelled, { once: true });
+  if (controller.signal.aborted) cancelled();
+  return Promise.race([Promise.resolve().then(() => { controller.signal.throwIfAborted(); return operation(controller.signal); }), failed]).finally(() => {
+    clearTimeout(timer); signal?.removeEventListener('abort', abort);
+    controller.signal.removeEventListener('abort', cancelled);
+  });
+}

package/dist/src/guest-entry.mjs

@@ -0,0 +1,146 @@
+// One pinned Substrate host; the interim adapter admits Node argv, never an OS shell.
+import childProcess from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { createNodeHost, serveAgent } from '@volter/browser-host-node';
+import { parseSimpleBrowserCommand } from '@volter/browser-runtime';
+import { signalOwnedProcess } from './process-signal.mjs';
+import { commandLifetime, COMMAND_GRACE_MS } from './command-lifetime.mjs';
+import { beginGuestProcess, retainGuestProcess, releaseGuestProcesses } from './guest-processes.mjs';
+import { admitGuestArgv, guestEnvironment } from './guest-command.mjs';
+import { guestControl } from './guest-control.mjs';
+
+const host = createNodeHost({ root: process.env.SUBSTRATE_ROOT });
+const routing = JSON.parse(process.env.SUBSTRATE_GUEST_ENV);
+const retained = new Map(), admissions = new Map();
+let closing = false, launching;
+const rawSpawn = childProcess.spawn;
+// The pinned lane creates/retains children synchronously in run(). Replace exactly its
+// launcher before spawning, and keep its own pipes, process tracking and socket discovery.
+// Scope is synchronous: inspectors and future unrelated spawns never acquire this admission.
+childProcess.spawn = (file, args, options) => {
+  if (file !== '/bin/sh') return rawSpawn(file, args, options);
+  if (!launching || args.length !== 2 || args[0] !== '-c' || args[1] !== 'world-owned-node') throw new Error('guest shell execution refused');
+  const launch = launching;
+  const admitted = admitGuestArgv(launch.argv, process.env.SUBSTRATE_GUEST_RUNTIME, host.root, options.cwd);
+  const receipt = beginGuestProcess(process.env.SUBSTRATE_RECEIPTS, process.env.SUBSTRATE_WORLD_INSTANCE, process.env.SUBSTRATE_GUEST_NAME, 'command');
+  const child = rawSpawn(process.execPath, admitted.argv.slice(1), { ...options, env: { ...guestEnvironment(options.env ?? {}), ...routing }, cwd: admitted.cwd, shell: false });
+  const lifetime = commandLifetime(child, launch.signal);
+  const held = { child, lifetime, receipt };
+  if (!child.pid) {
+    void lifetime.finish().then(() => releaseGuestProcesses([receipt])).catch(error => console.error('Unspawned guest receipt retained:', error));
+    throw new Error('guest Node process did not spawn');
+  }
+  retained.set(child.pid, held); // ownership before publication
+  retainGuestProcess(receipt, { pid: child.pid });
+  held.birth = lifetime.identity.then(birth => {
+    if (!birth?.start || child.exitCode !== null || child.signalCode !== null || retained.get(child.pid) !== held) {
+      throw new Error('guest spawn birth invalid: original child no longer held/live or birth unavailable; admission refused');
+    }
+    retainGuestProcess(receipt, birth); // readiness cannot precede this successful atomic publication
+    return birth;
+  });
+  held.birth.then(launch.resolve, launch.reject);
+  void lifetime.finish().then(() => {
+    retained.delete(child.pid);
+    releaseGuestProcesses([receipt]); // commandLifetime confirms close and whole-group absence
+  }).catch(error => console.error('Guest command retirement unconfirmed; receipt retained:', error));
+  launch.held = held;
+  return child;
+};
+syncBuiltinESMExports();
+const laneRun = host.lane.run.bind(host.lane);
+host.lane.run = () => Promise.reject(new Error('guest shell fallback refused; only admitted Node argv is supported'));
+host.lane.openPty = () => Promise.reject(new Error('guest PTY/shell execution is unsupported by Node argv admission'));
+const program = '__world_node_argv';
+host.runtime.registerProgram(program, async (argv, options) => {
+  const launch = argv.length === 2 ? admissions.get(argv[1]) : undefined;
+  if (closing || !launch || launch.consumed) throw new Error('guest command has no live argv admission');
+  launch.consumed = true;
+  if (options.terminal || options.stdinStream) throw new Error('guest PTY/streamed stdin is unsupported');
+  const cwd = host.filesystem.real(options.cwd ?? '/');
+  admitGuestArgv(launch.argv, process.env.SUBSTRATE_GUEST_RUNTIME, host.root, cwd);
+  launch.signal = options.signal;
+  let result;
+  try {
+    launching = launch;
+    // The pinned lane's raw abort callback signals a numeric PID; leave cancellation to
+    // our retained commandLifetime so every delivery uses the held child or verified birth.
+    result = laneRun('world-owned-node', { ...options, signal: undefined, env: { ...guestEnvironment(options.env ?? {}), ...routing } });
+  } catch (error) { launch.reject(error); throw error; }
+  finally { launching = undefined; }
+  if (!launch.held) { const error = new Error('Substrate did not retain the admitted Node child'); launch.reject(error); throw error; }
+  return (await Promise.all([result, launch.birth]))[0];
+});
+const runtimeStart = host.runtime.start.bind(host.runtime);
+host.runtime.start = (command, options) => {
+  let argv = parseSimpleBrowserCommand(command);
+  // RemoteRuntime's wire envelope is decoded as data; neither envelope nor payload runs in a shell.
+  if (argv.length === 3 && argv[0] === 'sh' && argv[1] === '-c') argv = parseSimpleBrowserCommand(argv[2]);
+  if (closing || argv.length !== 2 || argv[0] !== program || !admissions.has(argv[1])) throw new Error('guest command is not an admitted Node argv operation');
+  return runtimeStart(`${program} ${argv[1]}`, options);
+};
+async function signalCommands(signal) {
+  await Promise.all([...retained.values()].map(async held => {
+    const birth = await held.birth; // rejected/unheld captures can never authorize a numeric signal
+    await signalOwnedProcess(birth, signal, true);
+  }));
+}
+const agent = await guestControl(() => serveAgent({ host, token: process.env.SUBSTRATE_TOKEN, port: Number(process.env.SUBSTRATE_AGENT_PORT), bind: '127.0.0.1' }), 'guest agent startup');
+const streams = new Set();
+agent.server.on('request', (request, response) => {
+  if (!new URL(request.url, 'http://guest').pathname.endsWith('/events')) return;
+  streams.add(response); response.on('close', () => streams.delete(response));
+});
+async function close() {
+  if (closing) return;
+  closing = true;
+  const commands = [...retained.values()];
+  for (const held of commands) { held.lifetime.cancel('SIGCONT'); held.lifetime.cancel('SIGTERM'); }
+  // Every command retires through the same bounded grace/KILL/confirmation as World commands.
+  const results = await Promise.allSettled(commands.map(held => held.lifetime.finish()));
+  for (const result of results) if (result.status === 'rejected') throw result.reason;
+  await guestControl(async () => {
+    await host.close();
+    for (const response of streams) response.end();
+    await agent.close();
+  }, 'Substrate guest drain');
+  process.exit(0);
+}
+process.on('message', async ({ id, action, path }) => {
+  try {
+    let value;
+    if (action === 'prepare') {
+      if (closing) throw new Error('Substrate guest is retiring');
+      const argv = JSON.parse(path);
+      if (!Array.isArray(argv) || argv[0] !== 'node') throw new Error('admitted guest program is node');
+      const key = randomUUID();
+      let resolve, reject;
+      const birth = new Promise((yes, no) => { resolve = yes; reject = no; });
+      birth.catch(() => {});
+      admissions.set(key, { argv, birth, resolve, reject, consumed: false });
+      value = key;
+    } else if (action === 'admission') {
+      const launch = admissions.get(path);
+      if (!launch) throw new Error('guest launch admission missing');
+      try { value = await guestControl(() => launch.birth, 'guest birth admission'); }
+      finally { if (launch.consumed) admissions.delete(path); }
+    } else if (action === 'pause' || action === 'resume') {
+      await guestControl(() => signalCommands(action === 'pause' ? 'SIGSTOP' : 'SIGCONT'), `guest ${action}`);
+    } else if (action === 'stat') {
+      const s = host.filesystem.statSync(path);
+      value = { size: s.size, mode: s.mode, mtime: s.mtime.toISOString(), type: s.isDirectory() ? 'directory' : 'file' };
+    } else throw new Error(`unsupported guest control ${action}`);
+    if (process.connected) process.send?.({ id, value });
+  } catch (error) { if (process.connected) process.send?.({ id, error: error.message }); }
+});
+const retire = () => void close().catch(error => {
+  console.error('Substrate guest retirement refused; ownership retained:', error);
+  // No success or receipt deletion on uncertainty; exit closes control. World down owns retry.
+  process.exit(1);
+});
+process.on('disconnect', retire);
+if (!process.connected) retire();
+process.on('SIGTERM', retire);
+process.on('SIGINT', retire);
+process.send?.({ ready: true, port: agent.port, controlBudgetMs: COMMAND_GRACE_MS });

package/dist/src/guest-processes.d.mts

@@ -0,0 +1,9 @@
+import type { SpawnIdentity } from './process-receipt.js';
+export interface GuestProcessRecord extends SpawnIdentity { instance: string; guest: string; kind: 'agent' | 'command' | 'pty'; launching: false }
+export interface GuestProcessReceipt { path: string; record: GuestProcessRecord }
+export interface GuestProcessLaunch { path: string; record: Omit<GuestProcessRecord, 'pid' | 'launching'> & { pid?: number; launching: boolean } }
+export function guestProcessDirectory(instanceDir: string): string;
+export function beginGuestProcess(directory: string, instance: string, guest: string, kind: GuestProcessRecord['kind']): GuestProcessLaunch;
+export function retainGuestProcess(receipt: GuestProcessLaunch, identity: SpawnIdentity): void;
+export function readGuestProcesses(instanceDir: string, expectedInstance?: string): GuestProcessReceipt[];
+export function releaseGuestProcesses(receipts: Array<{ path: string }>): void;

package/dist/src/guest-processes.mjs

@@ -0,0 +1,47 @@
+// Guest metadata over the existing atomic process receipt; no independent lifecycle.
+import { randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { publishProcessReceipt, readProcessReceipt } from './process-receipt.mjs';
+
+export const guestProcessDirectory = instanceDir => join(instanceDir, 'guest-processes');
+export function beginGuestProcess(directory, instance, guest, kind) {
+  mkdirSync(directory, { recursive: true });
+  const path = join(directory, `${randomUUID()}.json`);
+  const record = { instance, guest, kind, launching: true };
+  publishProcessReceipt(path, JSON.stringify(record));
+  return { path, record };
+}
+export function retainGuestProcess(receipt, identity) {
+  receipt.record = { ...receipt.record, launching: false, ...identity };
+  publishProcessReceipt(receipt.path, JSON.stringify(receipt.record));
+}
+export function readGuestProcesses(instanceDir, expectedInstance) {
+  const directory = guestProcessDirectory(instanceDir);
+  if (!existsSync(directory)) return [];
+  if (lstatSync(directory).isSymbolicLink()) throw new Error('Guest receipt directory is a symbolic link; ownership retained');
+  const names = readdirSync(directory);
+  if (!names.length) return [];
+  if (!expectedInstance) {
+    try { expectedInstance = JSON.parse(readFileSync(join(instanceDir, 'instance.json'), 'utf8')).instance; }
+    catch { throw new Error('Guest instance identity unreadable; ownership retained'); }
+  }
+  return names.map(name => {
+    const path = join(directory, name);
+    if (!/^[0-9a-f-]+\.json$/.test(name) || !lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()) throw new Error('Unresolved guest receipt publication; ownership retained');
+    const receipt = readProcessReceipt(path, text => {
+      const r = JSON.parse(text);
+      if (r.instance !== expectedInstance || typeof r.guest !== 'string' || !['agent', 'command', 'pty'].includes(r.kind)
+        || r.launching || !Number.isInteger(r.pid) || r.pid < 1 || (r.start !== undefined && (typeof r.start !== 'string' || !r.start))) {
+        throw new Error('Guest launch or spawn identity unresolved');
+      }
+      return r;
+    });
+    if (receipt.error || !receipt.value) throw receipt.error ?? new Error('Guest receipt disappeared during inspection; ownership retained');
+    return { path, record: receipt.value };
+  });
+}
+// The caller must have confirmed each recorded group absent before releasing these receipts.
+export function releaseGuestProcesses(receipts) {
+  for (const { path } of receipts) rmSync(path);
+}

package/dist/src/guest-runner.d.ts

@@ -0,0 +1,6 @@
+import type { MachinePool, LightPoolOptions } from '@volter/world-core/runtime';
+/** Local provider for Substrate's sandbox contract; all guest operations are vendor-neutral. */
+export declare function createLightGuestPool(options: LightPoolOptions & {
+    world: string;
+    root?: string;
+}): MachinePool;