@volter/world-runtime 3.0.38 → 3.0.39

package/src/redis-backing.ts

@@ -8,14 +8,20 @@
 // in a container is state outside it (a branch of the World would share the container's queue and cache). The
 // twin keeps each key a subject of the World (the Redis pack's storage module). It needs nothing
 // installed: no container runtime, no redis-server binary.
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync } from 'node:fs';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
-import { spawn } from 'node:child_process';
+import { commandLifetime, COMMAND_GRACE_MS, COMMAND_CONFIRM_MS } from './command-lifetime.ts';
+import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, signalOwnedProcess } from './process-receipt.ts';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { survivingOwnedGroups } from './process-groups.ts';
+import { errorMessage } from './error-message.ts';
 import { findInstalledPackage, packCli } from './catalog.ts';
 import { vendorPackageDir } from '@volter/world-core/runtime';
 import type { HostLaunch, InfraService } from './pglite-backing.ts';
 
+interface RedisHost { child: ChildProcess; lifetime: ReturnType<typeof commandLifetime>; closed: boolean }
+const hosts = new Map<string, RedisHost>();
 const PACKAGE = '@volter/twin-redis';
 const READY_TIMEOUT_MS = 60_000;
 
@@ -34,7 +40,7 @@ const pidPath = (dataDir: string, service: InfraService): string => join(dataDir
 export const redisTwinRoot = (dataDir: string): string => join(dataDir, 'redis-twin');
 
 function alive(pid: number): boolean {
-  try { process.kill(pid, 0); return true; } catch { return false; }
+  try { process.kill(pid, 0); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false; throw error; }
 }
 
 function listening(port: number): Promise<boolean> {
@@ -53,7 +59,9 @@ const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 export async function redisTwinUp(services: InfraService[], dataDir: string, cli: string, launch: HostLaunch = {}): Promise<void> {
   for (const service of services) {
     const pidFile = pidPath(dataDir, service);
-    if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort)) continue;
+    if (hosts.has(pidFile) || existsSync(pidFile) || existsSync(spawnReceiptPath(pidFile))) {
+      await redisTwinDown([service], dataDir);
+    }
     // a port that already answers is another process's (another World's twin, a redis-server): serving there would
     // hand this World's app someone else's keys, so it is refused, never taken as ready
     if (await listening(service.hostPort)) throw new Error(`port ${service.hostPort} already serves Redis for another process`);
@@ -66,21 +74,39 @@ export async function redisTwinUp(services: InfraService[], dataDir: string, cli
     // the runtime this runs on: Bun runs the pack's TypeScript as it is; Node (volter-world-infra's shebang) needs
     // type transformation, not only stripping (the kernel declares constructor parameter properties)
     const runtime = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
-    const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
-      env: launch.env ?? process.env,
-      detached: true,
-      windowsHide: true,
-      stdio: ['ignore', logFd, logFd],
-    });
-    child.unref();
-    closeSync(logFd);
-    writeFileSync(pidFile, `${child.pid}\n`);
-    const deadline = Date.now() + READY_TIMEOUT_MS;
-    while (!(await listening(service.hostPort)) || !alive(child.pid!)) {
-      if (!alive(child.pid!)) throw new Error(`redis exited before serving — see ${log}`);
+    let held: RedisHost | undefined;
+    try {
+      try {
+        const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
+          env: launch.env ?? process.env, detached: true, windowsHide: true, stdio: ['ignore', logFd, logFd],
+        });
+        // Retain BEFORE descriptor close, birth capture or either publication can fail.
+        held = { child, lifetime: commandLifetime(child, launch.signal), closed: false };
+        const observed = held;
+        child.once('close', () => { observed.closed = true; });
+        child.on('error', () => {}); // lifetime joins spawn failure and close
+        hosts.set(pidFile, held);
+      } finally { closeSync(logFd); }
+      if (!held.child.pid) throw new Error('Redis child did not start');
+      const identity = await held.lifetime.identity;
+      if (!identity?.start) throw new Error('Redis birth capture failed; retiring held child');
+      publishProcessReceipt(spawnReceiptPath(pidFile), JSON.stringify(identity) + '\n');
+      publishProcessReceipt(pidFile, `${held.child.pid}\n`);
+      const deadline = Date.now() + READY_TIMEOUT_MS;
+      while (!(await listening(service.hostPort)) || !alive(held.child.pid)) {
+        if (!alive(held.child.pid)) throw new Error(`redis exited before serving — see ${log}`);
+        launch.signal?.throwIfAborted();
+        if (Date.now() > deadline) throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+        await sleep(200);
+      }
       launch.signal?.throwIfAborted();
-      if (Date.now() > deadline) throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
-      await sleep(200);
+      held.child.unref();
+    } catch (error) {
+      if (held) {
+        try { await redisTwinDown([service], dataDir); }
+        catch (cleanup) { throw new AggregateError([error, cleanup], 'Redis startup and retirement failed; ownership retained'); }
+      }
+      throw error;
     }
   }
 }
