@volter/world-runtime 3.0.38 → 3.0.39

package/dist/src/process-groups.d.ts

@@ -1,4 +1 @@
-/** Inspect only groups already owned by the lifecycle. A dead leader does not prove that its
- * descendants exited. Zombies hold no resources; unknown inspection remains live. This is
- * retirement evidence, never an ownership token or a way to discover processes to kill. */
-export declare function survivingOwnedGroups(pids: number[]): number[];
+export { survivingOwnedGroups, processStarts } from './process-groups.mjs';

package/dist/src/process-groups.js

@@ -1,49 +1 @@
-import { spawnSync } from 'node:child_process';
-/** Inspect only groups already owned by the lifecycle. A dead leader does not prove that its
- * descendants exited. Zombies hold no resources; unknown inspection remains live. This is
- * retirement evidence, never an ownership token or a way to discover processes to kill. */
-export function survivingOwnedGroups(pids) {
-    const candidates = pids.filter(pid => {
-        try {
-            process.kill(process.platform === 'win32' ? pid : -pid, 0);
-            return true;
-        }
-        catch (error) {
-            if (error.code !== 'ESRCH')
-                return true;
-            try {
-                process.kill(pid, 0);
-                return true;
-            }
-            catch (cause) {
-                return cause.code !== 'ESRCH';
-            }
-        }
-    });
-    if (!candidates.length || process.platform === 'win32')
-        return candidates;
-    const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], { windowsHide: true,
-        encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024,
-    });
-    if (result.status !== 0 || result.error)
-        return candidates;
-    const rows = result.stdout.trim().split('\n').map(line => line.trim().split(/\s+/));
-    return candidates.filter(pid => {
-        const members = rows.filter(([id, group]) => Number(group) === pid || Number(id) === pid);
-        // Visibility restrictions can omit a live group. Only ESRCH proves absence.
-        if (!members.length) {
-            for (const target of [-pid, pid]) {
-                try {
-                    process.kill(target, 0);
-                    return true;
-                }
-                catch (error) {
-                    if (error.code !== 'ESRCH')
-                        return true;
-                }
-            }
-            return false;
-        }
-        return members.some(([, , state]) => !state || !state.startsWith('Z'));
-    });
-}
+export { survivingOwnedGroups, processStarts } from './process-groups.mjs';

package/dist/src/process-groups.mjs

@@ -0,0 +1,59 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+
+/** Inspect only groups already owned by the lifecycle. A dead leader does not prove that its
+ * descendants exited. Zombies hold no resources; unknown inspection remains live. This is
+ * retirement evidence, never an ownership token or a way to discover processes to kill. */
+export function survivingOwnedGroups(pids) {
+  const candidates = pids.filter(pid => {
+    try { process.kill(process.platform === 'win32' ? pid : -pid, 0); return true; }
+    catch (error) {
+      if (error.code !== 'ESRCH') return true;
+      try { process.kill(pid, 0); return true; }
+      catch (cause) { return cause.code !== 'ESRCH'; }
+    }
+  });
+  if (!candidates.length || process.platform === 'win32') return candidates;
+  const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], { windowsHide: true,
+    encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024,
+  });
+  if (result.status !== 0 || result.error) return candidates;
+  const rows = result.stdout.trim().split('\n').map(line => line.trim().split(/\s+/));
+  return candidates.filter(pid => {
+    const members = rows.filter(([id, group]) => Number(group) === pid || Number(id) === pid);
+    // Visibility restrictions can omit a live group. Only ESRCH proves absence.
+    if (!members.length) {
+      for (const target of [-pid, pid]) {
+        try { process.kill(target, 0); return true; }
+        catch (error) { if (error.code !== 'ESRCH') return true; }
+      }
+      return false;
+    }
+    return members.some(([, , state]) => !state || !state.startsWith('Z'));
+  });
+}
+
+/** Each running pid's start time; a pid with no process is absent. Printed in one fixed zone and locale, so the same
+ *  process reads the same whoever asks (`lstart` otherwise follows the caller's TZ and language). One `ps` per pid:
+ *  given two or more pids, macOS `ps -p` walks the whole process table (measured 2026-09-30 on Darwin 25.4, 944
+ *  processes: `/usr/bin/time -p ps -o pid=,lstart= -p 1,$$` 0.14–0.35 s, `… -p 1` 0.00 s), which every `status`
+ *  paid. */
+export function processStarts(pids) {
+  const starts = new Map();
+  if (!pids.length || process.platform === 'win32') return starts;
+  if (process.platform === 'linux' && existsSync('/proc/self/stat')) {
+    // Linux: the start tick since boot (field 22), which a wall-clock step does not move (lstart would).
+    for (const pid of pids) {
+      try { const stat = readFileSync(`/proc/${pid}/stat`, 'utf8'); starts.set(pid, `tick ${stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]}`); } catch { /* no process */ }
+    }
+    return starts;
+  }
+  const env = { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' };
+  for (const pid of pids) {
+    const result = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', String(pid)], { windowsHide: true, encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', env });
+    const match = /^\s*(\d+)\s+(.+?)\s*$/.exec((result.stdout ?? '').trim());
+    if (match && Number(match[1]) === pid) starts.set(pid, match[2]);
+  }
+  return starts;
+}
+

