@volter/twin-standard 1.0.29 → 1.0.31

package/dist/src/walk/behavior-journey.js

@@ -0,0 +1,1138 @@
+import { parseExactJson } from '@volter/world-core/exact-json';
+import { attributionName } from "../verdict.js";
+// THE WALK — a pack's life (journeys/customer-life.json) walked step by step against the pack's own fetch, on an
+// in-memory World under a pinned clock, reporting what a consumer would hit. What a life IS: ./journey-kit.ts.
+//
+// Every step is checked as it is written (STATUS, EXPECT, CAPTURE), and every successful answer of a derived pack for
+// SHAPE (./shape.ts): the fields and state values the spec gives what the operation answers, and nothing else.
+// score-pack walks the life through it twice, on two fresh roots, and compares what they answer.
+//
+// The caller names the pack repository first (usePacks).
+import { redis } from '@volter/world-core';
+import { gzipSync } from 'node:zlib';
+import { parse, visit } from 'graphql';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { databaseSession, getActiveWorldStore, MemoryBlobStore, MemoryWorldStore, setActiveBlobStore, setActiveWorldStore, setDeliveryObserver, setInProcessTwins } from '@volter/world-core/runtime';
+import { VENDOR_HOSTS } from '@volter/world-core/vendor-hosts';
+import packFactsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
+import { isResp, at, captureAt, echoFailures, expandFills, expectFailures, fill, fillJson, formBody, isGit, isLine, isSql, isSocket, isWait, jwtAuthorization, oauth1Authorization, presignedPath, sigv4Headers, waitMs } from "./journey-kit.js";
+import { lanesOf, lineShape, shapeChecker } from "./shape.js";
+import { xmlMembers } from "./xml-view.js";
+/** The pack repository the walk finds a vendor's pack in, set by the caller before its first walk. */
+let packsRoot;
+/** Where a socket step opens: an absolute `ws://` or `wss://` url on its own host, a path on the life's host otherwise. */
+function socketAt(open, host) {
+    if (!/^wss?:\/\//.test(open))
+        return { host, path: open };
+    const u = new URL(open);
+    return { host: u.host, path: `${u.pathname}${u.search}` };
+}
+export function usePacks(dir) { packsRoot = dir; }
+const packsDir = () => { if (packsRoot === undefined)
+    throw new Error('usePacks(<packs dir>) first'); return packsRoot; };
+/** The walk's World: the twin's own code on its in-memory World and blob stores (the backends a serverless
+ *  entry runs on), so a walk of any length is state changes in memory and never touches the disk; the World
+ *  clock, pinned to 2026-01-01, is world state in the same store, and the World is sealed. Each root is a fresh key
+ *  space in it.
+ *  Restored after ONE run: this module is imported by journey-walk.test.ts, and a store or clock left active
+ *  would leak into whichever suite the sweep runs next. */
+export function inMemoryWorld(label) {
+    const previousStore = setActiveWorldStore(new MemoryWorldStore());
+    const previousBlobs = setActiveBlobStore(new MemoryBlobStore());
+    const previousClock = process.env.TWIN_WORLD_CLOCK_FILE;
+    // sealed: nothing a walk does reaches a host outside the World (a webhook to a customer's server is refused, not sent)
+    const previousEgress = process.env.VOLTER_TWIN_STRICT_EGRESS;
+    process.env.VOLTER_TWIN_STRICT_EGRESS = '1';
+    const clock = `/memory/${label}/world-clock`;
+    getActiveWorldStore().write(clock, '2026-01-01T00:00:00.000Z');
+    process.env.TWIN_WORLD_CLOCK_FILE = clock;
+    let n = 0;
+    return {
+        root: () => `/memory/${label}/world-${++n}`,
+        restore: () => {
+            setActiveWorldStore(previousStore);
+            setActiveBlobStore(previousBlobs);
+            if (previousClock === undefined)
+                delete process.env.TWIN_WORLD_CLOCK_FILE;
+            else
+                process.env.TWIN_WORLD_CLOCK_FILE = previousClock;
+            if (previousEgress === undefined)
+                delete process.env.VOLTER_TWIN_STRICT_EGRESS;
+            else
+                process.env.VOLTER_TWIN_STRICT_EGRESS = previousEgress;
+        },
+    };
+}
+import { vendorAnswerViews, vendorFetch as vendorFetchFrom, vendorStream } from "./vendor-fetch.js";
+import { gitClone, gitPush } from "./git-client.js";
+/** The type a step's body goes with when it names none, as fetch labels it: JSON for a value or a JSON text, plain text
+ *  for any other string (an upload's bytes). */
+function defaultType(body) {
+    if (typeof body !== 'string')
+        return 'application/json';
+    try {
+        parseExactJson(body);
+        return 'application/json';
+    }
+    catch {
+        return 'text/plain;charset=UTF-8';
+    }
+}
+const vendorFetch = (vendor) => vendorFetchFrom(packsDir(), vendor);
+const shapes = new Map();
+const shapeOf = (vendor) => { if (!shapes.has(vendor))
+    shapes.set(vendor, shapeChecker(join(packsDir(), vendor))); return shapes.get(vendor); };
+/** The routing keys a pack answers under: its descriptor's host rules (pack-facts), each rule's `key` or the vendor's own
+ *  name, as vendor-hosts.cjs compiles them. */
+function routingKeys(vendor) {
+    const name = vendor.split('/')[0];
+    const hosts = (packFactsDocument.packs[name]?.hosts) ?? [];
+    return [...new Set(hosts.map((rule) => rule.key ?? name))].filter((key) => VENDOR_HOSTS[key] !== undefined);
+}
+/** Whether one of `keys`' host rules claims `url` (an absolute URL; a path is the life's own host). */
+const claims = (keys, url) => {
+    if (!/^https?:\/\//.test(url) || !URL.canParse(url))
+        return false;
+    const u = new URL(url);
+    return keys.some((key) => VENDOR_HOSTS[key](u.hostname, u.pathname));
+};
+/** What a stored row keeps for the twin that no schema of the vendor's spec names, by path, in anything the World shows a
+ *  client: the pack's `_`-prefixed bookkeeping (GitHub's `_links` is the vendor's), and, in what no answer's SHAPE
+ *  reads (an event's delivery, a socket frame), the kernel's own `updatedAt`, which a raw row filtered on `_` alone
+ *  carries (Slack's message events once did). The kernel's `deleted` is not read there: vendors send their own
+ *  (Stripe's deleted customer's `deleted: true`). */
+function leaked(v, vendorFields, at = '', unshaped = false) {
+    if (Array.isArray(v))
+        return v.flatMap((x, i) => leaked(x, vendorFields, `${at}[${i}]`, unshaped)).slice(0, 5);
+    if (!v || typeof v !== 'object')
+        return [];
+    return Object.entries(v).flatMap(([k, x]) => ((k.startsWith('_') || (unshaped && k === 'updatedAt')) && !vendorFields.has(k) ? [`${at}${at ? '.' : ''}${k}`] : leaked(x, vendorFields, `${at}${at ? '.' : ''}${k}`, unshaped))).slice(0, 5);
+}
+/** Whether a tool_choice forbids every tool call (OpenAI's 'none', Anthropic's { type: 'none' }). */
+const forbidsTools = (choice) => choice === 'none' || (!!choice && typeof choice === 'object' && choice.type === 'none');
+/** The tool calls an answer or frames carry, in any vendor's form: a chat message's `tool_calls`, a Responses or
+ *  Realtime `function_call` item, an Anthropic `tool_use` block. */
+function toolCallsIn(v, out = []) {
+    if (Array.isArray(v)) {
+        for (const x of v)
+            toolCallsIn(x, out);
+        return out;
+    }
+    if (!v || typeof v !== 'object')
+        return out;
+    const o = v;
+    if (o.type === 'function_call' || o.type === 'tool_use')
+        out.push(String(o.name ?? o.type));
+    if (Array.isArray(o.tool_calls) && o.tool_calls.length)
+        out.push(...o.tool_calls.map((c) => String(c.function?.name ?? 'tool_calls')));
+    for (const [k, x] of Object.entries(o))
+        if (k !== 'tool_calls')
+            toolCallsIn(x, out);
+    return out;
+}
+/** Every field name the vendor's spec gives any resource (the derived surface), per vendor. */
+const fieldsByVendor = new Map();
+function specFields(vendor) {
+    if (!fieldsByVendor.has(vendor)) {
+        // the pack's surface and each of its lanes' (a walk reaches a lane through the pack's router)
+        const files = [join(packsDir(), vendor), ...lanesOf(join(packsDir(), vendor))].map((dir) => join(dir, 'src', 'generated', 'surface.gen.json')).filter((f) => existsSync(f));
+        const surfaces = files.map((f) => parseExactJson(readFileSync(f, 'utf8')));
+        fieldsByVendor.set(vendor, new Set(surfaces.flatMap((surface) => (surface.resources ?? []).flatMap((r) => r.fields.map((f) => f.name)))));
+    }
+    return fieldsByVendor.get(vendor);
+}
+/** The complete replies a connection has written since last read, leaving an unfinished one. */
+function takeReplies(c) {
+    const out = [];
+    let reply;
+    let used = 0;
+    for (const m of c.out.matchAll(/(\d{3})([ -])([^\r\n]*)\r?\n/g)) {
+        (reply ??= { code: Number(m[1]), lines: [] }).lines.push(m[3]);
+        if (m[2] === ' ') {
+            out.push(reply);
+            reply = undefined;
+            used = m.index + m[0].length;
+        }
+    }
+    c.out = c.out.slice(used);
+    return out;
+}
+export async function walk(journey, root, collect, opts) {
+    attributionName(journey.author);
+    const declaredSteps = journey.steps;
+    journey = expandFills(journey);
+    // Observers name the original declaration; execution uses its expanded body.
+    const hooks = opts.hooks;
+    const declared = (step) => declaredSteps[journey.steps.indexOf(step)];
+    if (hooks)
+        opts = { ...opts, hooks: {
+                before: hooks.before ? (step, path, body) => hooks.before(declared(step), path, body) : undefined,
+                after: hooks.after ? (step, path, answer, failures) => hooks.after(declared(step), path, answer, failures) : undefined,
+            } };
+    // the life's host is a hostname (the vendor's, `api.x.ai`); a URL there would put a second scheme in every request
+    if (journey.host !== undefined && !/^[A-Za-z0-9.-]+(:\d+)?$/.test(journey.host)) {
+        collect.push({ step: '(setup)', beat: 'HOST', detail: `the life's host "${journey.host}" is no hostname: write the vendor's host alone (api.example.com), no scheme or path` });
+        return {};
+    }
+    const factory = await vendorFetch(journey.vendor);
+    const views = await vendorAnswerViews(packsDir(), journey.vendor);
+    if (!factory) {
+        collect.push({ step: '(setup)', beat: 'ADAPTER', detail: `no create<Name>TwinFetch adapter enrolled for ${journey.vendor}` });
+        return {};
+    }
+    // the life's companions (`companions`): the packs its vendor calls, each over this walk's root, on the same World and
+    // clock; reached in process by the vendor's ctx.vendorFetch and by a step to a URL their host rules claim
+    const companions = [];
+    for (const vendor of journey.companions ?? []) {
+        const keys = routingKeys(vendor);
+        const companion = vendor === journey.vendor ? undefined : await vendorFetch(vendor);
+        if (!companion || !keys.length) {
+            collect.push({ step: '(setup)', beat: 'ADAPTER', detail: vendor === journey.vendor ? `the life's own vendor ${vendor} is no companion of it` : !companion ? `no create<Name>Fetch adapter for the companion ${vendor}` : `the companion ${vendor} declares no host rules (pack facts) a call could reach it by` });
+            return {};
+        }
+        companions.push({ vendor, keys, fetch: companion(root) });
+    }
+    const ownKeys = routingKeys(journey.vendor);
+    /** The companion that serves a step's URL: one whose host rules claim it where the life's own vendor's do not. */
+    const companionOf = (url) => (claims(ownKeys, url) ? undefined : companions.find((c) => claims(c.keys, url)));
+    // the life's scenario is the World's: written into the walk's World store, which the pack reads it from as a World's
+    // handlers/<vendor>.json is read
+    const scenarioPath = journey.scenario ? join(packsDir(), journey.vendor, 'journeys', journey.scenario) : undefined;
+    if (scenarioPath)
+        getActiveWorldStore().write(scenarioPath, readFileSync(scenarioPath, 'utf8'));
+    // the application the vendor asks (ctx.ask) is the life's stand-in, this walk's fetch's alone: its answers, in order,
+    // by method and URL prefix, each request header it declares checked as sent; a question none takes is unreachable, as
+    // in a sealed World
+    const answers = [...(journey.application ?? [])];
+    // the step being walked, for what the stand-in and the delivery observer report
+    let stepNow = '(setup)';
+    const application = async (url, init) => {
+        const method = (init.method ?? 'GET').toUpperCase();
+        const i = answers.findIndex((a) => (a.method ?? 'POST').toUpperCase() === method && url.startsWith(a.url));
+        if (i < 0)
+            return 'unreachable';
+        const [a] = answers.splice(i, 1);
+        const sent = new Headers(init.headers);
+        for (const [name, value] of Object.entries(a.requestHeaders ?? {})) {
+            if (sent.get(name) !== fill(value, captured))
+                collect.push({ step: stepNow, beat: 'APPLICATION', detail: `the vendor request to ${url} did not carry the declared ${name} header` });
+        }
+        return { status: a.status, ...(a.headers ? { headers: a.headers } : {}), ...(a.bodyError === undefined ? {} : { bodyError: a.bodyError }), body: typeof a.body === 'string' ? a.body : a.body === undefined ? '' : JSON.stringify(a.body) };
+    };
+    const served = opts.served ? await opts.served(root, scenarioPath ? { scenarioPath } : {}) : undefined;
+    const twin = served ? served.fetch : factory(root, { ...(scenarioPath ? { scenarioPath } : {}), application });
+    const shape = await shapeOf(journey.vendor);
+    const host = journey.host ?? 'twin.local';
+    // what an earlier walk captured, when this one continues it (the branch round-trip sends a life's write again)
+    const captured = { ...(opts.captured ?? {}) };
+    // a capture's JSON value where it is not text (a number, a boolean, an object such as database-js's `session`)
+    const typedValues = {};
+    const remember = (name, v) => {
+        captured[name] = v !== null && typeof v === 'object' ? JSON.stringify(v) : String(v);
+        typedValues[name] = v;
+    };
+    const created = [];
+    const send = async (step, path, signal) => {
+        // raw bytes carry only the type the step names (a client that sends none, Dub's base64 image upload, sends none); a
+        // form its own multipart type and boundary
+        const headers = { ...(step.formed ? { 'content-type': step.formed.contentType } : step.bodyBase64 === undefined ? { 'content-type': defaultType(step.body) } : {}), ...(journey.headers ?? {}), ...(step.headers ?? {}) };
+        const init = { method: step.method, headers, signal };
+        if ([step.body, step.bodyBase64, step.formed].filter((b) => b !== undefined).length > 1)
+            throw new Error('a step carries one of body, bodyBase64 and form');
+        if (step.formed)
+            init.body = step.formed.bytes;
+        else if (step.bodyBase64 !== undefined)
+            init.body = Uint8Array.from(Buffer.from(step.bodyBase64, 'base64'));
+        else if (step.body !== undefined)
+            init.body = typeof step.body === 'string' ? step.body : JSON.stringify(step.body);
+        // a body the client compresses or encodes as it sends it (posthog-js's gzip-js, its base64 form), captures filled first
+        if (step.encode && typeof init.body === 'string')
+            init.body = step.encode === 'gzip' ? new Uint8Array(gzipSync(Buffer.from(init.body))) : `data=${encodeURIComponent(Buffer.from(init.body).toString('base64'))}`;
+        // a step may follow an absolute url an answer gave it (a hosted page's), as the application does
+        // a twin that throws answers 500, as a server would: the walk reports the step and goes on to the next
+        let res;
+        try {
+            res = await (companionOf(path)?.fetch ?? twin)(new Request(/^https?:\/\//.test(path) ? path : `http://${host}${path}`, init));
+        }
+        catch (error) {
+            res = new Response(`twin threw: ${error instanceof Error ? error.message : String(error)}`, { status: 500 });
+        }
+        const text = await res.text();
+        let body;
+        try {
+            body = parseExactJson(text);
+        }
+        catch {
+            body = text;
+        }
+        // an XML answer (S3's) is its root element's members (xml-view.ts), as a JSON answer is its object
+        if (typeof body === 'string' && /xml/.test(res.headers.get('content-type') ?? ''))
+            body = xmlMembers(text) ?? text;
+        // a hosted flow answers with a redirect: its target and query are what a step captures (redirect.code)
+        const location = res.status >= 300 && res.status < 400 ? res.headers.get('location') : null;
+        if (location)
+            body = { location, redirect: Object.fromEntries(new URL(location, `http://${host}`).searchParams) };
+        // every cookie an answer sets, joined as one header: a sign-in sets several, and a map keeps only the last
+        const cookies = res.headers.getSetCookie();
+        return { status: res.status, body, text, headers: { ...Object.fromEntries(res.headers), ...(cookies.length ? { 'set-cookie': cookies.join(', ') } : {}) } };
+    };
+    // a wait moves the World clock; the walk puts it back where it found it, so a replay starts at the same instant
+    // a step's read-backs are read as the step's own person (its headers, captures filled)
+    const stepHeaders = (step) => {
+        if (!step.headers)
+            return undefined;
+        try {
+            return parseExactJson(fill(JSON.stringify(step.headers), captured));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // A line step speaks on a connection of the pack's byte-stream wire, one line at a time, reading the
+    // replies each line drew; its answer is checked as a request's is (status, SHAPE, captures, expectations).
+    const connections = new Map();
+    let streams;
+    const lines = lineShape(join(packsDir(), journey.vendor));
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    const speak = async (step) => {
+        let sent;
+        try {
+            sent = (Array.isArray(step.send) ? step.send : step.send === undefined ? [] : [step.send]).map((l) => fill(l, captured));
+        }
+        catch (e) {
+            collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+            return;
+        }
+        const failuresBefore = collect.length;
+        opts.hooks?.before?.(step, step.on, sent);
+        let answered = { status: 0, body: undefined };
+        try {
+            const drawn = [];
+            const shaped = (c, line, got) => {
+                drawn.push(...got);
+                for (const detail of lines?.check(c.shape, line, got.map((r) => r.code)) ?? [])
+                    collect.push({ step: step.name, beat: 'SHAPE', detail });
+            };
+            if (step.connect) {
+                // served, a connection is the application's: TCP to the listener the server started with its own options. A step's
+                // connect options configure only the in-process stream, which a served walk does not use: they are a finding there,
+                // never a way back to the in-process stream (which would pass a listener wired apart from the World)
+                if (served?.stream && Object.keys(step.connect).length) {
+                    collect.push({ step: step.name, beat: 'CONNECTION', detail: `a served walk opens "${step.on}" as the application does, over TCP to the listener; connect options (${Object.keys(step.connect).join(', ')}) configure only the in-process stream` });
+                    return;
+                }
+                const viaServed = served?.stream;
+                if (!viaServed)
+                    streams ??= await vendorStream(packsDir(), journey.vendor);
+                if (!viaServed && !streams) {
+                    collect.push({ step: step.name, beat: 'ADAPTER', detail: `no create<Name>TwinStream adapter enrolled for ${journey.vendor}` });
+                    return;
+                }
+                const opened = { conn: undefined, out: '', closed: false, shape: {} };
+                opened.conn = (viaServed ?? streams(root, step.connect))({ write: (bytes) => { opened.out += decoder.decode(bytes); }, end: () => { opened.closed = true; } }, '127.0.0.1');
+                await opened.conn.settled();
+                connections.set(step.on, opened);
+                shaped(opened, null, takeReplies(opened));
+            }
+            const c = connections.get(step.on);
+            if (!c) {
+                collect.push({ step: step.name, beat: 'CONNECTION', detail: `no connection "${step.on}" is open` });
+                return;
+            }
+            for (const line of sent) {
+                if (c.closed) {
+                    collect.push({ step: step.name, beat: 'CONNECTION', detail: `the server closed "${step.on}" before "${line.slice(0, 40)}"` });
+                    break;
+                }
+                c.conn.data(encoder.encode(`${line}\r\n`));
+                await c.conn.settled();
+                shaped(c, line, takeReplies(c));
+            }
+            const last = drawn.at(-1);
+            const body = { code: last?.code ?? 0, lines: last?.lines ?? [], text: (last?.lines ?? []).join('\n'), replies: drawn };
+            answered = { status: body.code, body };
+            if (opts.verbose)
+                console.log(`  ${String(body.code).padEnd(4)} ${step.on.padEnd(6)} ${(sent[0] ?? '(connect)').slice(0, 70).padEnd(70)} ${step.name}`);
+            const ok = step.status === undefined ? body.code > 0 && body.code < 400 : body.code === step.status;
+            if (!ok) {
+                collect.push({ step: step.name, beat: 'STATUS', detail: `${step.on} answered ${body.code}${step.status ? ` (wanted ${step.status})` : ' (wanted below 400)'}: ${body.text.slice(0, 160)}` });
+                return;
+            }
+            for (const [name, dot] of Object.entries(step.capture ?? {})) {
+                const v = captureAt(body, dot);
+                if (v === undefined || v === null) {
+                    collect.push({ step: step.name, beat: 'CAPTURE', detail: `nothing at "${dot}" in the answer to capture as {${name}}` });
+                    continue;
+                }
+                remember(name, v);
+            }
+            try {
+                for (const f of step.expect ? expectFailures(step.expect, body, captured) : [])
+                    collect.push({ step: step.name, beat: 'EXPECT', detail: f });
+            }
+            catch (e) {
+                collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+            }
+        }
+        finally {
+            opts.hooks?.after?.(step, step.on, answered, collect.slice(failuresBefore));
+        }
+    };
+    // Typed stream steps drive the same pack adapter as the owned TCP listener.
+    let respStream;
+    const respConnections = new Map();
+    const respStep = async (step) => {
+        const before = collect.length;
+        let answered = { status: 200, body: undefined };
+        opts.hooks?.before?.(step, step.connection, step.resp);
+        try {
+            if (step.connect) {
+                if (served?.stream && Object.keys(step.connect).length)
+                    throw new Error('a served RESP walk configures its server, not the client connection');
+                if (!served?.stream)
+                    streams ??= await vendorStream(packsDir(), journey.vendor);
+                const factory = served?.stream ?? (respStream ??= streams?.(root, step.connect));
+                if (!factory)
+                    throw new Error('no byte-stream adapter');
+                const c = { conn: undefined, out: '', closed: false };
+                c.conn = factory({ write: (b) => { c.out += redis.binaryText(b); }, end: () => { c.closed = true; } }, '127.0.0.1');
+                respConnections.set(step.connection, c);
+                await c.conn.settled();
+            }
+            const c = respConnections.get(step.connection);
+            if (!c)
+                throw new Error(`no connection ${step.connection}`);
+            if (step.resp) {
+                const commands = Array.isArray(step.resp[0]) ? step.resp : [step.resp];
+                for (const command of commands) {
+                    const args = command.map((a) => typeof a === 'string' ? redis.binaryText(encoder.encode(fill(a, captured))) : redis.binaryText(Uint8Array.from(atob(a.base64), (x) => x.charCodeAt(0))));
+                    c.conn.data(redis.binaryBytes(redis.respReply(args))); // bulk arguments remain binary, including MessagePack
+                }
+            }
+            await c.conn.settled();
+            const replies = [];
+            const frameTypes = [];
+            let error = null;
+            while (c.out.length) {
+                const frame = redis.readResp(c.out);
+                if (!frame)
+                    break;
+                c.out = c.out.slice(frame.end);
+                frameTypes.push(frame.type);
+                replies.push(frame.error ? { error: frame.value } : frame.value);
+                if (frame.error)
+                    error = frame.value;
+            }
+            const body = { replies, last: replies.at(-1) ?? null, error, frameTypes };
+            answered = { status: error ? 400 : 200, body };
+            if (opts.verbose)
+                console.log(`  RESP ${step.connection} ${step.name}`);
+            if (step.resp && !step.pending && replies.length === 0)
+                collect.push({ step: step.name, beat: 'RESP', detail: 'the command returned no reply (declare pending for a blocking command)' });
+            if (step.refused ? !error?.startsWith(step.refused) : Boolean(error))
+                collect.push({ step: step.name, beat: 'STATUS', detail: `RESP ${error ?? 'success'}, wanted ${step.refused ?? 'success'}` });
+            for (const [name, dot] of Object.entries(step.capture ?? {})) {
+                const value = captureAt(body, dot);
+                if (value === undefined || value === null)
+                    collect.push({ step: step.name, beat: 'CAPTURE', detail: `nothing at ${dot}` });
+                else
+                    remember(name, value);
+            }
+            for (const detail of expectFailures(step.expect ?? [], body, captured))
+                collect.push({ step: step.name, beat: 'EXPECT', detail });
+            if (step.close) {
+                c.conn.close();
+                respConnections.delete(step.connection);
+            }
+        }
+        catch (e) {
+            collect.push({ step: step.name, beat: 'RESP', detail: e.message });
+        }
+        finally {
+            opts.hooks?.after?.(step, step.connection, answered, collect.slice(before));
+        }
+    };
+    // A git step is a git client's clone or push on the pack's smart-HTTP plane (packages/twin-standard/src/walk/git-client.ts); its answer is
+    // checked as a request's is (status, captures, expectations).
+    const gitStep = async (step) => {
+        let headers;
+        let files;
+        try {
+            headers = parseExactJson(fill(JSON.stringify({ ...(journey.headers ?? {}), ...(step.headers ?? {}) }), captured));
+            files = step.files && parseExactJson(fill(JSON.stringify(step.files), captured));
+        }
+        catch (e) {
+            collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+            return;
+        }
+        delete headers['content-type'];
+        const where = `/${step.repo}.git`;
+        const failuresBefore = collect.length;
+        opts.hooks?.before?.(step, where, files);
+        let answered = { status: 0, body: undefined };
+        try {
+            const base = `http://${host}${where}`;
+            const res = step.git === 'clone'
+                ? await gitClone(twin, base, { ...(step.ref ? { ref: step.ref } : {}) }, headers)
+                : await gitPush(twin, base, { ref: step.ref ?? 'refs/heads/main', ...(files ? { files } : {}), ...(step.message ? { message: step.message } : {}), ...(step.author ? { author: step.author } : {}), ...(step.amend ? { amend: true } : {}), ...(step.delete ? { delete: true } : {}) }, headers);
+            answered = { status: res.status, body: res.body };
+            if (opts.verbose)
+                console.log(`  ${String(res.status).padEnd(4)} ${`git ${step.git}`.padEnd(10)} ${where.slice(0, 66).padEnd(66)} ${step.name}`);
+            if (res.status !== (step.status ?? 200)) {
+                collect.push({ step: step.name, beat: 'STATUS', detail: `git ${step.git} ${where} answered ${res.status} (wanted ${step.status ?? 200}): ${res.text.slice(0, 160)}` });
+                return;
+            }
+            for (const [name, dot] of Object.entries(step.capture ?? {})) {
+                const v = captureAt(res.body, dot);
+                if (v === undefined || v === null) {
+                    collect.push({ step: step.name, beat: 'CAPTURE', detail: `nothing at "${dot}" in the answer to capture as {${name}}` });
+                    continue;
+                }
+                remember(name, v);
+            }
+            try {
+                for (const f of step.expect ? expectFailures(step.expect, res.body, captured) : [])
+                    collect.push({ step: step.name, beat: 'EXPECT', detail: f });
+            }
+            catch (e) {
+                collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+            }
+        }
+        finally {
+            opts.hooks?.after?.(step, where, answered, collect.slice(failuresBefore));
+        }
+    };
+    const sockets = new Map();
+    // a session's frames arrive on its own queue, after the request that wrote them: the walk lets the queues run out
+    // (a context's reads are synchronous in a walk's in-memory World; a timer turn after the immediates lets a slower one land)
+    const settle = async () => { for (let i = 0; i < 25; i++)
+        await new Promise((r) => setImmediate(r)); await new Promise((r) => setTimeout(r, 5)); };
+    /** A socket step's answer: the frames that arrived, checked (LEAK, TOOLS) and read for its status, captures and
+     *  expectations as an HTTP step's answer is. */
+    const answerSocket = (step, c) => {
+        const got = c.frames.splice(0);
+        for (const key of leaked(got, specFields(journey.vendor), '', true))
+            collect.push({ step: step.name, beat: 'LEAK', detail: `a frame on ${step.socket} carries the twin's own field ${key}` });
+        // the server's echo of an item the client made (conversation.item.created) is the client's, not an answer
+        if (c.noTools)
+            for (const call of toolCallsIn(got.filter((g) => !(g && typeof g === 'object' && g.type === 'conversation.item.created'))))
+                collect.push({ step: step.name, beat: 'TOOLS', detail: `${step.socket} answered a tool call (${call}) to a turn whose tool_choice is none` });
+        const body = { frames: got, last: got.at(-1) ?? null, closed: c.closed };
+        const status = c.closed ? c.closed.code : 101;
+        if (opts.verbose)
+            console.log(`  ${String(status).padEnd(4)} ${`ws ${step.socket}`.padEnd(10)} ${`${got.length} frame(s)`.padEnd(66)} ${step.name}`);
+        if (status !== (step.status ?? 101)) {
+            collect.push({ step: step.name, beat: 'STATUS', detail: `${step.socket} is ${c.closed ? `closed ${status} ${c.closed.reason}` : 'open'} (wanted ${step.status ?? 101})` });
+            return { status, body };
+        }
+        for (const [name, dot] of Object.entries(step.capture ?? {})) {
+            const v = captureAt(body, dot);
+            if (v === undefined || v === null) {
+                collect.push({ step: step.name, beat: 'CAPTURE', detail: `nothing at "${dot}" in the answer to capture as {${name}}` });
+                continue;
+            }
+            remember(name, v);
+        }
+        try {
+            for (const f of step.expect ? expectFailures(step.expect, body, captured) : [])
+                collect.push({ step: step.name, beat: 'EXPECT', detail: f });
+        }
+        catch (e) {
+            collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+        }
+        return { status, body };
+    };
+    /** What a turn's frames say of tools: a session's or a response's `tool_choice` the client sets (none forbids a call). */
+    const toolsBeat = (_step, frames, c) => {
+        // the session's choice holds until changed; a response's own choice holds for that response alone
+        let response;
+        for (const f of frames) {
+            let o;
+            try {
+                o = parseExactJson(f);
+            }
+            catch {
+                continue;
+            }
+            const session = o.session;
+            if (session && typeof session === 'object' && 'tool_choice' in session)
+                c.sessionNoTools = forbidsTools(session.tool_choice);
+            const own = o.response;
+            if (o.type === 'response.create')
+                response = own && typeof own === 'object' && 'tool_choice' in own ? forbidsTools(own.tool_choice) : undefined;
+        }
+        c.noTools = response ?? c.sessionNoTools;
+    };
+    const servedSocketStep = async (step) => {
+        let frames;
+        try {
+            frames = (Array.isArray(step.send) ? step.send : step.send === undefined ? [] : [step.send]).map((f) => fill(typeof f === 'string' ? f : JSON.stringify(f), captured));
+        }
+        catch (e) {
+            collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+            return;
+        }
+        opts.hooks?.before?.(step, step.socket, frames);
+        if (step.open !== undefined) {
+            // an absolute ws(s):// url opens on its own host (a client that dials the vendor's socket host itself), as a step
+            // may follow an absolute https url
+            const at = socketAt(fill(step.open, captured), host);
+            const opening = { host: at.host };
+            for (const [k, v] of Object.entries(step.headers ?? {}))
+                opening[k] = fill(v, captured);
+            const opened = { frames: [], closed: null, peer: { send: () => undefined, close: () => undefined } };
+            const ws = served.socket(at.path, opening);
+            ws.onmessage = (e) => { const text = String(e.data); try {
+                opened.frames.push(parseExactJson(text));
+            }
+            catch {
+                opened.frames.push(text);
+            } };
+            ws.onclose = (e) => { opened.closed ??= { code: e.code, reason: e.reason }; };
+            const up = await new Promise((done) => { ws.onopen = () => done(true); ws.onerror = () => done(false); setTimeout(() => done(false), 5000); });
+            if (!up) {
+                collect.push({ step: step.name, beat: 'STATUS', detail: `no socket at ${step.open}` });
+                return;
+            }
+            sockets.set(step.socket, opened);
+            wire.set(step.socket, ws);
+        }
+        const c = sockets.get(step.socket);
+        const ws = wire.get(step.socket);
+        if (!c || !ws) {
+            collect.push({ step: step.name, beat: 'CONNECTION', detail: `no socket "${step.socket}" is open` });
+            return;
+        }
+        toolsBeat(step, frames, c);
+        for (const frame of frames) {
+            await settleWire(c);
+            if (c.closed) {
+                collect.push({ step: step.name, beat: 'CONNECTION', detail: `the server closed "${step.socket}" before "${frame.slice(0, 40)}"` });
+                break;
+            }
+            ws.send(frame);
+        }
+        if (step.close) {
+            ws.close();
+            c.closed ??= { code: 1000, reason: '' };
+        }
+        await settleWire(c, step);
+        const failuresBefore = collect.length;
+        const answered = answerSocket(step, c);
+        opts.hooks?.after?.(step, step.socket, answered, collect.slice(failuresBefore));
+    };
+    // a served pack's socket is opened as an application opens it, a WebSocket to the served port; its frames are read as
+    // they arrive (the steps' settle waits until none has come for a moment)
+    const wire = new Map();
+    const settleWire = async (c, step) => {
+        const deadline = Date.now() + 10_000;
+        let seen = -1;
+        while (Date.now() < deadline) {
+            const body = { frames: c.frames, last: c.frames.at(-1) ?? null, closed: c.closed };
+            let expected = true;
+            try {
+                expected = (!step?.status || step.status === (c.closed?.code ?? 101))
+                    && !expectFailures(step?.expect ?? [], body, captured).length
+                    && Object.values(step?.capture ?? {}).every((path) => captureAt(body, path) != null);
+            }
+            catch {
+                expected = false;
+            }
+            if (c.frames.length === seen && (expected || c.closed))
+                return;
+            seen = c.frames.length;
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    };
+    const socketStep = async (step) => {
+        if (served?.socket)
+            return servedSocketStep(step);
+        const upgrade = twin.upgrade;
+        if (!upgrade) {
+            collect.push({ step: step.name, beat: 'ADAPTER', detail: `${journey.vendor} declares no socket` });
+            return;
+        }
+        let frames;
+        try {
+            frames = (Array.isArray(step.send) ? step.send : step.send === undefined ? [] : [step.send]).map((f) => fill(typeof f === 'string' ? f : JSON.stringify(f), captured));
+        }
+        catch (e) {
+            collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+            return;
+        }
+        const failuresBefore = collect.length;
+        opts.hooks?.before?.(step, step.socket, frames);
+        let answered = { status: 0, body: undefined };
+        try {
+            if (step.open !== undefined) {
+                const opening = {};
+                for (const [k, v] of Object.entries(step.headers ?? {}))
+                    opening[k] = fill(v, captured);
+                const at = socketAt(fill(step.open, captured), host);
+                const request = new Request(`http://${at.host}${at.path}`, { headers: { ...opening, upgrade: 'websocket', connection: 'Upgrade' } });
+                if (!upgrade.accepts(request)) {
+                    collect.push({ step: step.name, beat: 'STATUS', detail: `no socket at ${step.open}` });
+                    return;
+                }
+                const opened = { frames: [], closed: null, peer: { send: () => undefined, close: () => undefined } };
+                opened.peer = {
+                    send: (d) => { const text = typeof d === 'string' ? d : decoder.decode(d); try {
+                        opened.frames.push(parseExactJson(text));
+                    }
+                    catch {
+                        opened.frames.push(text);
+                    } },
+                    // a server's close ends the session as the serve seam's close does, so the kernel lets it go
+                    close: (code, reason) => { if (!opened.closed) {
+                        opened.closed = { code: code ?? 1000, reason: reason ?? '' };
+                        upgrade.close(opened.peer);
+                    } },
+                };
+                sockets.set(step.socket, opened);
+                upgrade.open(opened.peer, request);
+            }
+            const c = sockets.get(step.socket);
+            if (!c) {
+                collect.push({ step: step.name, beat: 'CONNECTION', detail: `no socket "${step.socket}" is open` });
+                return;
+            }
+            toolsBeat(step, frames, c);
+            for (const frame of frames) {
+                await settle();
+                if (c.closed) {
+                    collect.push({ step: step.name, beat: 'CONNECTION', detail: `the server closed "${step.socket}" before "${frame.slice(0, 40)}"` });
+                    break;
+                }
+                await upgrade.message(c.peer, frame);
+            }
+            if (step.close) {
+                upgrade.close(c.peer);
+                c.closed ??= { code: 1000, reason: '' };
+            }
+            await settle();
+            answered = answerSocket(step, c);
+        }
+        finally {
+            opts.hooks?.after?.(step, step.socket, answered, collect.slice(failuresBefore));
+        }
+    };
+    // A SQL step is what the application sends the World's managed database itself (its migrations and queries): on one
+    // connection of its own to the database this walk's World binds (vendor-fetch.ts), held across the walk's SQL steps
+    // as the application holds its client; a refusal fails it with its SQLSTATE unless the step expects that one.
+    let sqlSession;
+    const sqlStep = async (step) => {
+        const failuresBefore = collect.length;
+        opts.hooks?.before?.(step, 'sql', step.sql);
+        let answered = { status: 0, body: undefined };
+        try {
+            const url = await twin.managedDatabaseUrl?.();
+            if (url === undefined) {
+                collect.push({ step: step.name, beat: 'ADAPTER', detail: `${journey.vendor} binds no managed database in this walk, so a SQL step has none to run on` });
+                return;
+            }
+            let results;
+            try {
+                sqlSession ??= databaseSession(url);
+                // the SQL is the application's own text, sent as written (a `{presets}` in it is a JSON path, not a capture)
+                results = await (await sqlSession).query(step.sql, step.values?.map((v) => (v === null ? null : fill(v, captured))));
+            }
+            catch (e) {
+                const code = e.code ?? 'XX000';
+                answered = { status: 1, body: { code, message: e.message } };
+                if (step.refused !== code)
+                    collect.push({ step: step.name, beat: 'STATUS', detail: `Postgres refused it: ${code} ${e.message}${step.refused ? ` (wanted ${step.refused})` : ''}` });
+                return;
+            }
+            const last = results.at(-1) ?? { fields: [], rows: [], command: '' };
+            const body = { command: last.command, rows: last.rows.map((row) => Object.fromEntries(last.fields.map((field, i) => [field, row[i] ?? null]))) };
+            answered = { status: 0, body };
+            if (step.refused !== undefined) {
+                collect.push({ step: step.name, beat: 'STATUS', detail: `Postgres completed it (${last.command}), wanted ${step.refused}` });
+                return;
+            }
+            for (const [name, dot] of Object.entries(step.capture ?? {})) {
+                const v = captureAt(body, dot);
+                if (v === undefined || v === null) {
+                    collect.push({ step: step.name, beat: 'CAPTURE', detail: `nothing at "${dot}" in the answer to capture as {${name}}` });
+                    continue;
+                }
+                remember(name, v);
+            }
+            try {
+                for (const f of step.expect ? expectFailures(step.expect, body, captured) : [])
+                    collect.push({ step: step.name, beat: 'EXPECT', detail: f });
+            }
+            catch (e) {
+                collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+            }
+        }
+        finally {
+            opts.hooks?.after?.(step, 'sql', answered, collect.slice(failuresBefore));
+        }
+    };
+    const pending = new Map();
+    // the clock is world state, read and moved through the active World store (in memory for a walk)
+    const clockFile = process.env.TWIN_WORLD_CLOCK_FILE;
+    const store = getActiveWorldStore();
+    const startedAt = clockFile && store.exists(clockFile) ? (store.read(clockFile) ?? undefined) : undefined;
+    // a life that begins before the World's day one (`startsAt`: an account whose story starts while an API it used still
+    // made what it no longer makes) starts its clock there; its waits move it on, and the walk puts it back at the end
+    if (journey.startsAt !== undefined) {
+        if (!clockFile || startedAt === undefined)
+            collect.push({ step: '(setup)', beat: 'WAIT', detail: 'the life starts at its own instant (startsAt), and the walk has no World clock to set' });
+        else if (Number.isNaN(Date.parse(journey.startsAt)))
+            collect.push({ step: '(setup)', beat: 'WAIT', detail: `startsAt ${journey.startsAt} is no instant` });
+        else
+            store.write(clockFile, new Date(journey.startsAt).toISOString());
+    }
+    // what the World sends a receiver (an event's delivery) is read as the receiver reads it, for the twin's own fields
+    const previousObserver = setDeliveryObserver((d) => {
+        let body;
+        try {
+            body = parseExactJson(d.body);
+        }
+        catch {
+            return;
+        }
+        for (const key of leaked(body, specFields(journey.vendor), '', true))
+            collect.push({ step: stepNow, beat: 'LEAK', detail: `the event sent to ${d.url} carries the twin's own field ${key}` });
+    });
+    const previousTwins = setInProcessTwins(Object.fromEntries([
+        ...companions.flatMap((c) => c.keys.map((key) => [key, c.fetch])),
+        ...ownKeys.map((key) => [key, twin]),
+    ]));
+    try {
+        for (const step of journey.steps) {
+            stepNow = step.name;
+            if (isResp(step)) {
+                await respStep(step);
+                continue;
+            }
+            if (isLine(step)) {
+                await speak(step);
+                continue;
+            }
+            if (isGit(step)) {
+                await gitStep(step);
+                continue;
+            }
+            if (isSocket(step)) {
+                await socketStep(step);
+                continue;
+            }
+            if (isSql(step)) {
+                await sqlStep(step);
+                continue;
+            }
+            if (isWait(step)) {
+                if (!clockFile || startedAt === undefined) {
+                    collect.push({ step: step.name, beat: 'WAIT', detail: 'the walk has no World clock to move' });
+                    continue;
+                }
+                try {
+                    store.write(clockFile, new Date(Date.parse((store.read(clockFile) ?? '').trim()) + waitMs(step.wait)).toISOString());
+                }
+                catch (e) {
+                    collect.push({ step: step.name, beat: 'WAIT', detail: e.message });
+                }
+                continue;
+            }
+            let path;
+            try {
+                path = fill(step.path, captured);
+            }
+            catch (e) {
+                collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+                continue;
+            }
+            // a presigned URL is signed again with the key that presigned it, as its client's SDK signed it
+            if (step.presign) {
+                try {
+                    path = presignedPath(step.presign, captured, step.method, path, host, fillJson({ ...(step.bodyBase64 === undefined ? { 'content-type': defaultType(step.body) } : {}), ...(journey.headers ?? {}), ...(step.headers ?? {}) }, captured));
+                }
+                catch (e) {
+                    collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+                    continue;
+                }
+            }
+            const serving = companionOf(path)?.vendor ?? journey.vendor;
+            const graphqlBody = existsSync(join(packsDir(), serving, 'src', 'generated', 'graphql-sdl.gen.json'));
+            let body;
+            let headers;
+            // a form's bytes, built before anything signs the request, so a signature covers what is sent
+            let formed;
+            // a header carries captures as a path or a body does: the token an earlier step was issued
+            try {
+                body = fillJson(step.body, captured, typedValues, graphqlBody);
+                if (step.form)
+                    formed = formBody(step.form, captured);
+                headers = step.headers === undefined ? undefined : fillJson(step.headers, captured);
+                // an OAuth 1.0a step is signed as its client signs it, over the URL it sends to, at the World clock's instant
+                if (step.oauth1) {
+                    const o = parseExactJson(fill(JSON.stringify(step.oauth1), captured));
+                    const url = /^https?:\/\//.test(path) ? path : `http://${host}${path}`;
+                    // a form is signed as it is sent: its multipart type, whose parts OAuth 1.0a's base string never carries
+                    const sent = formed ? undefined : body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body);
+                    const contentType = Object.entries(headers ?? {}).find(([k]) => k.toLowerCase() === 'content-type')?.[1] ?? (formed ? formed.contentType : step.bodyBase64 === undefined ? defaultType(body) : undefined);
+                    const instant = clockFile && store.exists(clockFile) ? Date.parse((store.read(clockFile) ?? '').trim()) : Number.NaN;
+                    headers = { ...(headers ?? {}), authorization: oauth1Authorization(o, step.method, url, sent, contentType, Number.isNaN(instant) ? 0 : instant) };
+                }
+                if (step.jwt)
+                    headers = { ...(headers ?? {}), authorization: jwtAuthorization(step.jwt, captured) };
+                // an AWS SDK's request is signed as it sends it, at the World clock's instant
+                if (step.sigv4) {
+                    const url = /^https?:\/\//.test(path) ? path : `http://${host}${path}`;
+                    // the bytes and the type sent: a form's multipart body and boundary, raw bytes, or the body's text
+                    const sent = formed ? formed.bytes : step.bodyBase64 !== undefined ? Uint8Array.from(Buffer.from(step.bodyBase64, 'base64')) : body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body);
+                    const instant = clockFile && store.exists(clockFile) ? Date.parse((store.read(clockFile) ?? '').trim()) : Number.NaN;
+                    const base = { ...(formed ? { 'content-type': formed.contentType } : step.bodyBase64 === undefined ? { 'content-type': defaultType(body) } : {}), ...(journey.headers ?? {}), ...(headers ?? {}) };
+                    headers = { ...(headers ?? {}), ...sigv4Headers(step.sigv4, captured, step.method, url, base, sent, Number.isNaN(instant) ? 0 : instant) };
+                }
+            }
+            catch (e) {
+                collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+                continue;
+            }
+            if (step.defer) {
+                if (step.await || pending.has(step.defer) || step.expect?.length || step.capture || step.status !== undefined || step.creates || step.changes || step.check) {
+                    collect.push({ step: step.name, beat: 'PENDING', detail: 'a deferred request needs a unique key and no response checks or state beats' });
+                    continue;
+                }
+                const abort = new AbortController();
+                const timer = setTimeout(() => abort.abort(new Error('deferred request exceeded 10 s')), 10_000);
+                const answer = Promise.race([
+                    send({ ...step, body, headers, ...(formed ? { formed } : {}) }, path, abort.signal),
+                    new Promise((_, reject) => abort.signal.addEventListener('abort', () => reject(abort.signal.reason), { once: true })),
+                ]).finally(() => clearTimeout(timer));
+                // A rejected body read must not become an unhandled promise while socket steps run.
+                void answer.catch(() => undefined);
+                pending.set(step.defer, { method: step.method, path, body, headers, answer, abort, timer });
+                continue;
+            }
+            const deferred = step.await ? pending.get(step.await) : undefined;
+            if (step.await && (!deferred || deferred.method !== step.method || deferred.path !== path)) {
+                collect.push({ step: step.name, beat: 'PENDING', detail: 'no deferred request with this key, method and path' });
+                continue;
+            }
+            if (deferred) {
+                if (step.creates || step.changes || (step.body !== undefined && JSON.stringify(body) !== JSON.stringify(deferred.body)) || (step.headers !== undefined && JSON.stringify(headers) !== JSON.stringify(deferred.headers))) {
+                    collect.push({ step: step.name, beat: 'PENDING', detail: 'deferred collects cannot change dispatched body or headers, or request state beats' });
+                    continue;
+                }
+                body = deferred.body;
+                headers = deferred.headers;
+            }
+            // LANDED beat, part one: what the write is supposed to change, as it stands BEFORE the write.
+            let beforeChange;
+            let changesPath;
+            if (step.changes && opts.beats) {
+                try {
+                    changesPath = fill(step.changes, captured);
+                }
+                catch (e) {
+                    collect.push({ step: step.name, beat: 'LANDED', detail: e.message });
+                }
+                if (changesPath)
+                    beforeChange = (await send({ method: 'GET', headers: stepHeaders(step) }, changesPath)).text;
+            }
+            const failuresBefore = collect.length;
+            opts.hooks?.before?.(step, path, body);
+            let answered = { status: 0, body: undefined };
+            // every step that ran reports, however it ended: a scorer counts the failing ones too
+            try {
+                let res;
+                if (deferred) {
+                    pending.delete(step.await);
+                    try {
+                        res = await deferred.answer;
+                    }
+                    catch (error) {
+                        collect.push({ step: step.name, beat: 'PENDING', detail: String(error) });
+                        continue;
+                    }
+                }
+                else
+                    res = await send({ ...step, body, headers, ...(formed ? { formed } : {}) }, path);
+                answered = { status: res.status, body: res.body, headers: res.headers };
+                if (opts.verbose)
+                    console.log(`  ${String(res.status).padEnd(4)} ${step.method.padEnd(6)} ${path.slice(0, 70).padEnd(70)} ${step.name}`);
+                const wanted = step.status;
+                const ok = wanted === undefined ? res.status >= 200 && res.status < 300 : res.status === wanted;
+                if (!ok) {
+                    collect.push({ step: step.name, beat: 'STATUS', detail: `${step.method} ${path} answered ${res.status}${wanted ? ` (wanted ${wanted})` : ' (wanted 2xx)'}: ${res.text.slice(0, 160)}` });
+                    continue;
+                }
+                // a step a companion served is checked against the companion's spec
+                const stepShape = serving === journey.vendor ? shape : await shapeOf(serving);
+                const answering = stepShape && res.status >= 200 && res.status < 300 && !stepShape.pinsOlder({ ...(journey.headers ?? {}), ...(headers ?? {}) }) ? stepShape.operationOf(step.method, path, { ...(journey.headers ?? {}), ...(headers ?? {}) }) : undefined;
+                if (answering)
+                    for (const detail of stepShape.failures(answering.op, res.body, res.headers['content-type'], new Headers({ ...(journey.headers ?? {}), ...(headers ?? {}) }).get('accept') ?? undefined, res.status, { method: step.method, responseText: res.text }))
+                        collect.push({ step: step.name, beat: 'SHAPE', detail });
+                // what a pack keeps for itself is `_`-prefixed and never answered, under any name (Protocol 3, State)
+                const responseFields = new Set(specFields(serving));
+                if (body && typeof body === 'object' && typeof body.query === 'string' && graphqlBody) {
+                    try {
+                        visit(parse(body.query), { Field: (field) => { responseFields.add(field.alias?.value ?? field.name.value); } });
+                    }
+                    catch { /* malformed documents have no selected response keys */ }
+                }
+                if (res.status >= 200 && res.status < 300)
+                    for (const key of leaked(res.body, responseFields))
+                        collect.push({ step: step.name, beat: 'LEAK', detail: `answers the twin's own field ${key}` });
+                // a request that forbids tools (tool_choice none) is answered without a tool call, in any vendor's form
+                if (res.status >= 200 && res.status < 300 && step.body && typeof step.body === 'object' && forbidsTools(step.body.tool_choice))
+                    for (const call of toolCallsIn(res.body))
+                        collect.push({ step: step.name, beat: 'TOOLS', detail: `answered a tool call (${call}) to a request whose tool_choice is none` });
+                for (const [name, dot] of Object.entries(step.capture ?? {})) {
+                    // `view:<path>` captures from the pack's view of the answer (`step.view`), as a client reads a value it decodes
+                    // (an Upstash stream id the SDK decodes from base64 and sends back); any other path reads the answer as it came
+                    const viewDot = dot.startsWith('view:') ? dot.slice('view:'.length) : undefined;
+                    const v = viewDot === undefined ? captureAt(res.body, dot, res.headers, res.text) : step.view !== undefined && views[step.view] ? captureAt(views[step.view](res.body), viewDot) : undefined;
+                    if (v === undefined || v === null) {
+                        collect.push({ step: step.name, beat: 'CAPTURE', detail: `nothing at "${dot}" in the answer to capture as {${name}}` });
+                        continue;
+                    }
+                    remember(name, v);
+                }
+                if (step.check) {
+                    const verdict = step.check({ status: res.status, body: res.body }, captured);
+                    if (verdict !== true)
+                        collect.push({ step: step.name, beat: 'CHECK', detail: verdict });
+                }
+                // an expectation naming a capture an earlier failed step never made is this step's failure, not the walk's end
+                try {
+                    // a step's `view` asserts what the answer holds as the pack decodes it (a psdb result's rows)
+                    const viewed = step.view === undefined ? res.body : views[step.view] ? views[step.view](res.body) : undefined;
+                    if (step.view !== undefined && !views[step.view])
+                        collect.push({ step: step.name, beat: 'EXPECT', detail: `the pack has no answer view "${step.view}" (answerViews in its index)` });
+                    else
+                        for (const f of step.expect ? expectFailures(step.expect, viewed, captured, res.headers, step.view === undefined ? res.text : undefined) : [])
+                            collect.push({ step: step.name, beat: 'EXPECT', detail: f });
+                }
+                catch (e) {
+                    collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+                }
+                // LANDED beat, part two: a write that answered success must have moved something.
+                if (changesPath !== undefined && beforeChange !== undefined) {
+                    const after = await send({ method: 'GET', headers: stepHeaders(step) }, changesPath);
+                    if (after.text === beforeChange) {
+                        collect.push({ step: step.name, beat: 'LANDED', detail: `${step.method} ${path} answered ${res.status} and GET ${changesPath} is byte-identical to what it was before — the write reported success and stored nothing` });
+                    }
+                }
+                if (step.creates && opts.beats) {
+                    const except = step.creates.echoExcept ?? [];
+                    const payload = (b) => (step.creates.at ? at(b, step.creates.at) : b);
+                    if ((step.creates.echoOn ?? 'both') === 'both') {
+                        for (const f of echoFailures(body, payload(res.body), except))
+                            collect.push({ step: step.name, beat: 'ECHO (create)', detail: f });
+                    }
+                    let readPath;
+                    try {
+                        readPath = fill(step.creates.readBack, captured);
+                    }
+                    catch (e) {
+                        collect.push({ step: step.name, beat: 'ECHO (read back)', detail: e.message });
+                        continue;
+                    }
+                    const back = await send({ method: 'GET', headers: stepHeaders(step) }, readPath);
+                    if (back.status < 200 || back.status >= 300)
+                        collect.push({ step: step.name, beat: 'ECHO (read back)', detail: `GET ${readPath} answered ${back.status} right after the create` });
+                    else
+                        for (const f of echoFailures(body, payload(back.body), except))
+                            collect.push({ step: step.name, beat: 'ECHO (read back)', detail: `${f} — reading it back at ${readPath}` });
+                    created.push({ step: step.name, readBack: readPath, sent: body, except, at: step.creates.at });
+                }
+            }
+            finally {
+                opts.hooks?.after?.(step, path, answered, collect.slice(failuresBefore));
+            }
+        }
+        // PERSISTS — after the whole walk, everything created early must still be there.
+        if (opts.beats) {
+            for (const c of created) {
+                const back = await send({ method: 'GET' }, c.readBack);
+                if (back.status < 200 || back.status >= 300) {
+                    collect.push({ step: c.step, beat: 'PERSISTS', detail: `GET ${c.readBack} answered ${back.status} at the END of the walk — it was created and did not survive` });
+                    continue;
+                }
+                for (const f of echoFailures(c.sent, c.at ? at(back.body, c.at) : back.body, c.except))
+                    collect.push({ step: c.step, beat: 'PERSISTS', detail: `${f} — at the END of the walk` });
+            }
+        }
+        for (const key of pending.keys())
+            collect.push({ step: '(teardown)', beat: 'PENDING', detail: `deferred request ${key} was never collected` });
+        return captured;
+    }
+    finally {
+        for (const request of pending.values()) {
+            clearTimeout(request.timer);
+            request.abort.abort();
+        }
+        for (const ws of wire.values())
+            ws.close();
+        const upgrade = twin.upgrade;
+        for (const socket of sockets.values())
+            if (!socket.closed)
+                upgrade?.close(socket.peer);
+        await Promise.allSettled([...pending.values()].map((request) => request.answer));
+        setDeliveryObserver(previousObserver);
+        setInProcessTwins(previousTwins);
+        served?.stop();
+        if (sqlSession)
+            await sqlSession.then((session) => session.end(), () => { });
+        // a World's managed database ends with its walk (vendor-fetch.ts), so the next World declares it at the same port
+        await twin.stopDatabase?.();
+        if (clockFile && startedAt !== undefined)
+            store.write(clockFile, startedAt);
+    }
+}
+/** Run `fn` with every draw the kernel makes from the platform's random source (the World's seed and keys: a caller in
+ *  world-core's src) taken from one fixed stream, a pack's own draws left random: two Worlds walked so share the World's
+ *  own randomness, and what differs between them is randomness beyond it (R9; the board's `clone-distinct-ids` card). */
+// Key pairs belong to the measurement, never to a served World. An algorithm's nth kernel draw
+// gets the same pair in each measured walk; a pack calling generateKey directly stays random.
+const pinnedKeyPairs = new Map();
+export async function withPinnedWorldDraws(fn) {
+    const originalRandom = globalThis.crypto.getRandomValues;
+    const real = originalRandom.bind(globalThis.crypto);
+    const originalGenerate = globalThis.crypto.subtle.generateKey;
+    const generate = originalGenerate.bind(globalThis.crypto.subtle);
+    const keyDraws = new Map();
+    let n = 0;
+    globalThis.crypto.getRandomValues = ((array) => {
+        const caller = (new Error().stack ?? '').split('\n')[2] ?? '';
+        if (!/world-core\/src\//.test(caller))
+            return real(array);
+        if (array) {
+            const bytes = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+            for (let i = 0; i < bytes.length; i++)
+                bytes[i] = (n++ * 2654435761 + 97) >>> 24 & 0xff;
+        }
+        return array;
+    });
+    globalThis.crypto.subtle.generateKey = ((algorithm, extractable, usages) => {
+        const caller = (new Error().stack ?? '').split('\n')[2] ?? '';
+        if (!/world-core\/src\//.test(caller))
+            return generate(algorithm, extractable, usages);
+        const shape = JSON.stringify([algorithm, extractable, usages]);
+        const draw = keyDraws.get(shape) ?? 0;
+        keyDraws.set(shape, draw + 1);
+        const key = `${shape}:${draw}`;
+        let held = pinnedKeyPairs.get(key);
+        if (!held) {
+            held = generate(algorithm, extractable, usages);
+            pinnedKeyPairs.set(key, held);
+            void held.catch(() => pinnedKeyPairs.delete(key));
+        }
+        return held;
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        globalThis.crypto.getRandomValues = originalRandom;
+        globalThis.crypto.subtle.generateKey = originalGenerate;
+    }
+}