@volter/twin-world 0.1.0 → 0.1.2

package/src/inject-map.ts

@@ -0,0 +1,70 @@
+// The ONE world-runtime home for the injector's host→twin knowledge (`@volter/twin/inject`:
+// `VENDOR_HOSTS` + `readMap` + `resolveTwin` + `twinUrlVendor`). The redirect proxy, `covers`,
+// and `up`'s inert-injectEnv warning all read the injector THROUGH this module, so none of them
+// can re-encode (and silently drift from) what the injector actually redirects — the exact
+// failure mode of the LibreChat blind-adoption run, where a world injected AWS_TWIN_URL that no
+// injector vendor reads and nothing said so.
+import { createRequire } from 'node:module';
+
+/** The slice of `@volter/twin/inject` reused here (data + pure functions only). */
+export type InjectModule = {
+  readMap(env: Record<string, string | undefined>): Record<string, string>;
+  /** `pathname` is optional; it only disambiguates hosts two vendors share (see inject.cjs). */
+  resolveTwin(host: string, map: Record<string, string>, pathname?: string): { vendor: string; origin: string } | null;
+  /** `S3_TWIN_URL` → 's3'; a `*_TWIN_URL` name readMap would never read → null. */
+  twinUrlVendor(name: string): string | null;
+  VENDOR_HOSTS: Record<string, (host: string, pathname?: string) => boolean>;
+  restore(): void;
+};
+
+let injectCache: InjectModule | null = null;
+
+/** Lazily load the injector's host→twin table. Loading the CJS auto-installs its http/fetch
+ * patches as a side effect; we immediately `restore()` so requiring it here is inert (we only
+ * want the data + pure functions, not to patch THIS process). */
+export function loadInject(): InjectModule {
+  if (injectCache) return injectCache;
+  const require = createRequire(import.meta.url);
+  const mod = require('@volter/twin/inject') as InjectModule;
+  try { mod.restore(); } catch { /* nothing was installed */ }
+  injectCache = mod;
+  return mod;
+}
+
+/** The vendor keys the injector can redirect for (the keys of VENDOR_HOSTS). */
+export function injectableVendorKeys(): Set<string> {
+  return new Set(Object.keys(loadInject().VENDOR_HOSTS));
+}
+
+/** Does the injector actually read this env var name? (`S3_TWIN_URL` → 's3'; `AWS_TWIN_URL`
+ * → null — the consolidated aws twin answers under the s3/dynamodb/timestream keys.) */
+export function twinUrlVendorFor(name: string): string | null {
+  return loadInject().twinUrlVendor(name);
+}
+
+/** WARN lines for twin-shaped injectEnv vars the injector will never read — an injectEnv like
+ * `AWS_TWIN_URL` is written into the world env, looks wired, and does NOTHING (readMap iterates
+ * VENDOR_HOSTS keys looking for `<VENDOR>_TWIN_URL`; there is no `aws` vendor key). `up` prints
+ * these loudly so the disagreement is visible at boot instead of surfacing as silently-real
+ * vendor traffic later. Vars that do not end in `_TWIN_URL` are app-read config (SUPABASE_URL,
+ * LIVEKIT_URL, …), not injector input — never warned about. */
+export function inertInjectEnvWarnings(
+  services: Array<{ id: string; injectEnv?: string }>,
+): string[] {
+  const warnings: string[] = [];
+  for (const service of services) {
+    const name = service.injectEnv;
+    if (!name || !/_TWIN_URL$/.test(name)) continue;
+    if (twinUrlVendorFor(name) !== null) continue;
+    const stem = name.replace(/_TWIN_URL$/, '');
+    const hint = stem.toUpperCase() === 'AWS'
+      ? ' The consolidated aws twin is read under its per-AREA keys — S3_TWIN_URL / DYNAMODB_TWIN_URL / TIMESTREAM_TWIN_URL / SESV2_TWIN_URL / SECRETSMANAGER_TWIN_URL / BEDROCK_TWIN_URL — point those at the aws twin instead.'
+      : '';
+    warnings.push(
+      `[volter-world] WARN: service "${service.id}" injects ${name}, but the injector reads no such vendor` +
+      ` ("${stem.toLowerCase()}" is not a VENDOR_HOSTS key in @volter/twin/inject) — the var is INERT and this` +
+      ` vendor's SDK traffic will NOT be redirected to the twin.${hint}`,
+    );
+  }
+  return warnings;
+}