package/dist/src/process-receipt.d.mts

@@ -0,0 +1,6 @@
+import type { ReceiptRead, SpawnIdentity } from './process-receipt.js';
+export { spawnIdentity, verifySpawnIdentity, signalOwnedProcess } from './process-signal.mjs';
+export function publishProcessReceipt(path: string, text: string): void;
+export function readProcessReceipt<T>(path: string, parse: (text: string) => T): ReceiptRead<T>;
+export function spawnReceiptPath(path: string): string;
+export function readSpawnReceipt(path: string): ReceiptRead<SpawnIdentity>;

package/dist/src/process-receipt.d.ts

@@ -0,0 +1,11 @@
+export { spawnIdentity, verifySpawnIdentity, signalOwnedProcess } from './process-signal.mjs';
+export { publishProcessReceipt, readProcessReceipt, spawnReceiptPath, readSpawnReceipt } from './process-receipt.mjs';
+export interface ReceiptRead<T> {
+    present: boolean;
+    value?: T;
+    error?: Error;
+}
+export interface SpawnIdentity {
+    pid: number;
+    start?: string;
+}

package/dist/src/process-receipt.js

@@ -0,0 +1,3 @@
+// Native Node guests and the World use one atomic process-receipt implementation.
+export { spawnIdentity, verifySpawnIdentity, signalOwnedProcess } from './process-signal.mjs';
+export { publishProcessReceipt, readProcessReceipt, spawnReceiptPath, readSpawnReceipt } from './process-receipt.mjs';

package/dist/src/process-receipt.mjs

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+export { spawnIdentity, verifySpawnIdentity, signalOwnedProcess } from './process-signal.mjs';
+
+/** A failed publication never truncates the previous receipt. */
+export function publishProcessReceipt(path, text) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  let descriptor;
+  const failures = [];
+  try {
+    descriptor = fs.openSync(temporary, 'wx', 0o600);
+    fs.writeFileSync(descriptor, text);
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor); descriptor = undefined;
+    fs.renameSync(temporary, path);
+    descriptor = fs.openSync(dirname(path), 'r');
+    fs.fsyncSync(descriptor);
+  } catch (error) { failures.push(error); }
+  if (descriptor !== undefined) {
+    try { fs.closeSync(descriptor); } catch (error) { failures.push(error); }
+  }
+  try { fs.rmSync(temporary, { force: true }); } catch (error) { failures.push(error); }
+  if (failures.length) throw new AggregateError(failures, `Process receipt publication failed: ${path}`);
+}
+
+/** Unreadable is uncertainty, not absence; a separate spawn receipt may still establish ownership. */
+export function readProcessReceipt(path, parse) {
+  try { return { present: true, value: parse(fs.readFileSync(path, 'utf8')) }; }
+  catch (cause) {
+    if (cause.code === 'ENOENT') return { present: false };
+    return { present: true, error: new Error(`Process receipt unreadable; ownership uncertain: ${path}`, { cause }) };
+  }
+}
+
+export const spawnReceiptPath = (path) => `${path}.spawn.json`;
+export function readSpawnReceipt(path) {
+  return readProcessReceipt(spawnReceiptPath(path), text => {
+    const value = JSON.parse(text);
+    if (!Number.isInteger(value?.pid) || value.pid <= 0 || (typeof value.start !== 'string' || !value.start.trim())) {
+      throw new Error('Invalid process spawn identity');
+    }
+    return value;
+  });
+}

package/dist/src/process-signal.d.mts

