@volter/world-runtime 2.0.0

package/src/pglite-host.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// One managed-infrastructure postgres service, served without a container:
+// PGlite (real Postgres compiled to WASM) behind a pg-gateway wire-protocol
+// front. Spawned by `volter-world-infra` when the pglite backing is
+// selected; never operated directly (the same contract as the compose file).
+//
+// Plain .mjs under node, deliberately: PGlite's WASM init does not complete
+// under bun, and under node its create() promise only progresses while
+// something holds the event loop — an interval carries the init, and the TCP
+// server starts listening only once the backend is ready, so a port that
+// answers is a port that serves.
+//
+// PGlite is a SINGLE-SESSION backend, so this host serializes connections
+// with a transaction-affinity lock: a connection acquires the global lock at
+// its first protocol message and keeps it for as long as the backend reports
+// an open transaction (ReadyForQuery status != 'I'). Without the hold, two
+// pooled clients interleave into one session and a ROLLBACK on one swallows
+// the other's writes. A connection that dies mid-transaction is rolled back
+// before the lock is released.
+//
+// Identity is aliased, not faked: trust auth accepts the world's declared
+// user/password/database, but the backend is PGlite's single `postgres`
+// database — apps that introspect current_database() will see that. Worlds
+// accept this; an app needing true multi-database Postgres needs the
+// container backing.
+import net from 'node:net';
+import { mkdirSync } from 'node:fs';
+import { PGlite } from '@electric-sql/pglite';
+import { fromNodeSocket } from 'pg-gateway/node';
+
+function arg(name) {
+  const index = process.argv.indexOf(name);
+  const value = index >= 0 ? process.argv[index + 1] : undefined;
+  if (!value) {
+    process.stderr.write(`pglite-host: ${name} is required\n`);
+    process.exit(2);
+  }
+  return value;
+}
+
+const port = Number(arg('--port'));
+const dataDir = arg('--data');
+if (!Number.isInteger(port) || port < 1 || port > 65535) {
+  process.stderr.write('pglite-host: --port must be 1-65535\n');
+  process.exit(2);
+}
+
+mkdirSync(dataDir, { recursive: true });
+// stdio may be a log fd whose reader is gone; never die on a status line
+process.stdout.on('error', () => {});
+process.stderr.on('error', () => {});
+// PGlite's create() only progresses while something holds the event loop;
+// listening starts AFTER readiness so "port answers" means "serves queries"
+const initKeepAlive = setInterval(() => {}, 500);
+const dbReady = PGlite.create({ dataDir });
+dbReady.catch((error) => {
+  process.stderr.write(`pglite-host: backend failed to start: ${error?.message ?? error}\n`);
+  process.exit(1);
+});
+
+// ---- transaction-affinity lock ---------------------------------------------
+let holder = null;
+const waiters = [];
+async function acquire(token) {
+  while (holder !== null && holder !== token) {
+    await new Promise((resolve) => waiters.push(resolve));
+  }
+  holder = token;
+}
+function release(token) {
+  if (holder !== token) return;
+  holder = null;
+  const next = waiters.shift();
+  if (next) next();
+}
+
+/** The transaction status of the LAST ReadyForQuery ('Z') message in a raw
+ * protocol response, or null when the response carries none (mid-pipeline:
+ * the sender keeps the lock). 'I' = idle, 'T' = in transaction, 'E' = failed
+ * transaction. */
+function lastReadyStatus(response) {
+  let status = null;
+  let offset = 0;
+  while (offset + 5 <= response.length) {
+    const type = response[offset];
+    const length = (response[offset + 1] << 24) | (response[offset + 2] << 16)
+      | (response[offset + 3] << 8) | response[offset + 4];
+    if (length < 4) break; // malformed; stop scanning rather than loop
+    if (type === 0x5a /* 'Z' */ && offset + 5 < response.length) {
+      status = String.fromCharCode(response[offset + 5]);
+    }
+    offset += 1 + length;
+  }
+  return status;
+}
+
+const server = net.createServer(async (socket) => {
+  const token = {};
+  let holding = false;
+  socket.on('close', () => {
+    if (!holding) return;
+    // the client vanished inside its transaction: roll it back, then let the
+    // next connection in — never leak a half-open transaction into a stranger
+    void dbReady
+      .then((db) => db.query('ROLLBACK'))
+      .catch(() => {})
+      .then(() => {
+        holding = false;
+        release(token);
+      });
+  });
+  socket.on('error', () => { /* close handler owns cleanup */ });
+  await fromNodeSocket(socket, {
+    serverVersion: '18.3 (PGlite)',
+    auth: { method: 'trust' },
+    async onMessage(data, { isAuthenticated }) {
+      if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
+      const db = await dbReady;
+      await acquire(token);
+      holding = true;
+      const response = await db.execProtocolRaw(data);
+      const status = lastReadyStatus(response);
+      if (status === 'I') {
+        holding = false;
+        release(token);
+      }
+      return response;
+    },
+  });
+});
+
+void dbReady.then(() => {
+  clearInterval(initKeepAlive);
+  server.listen(port, '127.0.0.1', () => {
+    process.stdout.write(`pglite-host serving postgres wire protocol on 127.0.0.1:${port}\n`);
+  });
+});
+
+for (const signal of ['SIGTERM', 'SIGINT']) {
+  process.on(signal, () => {
+    server.close(() => {
+      void dbReady.then((db) => db.close()).finally(() => process.exit(0));
+    });
+    // a hung close must not make `down` hang the world
+    setTimeout(() => process.exit(0), 3000).unref();
+  });
+}