package/src/managed-infra-cli.ts

@@ -0,0 +1,208 @@
+#!/usr/bin/env bun
+// Private implementation for infrastructure emitted by `volter-world init`. World configs invoke
+// this declared service; application agents never operate or diagnose its backing mechanism.
+import { existsSync, readFileSync, statfsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const phase = process.argv[2];
+if (phase !== 'up' && phase !== 'status' && phase !== 'down') {
+  process.stderr.write('managed infrastructure: expected up, status, or down\n');
+  process.exit(2);
+}
+
+const worldConfig = process.env.VOLTER_WORLD_CONFIG;
+const worldData = process.env.VOLTER_WORLD_DATA;
+if (!worldConfig || !worldData) {
+  process.stderr.write('managed infrastructure: missing World lifecycle context\n');
+  process.exit(2);
+}
+const definition = join(dirname(worldConfig), 'world.infrastructure.yml');
+if (!existsSync(definition)) {
+  process.stderr.write('managed infrastructure: declared definition is missing\n');
+  process.exit(2);
+}
+
+const base = ['compose', '-f', definition];
+const MIB = 1024 * 1024;
+const run = (args: string[]) => spawnSync('docker', [...base, ...args], {
+  encoding: 'utf8',
+  env: { ...process.env, VOLTER_WORLD_DATA: worldData },
+  timeout: 120_000,
+});
+const classify = (raw: string): string => /no space left on device|enospc/iu.test(raw)
+  ? 'insufficient writable storage'
+  : /out of memory|cannot allocate memory|killed/iu.test(raw)
+    ? 'insufficient memory'
+    : /cannot connect|not running|daemon/iu.test(raw)
+      ? 'local execution capacity is unavailable'
+      : 'managed infrastructure operation failed';
+const fail = (result: ReturnType<typeof run>): never => {
+  const raw = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+  process.stderr.write(`managed infrastructure ${phase} failed: ${classify(raw)}\n`);
+  process.exit(result.status && result.status > 0 ? result.status : 1);
+};
+
+function writableStorageAvailableMiB(rootDir: string): number | undefined {
+  if (rootDir && existsSync(rootDir)) {
+    const fs = statfsSync(rootDir);
+    return Math.floor((Number(fs.bavail) * Number(fs.bsize)) / MIB);
+  }
+  const context = spawnSync('docker', ['context', 'inspect', '--format', '{{json .Endpoints.docker.Host}}'], { encoding: 'utf8', timeout: 5_000 });
+  let endpoint = '';
+  try { endpoint = context.status === 0 ? JSON.parse(context.stdout.trim() || '""') as string : ''; } catch { return undefined; }
+  const match = /\/colima\/([^/]+)\/docker\.sock$/u.exec(endpoint);
+  if (!match) return undefined;
+  const config = spawnSync('colima', ['-p', match[1]!, 'ssh-config'], { encoding: 'utf8', timeout: 5_000 });
+  if (config.status !== 0) return undefined;
+  const field = (name: string): string | undefined => {
+    const value = new RegExp(`^\\s*${name}\\s+(.+?)\\s*$`, 'mu').exec(config.stdout)?.[1];
+    return value?.replace(/^"|"$/gu, '');
+  };
+  const identity = field('IdentityFile');
+  const user = field('User');
+  const host = field('Hostname');
+  const port = field('Port');
+  const controlPath = field('ControlPath');
+  if (!identity || !user || !host || !port) return undefined;
+  const status = spawnSync('ssh', [
+    '-o', 'StrictHostKeyChecking=no', '-o', 'UserKnownHostsFile=/dev/null', '-o', 'BatchMode=yes',
+    '-o', 'IdentitiesOnly=yes', ...(controlPath ? ['-o', 'ControlMaster=auto', '-o', `ControlPath=${controlPath}`, '-o', 'ControlPersist=yes'] : []),
+    '-i', identity, '-p', port, `${user}@${host}`, 'df', '-Pk', rootDir || '/',
+  ], { encoding: 'utf8', timeout: 5_000 });
+  if (status.status !== 0) return undefined;
+  const fields = (status.stdout.trim().split(/\r?\n/u).at(-1) ?? '').trim().split(/\s+/u);
+  const availableKiB = Number(fields[3]);
+  return Number.isFinite(availableKiB) ? Math.floor(availableKiB / 1024) : undefined;
+}
+
+function admit(): void {
+  const requestedMemoryMiB = Number(process.env.VOLTER_WORLD_RESOURCE_MEMORY_MIB ?? 0);
+  const requestedStorageMiB = Number(process.env.VOLTER_WORLD_RESOURCE_WRITABLE_STORAGE_MIB ?? 0);
+  const info = spawnSync('docker', ['info', '--format', '{{.MemTotal}} {{.DockerRootDir}}'], { encoding: 'utf8', timeout: 15_000 });
+  if (info.status !== 0) {
+    process.stderr.write(`managed infrastructure resource admission refused: ${classify(`${info.stdout ?? ''}\n${info.stderr ?? ''}`)}\n`);
+    process.exit(1);
+  }
+  const [memoryRaw, rootDir = ''] = info.stdout.trim().split(/\s+/u);
+  const totalMemoryMiB = Math.floor(Number(memoryRaw) / MIB);
+  if (!Number.isFinite(totalMemoryMiB) || requestedMemoryMiB + 1024 > totalMemoryMiB) {
+    process.stderr.write(`managed infrastructure resource admission refused: memory requires ${requestedMemoryMiB} MiB plus 1024 MiB safety, ${totalMemoryMiB || 0} MiB available\n`);
+    process.exit(1);
+  }
+  const storageMiB = writableStorageAvailableMiB(rootDir);
+  if (storageMiB === undefined) {
+    process.stderr.write('managed infrastructure resource admission refused: writable-storage capacity could not be verified\n');
+    process.exit(1);
+  }
+  if (requestedStorageMiB + 2048 > storageMiB) {
+    process.stderr.write(`managed infrastructure resource admission refused: writable storage requires ${requestedStorageMiB} MiB plus 2048 MiB safety, ${storageMiB} MiB available\n`);
+    process.exit(1);
+  }
+}
+
+// ---- backing selection ------------------------------------------------------
+// The declared service contract (up/status/down) is the boundary; WHICH
+// runtime answers it is private and chosen here, per machine, at each phase:
+//   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite — explicit, for tests/operators;
+//   2. a working container runtime — the compose path, byte-identical to before;
+//   3. no container runtime + a postgres-only definition — the PGlite backing
+//      (pglite-host.ts), announced loudly;
+//   4. otherwise the honest refusal naming what this machine cannot serve.
+function selectBacking(): 'docker' | 'pglite' {
+  const forced = process.env.VOLTER_WORLD_INFRA_BACKING;
+  if (forced === 'docker' || forced === 'pglite') return forced;
+  if (forced !== undefined) {
+    process.stderr.write(`managed infrastructure: VOLTER_WORLD_INFRA_BACKING must be docker or pglite (got ${JSON.stringify(forced)})\n`);
+    process.exit(2);
+  }
+  const probe = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { encoding: 'utf8', timeout: 10_000 });
+  if (probe.status === 0) return 'docker';
+  // Absence of a container runtime (no binary, no daemon) is a capability
+  // difference: swap backings. A PRESENT runtime failing on resources stays
+  // on the docker path so the real capacity problem is classified and
+  // surfaced — a full disk starves every backing equally.
+  if (probe.error !== undefined) return 'pglite';
+  const reason = classify(`${probe.stdout ?? ''}\n${probe.stderr ?? ''}`);
+  return reason === 'local execution capacity is unavailable' ? 'pglite' : 'docker';
+}
+
+async function runPglite(): Promise<never> {
+  const { parseInfraDefinition, unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
+  const services = parseInfraDefinition(readFileSync(definition, 'utf8'));
+  if (services.length === 0) {
+    process.stderr.write('managed infrastructure: the declared definition names no services\n');
+    process.exit(1);
+  }
+  const unsupported = unsupportedKinds(services);
+  if (unsupported.length > 0) {
+    process.stderr.write(`managed infrastructure ${phase} failed: local execution capacity is unavailable (no container runtime, and the containerless backing cannot serve: ${unsupported.join(', ')})\n`);
+    process.exit(1);
+  }
+  if (phase === 'up') {
+    admitPglite();
+    process.stdout.write('managed infrastructure backing: pglite (no container runtime)\n');
+    try {
+      await pgliteUp(services, worldData!);
+    } catch (error) {
+      process.stderr.write(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
+      process.exit(1);
+    }
+    process.stdout.write('managed infrastructure ready\n');
+    process.exit(0);
+  }
+  if (phase === 'status') {
+    const status = await pgliteStatus(services, worldData!);
+    if (!status.ok) {
+      process.stderr.write(`managed infrastructure status failed: ${status.ready}/${services.length} declared services are ready\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`${JSON.stringify({ ok: true, services: services.length })}\n`);
+    process.exit(0);
+  }
+  await pgliteDown(services, worldData!);
+  process.stdout.write('managed infrastructure stopped\n');
+  process.exit(0);
+}
+
+/** Admission without a container runtime: same declared bounds, measured on
+ * the host directly (PGlite runs in-process, its bytes under VOLTER_WORLD_DATA). */
+function admitPglite(): void {
+  const requestedStorageMiB = Number(process.env.VOLTER_WORLD_RESOURCE_WRITABLE_STORAGE_MIB ?? 0);
+  const storageMiB = writableStorageAvailableMiB(worldData!);
+  if (storageMiB === undefined) {
+    process.stderr.write('managed infrastructure resource admission refused: writable-storage capacity could not be verified\n');
+    process.exit(1);
+  }
+  if (requestedStorageMiB + 2048 > storageMiB) {
+    process.stderr.write(`managed infrastructure resource admission refused: writable storage requires ${requestedStorageMiB} MiB plus 2048 MiB safety, ${storageMiB} MiB available\n`);
+    process.exit(1);
+  }
+}
+
+if (selectBacking() === 'pglite') {
+  await runPglite();
+}
+
+if (phase === 'up') {
+  admit();
+  const result = run(['up', '-d', '--wait']);
+  if (result.status !== 0) fail(result);
+  process.stdout.write('managed infrastructure ready\n');
+} else if (phase === 'status') {
+  const expected = run(['config', '--services']);
+  if (expected.status !== 0) fail(expected);
+  const running = run(['ps', '--status', 'running', '--services']);
+  if (running.status !== 0) fail(running);
+  const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).sort();
+  const runningNames = running.stdout.split(/\s+/u).filter(Boolean).sort();
+  if (expectedNames.length === 0 || expectedNames.join('\0') !== runningNames.join('\0')) {
+    process.stderr.write(`managed infrastructure status failed: ${runningNames.length}/${expectedNames.length} declared services are ready\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`${JSON.stringify({ ok: true, services: expectedNames.length })}\n`);
+} else {
+  const result = run(['down', '--remove-orphans']);
+  if (result.status !== 0) fail(result);
+  process.stdout.write('managed infrastructure stopped\n');
+}

package/src/pack-facts.ts

@@ -0,0 +1,136 @@
+// PACK FACTS OVERLAY — the world-runtime consumer of the generated pack-facts artifact
+// (packages/twin/control-plane/generated/pack-facts.json, compiled by scripts/pack-facts.ts
+// from each pack's `pack: TwinPack` descriptor).
+//
+// During the TWIN-PACK-CONTRACT migration (company-repo BRIEFS/TWIN-PACK-CONTRACT.md), the
+// adoption tables here are the UNION of the legacy central maps and the pack declarations.
+// The overlay MUTATES the central tables at module init — every use-site keeps reading the
+// object it always read — and a fact declared in BOTH places throws: dual declaration is the
+// drift this migration exists to end, so it is loud everywhere, not just in a test.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type PackAdoption = { sdks?: string[]; pypi?: string[]; scopes?: string[]; envStems?: string[]; worldIds?: string[] };
+export type PackFacts = {
+  adoption?: PackAdoption;
+  hosts?: Array<{ host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true }>;
+  hostsNone?: string;
+  endpointEnv?: { name: string; templates?: Record<string, string>; note: string };
+  endpointEnvNone?: string;
+  /** The pack's colocatable `create<Name>TwinServer` factory export, derived (or descriptor-
+   *  declared under ambiguity) by scripts/pack-facts.ts. Consumed by `init` to emit
+   *  `colocate:` service entries so a world's twins boot inside ONE host process (R2a). */
+  serveExport?: string;
+};
+
+// The artifact is committed in the control plane and shipped with it: resolved through the package (@volter/twin,
+// installed or workspace-linked), else the sibling workspace path. A missing file is a broken checkout (or an
+// unbuilt generator change), never a soft state.
+const FACTS_PATH = (() => {
+  try { return fileURLToPath(import.meta.resolve('@volter/twin/generated/pack-facts.json')); } catch { /* not resolvable: a checkout without node_modules */ }
+  return join(import.meta.dir, '..', '..', 'control-plane', 'generated', 'pack-facts.json');
+})();
+
+let cached: Record<string, PackFacts> | null = null;
+export function packFacts(): Record<string, PackFacts> {
+  if (cached !== null) return cached;
+  let raw: string;
+  try {
+    raw = readFileSync(FACTS_PATH, 'utf8');
+  } catch (error) {
+    throw new Error(
+      `pack-facts artifact missing at ${FACTS_PATH} — run \`bun scripts/pack-facts.ts\` at the twin repo root and commit the result (${String(error)})`,
+    );
+  }
+  cached = (JSON.parse(raw) as { packs: Record<string, PackFacts> }).packs;
+  return cached;
+}
+
+const dual = (vendor: string, kind: string, key: string, holder: string): Error =>
+  new Error(
+    `pack-facts: ${kind} "${key}" is declared BOTH on the ${vendor} pack descriptor AND in the central ${holder} table — ` +
+    `the migration rule is one home per fact. Delete the central entry (the descriptor wins).`,
+  );
+
+/** Overlay descriptor-declared npm SDK names onto the central SDK_TWINS map (project-inspect.ts). */
+/** The PyPI half of the SDK map, built the same way from each descriptor's `adoption.pypi`
+ *  (PEP 503 names). One name belongs to one pack; a second claim refuses at load. */
+export function overlayPypiTwins(pypiTwins: Record<string, { vendor: string; twin: string }>): void {
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    for (const raw of facts.adoption?.pypi ?? []) {
+      const name = normalizePypiName(raw);
+      if (Object.hasOwn(pypiTwins, name)) {
+        const holder = pypiTwins[name]!.vendor;
+        if (holder !== vendor) throw new Error(`pack-facts overlay: pypi package "${name}" is claimed by BOTH the "${holder}" and "${vendor}" packs' descriptors — one name, one pack`);
+        continue;
+      }
+      pypiTwins[name] = { vendor, twin: `@volter/twin-${vendor}` };
+    }
+  }
+}
+/** PEP 503: case-insensitive, runs of `-_.` collapse to one `-`. */
+export function normalizePypiName(name: string): string {
+  return name.trim().toLowerCase().replace(/[-_.]+/g, '-');
+}
+
+export function overlaySdkTwins(sdkTwins: Record<string, { vendor: string; twin: string }>): void {
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    for (const sdk of facts.adoption?.sdks ?? []) {
+      // Object.hasOwn, not `in`: `in` walks the prototype chain, so a pathological name like
+      // 'constructor' would throw a bogus dual error. And when the holder is another PACK's
+      // overlay (two descriptors claiming one name), the right fix is different from a hand-
+      // table collision — say which it is (§9 round two L2, 2026-08-31).
+      if (Object.hasOwn(sdkTwins, sdk)) {
+        const holder = sdkTwins[sdk]!.vendor;
+        if (holder !== vendor) {
+          throw new Error(
+            `pack-facts overlay: npm sdk "${sdk}" is claimed by BOTH the "${holder}" and "${vendor}" packs' descriptors (or by ${holder} in the central SDK_TWINS table) — one home per fact: decide which pack owns the client and remove the other claim.`,
+          );
+        }
+        throw dual(vendor, 'sdk', sdk, 'SDK_TWINS');
+      }
+      sdkTwins[sdk] = { vendor, twin: `@volter/twin-${vendor}` };
+    }
+  }
+}
+
+/** Overlay descriptor-declared scopes/env stems/world ids onto covers.ts's central maps. */
+export function overlayCoversMaps(maps: {
+  scopeVendors: Record<string, string>;
+  envStemVendors: Record<string, string>;
+  vendorWorldIds: Record<string, string[]>;
+}): void {
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    for (const scope of facts.adoption?.scopes ?? []) {
+      if (scope in maps.scopeVendors) throw dual(vendor, 'scope', scope, 'SDK_SCOPE_VENDORS');
+      maps.scopeVendors[scope] = vendor;
+    }
+    for (const stemRaw of facts.adoption?.envStems ?? []) {
+      const stem = stemRaw.toLowerCase();
+      if (stem in maps.envStemVendors) throw dual(vendor, 'env stem', stem, 'ENV_STEM_VENDORS');
+      maps.envStemVendors[stem] = vendor;
+    }
+    const worldIds = facts.adoption?.worldIds ?? [];
+    if (worldIds.length > 0) {
+      if (vendor in maps.vendorWorldIds) throw dual(vendor, 'world ids', vendor, 'VENDOR_WORLD_IDS');
+      maps.vendorWorldIds[vendor] = [vendor, ...worldIds];
+    }
+  }
+}
+
+/** Overlay descriptor-declared endpoint-env wiring onto init.ts's APP_READ_ENDPOINT_ENV map. */
+export function overlayEndpointEnv(
+  table: Record<string, { injectEnv?: string; injectEnvTemplates?: Record<string, string>; note: string }>,
+): void {
+  for (const [vendor, facts] of Object.entries(packFacts())) {
+    if (facts.endpointEnv === undefined) continue;
+    if (vendor in table) throw dual(vendor, 'endpoint env', vendor, 'APP_READ_ENDPOINT_ENV');
+    table[vendor] = {
+      injectEnv: facts.endpointEnv.name,
+      ...(facts.endpointEnv.templates ? { injectEnvTemplates: facts.endpointEnv.templates } : {}),
+      note: facts.endpointEnv.note,
+    };
+  }
+}

package/src/pglite-backing.ts

@@ -0,0 +1,125 @@
+// The containerless backing for World-managed infrastructure: PGlite hosts
+// (see pglite-host.ts) instead of docker compose. Selected by
+// `volter-world-managed-infra` when no container runtime is available (or by
+// explicit 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
+// managed-infra-cli.ts promises.
+//
+// Capability is stated, not stretched: this backing serves POSTGRES services
+// only. A definition declaring mysql/redis without a container runtime is
+// refused with the kinds named, never half-booted.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+export interface InfraService { kind: string; hostPort: number }
+
+/** 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. */
+export function parseInfraDefinition(text: string): InfraService[] {
+  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;
+    }
+  }
+  return services;
+}
+
+const HOST = join(import.meta.dir, 'pglite-host.mjs');
+const READY_TIMEOUT_MS = 60_000;
+
+function pidPath(dataDir: string, kind: string): string {
+  return join(dataDir, `pglite-${kind}.pid`);
+}
+
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function listening(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: 1000 }, () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.on('error', () => resolve(false));
+    socket.on('timeout', () => { socket.destroy(); resolve(false); });
+  });
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** The kinds this backing cannot serve, or [] when it can serve the world. */
+export function unsupportedKinds(services: InfraService[]): string[] {
+  return [...new Set(services.filter((s) => s.kind !== 'postgres').map((s) => s.kind))];
+}
+
+export async function pgliteUp(services: InfraService[], dataDir: string): Promise<void> {
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service.kind);
+    if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim()))) continue;
+    const serviceData = join(dataDir, `pglite-${service.kind}-data`);
+    mkdirSync(serviceData, { recursive: true });
+    const log = join(dataDir, `pglite-${service.kind}.log`);
+    mkdirSync(dirname(log), { recursive: true });
+    // a real fd, not a pipe: the host must outlive this process untethered
+    const logFd = openSync(log, 'a');
+    const child = spawn('node', [HOST, '--port', String(service.hostPort), '--data', serviceData], {
+      detached: 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))) {
+      if (!alive(child.pid!)) {
+        throw new Error(`pglite ${service.kind} exited before serving — see ${log}`);
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`pglite ${service.kind} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+      }
+      await sleep(200);
+    }
+  }
+}
+
+export async function pgliteStatus(services: InfraService[], dataDir: string): Promise<{ ok: boolean; ready: number }> {
+  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;
+  }
+  return { ok: ready === services.length && services.length > 0, ready };
+}
+
+export async function pgliteDown(services: InfraService[], dataDir: string): Promise<void> {
+  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 });
+  }
+}