@volter/world-runtime 3.0.38 → 3.0.40

package/src/pglite-backing.ts

@@ -1,8 +1,7 @@
 // The containerless backing for World-managed infrastructure, instead of docker
 // compose: a POSTGRES service is a PGlite host (see pglite-host.mjs), a MONGODB
-// service is the MongoDB twin (@volter/twin-mongodb: the MongoDB wire protocol over
-// the World state kernel). Selected by `volter-world-infra` when no container
-// runtime is available (or by explicit VOLTER_WORLD_INFRA_BACKING=pglite); the
+// service is MongoDB's own mongod (mongodb-backing.ts). MongoDB is always native; Postgres is selected
+// when no container runtime is available (or by VOLTER_WORLD_INFRA_BACKING=pglite). The
 // world config, definition file, injected env, and declared-service contract are
 // byte-identical either way — backing is private, exactly as the boundary comment
 // in infra-cli.ts promises. Each service's bytes live under VOLTER_WORLD_DATA, so
@@ -12,35 +11,42 @@
 // services only. A definition declaring mysql without a container runtime is
 // refused with the kinds named, never half-booted. Redis never reaches it: every
 // redis service is the redis twin's (redis-backing.ts).
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { commandLifetime, COMMAND_GRACE_MS, COMMAND_CONFIRM_MS } from './command-lifetime.ts';
+import { survivingOwnedGroups } from './process-groups.ts';
+import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess, type SpawnIdentity } from './process-receipt.ts';
+import { errorMessage } from './error-message.ts';
 import { fileURLToPath } from 'node:url';
-import { findInstalledPackage, packCli } from './catalog.ts';
-import { vendorPackageDir } from '@volter/world-core/runtime';
+import { parse } from 'yaml';
+import { mongodbArgv, mongodbListening, mongodbReady } from './mongodb-backing.ts';
 
-export interface InfraService { kind: string; hostPort: number }
+export interface InfraService { kind: string; hostPort: number; replicaSet?: string }
 