@@ -0,0 +1,9 @@
+import type { SpawnIdentity } from './process-receipt.js';
+import type { ChildProcess } from 'node:child_process';
+export function processBirth(pid: number): Promise<string | undefined>;
+export function spawnIdentity(pid: number): Promise<SpawnIdentity>;
+export function verifySpawnIdentity(identity: SpawnIdentity | undefined): Promise<void>;
+export function signalOwnedProcess(identity: SpawnIdentity | undefined, signal: NodeJS.Signals, group?: boolean): Promise<boolean>;
+export function signalChild(child: ChildProcess, signal: NodeJS.Signals, group?: boolean): boolean;
+export function signalHeldChild(child: ChildProcess, signal: NodeJS.Signals, group?: boolean, birth?: Promise<SpawnIdentity | undefined>): Promise<boolean>;
+export function childIdentity(child: ChildProcess): Promise<SpawnIdentity | undefined>;

package/dist/src/process-signal.mjs

@@ -0,0 +1,92 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+// Retain the existing 1000 ms inspection ceiling, not a new timeout chosen from one sample.
+// Measured 2026-10-03 on shared Darwin 25.4.0 ARM64, Bun 1.3.11 (process.version
+// v24.3.0), parent 38b5290 plus this change; no Cal server, one live driver PID:
+// `/usr/bin/time -p /bin/ps -o pid=,lstart= -p <driver-pid>` with LC_ALL/LANG=C,
+// TZ=UTC took 9.26 ms from spawn to close; time printed real/user/sys 0.00 s.
+// This includes the time wrapper/event-loop overhead, not an isolated benchmark.
+// Full command/output: cookbook/calcom/output/held-backing-lifecycle.txt.
+const BIRTH_LOOKUP_MS = 1000;
+/** No subprocess on Linux; elsewhere the lookup never blocks the lifecycle event loop. */
+export async function processBirth(pid) {
+  if (process.platform === 'win32') return undefined;
+  if (process.platform === 'linux') {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const tick = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+      return /^\d+$/.test(tick ?? '') ? `tick ${tick}` : undefined;
+    } catch { return undefined; }
+  }
+  return new Promise(resolve => {
+    const child = spawn('ps', ['-o', 'pid=,lstart=', '-p', String(pid)], {
+      windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'],
+      env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' },
+    });
+    let output = '', settled = false;
+    const finish = value => { if (!settled) { settled = true; clearTimeout(timer); child.stdout.destroy(); resolve(value); } };
+    // This is our still-held inspector, not a PID from a receipt.
+    const timer = setTimeout(() => {
+      try { signalChild(child, 'SIGKILL'); } catch { /* failed inspection remains unavailable */ }
+      finish(undefined); // an exited wrapper's descendant may keep stdout open indefinitely
+    }, BIRTH_LOOKUP_MS);
+    child.stdout.on('data', chunk => { output += chunk; });
+    child.once('error', () => finish(undefined));
+    child.once('close', code => {
+      const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(output.trim());
+      finish(code === 0 && match && Number(match[1]) === pid ? match[2] : undefined);
+    });
+  });
+}
+/** Capture at spawn for durable ownership, never when retrying a retained PID. */
+export async function spawnIdentity(pid) {
+  const start = await processBirth(pid);
+  return { pid, ...(start === undefined ? {} : { start }) };
+}
+/** An async capture is accepted only while its original child is still held and live. */
+export async function childIdentity(child) {
+  if (!child.pid) return undefined;
+  const identity = await spawnIdentity(child.pid);
+  return child.exitCode === null && child.signalCode === null ? identity : undefined;
+}
+/** A birth token is required even when an absent leader leaves a surviving group. */
+export async function verifySpawnIdentity(identity) {
+  if (!identity || !Number.isInteger(identity.pid) || identity.pid <= 0 || typeof identity.start !== 'string' || !identity.start.trim()) {
+    throw new Error('Process recorded birth token missing; retirement refused; ownership retained');
+  }
+  const current = await processBirth(identity.pid);
+  if (current !== undefined && current !== identity.start) {
+    throw new Error(`Process ${identity.pid} no longer matches its recorded spawn identity; retirement refused`);
+  }
+  if (current === undefined) {
+    try { process.kill(identity.pid, 0); }
+    catch (error) { if (error.code === 'ESRCH') return; throw error; }
+    throw new Error(`Process ${identity.pid} identity cannot be established; ownership retained`);
+  }
+}
+/** Stored or retained numbers use birth verification before every delivery. */
+export async function signalOwnedProcess(identity, signal, group = false) {
+  await verifySpawnIdentity(identity);
+  try { return process.kill(group && process.platform !== 'win32' ? -identity.pid : identity.pid, signal); }
+  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+}
+/** A live ChildProcess is ownership until exit. A group additionally needs its leader alive.
+ * False means no held delivery was possible; a caller with surviving descendants needs a birth. */
+export function signalChild(child, signal, group = false) {
+  if (!child.pid || child.exitCode !== null || child.signalCode !== null) return false;
+  if (!group || process.platform === 'win32') return child.kill(signal);
+  try { process.kill(child.pid, 0); }
+  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+  try { return process.kill(-child.pid, signal); }
+  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+}
+
+/** Held first; an orphaned group then becomes retained numeric ownership. */
+export async function signalHeldChild(child, signal, group = false, birth = Promise.resolve(undefined)) {
+  if (signalChild(child, signal, group)) return true;
+  if (!group || process.platform === 'win32' || !child.pid) return false;
+  try { process.kill(-child.pid, 0); }
+  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+  return signalOwnedProcess(await birth, signal, true);
+}

