@volter/twin-standard 1.0.80 → 1.0.82

package/dist/src/walk/vendor-fetch.js

@@ -34,7 +34,7 @@ export async function vendorFetch(twinDir, vendor) {
         const bare = factory({ root, ...options });
         let bound;
         let host;
-        const bind = () => (bound ??= startPgliteHost().then((started) => { hosts.push(started); host = started; return factory({ root, database: started.url, ...options }); }));
+        const bind = () => (bound ??= startPgliteHost().then((started) => { host = started; return factory({ root, database: started.url, ...options }); }));
         const served = (request) => bind().then((fetch) => { host.clock(worldNow()); return fetch(request); });
         // the World's database itself, for what an application sends it over its own wire (a SQL step: journey-kit.ts)
         const managedDatabaseUrl = () => bind().then(() => { host.clock(worldNow()); return host.url; });
@@ -44,13 +44,6 @@ export async function vendorFetch(twinDir, vendor) {
         return Object.assign(served, bare, { managedDatabaseUrl, stopDatabase });
     };
 }
-const hosts = [];
-process.once('exit', () => { for (const host of hosts) {
-    try {
-        process.kill(host.pid, 'SIGTERM');
-    }
-    catch { /* ended */ }
-} });
 const jwtView = (field) => (body) => {
     const token = body?.[field];
     if (typeof token !== 'string')

package/dist/src/walk/walk-database.d.ts

@@ -1,12 +1,7 @@
-/** `clock(at)` sets the World clock the database reads (pglite-host.mjs: the World's time), frozen at the instant `at`. */
 export type PgliteHost = {
     url: string;
     port: number;
-    pid: number;
     clock: (at: string) => void;
     stop: () => Promise<void>;
 };
-/** Start a PGlite host under node (PGlite's WASM init does not complete under bun) and wait until it serves. Its clock
- *  is a file of the host's own, which the walk sets to the walked World's clock before each request (`clock`); its
- *  port is the same for every walked World. Database randomness is not pinned. */
 export declare function startPgliteHost(): Promise<PgliteHost>;

package/dist/src/walk/walk-database.js

@@ -1,13 +1,14 @@
-// The walker's managed database: the World's own containerless Postgres (world-runtime's pglite-host.mjs, the PGlite host a World
-// without a container runtime serves its postgres service with), started on a free loopback port in a temp dir and
-// stopped by its own PID, for a pack that declares `managedDatabase` (packages/twin-standard/src/walk/vendor-fetch.ts). Not on the serve path.
-import { spawn } from 'node:child_process';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { createServer, connect } from 'node:net';
+// The walker's Postgres is a declared, task-owned World. The runtime supervises its lifetime and backing;
+// the walker owns when to use and release it, never the backend's process or data directory.
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
-const HOST_SCRIPT = createRequire(import.meta.url).resolve('@volter/world-runtime/src/pglite-host.mjs');
+import { dirname, extname, join } from 'node:path';
+import { runWorld, setWorldClock, worldConfigDocument } from '@volter/world-runtime';
+import { worldNow } from '@volter/world-core/runtime';
+const runtimeEntry = createRequire(import.meta.url).resolve('@volter/world-runtime');
+const infrastructureCli = join(dirname(runtimeEntry), `infra-cli${extname(runtimeEntry)}`);
 async function freePort() {
     return new Promise((done, fail) => {
         const server = createServer();
@@ -18,79 +19,81 @@ async function freePort() {
         });
     });
 }
-function answers(port) {
-    return new Promise((done) => {
-        const socket = connect(port, '127.0.0.1');
-        socket.once('connect', () => { socket.destroy(); done(true); });
-        socket.once('error', () => done(false));
-    });
-}
-// The port a walked World declares its postgres service at, as a World's infrastructure file declares one: the same for
-// every World this process walks, so two fresh Worlds hand an application the same database URL (R9), each World's
-// host on it once the one before has stopped (a walk stops its World's host when it ends). A World walked while another
-// still holds it gets a port of its own.
+// Sequential replays declare the same database endpoint. A concurrent walk declares its own port. Only a successful
+// runtime teardown releases this slot; unknown cleanup never licenses reusing its port or deleting its state.
 let declaredPort;
 let declaredHeld = false;
