@volter/twin-standard 1.0.30 → 1.0.32

package/src/walk/shape.ts

@@ -0,0 +1,208 @@
+// SHAPE — an answer carries only the fields the spec gives what the operation answers, and a state
+// candidate only the values the spec lists (docs/contributing/architecture.md, "Protocol 3",
+// State and The report), and every field the spec requires. The walk (behavior-journey.ts) runs it on every successful step of a derived
+// pack, so a walk an author iterates with fails where the score would; score-pack reads it from there.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { compileSurface, matchOperation } from '@volter/world-core/runtime';
+import { binaryMedia } from '../spec-ir.ts';
+
+export type ShapeOperation = { id: string; method: string; path: string; class: string; resource?: string; successStatus?: number; responseMedia?: Record<string, string[]>; defaultResponseMedia?: Record<string, string>; answers?: { resource: string; list: boolean; key?: string; extends?: string[]; alternatives?: string[] } };
+type Resource = { name: string; fields: Array<{ name: string; required?: boolean; enum?: string[] }> };
+/** Whether a resource is one of the objects `said` names (a union's `object` lists every alternative's). */
+const isObject = (r: Resource, said: unknown): boolean => typeof said === 'string' && (r.fields.find((f) => f.name === 'object')?.enum ?? []).includes(said);
+type Surface = { version: string; basePath?: string; operations: ShapeOperation[]; resources: Resource[] };
+
+export type ShapeChecker = {
+  /** The spec operation a request matches, if any. An RPC wire answers a method whatever the HTTP method. */
+  operationOf: (method: string, path: string, headers?: Record<string, string>) => { op: ShapeOperation; params: Record<string, string> } | undefined;
+  /** A request's URL as the unit routes it (a virtual-hosted S3 request's bucket moved from its host into its path). */
+  pathOf?: (path: string) => string;
+  /** What in an answer the spec does not give the operation's resource (or its view). */
+  failures: (op: ShapeOperation, body: unknown, mediaType?: string, accept?: string, status?: number, exchange?: { method: string; responseText: string }) => string[];
+  /** Whether a request pins an API version before the spec's, whose answers the spec does not describe (a Stripe
+   *  mobile SDK's `Stripe-Version: 2024-06-20`), by the version header the manifest declares. */
+  pinsOlder: (headers: Record<string, string> | undefined) => boolean;
+};
+
+/** The directories under a pack that are lanes: a derived unit with its own generated surface
+ *  (`../twin-packs-p3/aws/secretsmanager/`, `../twin-packs-p3/planetscale/api/`). */
+export function lanesOf(pkg: string): string[] {
+  if (!existsSync(pkg)) return [];
+  return readdirSync(pkg, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !['src', 'spec', 'journeys', 'node_modules', 'scripts', 'test-fixtures'].includes(e.name) && existsSync(join(pkg, e.name, 'src', 'generated', 'surface.gen.json')))
+    .map((e) => join(pkg, e.name));
+}
+
+/** A derived pack's shape checker, or undefined for a pack with no generated surface. A pack's walk reaches its lanes'
+ *  operations through the pack's router (a psdb life creates its database's passwords through the management API), so
+ *  a request is matched against the pack's own surface, then each lane's, and judged by the surface it matched. */
+export async function shapeChecker(pkg: string): Promise<ShapeChecker | undefined> {
+  const units = (await Promise.all([pkg, ...lanesOf(pkg)].map((dir) => unitChecker(dir)))).filter((c): c is ShapeChecker => !!c);
+  if (!units.length) return undefined;
+  if (units.length === 1) return units[0];
+  const owner = new WeakMap<ShapeOperation, ShapeChecker>();
+  return {
+    pinsOlder: (headers) => units[0]!.pinsOlder(headers),
+    pathOf: (path) => units.find((u) => u.operationOf('GET', path) || u.operationOf('PUT', path))?.pathOf?.(path) ?? path,
+    operationOf: (method, path, headers) => {
+      for (const u of units) {
+        const hit = u.operationOf(method, path, headers);
+        if (hit) { owner.set(hit.op, u); return hit; }
+      }
+      return undefined;
+    },
+    failures: (op, body, mediaType, accept, status, exchange) => (owner.get(op) ?? units[0]!).failures(op, body, mediaType, accept, status, exchange),
+  };
+}
+
+/** Accept's most specific media range decides its quality; an explicit q=0 overrides a wildcard. */
+function acceptsMedia(accept: string | undefined, media: string, defaultMedia?: string): boolean {
+  if (accept === undefined) return media === defaultMedia?.toLowerCase();
+  const [type] = media.split('/');
+  const matches = accept.toLowerCase().split(',').flatMap((part) => {
+    const [range, ...parameters] = part.trim().split(';').map((value) => value.trim());
+    const specificity = range === media ? 2 : range === `${type}/*` ? 1 : range === '*/*' ? 0 : -1;
+    if (specificity < 0) return [];
+    const quality = parameters.find((value) => value.startsWith('q='));
+    const q = quality === undefined ? 1 : Number(quality.slice(2));
+    return [{ specificity, q: Number.isFinite(q) && q >= 0 && q <= 1 ? q : 0 }];
+  }).sort((a, b) => b.specificity - a.specificity || b.q - a.q);
+  return (matches[0]?.q ?? 0) > 0;
+}
+
+async function unitChecker(pkg: string): Promise<ShapeChecker | undefined> {
+  const surfacePath = join(pkg, 'src', 'generated', 'surface.gen.json');
+  if (!existsSync(surfacePath)) return undefined;
+  const surface = JSON.parse(readFileSync(surfacePath, 'utf8')) as Surface;
+  // a line protocol's surface is its commands' replies (lineShape); a command table's commands ride in a request's body
+  // (Upstash's REST envelope), which a check by method and path cannot see: its replies are not shape-checked yet, and
+  // its examples assert what each answers
+  if (['command-reply', 'command-table'].includes(String((surface as { format?: string }).format))) return undefined;
+  const manifestModule = existsSync(join(pkg, 'src', 'manifest.ts')) ? ((await import(join(pkg, 'src', 'manifest.ts'))) as { manifest?: { doors?: ReadonlyArray<{ method: string; path: string }>; worldFields?: Record<string, Record<string, { type: 'array' | 'object' | 'string' | 'number' | 'boolean'; why: string }>>; version?: { header: string }; hosts?: ReadonlyArray<{ host?: string; suffix?: string }>; spanning?: ReadonlyArray<string>; pathFromHost?: string } }) : {};
+  // a unit whose host can name part of what its path names (S3's virtual-hosted bucket) is routed as the kernel routes it: a host whose label is part of the path (the manifest's pathFromHost, S3's virtual-hosted
+  // addressing) puts it in front of the path
+  const hostPath = manifestModule.manifest?.pathFromHost ? new RegExp(manifestModule.manifest.pathFromHost, 'i') : undefined;
+  const pathStyle = (u: string): string => {
+    const url = new URL(u);
+    const label = hostPath?.exec(url.hostname)?.[1];
+    return label ? `${url.protocol}//${url.host}/${label}${url.pathname === '/' ? '' : url.pathname}${url.search}` : u;
+  };
+  // a lane is routed by host ("Other wires: lanes"): one whose manifest names the hosts it serves is judged on those
+  // alone, so a page or door of its pack on another host (a dashboard, a World door) is never read as one of its operations
+  const hosts = manifestModule.manifest?.hosts;
+  const served = (hostname: string): boolean => !hosts || hosts.some((h) => (h.host ? hostname === h.host : !!h.suffix && hostname.endsWith(h.suffix)));
+  const versionHeader = manifestModule.manifest?.version?.header.toLowerCase();
+  const specDate = /^\d{4}-\d{2}-\d{2}/.exec(String(surface.version))?.[0];
+  // the path parameters whose values hold slashes (a git ref, a file path): the surface's own `spanning`, and the
+  // manifest's where the spec cannot say
+  const spans = [...((surface as { spanning?: string[] }).spanning ?? []), ...(manifestModule.manifest?.spanning ?? [])];
+  const routes = compileSurface({ ...surface, ...(spans.length ? { spanning: spans } : {}) });
+  const resources = new Map(surface.resources.map((r) => [r.name, r]));
+  return {
+    pinsOlder: (headers) => {
+      if (!versionHeader || !specDate || !headers) return false;
+      const pinned = Object.entries(headers).find(([k]) => k.toLowerCase() === versionHeader)?.[1];
+      return typeof pinned === 'string' && pinned.slice(0, 10) < specDate;
+    },
+    pathOf: (path) => (/^https?:\/\//.test(path) ? pathStyle(path) : path),
+    operationOf: (method, path, headers) => {
+      const url = new URL(/^https?:\/\//.test(path) ? pathStyle(path) : path, 'http://twin.local');
+      if (/^https?:\/\//.test(path) && !served(new URL(path).hostname)) return undefined;
+      // a World door the manifest declares is that door, never the vendor's operation at a path it would also match
+      if (manifestModule.manifest?.doors?.some((door) => door.method.toUpperCase() === method.toUpperCase() && door.path === url.pathname)) return undefined;
+      const h = new Headers(headers ?? {});
+      const hit = matchOperation(routes, method, url.pathname, url.searchParams, h) ?? [...routes.keys()].map((m) => matchOperation(routes, m, url.pathname, url.searchParams, h)).find(Boolean);
+      return hit ? { op: hit.operation as ShapeOperation, params: hit.params } : undefined;
+    },
+    failures: (op, body, mediaType, accept, status = op.successStatus ?? 200, exchange) => {
+      // HEAD's headers describe GET's representation, while HTTP forbids response content.
+      if ((exchange?.method ?? op.method).toUpperCase() === 'HEAD') {
+        const empty = exchange ? exchange.responseText.length === 0 : body === undefined || body === null || body === '';
+        return empty ? [] : ['a HEAD response carries content, which HTTP forbids'];
+      }
+      const media = mediaType?.split(';')[0]?.trim().toLowerCase();
+      const binary = media !== undefined && binaryMedia(media);
+      const declared = op.responseMedia?.[String(status)] ?? op.responseMedia?.[`${Math.floor(status / 100)}XX`] ?? op.responseMedia?.default ?? [];
+      const defaultMedia = op.defaultResponseMedia?.[String(status)] ?? op.defaultResponseMedia?.[`${Math.floor(status / 100)}XX`] ?? op.defaultResponseMedia?.default;
+      if (binary && declared.some((value) => value.toLowerCase() === media) && acceptsMedia(accept, media, defaultMedia)) return [];
+      const primary = op.answers ? resources.get(op.answers.resource) : undefined;
+      if (!primary) return [];
+      if (!body || typeof body !== 'object') return binary ? [`the answer is not the operation's ${primary.name} resource`] : [];
+      // an answer that may be one of several resources (a card or a bank account) is judged as the one it says it is
+      const alternatives = [primary, ...(op.answers!.alternatives ?? []).map((n) => resources.get(n)).filter((x): x is Resource => !!x)];
+      const holder = op.answers!.key ? (body as Record<string, unknown>)[op.answers!.key] : body;
+      const items = op.answers!.list ? (Array.isArray(holder) ? holder : (((holder as Record<string, unknown>)?.data as unknown[]) ?? [])) : [holder];
+      const out: string[] = [];
+      for (const item of items) {
+        if (!item || typeof item !== 'object') continue;
+        const said = (item as Record<string, unknown>).object;
+        // a deleted object is judged as the deleted form of what it says it is
+        const gone = (item as Record<string, unknown>).deleted === true;
+        const judged = (r: Resource): string[] => {
+          const found: string[] = [];
+          const known = new Map<string, { enum?: string[] }>([...r.fields.map((f) => [f.name, f] as const), ...(op.answers!.extends ?? []).map((name) => [name, {}] as const)]);
+          for (const [k, v] of Object.entries(item as Record<string, unknown>)) {
+            const f = known.get(k);
+            const local = manifestModule.manifest?.worldFields?.[r.name]?.[k];
+            if (local) {
+              if (!k.startsWith('twin_') || !local.why?.trim() || f) found.push(`${r.name}.${k}: a World field must have a twin_ name and reason and must not replace a vendor field`);
+              const type = Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v;
+              if (type !== local.type) found.push(`${r.name}.${k}: World field is ${type}, expected ${local.type}`);
+              continue;
+            }
+            if (!f) found.push(`${r.name} answers \`${k}\`, which the spec does not give it`);
+            else if (f.enum && typeof v === 'string' && !f.enum.includes(v)) found.push(`${r.name}.${k} is \`${v}\`, not one of the spec's ${f.enum.join(', ')}`);
+          }
+          for (const f of r.fields) if (f.required && !(f.name in (item as Record<string, unknown>))) found.push(`${r.name} leaves out \`${f.name}\`, which the spec requires`);
+          return found;
+        };
+        const named = alternatives.find((a) => isObject(a, said) && gone === a.fields.some((f) => f.name === 'deleted'))
+          ?? alternatives.find((a) => isObject(a, said));
+        // an item that names no `object` is judged as the alternative its own values say it is: one whose every enum field
+        // the item carries holds that value (a key's `kty`), the one it fits best where several do
+        const consistent = (a: Resource): boolean => a.fields.every((f) => !f.enum || typeof (item as Record<string, unknown>)[f.name] !== 'string' || f.enum.includes((item as Record<string, unknown>)[f.name] as string));
+        const r = named ?? (alternatives.length > 1
+          ? [...alternatives].filter(consistent).sort((a, b) => judged(a).length - judged(b).length)[0] ?? primary
+          : primary);
+        out.push(...judged(r));
+      }
+      return [...new Set(out)];
+    },
+  };
+}
+
+// ── a line protocol's replies ─────────────────────────────────────────────────────────────────
+
+/** Where one connection stands for the check: the command whose intermediate reply the next lines answer. */
+export type LineConnection = { pending?: string };
+export type LineShape = {
+  /** What is wrong with the replies one line drew (null: the connection's opening), as the spec's
+   *  command-reply table reads them; moves `conn` past an intermediate reply. */
+  check: (conn: LineConnection, line: string | null, codes: number[]) => string[];
+};
+
+/** The SHAPE of a line protocol (scripts/derive-pack.ts from an RFC's command-reply table): each reply a
+ *  code the spec allows the command it answers, or one any command may answer. A line after an
+ *  intermediate reply (DATA's payload, a SASL response) is answered as that command's `then`. */
+export function lineShape(pkg: string): LineShape | undefined {
+  const surfacePath = join(pkg, 'src', 'generated', 'surface.gen.json');
+  if (!existsSync(surfacePath)) return undefined;
+  type Replies = { intermediate: number[]; success: number[]; error: number[] };
+  const surface = JSON.parse(readFileSync(surfacePath, 'utf8')) as { format?: string; anyCommand: number[]; commands: Array<Replies & { id: string; then?: Replies }> };
+  if (surface.format !== 'command-reply') return undefined;
+  const commands = new Map(surface.commands.map((c) => [c.id, c]));
+  return {
+    check: (conn, line, codes) => {
+      const pending = conn.pending ? commands.get(conn.pending) : undefined;
+      const verb = line === null ? 'CONNECTION ESTABLISHMENT' : line.trim().split(/\s/)[0]!.toUpperCase();
+      const command = pending ?? commands.get(verb);
+      const replies = pending?.then ?? command;
+      const allowed = new Set([...surface.anyCommand, ...(replies ? [...replies.intermediate, ...replies.success, ...replies.error] : [])]);
+      const out = codes.filter((c) => !allowed.has(c)).map((c) => `${pending ? `the lines after ${pending.id}` : verb} answered ${c}, which the spec does not give it`);
+      const last = codes.at(-1);
+      if (last !== undefined) conn.pending = command && replies?.intermediate.includes(last) ? command.id : undefined;
+      return out;
+    },
+  };
+}

package/src/walk/sse-example.ts

@@ -0,0 +1,25 @@
+import { parseExactJson } from '@volter/world-core/exact-json';
+/** Match a published SDK-decoded SSE sample to a real HTTP frame; preserve non-SSE answers and mismatches. */
+export function sseExampleAnswer(example: unknown, answer: unknown, matches: (frame: unknown) => boolean): unknown {
+  if (typeof answer !== 'string' || !example || typeof example !== 'object') return answer;
+  const wrapped = 'data' in example;
+  if (!wrapped && !('type' in example) && !('object' in example)) return answer;
+  const sample = (wrapped ? example : { data: example }) as { data: unknown; event?: string };
+  const frames: Array<{ data: unknown; event?: string }> = [];
+  for (const block of answer.replace(/\r\n/g, '\n').split('\n\n')) {
+    const lines = block.split('\n');
+    const data = lines.filter((s) => s.startsWith('data:')).map((s) => s.slice(5).replace(/^ /, '')).join('\n');
+    if (!data || data === '[DONE]') continue;
+    const event = lines.find((s) => s.startsWith('event:'))?.slice(6).trim();
+    try { frames.push({ data: parseExactJson(data), ...(event ? { event } : {}) }); } catch { /* not a decoded JSON frame */ }
+  }
+  const relevant = frames.filter((f) => {
+    if (sample.event && f.event !== sample.event) return false;
+    const want = sample.data as Record<string, unknown> | null;
+    const got = f.data as Record<string, unknown> | null;
+    return !want || typeof want !== 'object' || !got || typeof got !== 'object'
+      || (!want.type || want.type === got.type) && (!want.object || want.object === got.object);
+  });
+  const candidates = relevant.map((frame) => wrapped ? frame : frame.data);
+  return candidates.find(matches) ?? candidates[0] ?? answer;
+}

package/src/walk/vendor-fetch.ts

@@ -0,0 +1,80 @@
+// A vendor's wire, in process: the pack's own fetch factory (`create<Name>Fetch`), found on its
+// index. What the catalog's walkers drive (behavior journeys, the spec census probe, the invariants)
+// since the worker render left with the v1 host.
+import { join } from 'node:path';
+import packFacts from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
+import { type PgliteHost, startPgliteHost } from './walk-database.ts';
+import { type TwinStream, worldNow } from '@volter/world-core/runtime';
+import type { PackFetchOptions } from '@volter/world-core';
+
+type ApplicationStandIn = NonNullable<PackFetchOptions['application']>;
+
+/** A pack's fetch over a World's root; a walk whose life names a scenario loads it as the World's (`scenarioPath`), and a
+ *  life's application answers stand in for the application the vendor asks (`application`, this fetch's alone). */
+export type VendorFetchFactory = (root: string, options?: { scenarioPath?: string; application?: ApplicationStandIn }) => (request: Request) => Response | Promise<Response>;
+
+export async function vendorFetch(twinDir: string, vendor: string): Promise<VendorFetchFactory | undefined> {
+  let mod: Record<string, unknown>;
+  try { mod = (await import(join(twinDir, vendor, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }
+  // a pack exports create<Name>Fetch (its generated fetch.ts)
+  const name = Object.keys(mod).find((k) => /^create\w+?Fetch$/.test(k) && !/TwinFetch$/.test(k) && typeof mod[k] === 'function');
+  if (!name) return undefined;
+  const factory = mod[name] as (options: { root: string; database?: string; scenarioPath?: string; application?: ApplicationStandIn }) => ((request: Request) => Response | Promise<Response>) & Record<string, unknown>;
+  if (!declaresManagedDatabase(vendor)) return (root: string, options = {}) => factory({ root, ...options });
+  // A pack whose data plane is the World's managed Postgres is walked over one, as a World binds it: each World (each
+  // root) its own fresh database, started on its first request and stopped when the walk's process ends, its clock the
+  // walked World's (set before each request: the walk moves the World clock between steps).
+  return (root: string, options = {}) => {
+    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 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; });
+    // the walk's end stops its World's database, so the next World walked declares it at the same port
+    const stopDatabase = async () => { if (bound === undefined) return; await bound.catch(() => undefined); await host?.stop(); };
+    return Object.assign(served, bare, { managedDatabaseUrl, stopDatabase });
+  };
+}
+
+const hosts: PgliteHost[] = [];
+process.once('exit', () => { for (const host of hosts) { try { process.kill(host.pid, 'SIGTERM'); } catch { /* ended */ } } });
+
+/** Whether a pack declares the World's managed database (its descriptor's `managedDatabase`, in the pack facts: this
+ *  checkout's kernel's, as the walk's other readers of them import them). */
+function declaresManagedDatabase(vendor: string): boolean {
+  return (packFacts as { packs: Record<string, { managedDatabase?: unknown }> }).packs[vendor.split('/')[0]!]?.managedDatabase !== undefined;
+}
+
+/** 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
+ *  claims). A pack's own (`answerViews` in its index) beside them. */
+export type AnswerViews = Record<string, (body: unknown) => unknown>;
+
+const jwtView = (field: string) => (body: unknown): unknown => {
+  const token = (body as Record<string, unknown> | null)?.[field];
+  if (typeof token !== 'string') return null;
+  try { return JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8')); } catch { return null; }
+};
+
+export async function vendorAnswerViews(twinDir: string, vendor: string): Promise<AnswerViews> {
+  let own: AnswerViews = {};
+  try {
+    own = ((await import(join(twinDir, vendor, 'src', 'index.ts'))) as { answerViews?: AnswerViews }).answerViews ?? {};
+  } catch { /* none of its own */ }
+  return new Proxy(own, { get: (views, name) => (typeof name === 'string' && name.startsWith('jwt:') ? jwtView(name.slice(4)) : views[name as string]) });
+}
+
+/** A vendor's byte-stream wire (a line protocol), in process: the pack's `create<Name>TwinStream`, what a
+ *  hosted World hands a WebSocket's bytes. The walk drives it for a journey's line steps. */
+export type VendorStreamFactory = (root: string, options?: Record<string, unknown>) => TwinStream;
+
+export async function vendorStream(twinDir: string, vendor: string): Promise<VendorStreamFactory | undefined> {
+  let mod: Record<string, unknown>;
+  try { mod = (await import(join(twinDir, vendor, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }
+  const name = Object.keys(mod).find((k) => /^create\w+TwinStream$/.test(k) && typeof mod[k] === 'function');
+  if (!name) return undefined;
+  const factory = mod[name] as (options: Record<string, unknown>) => TwinStream;
+  return (root: string, options = {}) => factory({ ...options, root });
+}

package/src/walk/walk-database.ts

@@ -0,0 +1,97 @@
+// 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';
+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');
+
+async function freePort(): Promise<number> {
+  return new Promise((done, fail) => {
+    const server = createServer();
+    server.once('error', fail);
+    server.listen(0, '127.0.0.1', () => {
+      const port = (server.address() as { port: number }).port;
+      server.close(() => done(port));
+    });
+  });
+}
+
+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> };
+
+// 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.
+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();
+  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));
+  }
+  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 });
+      if (holdsDeclared) declaredHeld = false;
+    },
+  };
+}