@@ -98,14 +124,37 @@ export async function redisTwinStatus(services: InfraService[], dataDir: string)
 export async function redisTwinDown(services: InfraService[], dataDir: string): Promise<void> {
   for (const service of services) {
     const pidFile = pidPath(dataDir, service);
-    if (!existsSync(pidFile)) continue;
-    const pid = Number(readFileSync(pidFile, 'utf8').trim());
-    if (alive(pid)) {
-      try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
-      const deadline = Date.now() + 5000;
-      while (alive(pid) && Date.now() < deadline) await sleep(100);
-      if (alive(pid)) { try { process.kill(pid, 'SIGKILL'); } catch { /* raced */ } }
+    const recorded = readProcessReceipt(pidFile, text => {
+      const pid = Number(text.trim());
+      if (!Number.isInteger(pid) || pid <= 0) throw new Error('Invalid Redis ownership PID');
+      return pid;
+    });
+    const identity = readSpawnReceipt(pidFile);
+    const held = hosts.get(pidFile);
+    if (recorded.error || identity.error) process.stderr.write(`${errorMessage(new AggregateError([recorded.error, identity.error].filter(Boolean), 'Redis ownership uncertain; retrying established ownership'))}\n`);
+    if (held) {
+      const retired = () => held!.closed && (!held!.child.pid || !survivingOwnedGroups([held!.child.pid]).length);
+      if (!retired()) {
+        held.child.ref(); held.lifetime.cancel('SIGTERM');
+        try { await held.lifetime.finish(); }
+        catch (error) { if (!retired()) throw error; }
+      }
+    } else {
+      if (!recorded.present && !identity.present) continue;
+      const pid = identity.value?.pid ?? recorded.value;
+      if (!pid) throw new AggregateError([recorded.error, identity.error].filter(Boolean), 'Redis ownership uncertain; receipts retained');
+      if (recorded.value && identity.value && recorded.value !== identity.value.pid) throw new Error('Redis ownership receipts disagree; retirement refused; receipts retained');
+      const live = () => survivingOwnedGroups([pid]).length > 0;
+      for (const [signal, limit] of [['SIGTERM', COMMAND_GRACE_MS], ['SIGKILL', COMMAND_CONFIRM_MS]] as const) {
+        if (!live()) break;
+        await signalOwnedProcess(identity.value, signal, true);
+        const deadline = Date.now() + limit;
+        while (live() && Date.now() < deadline) await sleep(20);
+      }
+      if (live()) throw new Error('Redis retirement unconfirmed; receipts retained');
     }
     rmSync(pidFile, { force: true });
+    rmSync(spawnReceiptPath(pidFile), { force: true });
+    hosts.delete(pidFile);
   }
 }

package/src/reflect.ts

@@ -1,3 +1,4 @@
+import { errorMessage } from './error-message.ts';
 import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
 import { websocketRelay } from './websocket-relay.ts';
 import { sessionTrustEnv } from './ca-trust.ts';
@@ -178,7 +179,7 @@ export async function startReflectFront(options: ReflectFrontOptions): Promise<R
         } catch (error) {
           let world: string | undefined;
           try { world = options.envLoader().VOLTER_WORLD; } catch { /* the answer still goes out */ }
-          return new Response(twinUnreachableMessage(target.vendor, origin.origin, error instanceof Error ? error : new Error(String(error)), world), { status: 502 });
+          return new Response(twinUnreachableMessage(target.vendor, origin.origin, error instanceof Error ? error : new Error(errorMessage(error)), world), { status: 502 });
         }
       },
       upgrade: websocketRelay(req => {

package/src/root.ts

@@ -7,6 +7,7 @@
 // never in a pack, never an env var). `volter world deploy` performs landed entries against each
 // root through the pack's adapters over the kernel executor, with the world's checks in front;
 // `deploy: auto` does the same the moment an entry is appended (the host installs the hook).
+import { errorMessage } from './error-message.ts';
 import { randomBytes } from 'node:crypto';
 import { packEntry } from './catalog.ts';
 import { existsSync, readFileSync } from 'node:fs';
@@ -111,7 +112,7 @@ export async function bindLegacyCredentials(worldRoot: string, current: () => Re
     // admits nothing until it opens again, and is never taken again from roots a request may have changed
     try { inventory = (await currentSealer().open(JSON.parse(heldInventory) as SealedCredential, INVENTORY_SLOT)) as unknown as Inventory; }
     catch (error) {
-      console.error(`[credential] the inventory beside the World does not open (${(error as Error).message}): nothing is admitted until it does`);
+      console.error(`[credential] the inventory beside the World does not open (${errorMessage(error)}): nothing is admitted until it does`);
       return { bound: [], failed: [], refused: [], ready: false };
     }
   }
@@ -121,7 +122,7 @@ export async function bindLegacyCredentials(worldRoot: string, current: () => Re
       store.write(inventoryPath, `${JSON.stringify(sealed, null, 2)}\n`, { secret: true });
       return true;
     } catch (error) {
-      console.error(`[credential] the inventory could not be kept (${(error as Error).message})`);
+      console.error(`[credential] the inventory could not be kept (${errorMessage(error)})`);
       return false;
     }
   };
@@ -149,7 +150,7 @@ export async function bindLegacyCredentials(worldRoot: string, current: () => Re
       delete inventory.pending[name]; changed = true;
       bound.push(name);
     } catch (error) {
-      console.warn(`[credential] ${name}: not bound to its destination (${(error as Error).message})`);
+      console.warn(`[credential] ${name}: not bound to its destination (${errorMessage(error)})`);
       failed.push(name);
     }
   }