package/src/placeholder.ts

@@ -0,0 +1,89 @@
+// `volter-world seed <world>` and `volter-world reset <world>` — the placeholder remote's verbs
+// (docs/concepts/the-model.md#a-branch-is-a-position-not-a-copy, "default data"). `seed` opens every twin's placeholder-pull window,
+// runs the world's seed entry under the world env (the pack defaults and your story, through each
+// vendor's own API), and closes the windows: the seed lands as the placeholder's observed state,
+// `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 { materializeRoots } from './root.ts';
+import { loadWorldConfig } from './configs.ts';
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { beginPlaceholderPull, endPlaceholderPull, listEvents, PLACEHOLDER_REMOTE, worldStateRoot } from '@volter/world-core';
+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 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. */
+export function seedEntryFor(instance: WorldInstance, entry?: string): string {
+  const path = resolve(entry ?? join(dirname(instance.configPath), 'seed.ts'));
+  if (!existsSync(path)) throw new Error(`No seed entry at ${path} — \`volter-world init\` writes one beside the world config (seed.ts); pass --entry <file> to name another`);
+  return path;
+}
+
+/** Placeholder rows under one world service's root, summed across every state service the twin
+ *  records under (slack records under `chat`): every state dir with an events log, whether or not
+ *  an actions log exists yet (a placeholder-only twin has none). */
+function placeholderCount(controlRoot: string): number {
+  const stateRoot = worldStateRoot(controlRoot);
+  if (!existsSync(stateRoot)) return 0;
+  let n = 0;
+  for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !existsSync(join(stateRoot, entry.name, 'events.jsonl'))) continue;
+    try { n += listEvents(entry.name, controlRoot).filter((e) => (e.data as { remote?: unknown } | undefined)?.remote === PLACEHOLDER_REMOTE).length; } catch { /* unreadable ledger: not counted */ }
+  }
+  return n;
+}
+
+/** Pull from the placeholder: every twin's window open around the seed entry. */
+export async function seedWorld(name: string, options: SeedWorldOptions = {}): Promise<SeedWorldOutcome> {
+  const root = resolve(options.root ?? process.cwd());
+  const instance = statusWorld(name, root);
+  const entry = seedEntryFor(instance, options.entry);
+  const services = Object.keys(instance.services).sort();
+  const at = new Date().toISOString();
+  for (const service of services) beginPlaceholderPull(service, join(instance.dirs.data, service), at);
+  let exitCode = 1;
+  try {
+    // The runtime that is running runs the seed: Bun, or Node with its TypeScript type stripping
+    // (`--experimental-strip-types`, accepted from Node 22.6 and on by default since 23.6). Never
+    // `bun` by name: the published runtime supports Node alone, and the tab's engine has no Bun.
+    if (typeof Bun === 'undefined' && /\.[cm]?ts$/.test(entry)) {
+      const [major, minor] = process.versions.node.split('.').map(Number) as [number, number];
+      if (major < 22 || (major === 22 && minor < 6)) throw new Error(`${entry} is TypeScript: seeding it under Node needs Node 22.6 or newer (type stripping), or Bun; this is Node ${process.versions.node}`);
+    }
+    const runner = typeof Bun !== 'undefined' ? ['bun', entry] : [process.execPath, '--experimental-strip-types', '--no-warnings', entry];
+    exitCode = await runWithWorldEnv(name, runner, root, { cwd: options.cwd ?? dirname(entry) });
+  } finally {
+    for (const service of services) endPlaceholderPull(service, join(instance.dirs.data, service));
+  }
+  const observed: Record<string, number> = {};
+  for (const service of services) observed[service] = placeholderCount(join(instance.dirs.data, service));
+  return { world: name, entry, exitCode, observed };
+}
+
+/** Back to the defaults: down with purge, up from the same config and env file, 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;
+  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 });
+  // 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 } : {}) } };
+  if (before.origin !== undefined) saveWorldInstance(instance);
+  // the roots reach the twins' state after the default data, so the seed runs simulated (as a fresh `up` does)
+  const rooted = () => materializeRoots(loadWorldConfig(existsSync(before.configPath) ? before.configPath : before.config, root).config, booted.dirs.data, root);
+  if (entry === null) { rooted(); return { world: name, entry: '', exitCode: 0, observed: {}, instance }; }
+  try {
+    const seeded = await seedWorld(name, { root, entry, ...(options.cwd ? { cwd: options.cwd } : {}) });
+    return { ...seeded, instance };
+  } finally { rooted(); }
+}

package/src/prerequisites.ts

@@ -0,0 +1,66 @@
+import { spawnSync } from 'node:child_process';
+
+export type PrerequisiteId = 'local-execution';
+
+export type PrerequisiteCheck = {
+  id: PrerequisiteId;
+  ok: boolean;
+  label: string;
+  message: string;
+  guidance: string[];
+  details?: Record<string, string>;
+};
+
+type RunResult = { status: number | null; stdout: string; stderr: string };
+type Runner = (cmd: string, args: string[]) => RunResult;
+
+const realRunner: Runner = (cmd, args) => {
+  const result = spawnSync(cmd, args, { encoding: 'utf8' });
+  return {
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+};
+
+/** Private implementation probe behind the public World capability name. Its implementation and
+ * diagnostics never become instructions for application agents. */
+export function checkLocalExecution(runner: Runner = realRunner): PrerequisiteCheck {
+  const info = runner('docker', ['info']);
+  if (info.status === 0) {
+    return {
+      id: 'local-execution',
+      ok: true,
+      label: 'Local execution',
+      message: 'Local execution capacity is available.',
+      guidance: [],
+    };
+  }
+
+  return {
+    id: 'local-execution',
+    ok: false,
+    label: 'Local execution',
+    message: 'Local execution capacity is unavailable.',
+    guidance: [
+      'Run the World through `volter-world up`, then use `volter-world doctor <world>` and its declared service log if startup still fails.',
+      'Do not start, inspect, or clean up a backing runtime separately; the declared World service owns it.',
+    ],
+  };
+}
+
+export function checkPrerequisites(ids: PrerequisiteId[], runner: Runner = realRunner): PrerequisiteCheck[] {
+  return ids.map((id) => {
+    if (id === 'local-execution') return checkLocalExecution(runner);
+    throw new Error(`Unknown prerequisite: ${id}`);
+  });
+}
+
+export function formatPrerequisiteChecks(checks: PrerequisiteCheck[]): string {
+  return checks.flatMap((check) => {
+    const status = check.ok ? 'ok' : 'missing';
+    const lines = [`${status} ${check.label}: ${check.message}`];
+    if (!check.ok) lines.push(...check.guidance.map((line) => `  ${line}`));
+    return lines;
+  }).join('\n');
+}

package/src/process-groups.ts

@@ -0,0 +1,33 @@
+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: number[]): number[] {
+  const candidates = pids.filter(pid => {
+    try { process.kill(process.platform === 'win32' ? pid : -pid, 0); return true; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ESRCH') return true;
+      try { process.kill(pid, 0); return true; }
+      catch (cause) { return (cause as NodeJS.ErrnoException).code !== 'ESRCH'; }
+    }
+  });
+  if (!candidates.length || process.platform === 'win32') return candidates;
+  const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], {
+    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 as NodeJS.ErrnoException).code !== 'ESRCH') return true; }
+      }
+      return false;
+    }
+    return members.some(([, , state]) => !state || !state.startsWith('Z'));
+  });
+}