package/dist/src/project-inspect.d.ts

@@ -91,7 +91,7 @@ export declare function connectionProtocol(value: string): string | null;
 /** Native connections are independent of the vendor's HTTP SDK. Inspect ordinary URL schemes
  * and Prisma datasource declarations; never infer a selected Prisma adapter from its presence
  * in package.json. Dynamic/config-file-only datasources remain unknown, as do unbound drivers. */
-export declare function projectConnections(input?: string, attributedEnv?: Set<string>): ProjectConnection[];
+export declare function projectConnections(input?: string, attributedEnv?: Set<string>, boundProtocols?: ReadonlyMap<string, string>): ProjectConnection[];
 /** Literal HTTP(S) destinations passed directly to the platform fetch API in production source.
  *
  * This is the third vendor signal beside dependencies and env names: hand-written REST clients

package/dist/src/project-inspect.js

@@ -592,7 +592,7 @@ export function connectionProtocol(value) {
 /** Native connections are independent of the vendor's HTTP SDK. Inspect ordinary URL schemes
  * and Prisma datasource declarations; never infer a selected Prisma adapter from its presence
  * in package.json. Dynamic/config-file-only datasources remain unknown, as do unbound drivers. */
-export function projectConnections(input = process.cwd(), attributedEnv = new Set()) {
+export function projectConnections(input = process.cwd(), attributedEnv = new Set(), boundProtocols = new Map()) {
     const root = resolve(input);
     const found = [];
     const dependencies = projectDependencies(root);
@@ -616,7 +616,9 @@ export function projectConnections(input = process.cwd(), attributedEnv = new Se
                 if (connectionProtocol(resolved) === null && attributedEnv.has(match[1]) &&
                     (/^https?:/i.test(resolved) || /_REST_URL$/.test(match[1])))
                     continue;
-                found.push({ protocol: connectionProtocol(resolved), env: match[1], sources: [`env: ${relative(root, resolve(dir, file))}:${index + 1} ${match[1]}`] });
+                // An empty example leaves the actual value to environment injection. Only an owned binding supplies its protocol.
+                const protocol = connectionProtocol(resolved) ?? (value.trim() === '' ? boundProtocols.get(match[1]) ?? null : null);
+                found.push({ protocol, env: match[1], sources: [`env: ${relative(root, resolve(dir, file))}:${index + 1} ${match[1]}`] });
             }
         }
     }

package/dist/src/proxy-daemon.js

@@ -2,6 +2,7 @@
 // Detached entry for the ambient TLS redirect proxy. `activate` spawns this as its own process so a
 // long-lived proxy can serve the activated shell(s) for the world's lifetime; it records its
 // pid/url/CA in the instance dir and is stopped by `volter-world down`. Not a user-facing command.
+import { errorMessage } from "./error-message.js";
 import { runProxyDaemon } from "./runtime.js";
 const [name, ...rest] = process.argv.slice(2);
 const rootIndex = rest.indexOf('--root');
@@ -13,6 +14,6 @@ if (!name) {
     process.exit(1);
 }
 runProxyDaemon(name, root, envFile).catch((error) => {
-    process.stderr.write(`proxy-daemon: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.stderr.write(`proxy-daemon: ${errorMessage(error)}\n`);
     process.exit(1);
 });