@@ -170,7 +171,7 @@ export async function bindLegacyCredentials(worldRoot: string, current: () => Re
         store.write(path, `${JSON.stringify({ ...moved, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`, { secret: true });
         bound.push(name);
       } catch (error) {
-        console.warn(`[credential] ${name}: not moved to the vault (${(error as Error).message})`);
+        console.warn(`[credential] ${name}: not moved to the vault (${errorMessage(error)})`);
         failed.push(name);
       }
     }
@@ -246,7 +247,7 @@ export async function rootCredentialInput(worldRoot: string, vendor: string, env
     try {
       response = await fetch(at, { headers: { 'x-vault-token': vault.token, ...(vault.namespace ? { 'x-vault-namespace': vault.namespace } : {}) }, signal: AbortSignal.timeout(10_000) });
     } catch (error) {
-      notes.push(`the vault at ${vault.addr} did not answer (${(error as Error).message}; a private CA is not read from BAO_CACERT/VAULT_CACERT here)`);
+      notes.push(`the vault at ${vault.addr} did not answer (${errorMessage(error)}; a private CA is not read from BAO_CACERT/VAULT_CACERT here)`);
     }
     if (response) {
       if (response.status === 403) throw new Error(`the vault at ${vault.addr} refused kv/vendors/${vendor} (403): sign in again, or with a token that may read it`);
@@ -448,7 +449,7 @@ export async function refreshTwin(opts: { worldRoot: string; vendor: string; con
     // failure — its reason and how many in a row — so the status door and the twin's status say so
     const held = store.read(marker);
     const previous = held !== null ? (JSON.parse(held) as { failed?: { count?: number } }) : {};
-    const reason = error instanceof Error ? error.message : String(error);
+    const reason = errorMessage(error);
     store.write(marker, `${JSON.stringify({ ...previous, at: new Date().toISOString(), failed: { at, reason, count: (previous.failed?.count ?? 0) + 1 } })}\n`);
     throw error;
   }

package/src/run-task-worker.ts

@@ -1,4 +1,5 @@
 import { runWorldOwned } from './runtime.ts';
+import { errorMessage } from './error-message.ts';
 import type { RunTaskReply, RunTaskRequest } from './run-task.ts';
 
 // Only this process owns the IPC endpoint; child stdio explicitly excludes fd 3. A lost
@@ -20,7 +21,7 @@ process.on('message', async message => {
   started = true;
   let reply: RunTaskReply;
   try { reply = { result: await runWorldOwned(request.configId, request.command, request.options, abort.signal) }; }
-  catch (error) { reply = { error: error instanceof Error ? error.message : String(error) }; }
+  catch (error) { reply = { error: errorMessage(error) }; }
   if ('error' in reply) process.stderr.write(`${reply.error}\n`);
   if (process.connected) process.send!(reply, () => process.exit('error' in reply ? 1 : 0));
   else process.exit('error' in reply ? 1 : 0);