package/src/walk/xml-view.ts

@@ -0,0 +1,44 @@
+// An XML answer as the members of its root element (S3's `<ListBucketResult><Name>…</Name><Contents>…</Contents>…`,
+// its `<Error><Code>…`): each child element by its name, a repeated one as a list, an element with no children as its
+// text. What a restXml output structure's members are on the wire, so a journey asserts and captures them (`Contents.0.Key`)
+// and SHAPE checks them as it checks a JSON answer's. Attributes and namespaces are not members and are dropped. XML
+// cannot say a lone element is a list: one `<Contents>` reads as an object, two as a list. A root with no children is
+// its one member, by its name.
+
+const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+const decode = (s: string): string => s.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e: string) => (e[0] === '#' ? String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))) : ENTITIES[e] ?? m));
+
+type Node = { name: string; children: Node[]; text: string };
+
+/** The root element's members, or undefined when the text is not one XML document. */
+export function xmlMembers(text: string): Record<string, unknown> | undefined {
+  const src = text.replace(/<\?[\s\S]*?\?>/g, '').replace(/<!--[\s\S]*?-->/g, '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, c: string) => c.replace(/&/g, '&amp;').replace(/</g, '&lt;'));
+  const stack: Node[] = [{ name: '', children: [], text: '' }];
+  const tag = /<(\/?)([\w:.-]+)[^>]*?(\/?)>|([^<]+)/g;
+  for (let m = tag.exec(src); m; m = tag.exec(src)) {
+    const top = stack.at(-1)!;
+    if (m[4] !== undefined) { top.text += m[4]; continue; }
+    const name = m[2]!.replace(/^[\w.-]+:/, '');
+    if (m[1]) { if (stack.length < 2 || top.name !== name) return undefined; stack.pop(); continue; }
+    const node: Node = { name, children: [], text: '' };
+    top.children.push(node);
+    if (!m[3]) stack.push(node);
+  }
+  const root = stack.length === 1 && stack[0]!.children.length === 1 ? stack[0]!.children[0]! : undefined;
+  if (!root) return undefined;
+  // an element with no children is its text; a name that repeats among siblings is a list
+  const value = (n: Node): unknown => {
+    if (!n.children.length) return decode(n.text.trim());
+    const count = new Map<string, number>();
+    for (const c of n.children) count.set(c.name, (count.get(c.name) ?? 0) + 1);
+    const out: Record<string, unknown> = {};
+    for (const c of n.children) {
+      if ((count.get(c.name) ?? 0) > 1) ((out[c.name] ??= []) as unknown[]).push(value(c));
+      else out[c.name] = value(c);
+    }
+    return out;
+  };
+  // a document whose root is a leaf (S3's `<LocationConstraint>auto</LocationConstraint>`) is that one member
+  if (!root.children.length) return { [root.name]: value(root) };
+  return value(root) as Record<string, unknown>;
+}