-async function released(port) {
-    for (const deadline = Date.now() + 5000; Date.now() < deadline; await new Promise((r) => setTimeout(r, 100)))
-        if (!(await answers(port)))
-            return true;
-    return false;
-}
-/** Start a PGlite host under node (PGlite's WASM init does not complete under bun) and wait until it serves. Its clock
- *  is a file of the host's own, which the walk sets to the walked World's clock before each request (`clock`); its
- *  port is the same for every walked World. Database randomness is not pinned. */
 export async function startPgliteHost() {
-    const dir = mkdtempSync(join(tmpdir(), 'walk-database-'));
-    const clockFile = join(dir, 'world-clock');
-    const declared = declaredPort !== undefined && !declaredHeld && (await released(declaredPort));
-    const port = declared ? declaredPort : await freePort();
+    if (!process.env.VOLTER_WORLD)
+        throw new Error('A managed database walk requires its enclosing World');
+    const root = mkdtempSync(join(tmpdir(), 'walk-database-world-'));
+    const name = 'pack-walk-postgres';
+    const port = declaredPort !== undefined && !declaredHeld ? declaredPort : await freePort();
     declaredPort ??= port;
     const holdsDeclared = port === declaredPort;
     if (holdsDeclared)
         declaredHeld = true;
-    // The host runs under a small guard that ends it (and removes its data) when this process's end closes the guard's
-    // stdin: a test runner or a manifest run that exits without its teardown leaves no PGlite host behind.
-    const guard = `
-    import { spawn } from 'node:child_process'; import { rmSync } from 'node:fs';
-    const [script, port, data, dir] = process.argv.slice(1);
-    const host = spawn(process.execPath, [script, '--port', port, '--data', data], { stdio: ['ignore', 'ignore', 'inherit'] });
-    const end = () => { try { host.kill('SIGTERM'); } catch {} setTimeout(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} process.exit(0); }, 500); };
-    process.stdin.on('end', end); process.stdin.on('close', end); process.stdin.resume();
-    process.on('SIGTERM', end);
-    host.on('exit', (code) => { try { rmSync(dir, { recursive: true, force: true }); } catch {} process.exit(code ?? 0); });`;
-    const child = spawn('node', ['--input-type=module', '-e', guard, HOST_SCRIPT, String(port), join(dir, 'pgdata'), dir], { stdio: ['pipe', 'ignore', 'pipe'], env: { ...process.env, TWIN_WORLD_CLOCK_FILE: clockFile } });
-    let stderr = '';
-    child.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
-    // the host never keeps the walk's process alive: its end closes the guard's stdin, which ends the host (a walk that
-    // finished otherwise waited on these pipes forever, and grade-pack on its 600 s timeout)
-    child.unref();
-    child.stdin?.unref?.();
-    child.stderr?.unref?.();
-    const deadline = Date.now() + 60_000;
-    while (!(await answers(port))) {
-        if (child.exitCode !== null)
-            throw new Error(`pglite-host exited ${child.exitCode}: ${stderr}`);
-        if (Date.now() > deadline) {
-            child.kill('SIGTERM');
-            throw new Error(`pglite-host did not listen within 60s: ${stderr}`);
+    const fake = { user: 'world', database: 'world', password: 'walk-only-fake-password' };
+    const url = `postgresql://${fake.user}:${fake.password}@127.0.0.1:${port}/${fake.database}`;
+    const config = join(root, 'world.json');
+    const command = [process.execPath, infrastructureCli];
+    writeFileSync(join(root, 'world.infrastructure.yml'), JSON.stringify({ services: { postgres: {
+                image: 'postgres:18-alpine', ports: [`127.0.0.1:${port}:5432`],
+                environment: { POSTGRES_USER: fake.user, POSTGRES_DB: fake.database, POSTGRES_PASSWORD: fake.password },
+            } } }, null, 2) + '\n');
+    writeFileSync(config, JSON.stringify(worldConfigDocument({ id: name,
+        env: { DATABASE_URL: url, VOLTER_WORLD_INFRA_BACKING: 'pglite' }, network: { egress: [] },
+        services: [{ id: 'infrastructure', type: 'external', controlPlane: true, external: {
+                    up: [...command, 'up'], status: [...command, 'status'], down: [...command, 'down'],
+                    discover: [{ as: 'DATABASE_URL', jsonPath: 'connections.DATABASE_URL', protocol: 'postgres' }],
+                    readyWhen: { command: command[0], args: [...command.slice(1), 'status'], timeoutMs: 120_000, intervalMs: 500 },
+                } }],
+    }), null, 2) + '\n');
+    setWorldClock(name, root, worldNow());
+    const readyFile = join(root, 'ready.json'), releaseFile = join(root, 'release');
+    // This is the registered consumer held by runWorld, not an infrastructure supervisor. It exposes only its own
+    // connection env, and exits when the caller's sequence is done. Caller loss belongs to the runtime's run guardian.
+    const hold = `
+    import { existsSync, renameSync, watch, writeFileSync } from 'node:fs';
+    import { dirname } from 'node:path';
+    const [ready, release] = process.argv.slice(1);
+    if (!process.env.VOLTER_WORLD || !process.env.DATABASE_URL) throw new Error('Missing held World connection');
+    const done = () => { if (existsSync(release)) process.exit(0); };
+    watch(dirname(release), done);
+    writeFileSync(ready + '.tmp', JSON.stringify({ url: process.env.DATABASE_URL }));
+    renameSync(ready + '.tmp', ready);
+    done();`;
+    let finished;
+    const task = runWorld(config, [process.execPath, '--input-type=module', '-e', hold, readyFile, releaseFile], {
+        root, cwd: root, owner: 'pack-walk-managed-database',
+    }).then(result => { finished = { result, failed: false }; return result; }, error => {
+        finished = { error, failed: true };
+        throw error;
+    });
+    // Startup and normal stop await this promise; keep an early rejection handled while waiting for readiness.
+    void task.catch(() => undefined);
+    while (!existsSync(readyFile)) {
+        if (finished) {
+            if (!finished.failed && holdsDeclared)
+                declaredHeld = false;
+            if (finished.failed)
+                throw finished.error;
+            throw new Error(`Managed database World ended before its consumer was ready (exit ${finished.result.exitCode}); evidence: ${root}`);
         }
-        await new Promise((r) => setTimeout(r, 200));
+        await new Promise(resolve => setTimeout(resolve, 100));
     }
+    const ready = JSON.parse(readFileSync(readyFile, 'utf8'));
+    let stopping;
     return {
-        url: `postgresql://postgres:postgres@127.0.0.1:${port}/postgres`,
-        port,
-        pid: child.pid,
-        clock: (at) => writeFileSync(clockFile, `${at}\n`),
-        stop: async () => {
-            if (child.exitCode === null && child.pid !== undefined) {
-                const ended = new Promise((r) => child.once('exit', r));
-                process.kill(child.pid, 'SIGTERM');
-                await Promise.race([ended, new Promise((r) => setTimeout(r, 5000))]);
-            }
-            rmSync(dir, { recursive: true, force: true });
+        url: ready.url, port: Number(new URL(ready.url).port),
+        clock: at => setWorldClock(name, root, at),
+        stop: () => stopping ??= (async () => {
+            writeFileSync(releaseFile, 'released\n');
+            const result = await task;
+            if (result.exitCode !== 0)
+                throw new Error(`Managed database World consumer exited ${result.exitCode}; evidence: ${root}`);
             if (holdsDeclared)
                 declaredHeld = false;
-        },
+        })(),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -75,7 +75,7 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.88",
+    "@volter/world-core": "3.0.90",
     "@volter/world-runtime": "*",
     "playwright": "^1.63.0"
   },

package/src/walk/vendor-fetch.ts

@@ -27,7 +27,7 @@ export async function vendorFetch(twinDir: string, vendor: string): Promise<Vend
     const bare = factory({ root, ...options });
     let bound: Promise<(request: Request) => Response | Promise<Response>> | undefined;
     let host: PgliteHost | undefined;
-    const bind = () => (bound ??= startPgliteHost().then((started) => { hosts.push(started); host = started; return factory({ root, database: started.url, ...options }); }));
+    const bind = () => (bound ??= startPgliteHost().then((started) => { host = started; return factory({ root, database: started.url, ...options }); }));
     const served = (request: Request) => bind().then((fetch) => { host!.clock(worldNow()); return fetch(request); });
     // the World's database itself, for what an application sends it over its own wire (a SQL step: journey-kit.ts)
     const managedDatabaseUrl = () => bind().then(() => { host!.clock(worldNow()); return host!.url; });
@@ -37,8 +37,6 @@ export async function vendorFetch(twinDir: string, vendor: string): Promise<Vend
   };
 }
 
-const hosts: PgliteHost[] = [];
-process.once('exit', () => { for (const host of hosts) { try { process.kill(host.pid, 'SIGTERM'); } catch { /* ended */ } } });
 
 /** Named views of an answer: what a journey step's `view` asserts against. The kit's own: `jwt:<field>`, the payload of the
  *  JSON Web Token at that field of the answer, decoded as the application verifying it reads it (a session token's

package/src/walk/walk-database.ts

@@ -1,14 +1,15 @@
-// The walker's managed database: the World's own containerless Postgres (world-runtime's pglite-host.mjs, the PGlite host a World
-// without a container runtime serves its postgres service with), started on a free loopback port in a temp dir and
-// stopped by its own PID, for a pack that declares `managedDatabase` (packages/twin-standard/src/walk/vendor-fetch.ts). Not on the serve path.
-import { spawn, type ChildProcess } from 'node:child_process';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { createServer, connect } from 'node:net';
+// The walker's Postgres is a declared, task-owned World. The runtime supervises its lifetime and backing;
+// the walker owns when to use and release it, never the backend's process or data directory.
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
+import { dirname, extname, join } from 'node:path';
+import { runWorld, setWorldClock, worldConfigDocument } from '@volter/world-runtime';
+import { worldNow } from '@volter/world-core/runtime';
 
-const HOST_SCRIPT = createRequire(import.meta.url).resolve('@volter/world-runtime/src/pglite-host.mjs');
+const runtimeEntry = createRequire(import.meta.url).resolve('@volter/world-runtime');
+const infrastructureCli = join(dirname(runtimeEntry), `infra-cli${extname(runtimeEntry)}`);
 
 async function freePort(): Promise<number> {
   return new Promise((done, fail) => {
@@ -21,77 +22,77 @@ async function freePort(): Promise<number> {
   });
 }
 
-function answers(port: number): Promise<boolean> {
-  return new Promise((done) => {
-    const socket = connect(port, '127.0.0.1');
-    socket.once('connect', () => { socket.destroy(); done(true); });
-    socket.once('error', () => done(false));
-  });
-}
-
-/** `clock(at)` sets the World clock the database reads (pglite-host.mjs: the World's time), frozen at the instant `at`. */
-export type PgliteHost = { url: string; port: number; pid: number; clock: (at: string) => void; stop: () => Promise<void> };
+export type PgliteHost = { url: string; port: number; clock: (at: string) => void; stop: () => Promise<void> };
 
-// The port a walked World declares its postgres service at, as a World's infrastructure file declares one: the same for
-// every World this process walks, so two fresh Worlds hand an application the same database URL (R9), each World's
-// host on it once the one before has stopped (a walk stops its World's host when it ends). A World walked while another
-// still holds it gets a port of its own.
+// Sequential replays declare the same database endpoint. A concurrent walk declares its own port. Only a successful
+// runtime teardown releases this slot; unknown cleanup never licenses reusing its port or deleting its state.
 let declaredPort: number | undefined;
 let declaredHeld = false;
 
-async function released(port: number): Promise<boolean> {
-  for (const deadline = Date.now() + 5000; Date.now() < deadline; await new Promise((r) => setTimeout(r, 100))) if (!(await answers(port))) return true;
-  return false;
-}
-
-/** Start a PGlite host under node (PGlite's WASM init does not complete under bun) and wait until it serves. Its clock
- *  is a file of the host's own, which the walk sets to the walked World's clock before each request (`clock`); its
- *  port is the same for every walked World. Database randomness is not pinned. */
 export async function startPgliteHost(): Promise<PgliteHost> {
-  const dir = mkdtempSync(join(tmpdir(), 'walk-database-'));
-  const clockFile = join(dir, 'world-clock');
-  const declared = declaredPort !== undefined && !declaredHeld && (await released(declaredPort));
-  const port = declared ? declaredPort! : await freePort();
+  if (!process.env.VOLTER_WORLD) throw new Error('A managed database walk requires its enclosing World');
+  const root = mkdtempSync(join(tmpdir(), 'walk-database-world-'));
+  const name = 'pack-walk-postgres';
+  const port = declaredPort !== undefined && !declaredHeld ? declaredPort : await freePort();
   declaredPort ??= port;
   const holdsDeclared = port === declaredPort;
   if (holdsDeclared) declaredHeld = true;
-  // The host runs under a small guard that ends it (and removes its data) when this process's end closes the guard's
-  // stdin: a test runner or a manifest run that exits without its teardown leaves no PGlite host behind.
-  const guard = `
-    import { spawn } from 'node:child_process'; import { rmSync } from 'node:fs';
-    const [script, port, data, dir] = process.argv.slice(1);
-    const host = spawn(process.execPath, [script, '--port', port, '--data', data], { stdio: ['ignore', 'ignore', 'inherit'] });
-    const end = () => { try { host.kill('SIGTERM'); } catch {} setTimeout(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} process.exit(0); }, 500); };
-    process.stdin.on('end', end); process.stdin.on('close', end); process.stdin.resume();
-    process.on('SIGTERM', end);
-    host.on('exit', (code) => { try { rmSync(dir, { recursive: true, force: true }); } catch {} process.exit(code ?? 0); });`;
-  const child: ChildProcess = spawn('node', ['--input-type=module', '-e', guard, HOST_SCRIPT, String(port), join(dir, 'pgdata'), dir], { stdio: ['pipe', 'ignore', 'pipe'], env: { ...process.env, TWIN_WORLD_CLOCK_FILE: clockFile } });
-  let stderr = '';
-  child.stderr?.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8'); });
-  // the host never keeps the walk's process alive: its end closes the guard's stdin, which ends the host (a walk that
-  // finished otherwise waited on these pipes forever, and grade-pack on its 600 s timeout)
-  child.unref();
-  (child.stdin as unknown as { unref?: () => void } | null)?.unref?.();
-  (child.stderr as unknown as { unref?: () => void } | null)?.unref?.();
-  const deadline = Date.now() + 60_000;
-  while (!(await answers(port))) {
-    if (child.exitCode !== null) throw new Error(`pglite-host exited ${child.exitCode}: ${stderr}`);
-    if (Date.now() > deadline) { child.kill('SIGTERM'); throw new Error(`pglite-host did not listen within 60s: ${stderr}`); }
-    await new Promise((r) => setTimeout(r, 200));
+  const fake = { user: 'world', database: 'world', password: 'walk-only-fake-password' };
+  const url = `postgresql://${fake.user}:${fake.password}@127.0.0.1:${port}/${fake.database}`;
+  const config = join(root, 'world.json');
+  const command = [process.execPath, infrastructureCli];
+  writeFileSync(join(root, 'world.infrastructure.yml'), JSON.stringify({ services: { postgres: {
+    image: 'postgres:18-alpine', ports: [`127.0.0.1:${port}:5432`],
+    environment: { POSTGRES_USER: fake.user, POSTGRES_DB: fake.database, POSTGRES_PASSWORD: fake.password },
+  } } }, null, 2) + '\n');
+  writeFileSync(config, JSON.stringify(worldConfigDocument({ id: name,
+    env: { DATABASE_URL: url, VOLTER_WORLD_INFRA_BACKING: 'pglite' }, network: { egress: [] },
+    services: [{ id: 'infrastructure', type: 'external', controlPlane: true, external: {
+      up: [...command, 'up'], status: [...command, 'status'], down: [...command, 'down'],
+      discover: [{ as: 'DATABASE_URL', jsonPath: 'connections.DATABASE_URL', protocol: 'postgres' }],
+      readyWhen: { command: command[0], args: [...command.slice(1), 'status'], timeoutMs: 120_000, intervalMs: 500 },
+    } }],
+  }), null, 2) + '\n');
+  setWorldClock(name, root, worldNow());
+  const readyFile = join(root, 'ready.json'), releaseFile = join(root, 'release');
+  // This is the registered consumer held by runWorld, not an infrastructure supervisor. It exposes only its own
+  // connection env, and exits when the caller's sequence is done. Caller loss belongs to the runtime's run guardian.
+  const hold = `
+    import { existsSync, renameSync, watch, writeFileSync } from 'node:fs';
+    import { dirname } from 'node:path';
+    const [ready, release] = process.argv.slice(1);
+    if (!process.env.VOLTER_WORLD || !process.env.DATABASE_URL) throw new Error('Missing held World connection');
+    const done = () => { if (existsSync(release)) process.exit(0); };
+    watch(dirname(release), done);
+    writeFileSync(ready + '.tmp', JSON.stringify({ url: process.env.DATABASE_URL }));
+    renameSync(ready + '.tmp', ready);
+    done();`;
+  let finished: { result?: Awaited<ReturnType<typeof runWorld>>; error?: unknown; failed: boolean } | undefined;
+  const task = runWorld(config, [process.execPath, '--input-type=module', '-e', hold, readyFile, releaseFile], {
+    root, cwd: root, owner: 'pack-walk-managed-database',
+  }).then(result => { finished = { result, failed: false }; return result; }, error => {
+    finished = { error, failed: true }; throw error;
+  });
+  // Startup and normal stop await this promise; keep an early rejection handled while waiting for readiness.
+  void task.catch(() => undefined);
+  while (!existsSync(readyFile)) {
+    if (finished) {
+      if (!finished.failed && holdsDeclared) declaredHeld = false;
+      if (finished.failed) throw finished.error;
+      throw new Error(`Managed database World ended before its consumer was ready (exit ${finished.result!.exitCode}); evidence: ${root}`);
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
   }
+  const ready = JSON.parse(readFileSync(readyFile, 'utf8')) as { url: string };
+  let stopping: Promise<void> | undefined;
   return {
-    url: `postgresql://postgres:postgres@127.0.0.1:${port}/postgres`,
-    port,
-    pid: child.pid!,
-    clock: (at) => writeFileSync(clockFile, `${at}\n`),
-    stop: async () => {
-      if (child.exitCode === null && child.pid !== undefined) {
-        const ended = new Promise((r) => child.once('exit', r));
-        process.kill(child.pid, 'SIGTERM');
-        await Promise.race([ended, new Promise((r) => setTimeout(r, 5000))]);
-      }
-      rmSync(dir, { recursive: true, force: true });
+    url: ready.url, port: Number(new URL(ready.url).port),
+    clock: at => setWorldClock(name, root, at),
+    stop: () => stopping ??= (async () => {
+      writeFileSync(releaseFile, 'released\n');
+      const result = await task;
+      if (result.exitCode !== 0) throw new Error(`Managed database World consumer exited ${result.exitCode}; evidence: ${root}`);
       if (holdsDeclared) declaredHeld = false;
-    },
+    })(),
   };
 }