@volter/twin-standard 1.0.30 → 1.0.31

package/dist/src/walk/shape.d.ts

@@ -0,0 +1,54 @@
+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[];
+    };
+};
+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 declare function lanesOf(pkg: string): string[];
+/** 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 declare function shapeChecker(pkg: string): Promise<ShapeChecker | undefined>;
+/** 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 declare function lineShape(pkg: string): LineShape | undefined;

package/dist/src/walk/shape.js

@@ -0,0 +1,210 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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.js";
+/** Whether a resource is one of the objects `said` names (a union's `object` lists every alternative's). */
+const isObject = (r, said) => typeof said === 'string' && (r.fields.find((f) => f.name === 'object')?.enum ?? []).includes(said);
+/** 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) {
+    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) {
+    const units = (await Promise.all([pkg, ...lanesOf(pkg)].map((dir) => unitChecker(dir)))).filter((c) => !!c);
+    if (!units.length)
+        return undefined;
+    if (units.length === 1)
+        return units[0];
+    const owner = new WeakMap();
+    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, media, defaultMedia) {
+    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) {
+    const surfacePath = join(pkg, 'src', 'generated', 'surface.gen.json');
+    if (!existsSync(surfacePath))
+        return undefined;
+    const surface = JSON.parse(readFileSync(surfacePath, 'utf8'));
+    // 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.format)))
+        return undefined;
+    const manifestModule = existsSync(join(pkg, 'src', 'manifest.ts')) ? (await import(__rewriteRelativeImportExtension(join(pkg, 'src', 'manifest.ts')))) : {};
+    // 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) => {
+        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) => !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.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, 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)];
+            const holder = op.answers.key ? body[op.answers.key] : body;
+            const items = op.answers.list ? (Array.isArray(holder) ? holder : (holder?.data ?? [])) : [holder];
+            const out = [];
+            for (const item of items) {
+                if (!item || typeof item !== 'object')
+                    continue;
+                const said = item.object;
+                // a deleted object is judged as the deleted form of what it says it is
+                const gone = item.deleted === true;
+                const judged = (r) => {
+                    const found = [];
+                    const known = new Map([...r.fields.map((f) => [f.name, f]), ...(op.answers.extends ?? []).map((name) => [name, {}])]);
+                    for (const [k, v] of Object.entries(item)) {
+                        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))
+                            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) => a.fields.every((f) => !f.enum || typeof item[f.name] !== 'string' || f.enum.includes(item[f.name]));
+                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)];
+        },
+    };
+}
+/** 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) {
+    const surfacePath = join(pkg, 'src', 'generated', 'surface.gen.json');
+    if (!existsSync(surfacePath))
+        return undefined;
+    const surface = JSON.parse(readFileSync(surfacePath, 'utf8'));
+    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/dist/src/walk/sse-example.d.ts

@@ -0,0 +1,2 @@
+/** Match a published SDK-decoded SSE sample to a real HTTP frame; preserve non-SSE answers and mismatches. */
+export declare function sseExampleAnswer(example: unknown, answer: unknown, matches: (frame: unknown) => boolean): unknown;

package/dist/src/walk/sse-example.js

@@ -0,0 +1,32 @@
+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, answer, matches) {
+    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 });
+    const frames = [];
+    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;
+        const got = f.data;
+        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/dist/src/walk/vendor-fetch.d.ts

@@ -0,0 +1,20 @@
+import { type TwinStream } 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 declare function vendorFetch(twinDir: string, vendor: string): Promise<VendorFetchFactory | 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>;
+export declare function vendorAnswerViews(twinDir: string, vendor: string): Promise<AnswerViews>;
+/** 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 declare function vendorStream(twinDir: string, vendor: string): Promise<VendorStreamFactory | undefined>;
+export {};

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

@@ -0,0 +1,92 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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 { startPgliteHost } from "./walk-database.js";
+import { worldNow } from '@volter/world-core/runtime';
+export async function vendorFetch(twinDir, vendor) {
+    let mod;
+    try {
+        mod = (await import(__rewriteRelativeImportExtension(join(twinDir, vendor, 'src', 'index.ts'))));
+    }
+    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];
+    if (!declaresManagedDatabase(vendor))
+        return (root, 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, options = {}) => {
+        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 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; });
+        // 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 = [];
+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) {
+    return packFacts.packs[vendor.split('/')[0]]?.managedDatabase !== undefined;
+}
+const jwtView = (field) => (body) => {
+    const token = body?.[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, vendor) {
+    let own = {};
+    try {
+        own = (await import(__rewriteRelativeImportExtension(join(twinDir, vendor, 'src', 'index.ts')))).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]) });
+}
+export async function vendorStream(twinDir, vendor) {
+    let mod;
+    try {
+        mod = (await import(__rewriteRelativeImportExtension(join(twinDir, vendor, 'src', 'index.ts'))));
+    }
+    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];
+    return (root, options = {}) => factory({ ...options, root });
+}

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

@@ -0,0 +1,12 @@
+/** `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

@@ -0,0 +1,96 @@
+// 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';
+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() {
+    return new Promise((done, fail) => {
+        const server = createServer();
+        server.once('error', fail);
+        server.listen(0, '127.0.0.1', () => {
+            const port = server.address().port;
+            server.close(() => done(port));
+        });
+    });
+}
+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.
+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();
+    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}`);
+        }
+        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/dist/src/walk/xml-view.d.ts

@@ -0,0 +1,2 @@
+/** The root element's members, or undefined when the text is not one XML document. */
+export declare function xmlMembers(text: string): Record<string, unknown> | undefined;

package/dist/src/walk/xml-view.js

@@ -0,0 +1,55 @@
+// 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 = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+const decode = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e) => (e[0] === '#' ? String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))) : ENTITIES[e] ?? m));
+/** The root element's members, or undefined when the text is not one XML document. */
+export function xmlMembers(text) {
+    const src = text.replace(/<\?[\s\S]*?\?>/g, '').replace(/<!--[\s\S]*?-->/g, '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, c) => c.replace(/&/g, '&amp;').replace(/</g, '&lt;'));
+    const stack = [{ 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 = { 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) => {
+        if (!n.children.length)
+            return decode(n.text.trim());
+        const count = new Map();
+        for (const c of n.children)
+            count.set(c.name, (count.get(c.name) ?? 0) + 1);
+        const out = {};
+        for (const c of n.children) {
+            if ((count.get(c.name) ?? 0) > 1)
+                (out[c.name] ??= []).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);
+}