-/** Parse the services out of world.infrastructure.yml. This is NOT a YAML
- * parser: init's renderComposeFile emits a deterministic shape, and this
- * reads exactly that shape back (service key at 2-space indent = the kind;
- * the single loopback port mapping beneath it). Anything else is a malformed
- * definition and fails loudly. */
+/** Read the generated definition's loopback port mappings. MongoDB may explicitly request
+ *  one replica-set member through its Compose-compatible command; other mongod options are refused. */
 export function parseInfraDefinition(text: string): InfraService[] {
+  const definition = parse(text);
   const services: InfraService[] = [];
-  let current: string | null = null;
-  let inServices = false;
-  for (const line of text.split(/\r?\n/)) {
-    if (/^services:\s*$/.test(line)) { inServices = true; continue; }
-    if (!inServices) continue;
-    const service = line.match(/^ {2}([a-z][a-z0-9_-]*):\s*$/);
-    if (service) { current = service[1]!; continue; }
-    const port = line.match(/^ {6}- "127\.0\.0\.1:(\d+):\d+"\s*$/);
-    if (port && current) {
-      services.push({ kind: current, hostPort: Number(port[1]) });
-      current = null;
+  for (const [kind, value] of Object.entries(definition?.services ?? {})) {
+    const declared = value as { ports?: unknown[]; command?: unknown };
+    let replicaSet: string | undefined;
+    if (kind === 'mongodb' && declared.command !== undefined) {
+      const command = declared.command;
+      if (!Array.isArray(command) || command.length !== 3 || command[0] !== 'mongod' || command[1] !== '--replSet'
+        || typeof command[2] !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(command[2])) {
+        throw new Error('World-managed MongoDB command must be ["mongod", "--replSet", "<name>"] or absent for standalone');
+      }
+      replicaSet = command[2];
     }
+    const ports = (declared.ports ?? []).flatMap((port) => {
+      const match = typeof port === 'string' ? port.match(/^127\.0\.0\.1:(\d+):\d+$/) : null;
+      return match ? [Number(match[1])] : [];
+    });
+    if (ports.length !== 1) throw new Error(`managed infrastructure ${kind} needs exactly one declared loopback port`);
+    services.push({ kind, hostPort: ports[0]!, ...(replicaSet ? { replicaSet } : {}) });
   }
   return services;
 }
@@ -68,34 +74,35 @@ export function infraConnections(services: InfraService[], env: Record<string, s
 const here = (): string => fileURLToPath(new URL('.', import.meta.url));
 const hostScript = (): string => join(here(), 'pglite-host.mjs');
 const READY_TIMEOUT_MS = 60_000;
-const MONGODB_TWIN = '@volter/twin-mongodb';
 
 /** The kinds this backing serves, and the name its files carry under the data dir. */
-const CONTAINERLESS: Record<string, string> = { postgres: 'pglite-postgres', mongodb: 'twin-mongodb' };
+const CONTAINERLESS: Record<string, string> = { postgres: 'pglite-postgres', mongodb: 'mongod-mongodb' };
+
+// Shared with stopped-state branching: only these backings own cold-copied database bytes.
+export function containerlessDataDirectory(kind: string): string | undefined {
+  const name = CONTAINERLESS[kind];
+  return name === undefined ? undefined : `${name}-data`;
+}
 
 function pidPath(dataDir: string, kind: string): string {
   return join(dataDir, `${CONTAINERLESS[kind] ?? `pglite-${kind}`}.pid`);
 }
 
-/** The MongoDB twin's cli: the package installed above the World's config (an app repo), else the one
- *  this runtime was installed with (its dependency, or the checkout's workspace link). */
-export function mongodbTwinCli(worldConfig?: string, froms: string[] = [...(worldConfig ? [dirname(worldConfig)] : []), here()]): string {
-  for (const from of froms) {
-    const dir = vendorPackageDir(from, 'mongodb') ?? findInstalledPackage(from, MONGODB_TWIN);
-    const cli = dir === undefined ? undefined : packCli(dir);
-    if (cli !== undefined) return cli;
+interface Host { child: ChildProcess; lifetime: ReturnType<typeof commandLifetime>; closed: boolean; identity?: SpawnIdentity }
+const hosts = new Map<string, Host>();
+function hostOwnership(pidFile: string) {
+  const receipt = readProcessReceipt(pidFile, text => {
+    if (!/^[1-9][0-9]*\s*$/.test(text)) throw new Error('Invalid managed host PID');
+    const pid = Number(text.trim());
+    if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error('Invalid managed host PID');
+    return pid;
+  });
+  const spawn = readSpawnReceipt(pidFile);
+  const errors = [receipt.error, spawn.error].filter((error): error is Error => !!error);
+  if (receipt.value && spawn.value && receipt.value !== spawn.value.pid) {
+    errors.push(new Error('Managed host receipts disagree; ownership uncertain'));
   }
-  throw new Error(`the containerless mongodb service is served by ${MONGODB_TWIN} (an optional dependency of @volter/world-runtime), which is not installed above ${froms.join(' or ')} — install it, or run the World with a container runtime`);
-}
-
-/** The runtime a twin's cli runs under. A published package's cli is JavaScript and runs under this
- *  process's own runtime; a checkout's is TypeScript whose kernel needs more than Node's type
- *  stripping, so it runs under Bun (this process's, or the one on PATH) — the repository's toolchain —
- *  and without Bun it is refused by name rather than started to fail. */
-export function twinRunner(cli: string, bunOnPath: () => boolean = () => spawnSync('bun', ['--version'], { stdio: 'ignore', timeout: 10_000, windowsHide: true }).status === 0, underBun = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'): string {
-  if (!cli.endsWith('.ts') || underBun) return process.execPath;
-  if (bunOnPath()) return 'bun';
-  throw new Error(`a checkout's MongoDB twin runs under bun, which is not on PATH (${cli} is TypeScript that Node cannot run)`);
+  return { present: receipt.present || spawn.present, pid: spawn.value?.pid ?? receipt.value, identity: spawn.value, errors, recordedPid: receipt.value, readyReceipt: receipt.value !== undefined, spawnPresent: spawn.present };
 }
 
 /** How a backing starts its hosts: the environment they run in (the World's service environment, which
@@ -106,17 +113,14 @@ export function twinRunner(cli: string, bunOnPath: () => boolean = () => spawnSy
 export interface HostLaunch { env?: NodeJS.ProcessEnv; signal?: AbortSignal }
 
 /** The argv that serves one service on its declared loopback port, with its bytes in `serviceData`. */
-function hostArgv(service: InfraService, serviceData: string, env: NodeJS.ProcessEnv): string[] {
-  if (service.kind === 'mongodb') {
-    const cli = mongodbTwinCli(env.VOLTER_WORLD_CONFIG);
-    // blocking (spawnSync), as it was in the tool: reached only for a checkout's TypeScript cli under Node
-    return [twinRunner(cli, () => spawnSync('bun', ['--version'], { stdio: 'ignore', timeout: 10_000, windowsHide: true, env }).status === 0), cli, 'serve', '--port', String(service.hostPort), '--root', serviceData];
-  }
+function hostArgv(service: InfraService, serviceData: string): string[] {
+  if (service.kind === 'mongodb') return mongodbArgv(service, serviceData);
   return ['node', hostScript(), '--port', String(service.hostPort), '--data', serviceData];
 }
 
 function alive(pid: number): boolean {
-  try { process.kill(pid, 0); return true; } catch { return false; }
+  if (!Number.isInteger(pid) || pid <= 0) 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> {
@@ -139,12 +143,12 @@ export function unsupportedKinds(services: InfraService[]): string[] {
 
 /** The line each host prints once ITS OWN listener is bound: readiness is taken from the child, never
  *  from a connect to the port, which any other process holding the port would answer. */
-function readyLine(kind: string, port: number): string {
-  return kind === 'mongodb' ? `listening on mongodb://127.0.0.1:${port}` : `serving postgres wire protocol on 127.0.0.1:${port}`;
+function readyLine(port: number): string {
+  return `serving postgres wire protocol on 127.0.0.1:${port}`;
 }
 
 function logSince(log: string, offset: number): string {
-  try { return readFileSync(log).subarray(offset).toString('utf8'); } catch { return ''; }
+  return readFileSync(log).subarray(offset).toString('utf8');
 }
 
 export async function pgliteUp(services: InfraService[], dataDir: string, launch: HostLaunch = {}): Promise<void> {
@@ -153,16 +157,23 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
   const plan: Array<{ service: InfraService; name: string; serviceData: string; log: string; pidFile: string; argv: string[] }> = [];
   for (const service of services) {
     const pidFile = pidPath(dataDir, service.kind);
-    if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim()))) continue;
+    const ownership = hostOwnership(pidFile);
+    if (ownership.present || hosts.has(pidFile)) {
+      if (!ownership.errors.length && ownership.readyReceipt && ownership.pid && alive(ownership.pid)) {
+        if (ownership.identity) await verifySpawnIdentity(ownership.identity);
+        continue;
+      }
+      await stopHost(pidFile);
+    }
     const name = CONTAINERLESS[service.kind] ?? `pglite-${service.kind}`;
-    const serviceData = join(dataDir, `${name}-data`);
+    const serviceData = join(dataDir, containerlessDataDirectory(service.kind) ?? `${name}-data`);
     const log = join(dataDir, `${name}.log`);
     if (await listening(service.hostPort)) {
       throw new Error(`${name} cannot serve port ${service.hostPort}: another process is already listening on it`);
     }
-    plan.push({ service, name, serviceData, log, pidFile, argv: hostArgv(service, serviceData, env) });
+    plan.push({ service, name, serviceData, log, pidFile, argv: hostArgv(service, serviceData) });
   }
-  const started: Array<{ pid: number; pidFile: string }> = [];
+  const started: string[] = [];
   try {
     for (const { service, name, serviceData, log, pidFile, argv } of plan) {
       mkdirSync(serviceData, { recursive: true });
@@ -177,28 +188,43 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
         detached: true,
         stdio: ['ignore', logFd, logFd],
       });
-      child.unref();
+      // Retain the actual child BEFORE descriptor close or either publication can fail.
+      const lifetime = commandLifetime(child, launch.signal);
+      const host: Host = { child, lifetime, closed: false };
+      child.once('close', () => { host.closed = true; });
+      hosts.set(pidFile, host); started.push(pidFile);
+      let spawnError: Error | undefined;
+      child.on('error', (error) => { spawnError = error; });
       closeSync(logFd);
-      writeFileSync(pidFile, `${child.pid}\n`);
-      started.push({ pid: child.pid!, pidFile });
+      if (!child.pid) throw new Error(service.kind === 'mongodb'
+        ? "World-managed MongoDB needs MongoDB's own mongod on PATH; see cookbook/mongodb-backing/README.md"
+        : `${name} could not start ${command}`);
+      host.identity = await lifetime.identity;
+      if (!host.identity?.start) throw new Error('Managed host birth capture failed; retiring held child');
+      publishProcessReceipt(spawnReceiptPath(pidFile), JSON.stringify(host.identity) + '\n');
+      publishProcessReceipt(pidFile, `${child.pid}\n`);
       const deadline = Date.now() + READY_TIMEOUT_MS;
-      const line = readyLine(service.kind, service.hostPort);
+      const line = readyLine(service.hostPort);
       // ready when OUR child says its listener is bound (a squatter that took the port after the check
       // above makes the child fail its bind and exit, never print this) and the port answers
-      while (!(alive(child.pid!) && logSince(log, offset).includes(line) && await listening(service.hostPort))) {
+      while (!(alive(child.pid!) && (service.kind === 'mongodb' ? mongodbListening(logSince(log, offset), service.hostPort) : logSince(log, offset).includes(line)) && await listening(service.hostPort))) {
+        if (spawnError) throw spawnError;
         if (!alive(child.pid!)) throw new Error(`${name} exited before serving — see ${log}`);
         if (Date.now() > deadline) throw new Error(`${name} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
         // an aborted boot (Ctrl-C during up) stops waiting; the catch below ends what this up started
         launch.signal?.throwIfAborted();
         await sleep(200);
       }
+      if (service.kind === 'mongodb') await mongodbReady(service, launch, deadline);
+      child.unref();
     }
   } catch (error) {
     // tear down what this up started, so a failed up leaves nothing running
-    for (const { pid, pidFile } of started) {
-      if (alive(pid)) { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } }
-      rmSync(pidFile, { force: true });
+    const errors: unknown[] = [error];
+    for (const pidFile of started) {
+      try { await stopHost(pidFile); } catch (cleanupError) { errors.push(cleanupError); }
     }
+    if (errors.length > 1) throw new AggregateError(errors, 'Managed infrastructure startup and cleanup failed');
     throw error;
   }
 }
@@ -207,24 +233,74 @@ export async function pgliteStatus(services: InfraService[], dataDir: string): P
   let ready = 0;
   for (const service of services) {
     const pidFile = pidPath(dataDir, service.kind);
-    if (!existsSync(pidFile)) continue;
-    const pid = Number(readFileSync(pidFile, 'utf8').trim());
-    if (alive(pid) && await listening(service.hostPort)) ready += 1;
+    const ownership = hostOwnership(pidFile);
+    if (ownership.errors.length) throw new AggregateError(ownership.errors, 'Managed infrastructure ownership uncertain; retry down');
+    if (!ownership.readyReceipt || !ownership.pid || !alive(ownership.pid) || !(await listening(service.hostPort))) continue;
+    if (ownership.identity) await verifySpawnIdentity(ownership.identity);
+    if (service.kind === 'mongodb') {
+      await mongodbReady(service, {}, Date.now() + READY_TIMEOUT_MS, false);
+    }
+    ready += 1;
   }
   return { ok: ready === services.length && services.length > 0, ready };
 }
 
+/** Retain evidence until both the child and its private group are confirmed stopped. */
+async function stopHost(pidFile: string): Promise<void> {
+  const held = hosts.get(pidFile);
+  const ownership = hostOwnership(pidFile);
+  if (ownership.errors.length) process.stderr.write(`${errorMessage(new AggregateError(ownership.errors, 'Managed host ownership uncertain; retrying established identity'))}\n`);
+  if (held) {
+    const pid = held.child.pid;
+    const retired = () => held.closed && (!pid || survivingOwnedGroups([pid]).length === 0);
+    // A failed lifetime promise is a past diagnosis. A later close and vanished
+    // owned group are current retirement evidence, even when finish stays rejected.
+    if (!retired()) {
+      held.child.ref(); held.lifetime.cancel('SIGTERM');
+      try { await held.lifetime.finish(); }
+      catch (error) { if (!retired()) throw error; }
+    }
+  } else if (ownership.pid) {
+    const pid = ownership.pid;
+    const live = () => survivingOwnedGroups([pid]).length > 0;
+    if (live()) {
+      if (ownership.identity) await verifySpawnIdentity(ownership.identity);
+      else throw new AggregateError(ownership.errors, 'Managed host spawn identity missing or unreadable; ownership retained');
+      // Reuse commandLifetime's existing grace and confirmation budgets; no new limit.
+      for (const [signal, limit] of [['SIGTERM', COMMAND_GRACE_MS], ['SIGKILL', COMMAND_CONFIRM_MS]] as const) {
+        if (!live()) break;
+        await signalOwnedProcess(ownership.identity, signal, true);
+        const deadline = Date.now() + limit;
+        while (live() && Date.now() < deadline) await sleep(20);
+      }
+      if (live()) throw new Error(`managed infrastructure group ${pid} did not stop; retained ${pidFile}`);
+    }
+  } else if (ownership.present) {
+    throw new AggregateError(ownership.errors, 'Managed host ownership uncertain; no established identity; receipt retained');
+  }
+  if (ownership.recordedPid && survivingOwnedGroups([ownership.recordedPid]).length) {
+    throw new AggregateError(ownership.errors, 'Managed host receipt still names a live or uncertain group; ownership retained');
+  }
+  const failures: unknown[] = [];
+  try { rmSync(pidFile, { force: true }); } catch (error) { failures.push(error); }
+  // A later CLI must still have this identity if clearing the damaged PID receipt failed.
+  if (!failures.length) {
+    try { rmSync(spawnReceiptPath(pidFile), { force: true }); } catch (error) { failures.push(error); }
+  }
+  if (failures.length) throw new AggregateError(failures, 'Managed host stopped but receipt cleanup failed');
+  hosts.delete(pidFile);
+}
+
 export async function pgliteDown(services: InfraService[], dataDir: string): Promise<void> {
+  const failures: unknown[] = [];
   for (const service of services) {
-    const pidFile = pidPath(dataDir, service.kind);
-    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 */ } }
-    }
-    rmSync(pidFile, { force: true });
+    try {
+      const pidFile = pidPath(dataDir, service.kind);
+      if (unsupportedKinds([service]).length && (hostOwnership(pidFile).present || hosts.has(pidFile))) {
+        throw new Error(`cannot stop recorded ${service.kind} infrastructure with this backing; use its owning runtime`);
+      }
+      await stopHost(pidFile);
+    } catch (error) { failures.push(error); }
   }
+  if (failures.length) throw new AggregateError(failures, 'Managed infrastructure retirement failed');
 }

package/src/pglite-host.mjs

@@ -84,12 +84,37 @@
 //   pg_try_advisory_lock on a held key returns true); a NOTIFY is delivered
 //   to the connection that sent it, not to the one that ran LISTEN.
 //   CREATE ROLE succeeds but connections never run as that role.
+//
+// Database timestamps use the World clock: PGlite reads Date.now() for now(),
+// CURRENT_TIMESTAMP, clock_timestamp() and transaction starts. Refresh the file
+// at each connection message; without a file the host uses machine time.
+// Gateway timers retain machineNow. A frozen database clock also freezes
+// pg_sleep; elapsed-time SQL and timeouts are not promised in that mode.
+// Randomness remains the host's own; no database schema objects are installed.
+import { errorMessage } from './error-message.mjs';
 import net from 'node:net';
-import { mkdirSync } from 'node:fs';
-import { PGlite } from '@electric-sql/pglite';
-import { vector } from '@electric-sql/pglite-pgvector';
+import { mkdirSync, readFileSync } from 'node:fs';
+import clockForm from '@volter/world-core/world-clock';
 import { fromNodeSocket } from 'pg-gateway/node';
 
+// ---- the World's time (above) --------------------------------
+const machineNow = Date.now.bind(Date);
+const clockFile = process.env.TWIN_WORLD_CLOCK_FILE;
+let worldClock = null;
+/** Read the World clock again: at each message a connection sends. */
+function readWorldClock() {
+  if (!clockFile) return;
+  try {
+    worldClock = clockForm.parseClock(readFileSync(clockFile, 'utf8'));
+  } catch (error) {
+    // no clock: the machine's time; a clock caught mid-write keeps the last one read until the next message
+    if (error?.code === 'ENOENT') worldClock = null;
+    else process.stderr.write(`pglite-host: clock read failed: ${errorMessage(error)}\n`);
+  }
+}
+readWorldClock();
+Date.now = () => (worldClock ? clockForm.clockNowMs(worldClock, machineNow()) : machineNow());
+
 // The contrib extensions shipped in @electric-sql/pglite/dist/contrib (the
 // module name; `uuid_ossp` installs as "uuid-ossp"). auto_explain is omitted:
 // it is a preload library with no CREATE EXTENSION control file.
@@ -101,6 +126,8 @@ const CONTRIB = [
   'pg_trgm', 'pg_visibility', 'pg_walinspect', 'pgcrypto', 'seg', 'tablefunc',
   'tcn', 'tsm_system_rows', 'tsm_system_time', 'unaccent', 'uuid_ossp',
 ];
+const { PGlite } = await import('@electric-sql/pglite');
+const { vector } = await import('@electric-sql/pglite-pgvector');
 const extensions = { vector };
 for (const name of CONTRIB) {
   const extension = (await import(`@electric-sql/pglite/contrib/${name}`))[name];
@@ -134,7 +161,7 @@ process.stderr.on('error', () => {});
 const initKeepAlive = setInterval(() => {}, 500);
 const dbReady = PGlite.create({ dataDir, extensions });
 dbReady.catch((error) => {
-  process.stderr.write(`pglite-host: backend failed to start: ${error?.message ?? error}\n`);
+  process.stderr.write(`pglite-host: backend failed to start: ${errorMessage(error)}\n`);
   process.exit(1);
 });
 
@@ -184,7 +211,7 @@ async function enter(token, session, data) {
       if (host && !host.busy && !host.wanting && !host.midBatch && host.status === 'T'
         && session.status !== 'T' && session.status !== 'E' && guestMessageAllowed(session, data)) {
         guestBatch = token;
-        guestStartedAt = Date.now();
+        guestStartedAt = machineNow();
         return 'guest';
       }
     }
@@ -451,7 +478,7 @@ async function flushClosed(db) {
     try {
       await db.execProtocolRaw(new Uint8Array(close));
       await db.execProtocolRaw(new Uint8Array([0x53, 0, 0, 0, 4])); // Sync
-    } catch { /* the backend's own failure surfaces on the next real message */ }
+    } catch (error) { process.stderr.write(`pglite-host: statement cleanup failed: ${errorMessage(error)}\n`); }
     if (heldStatements.get(nameKey(backend))?.closed) heldStatements.delete(nameKey(backend));
   }
 }
@@ -500,7 +527,9 @@ const READY_IDLE = Buffer.from([0x5a, 0, 0, 0, 5, 0x49]);
 
 /** A statement of the host's own around a guest; its failure (the holder's transaction already gone) is not fatal. */
 async function quiet(db, sql) {
-  try { await db.query(sql); } catch { /* the savepoint went with the transaction */ }
+  try { await db.query(sql); } catch (error) {
+    if (error?.code !== '3B001' && error?.code !== '25P01') throw error;
+  }
 }
 
 /** `response` with its last ReadyForQuery reporting `status`. */
@@ -532,7 +561,7 @@ function idleInTransactionFatal() {
 // the holder idle in its transaction past the limit while others wait: end it
 const idleWatch = setInterval(() => {
   // a guest holding its turn past GUEST_TURN_MS while others wait: its batch is refused, its savepoint undone
-  if (guestBatch !== null && waiters.length > 0 && Date.now() - guestStartedAt > GUEST_TURN_MS) {
+  if (guestBatch !== null && waiters.length > 0 && machineNow() - guestStartedAt > GUEST_TURN_MS) {
     const guest = sessions.get(guestBatch);
     const expired = guestBatch;
     if (guest && guest.guestRefused && !guest.guestRunning) {
@@ -541,7 +570,7 @@ const idleWatch = setInterval(() => {
       guest.guestExpired = true;
       guest.guestErrorSent = true;
       const host = sessions.get(holder);
-      if (host) host.idleSince += Date.now() - guestStartedAt;
+      if (host) host.idleSince += machineNow() - guestStartedAt;
       guestBatch = null;
       wakeAll();
     } else if (guest && guest.guestOpen && !guest.guestRunning) {
@@ -554,7 +583,7 @@ const idleWatch = setInterval(() => {
       }).then(() => {
         if (guestBatch !== expired) return;
         const host = sessions.get(holder);
-        if (host) host.idleSince += Date.now() - guestStartedAt;
+        if (host) host.idleSince += machineNow() - guestStartedAt;
         guestBatch = null;
         wakeAll();
       });
@@ -565,7 +594,7 @@ const idleWatch = setInterval(() => {
   // armed at ReadyForQuery inside a transaction, as Postgres arms it — never mid-pipeline
   // a holder waiting for its turn (behind a guest) is sending, not idle; a guest's turn is not the holder's idleness
   if (!session || session.busy || session.wanting || guestBatch !== null || session.terminated || (session.status !== 'T' && session.status !== 'E')) return;
-  if (Date.now() - session.idleSince < IDLE_IN_TRANSACTION_MS) return;
+  if (machineNow() - session.idleSince < IDLE_IN_TRANSACTION_MS) return;
   session.terminated = true;
   process.stderr.write('pglite-host: terminated a connection idle in its transaction while others waited\n');
   // the socket's close handler rolls the transaction back and releases the lock
@@ -727,7 +756,7 @@ function withoutEarlyReady(message, response) {
 const server = net.createServer(async (socket) => {
   const token = {};
   let holding = false;
-  const session = { socket, busy: false, idleSince: Date.now(), terminated: false, closed: false, status: null, midBatch: false,
+  const session = { socket, busy: false, idleSince: machineNow(), terminated: false, closed: false, status: null, midBatch: false,
     wanting: false, guestOpen: false, guestRefused: false, guestUnnamed: false, guestExpired: false, guestErrorSent: false, guestRunning: false, statements: new Map(),
     names: new Map() };
   sessions.set(token, session);
@@ -747,7 +776,7 @@ const server = net.createServer(async (socket) => {
     // next connection in — never leak a half-open transaction into a stranger
     void dbReady
       .then((db) => db.query('ROLLBACK'))
-      .catch(() => {})
+      .catch(error => { process.stderr.write(`pglite-host: connection cleanup failed: ${errorMessage(error)}\n`); })
       .then(() => {
         holding = false;
         release(token);
@@ -765,6 +794,7 @@ const server = net.createServer(async (socket) => {
       // after the closed connections' names are released (a reconnect's `s0` is its own again)
       data = scopeNames(session, client, false);
       const db = await dbReady;
+      readWorldClock();
       // a guest whose turn ran out: told once, the rest of its batch dropped until its Sync
       if (session.guestExpired) {
         if (data[0] === 0x53) { session.guestExpired = false; session.guestErrorSent = false; session.status = 'I'; return READY_IDLE; }
@@ -785,7 +815,7 @@ const server = net.createServer(async (socket) => {
           session.guestUnnamed = false;
           // the holder's idle clock stops while a guest runs, and goes on from where it was
           const host = sessions.get(holder);
-          if (host) host.idleSince += Date.now() - guestStartedAt;
+          if (host) host.idleSince += machineNow() - guestStartedAt;
           wakeAll();
         };
         // a batch refused mid-way: its remaining messages are dropped until its Sync, as Postgres skips after an error
@@ -811,7 +841,7 @@ const server = net.createServer(async (socket) => {
         try {
           raw = await db.execProtocolRaw(refuseStatements(data, own));
         } catch (error) {
-          process.stderr.write(`pglite-host: backend aborted: ${error?.message ?? error}\n`);
+          process.stderr.write(`pglite-host: backend aborted: ${errorMessage(error)}\n`);
           process.exit(1);
         }
         const response = withoutEarlyReady(data, raw);
@@ -847,11 +877,11 @@ const server = net.createServer(async (socket) => {
         // SQL errors arrive as ErrorResponse bytes; a throw means the WASM
         // backend itself aborted and every later call would hang. Exit so the
         // World sees the service down (status fails) instead of a wedged port.
-        process.stderr.write(`pglite-host: backend aborted: ${error?.message ?? error}\n`);
+        process.stderr.write(`pglite-host: backend aborted: ${errorMessage(error)}\n`);
         process.exit(1);
       }
       session.busy = false;
-      session.idleSince = Date.now();
+      session.idleSince = machineNow();
       const response = withoutEarlyReady(data, raw);
       settleClose(session, closes, response);
       const status = lastReadyStatus(response);

package/src/placeholder.ts

@@ -5,17 +5,18 @@
 // `diff` reads empty, nothing is pending. `reset` is a pull from the placeholder again — down
 // with purge, up, seed — so a world returns to its defaults at any time; local work you want to
 // keep is a fork, taken before.
+import { randomUUID } from 'node:crypto';
+import { claimEnvOutput } from './env-output.ts';
 import { materializeRoots } from './root.ts';
 import { loadWorldConfig } from './configs.ts';
 import { WorldDoors, servedName } from './served-world.ts';
-import { randomUUID } from 'node:crypto';
 import { existsSync, readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { serveHttp, beginPlaceholderPull, endPlaceholderPull, listEvents, PLACEHOLDER_REMOTE, worldStateRoot } from '@volter/world-core/runtime';
+import { serveHttp, beginPlaceholderPull, endPlaceholderPull, listEvents, PLACEHOLDER_REMOTE, stateDirName, worldStateRoot } from '@volter/world-core/runtime';
 import { downWorld, runWithWorldEnv, saveWorldInstance, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 
-export type SeedWorldOptions = { root?: string; entry?: string; cwd?: string };
+export type SeedWorldOptions = { root?: string; entry?: string; cwd?: string; /** Reset writes a new live environment output; never an input file. */ envFile?: string };
 export type SeedWorldOutcome = { world: string; entry: string; exitCode: number; observed: Record<string, number> };
 
 /** The seed entry `init` emits beside the world config, unless the caller names one. */
@@ -87,17 +88,21 @@ export async function seedWorld(name: string, options: SeedWorldOptions = {}): P
   return { world: name, entry, exitCode, observed };
 }
 
-/** Back to the defaults: down with purge, up from the same config and env file, seed. */
+/** Back to the defaults: down with purge, up from the same config and a fresh env output, seed. */
 export async function resetWorld(name: string, options: SeedWorldOptions = {}): Promise<SeedWorldOutcome & { instance: WorldInstance }> {
   const root = resolve(options.root ?? process.cwd());
   const before = statusWorld(name, root);
   // A world whose twins ship no default data has no seed entry: back to the defaults is back to
   // empty, and that is a reset too — not an error.
   const entry = existsSync(resolve(options.entry ?? join(dirname(before.configPath), 'seed.ts'))) ? seedEntryFor(before, options.entry) : null;
+  // Purge removes the previous output's ownership receipt. Select and validate a fresh output before
+  // destroying state; never force an overwrite of a file that may hold credentials.
+  const envFile = resolve(options.envFile ?? join(dirname(before.envFile), `${name}.reset-${randomUUID()}.world.env`));
+  claimEnvOutput(envFile, join(root, stateDirName(), 'env-output-backups'));
   const stopped = await downWorld(name, root, { purge: true });
   if (!stopped.purged || stopped.externalErrors.length) throw new Error(`World reset refused: teardown did not purge the old instance (${stopped.externalErrors.join('; ')})`);
   // a world booted from a config PATH re-ups from that path; one booted by id, by id
-  const booted = await upWorld(existsSync(before.configPath) ? before.configPath : before.config, { name, root, mode: before.mode, envFile: before.envFile });
+  const booted = await upWorld(existsSync(before.configPath) ? before.configPath : before.config, { name, root, mode: before.mode, owner: before.lifecycle?.owner ?? before.resources?.owner, envFile });
   // the origin belongs to the branch, not to its running state (git: a reset keeps the remote);
   // the cursors do not — the mirror is gone, so the next fetch starts from the beginning
   const instance = before.origin === undefined ? booted : { ...booted, origin: { url: before.origin.url, namespace: before.origin.namespace, ...(before.origin.clonedAt ? { clonedAt: before.origin.clonedAt } : {}) } };

package/src/process-groups.d.mts

@@ -0,0 +1,2 @@
+export function survivingOwnedGroups(pids: number[]): number[];
+export function processStarts(pids: number[]): Map<number, string>;

package/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;
+}
+