@volter/twin-standard 1.0.158 → 1.0.160

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

@@ -1,3 +1,11 @@
+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;
+};
 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
@@ -11,16 +19,18 @@ import { attributionName } from "../verdict.js";
 import { mongodb, mysql, redis } from '@volter/world-core';
 import { createRequire } from 'node:module';
 import { gzipSync } from 'node:zlib';
-import { parse, visit } from 'graphql';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { databaseSession, getActivePackAssets, getActiveWorldStore, LocalPackAssets, MemoryBlobStore, MemoryWorldStore, setActiveBlobStore, setActivePackAssets, setActiveWorldStore, setDeliveryObserver, setInProcessTwins } from '@volter/world-core/runtime';
+import { databaseSession, getActivePackAssets, getActiveWorldStore, LocalPackAssets, MemoryBlobStore, MemoryWorldStore, setActiveBlobStore, setActivePackAssets, setActiveWorldStore, setDeliveryObserver, setInProcessMailServers, setInProcessTwins, settleEventDeliveries, worldDoorMatcher, worldNow } from '@volter/world-core/runtime';
 import { createHostTable } from '@volter/world-core/host-routing';
 import packFactsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
 import { isMongo, isMysql, 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 { decodeResponse, leaked, lineShape, responseProblems, shapeChecker, vendorFieldsOf } from "./shape.js";
 import { walkPackDirectory } from "./pack-directory.js";
-import { xmlMembers } from "./xml-view.js";
+import { unitsIn } from "../lanes.js";
+import { openWebSocket, readHttpResponse } from "../clients/harness.js";
+import { timestampOrderFailures } from "./replay.js";
+export { leaked } from "./shape.js";
 /** The pack repository the walk finds a vendor's pack in, set by the caller before its first walk. */
 let packsRoot;
 /** Installed companions resolve from the selected pack, including its workspace-local dependencies. */
@@ -146,18 +156,6 @@ const claims = (keys, url) => {
     const u = new URL(url);
     return keys.some((key) => walkHosts[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`). */
-export 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
@@ -180,16 +178,9 @@ function toolCallsIn(v, out = []) {
             toolCallsIn(x, out);
     return out;
 }
-/** Every field name the vendor's spec gives any resource (the derived surface), per vendor. */
+/** The selected vendor's shared schema and native-error inventory, loaded before walking. */
 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 directory = directoryFor(vendor);
-        const files = [directory, ...lanesOf(directory)].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. */
@@ -231,6 +222,27 @@ export async function walk(journey, root, collect, opts) {
         collect.push({ step: '(setup)', beat: 'ADAPTER', detail: `no create<Name>Fetch adapter resolved for ${journey.vendor}` });
         return {};
     }
+    // what an earlier walk captured, when this one continues it (the branch round-trip sends a life's write again)
+    const captured = { ...(opts.captured ?? {}) };
+    // the application the vendors call is the life's stand-in, shared by this walk's packs: 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) };
+    };
     // 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 = [];
@@ -241,7 +253,36 @@ export async function walk(journey, root, collect, opts) {
             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) });
+        companions.push({ vendor, keys, fetch: companion(root, { application }), databaseDoor: companion.managedDatabaseDoor });
+    }
+    // a companion that receives mail (an SMTP side port: gmail's, gmail.com's MX) is the mail server ctx.mail reaches for
+    // the domains its host rules claim, on its byte-stream door in process over this walk's World, as a World reaches its
+    // listener: the life declares the provider of every address it mails
+    const mailServers = [];
+    for (const c of companions) {
+        const sides = walkFacts[c.vendor.split('/')[0]]?.sidePorts ?? [];
+        if (!sides.some((side) => side.scheme === 'smtp'))
+            continue;
+        const stream = await vendorStream(packsDir(), c.vendor, dependenciesDir());
+        if (!stream) {
+            collect.push({ step: '(setup)', beat: 'ADAPTER', detail: `the companion ${c.vendor} receives mail on an smtp side port and exports no create<Name>TwinStream` });
+            return {};
+        }
+        mailServers.push({ vendor: c.vendor, receives: (domain) => c.keys.some((key) => walkHosts[key](domain, '/')), stream: stream(root, { application }) });
+    }
+    const eventFields = new Map();
+    for (const vendor of [journey.vendor, ...companions.map((companion) => companion.vendor)]) {
+        const directory = directoryFor(vendor);
+        if (!fieldsByVendor.has(vendor))
+            fieldsByVendor.set(vendor, await vendorFieldsOf(directory));
+        for (const unit of unitsIn(directory)) {
+            const { manifest } = await import(__rewriteRelativeImportExtension(join(unit, 'src', 'manifest.ts')));
+            const service = manifest.service ?? manifest.vendor;
+            const fields = eventFields.get(service) ?? new Set();
+            for (const field of specFields(vendor))
+                fields.add(field);
+            eventFields.set(service, fields);
+        }
     }
     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. */
@@ -251,32 +292,11 @@ export async function walk(journey, root, collect, opts) {
     const scenarioPath = journey.scenario ? join(directoryFor(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 shape = await shapeOf(journey.vendor);
     const served = opts.served ? await opts.served(root, { ...(scenarioPath ? { scenarioPath } : {}), application }) : undefined;
     const twin = served ? served.fetch : factory(root, { ...(scenarioPath ? { scenarioPath } : {}), application });
-    const shape = await shapeOf(journey.vendor);
     const host = journey.host ?? 'twin.local';
     const origin = `${served?.scheme ?? 'http'}://${host}`;
-    // 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) => {
@@ -301,34 +321,27 @@ export async function walk(journey, root, collect, opts) {
         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 {
-            const request = new Request(/^https?:\/\//.test(path) ? path : `${origin}${path}`, init);
-            const companion = companionOf(path);
-            res = companion ? await companion.fetch(request) : served ? await served.fetch(request, { credentials: step.credentials ?? 'same-origin' }) : await twin(request);
-        }
-        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;
+        const companion = companionOf(path);
+        await (companion?.fetch ?? twin).managedDatabaseUrl?.();
+        const request = new Request(/^https?:\/\//.test(path) ? path : `${origin}${path}`, init);
+        const answer = await readHttpResponse(async (request) => {
+            // a twin that throws answers 500, as a server would: the walk reports the step and goes on to the next
+            try {
+                return companion ? await companion.fetch(request) : served ? await served.fetch(request, { credentials: step.credentials ?? 'same-origin' }) : await twin(request);
+            }
+            catch (error) {
+                if (served)
+                    throw error;
+                return new Response(`twin threw: ${error instanceof Error ? error.message : String(error)}`, { status: 500 });
+            }
+        }, request);
+        const wireBody = decodeResponse(answer.text, answer.headers['content-type']);
+        let body = wireBody;
         // 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;
+        const location = answer.status >= 300 && answer.status < 400 ? answer.headers.location : undefined;
         if (location)
             body = { location, redirect: Object.fromEntries(new URL(location, origin).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(', ') } : {}) } };
+        return { status: answer.status, body, wireBody, request: { method: request.method, url: request.url, headers: Object.fromEntries(request.headers) }, text: answer.text, headers: answer.headers, ...(answer.bodyError ? { bodyError: answer.bodyError } : {}) };
     };
     // 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)
@@ -810,8 +823,7 @@ export async function walk(journey, root, collect, opts) {
                 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) {
+            if (!await openWebSocket(ws)) {
                 collect.push({ step: step.name, beat: 'STATUS', detail: `no socket at ${step.open}` });
                 return;
             }
@@ -946,7 +958,8 @@ export async function walk(journey, root, collect, opts) {
         opts.hooks?.before?.(step, 'sql', step.sql);
         let answered = { status: 0, body: undefined };
         try {
-            const url = await twin.managedDatabaseUrl?.();
+            const database = twin;
+            const url = await database.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;
@@ -964,9 +977,14 @@ export async function walk(journey, root, collect, opts) {
                     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 last = results.at(-1) ?? { fields: [], fieldTypes: [], 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 };
+            // Duplicate column names have the same last-column ownership as the visible row projection.
+            const fieldTypes = Object.fromEntries(last.fields.map((field, i) => [field, last.fieldTypes[i]]));
+            const timeFields = Object.fromEntries(Object.entries(fieldTypes).filter(([, type]) => type === 1114 || type === 1184));
+            answered = { status: 0, body, ...(database.managedDatabaseClock === 'wall' ? { sql: { clock: database.managedDatabaseClock, timeFields } } : {}) };
+            for (const detail of timestampOrderFailures(body, timeFields, step.timeOrder ?? []))
+                collect.push({ step: step.name, beat: 'EXPECT', detail });
             if (step.refused !== undefined) {
                 collect.push({ step: step.name, beat: 'STATUS', detail: `Postgres completed it (${last.command}), wanted ${step.refused}` });
                 return;
@@ -1015,15 +1033,22 @@ export async function walk(journey, root, collect, opts) {
         catch {
             return;
         }
-        for (const key of leaked(body, specFields(journey.vendor), '', true))
+        const fields = eventFields.get(d.service);
+        if (!fields) {
+            collect.push({ step: stepNow, beat: 'LEAK', detail: `the event sent to ${d.url} names no selected owner for service ${d.service}` });
+            return;
+        }
+        for (const key of leaked(body, fields, '', 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]),
     ]));
+    const previousMailServers = setInProcessMailServers(mailServers);
     try {
         for (const step of journey.steps) {
+            await settleEventDeliveries(root);
             stepNow = step.name;
             if (isMongo(step)) {
                 await mongoStep(step);
@@ -1059,7 +1084,7 @@ export async function walk(journey, root, collect, opts) {
                     continue;
                 }
                 try {
-                    store.write(clockFile, new Date(Date.parse((store.read(clockFile) ?? '').trim()) + waitMs(step.wait)).toISOString());
+                    store.write(clockFile, new Date(Date.parse(worldNow()) + waitMs(step.wait)).toISOString());
                 }
                 catch (e) {
                     collect.push({ step: step.name, beat: 'WAIT', detail: e.message });
@@ -1103,8 +1128,7 @@ export async function walk(journey, root, collect, opts) {
                     // 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) };
+                    headers = { ...(headers ?? {}), authorization: oauth1Authorization(o, step.method, url, sent, contentType, Date.parse(worldNow())) };
                 }
                 if (step.jwt)
                     headers = { ...(headers ?? {}), authorization: jwtAuthorization(step.jwt, captured) };
@@ -1113,9 +1137,8 @@ export async function walk(journey, root, collect, opts) {
                     const url = /^https?:\/\//.test(path) ? path : `${origin}${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) };
+                    headers = { ...(headers ?? {}), ...sigv4Headers(step.sigv4, captured, step.method, url, base, sent, Date.parse(worldNow())) };
                 }
             }
             catch (e) {
@@ -1128,14 +1151,10 @@ export async function walk(journey, root, collect, opts) {
                     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));
+                const answer = send({ ...step, body, headers, ...(formed ? { formed } : {}) }, path, abort.signal);
                 // 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 });
+                pending.set(step.defer, { method: step.method, path, body, headers, answer, abort });
                 continue;
             }
             const deferred = step.await ? pending.get(step.await) : undefined;
@@ -1173,43 +1192,70 @@ export async function walk(journey, root, collect, opts) {
                 if (deferred) {
                     pending.delete(step.await);
                     const got = await deferred.answer.then((a) => ({ a }), (error) => ({ error }));
-                    // a body the vendor broke off, as the collect expects (`breaks`): its words are the answer
                     if ('error' in got) {
-                        if (step.breaks === undefined || !String(got.error).includes(step.breaks))
-                            collect.push({ step: step.name, beat: 'PENDING', detail: String(got.error) });
+                        collect.push({ step: step.name, beat: 'PENDING', detail: String(got.error) });
                         continue;
                     }
-                    // over a listener, which ends a broken stream as a short body, the ordinary checks hold the part that arrived
                     res = got.a;
                 }
-                else
-                    res = await send({ ...step, body, headers, ...(formed ? { formed } : {}) }, path);
-                answered = { status: res.status, body: res.body, headers: res.headers };
+                else {
+                    try {
+                        res = await send({ ...step, body, headers, ...(formed ? { formed } : {}) }, path);
+                    }
+                    catch (error) {
+                        collect.push({ step: step.name, beat: 'CONNECTION', detail: String(error) });
+                        continue;
+                    }
+                }
+                answered = { status: res.status, body: res.body, headers: res.headers, request: res.request, wireBody: res.wireBody };
+                if (step.breaks !== undefined) {
+                    if (!res.bodyError || res.bodyError.cancelled)
+                        collect.push({ step: step.name, beat: 'PENDING', detail: 'expected a response body interrupted by the vendor; clean EOF or caller cancellation is not an interruption' });
+                    else if (!served && !res.bodyError.message.includes(step.breaks))
+                        collect.push({ step: step.name, beat: 'PENDING', detail: res.bodyError.message });
+                }
+                else if (res.bodyError)
+                    collect.push({ step: step.name, beat: 'BODY', detail: res.bodyError.message });
                 if (opts.verbose)
                     console.log(`  ${String(res.status).padEnd(4)} ${step.method.padEnd(6)} ${path.slice(0, 70).padEnd(70)} ${step.name}`);
+                // A companion's answer belongs to its own schema, including when the status is unexpected.
+                const stepShape = serving === journey.vendor ? shape : await shapeOf(serving);
+                const companion = companionOf(res.request.url);
+                const databaseDoor = companion ? companion.databaseDoor : factory.managedDatabaseDoor;
+                if (databaseDoor && res.status >= 200 && res.status < 300) {
+                    const selectedPath = new URL(stepShape ? stepShape.pathOf(res.request.method, res.request.url, res.request.headers) : res.request.url).pathname;
+                    const declared = worldDoorMatcher([{ method: 'POST', path: databaseDoor }])(res.request.method, selectedPath);
+                    if (declared) {
+                        const connection = (companion?.fetch ?? twin).managedDatabaseConnection;
+                        if (!connection || !stepShape)
+                            collect.push({ step: step.name, beat: 'ADAPTER', detail: 'The selected native credential transport omitted its connection verification capability' });
+                        else {
+                            try {
+                                const verified = await connection(res.request.method, selectedPath, res.status, res.wireBody);
+                                if (!verified)
+                                    throw new Error('The selected native credential transport supplied no authentication provenance');
+                                answered.connection = verified;
+                            }
+                            catch (error) {
+                                collect.push({ step: step.name, beat: 'NATIVE-CONNECTION', detail: error.message });
+                            }
+                        }
+                    }
+                }
+                const problems = responseProblems(stepShape, specFields(serving), {
+                    method: res.request.method, path: res.request.url, requestHeaders: res.request.headers,
+                    graphqlBody: graphqlBody ? body : undefined, status: res.status, mediaType: res.headers['content-type'], body: res.wireBody, text: res.text,
+                });
+                for (const detail of problems.shape)
+                    collect.push({ step: step.name, beat: 'SHAPE', detail });
+                for (const key of problems.leaks)
+                    collect.push({ step: step.name, beat: 'LEAK', detail: `answers the twin's own field ${key}` });
                 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))
@@ -1295,30 +1341,50 @@ export async function walk(journey, root, collect, opts) {
         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);
         try {
-            if (sqlSession)
-                await sqlSession.then((session) => session.end(), () => { });
+            for (const request of pending.values())
+                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);
         }
         finally {
-            await served?.stop();
-            // 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?.();
+            try {
+                await Promise.allSettled([...pending.values()].map((request) => request.answer));
+                await settleEventDeliveries(root);
+            }
+            finally {
+                setDeliveryObserver(previousObserver);
+                setInProcessTwins(previousTwins);
+                setInProcessMailServers(previousMailServers);
+                try {
+                    if (sqlSession)
+                        await sqlSession.then((session) => session.end(), () => { });
+                }
+                finally {
+                    try {
+                        await served?.stop();
+                    }
+                    finally {
+                        try {
+                            // The selected twin's database ends with its walk.
+                            const retired = await Promise.allSettled([twin, ...companions.map(companion => companion.fetch)]
+                                .map(fetch => fetch.stopDatabase?.()));
+                            const failures = retired.filter(result => result.status === 'rejected').map(result => result.reason);
+                            if (failures.length)
+                                throw new AggregateError(failures, 'Walk native database retirement failed');
+                        }
+                        finally {
+                            if (clockFile && startedAt !== undefined)
+                                store.write(clockFile, startedAt);
+                        }
+                    }
+                }
+            }
         }
-        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

package/dist/src/walk/journey-kit.d.ts

@@ -10,7 +10,7 @@ export type JourneyStep = {
     defer?: string;
     /** Collect a previously deferred request once, with all ordinary response checks. */
     await?: string;
-    /** A collect whose answer's body breaks off with these words (a stream the vendor ends in an error), not arriving whole. */
+    /** Require an interrupted body; in-process, its error also contains these words. Status and received bytes retain all checks. */
     breaks?: string;
     body?: unknown;
     /** A body of raw bytes (a gzip'd package, an image, an audio file), base64 in the journey and sent decoded: a
@@ -127,7 +127,7 @@ export type JourneyStep = {
      *  whose values the wire encodes (a psdb result's rows, base64 values sliced by per-column lengths) is asserted by
      *  what it holds. Captures read the answer as it came. */
     view?: string;
-    /** This step sends a vendor's published example, `<operation>#<title>` (scripts/vendor-examples.ts): its answer
+    /** This step sends a vendor's published example, `<operation>#<title>` (tools/vendor-examples.ts): its answer
      *  must hold every key path of the example's answer with the same JSON type. */
     example?: string;
     /** Caller-chosen values of the example's named placeholders, compared literally; captures may fill them.
@@ -138,7 +138,7 @@ export type JourneyStep = {
     exampleDiffers?: Record<string, string>;
     /** A published body field this step leaves out (a dot path; `a[].b` in each item) → why: a rendered value naming an
      *  object the World does not hold (a Git repository behind an integration). Only a field the request schema does not
-     *  require may be left out (scripts/vendor-examples.ts). */
+     *  require may be left out (tools/vendor-examples.ts). */
     unsent?: Record<string, string>;
     /** answer paths whose value equals something the setup sent without the setup deciding it (a default the vendor applies
      *  that coincides), each with the reason: `vendor-examples.ts --sweep` does not ask them asserted, and the judge reads the reason */
@@ -376,12 +376,13 @@ export declare const isWait: (step: Step) => step is WaitStep;
  *  as written. Its answer is the last statement's `{ command, rows }`, each row its
  *  columns by name in Postgres's text format, which `expect` reads; a refusal fails the step with
  *  Postgres's SQLSTATE, unless the step names that SQLSTATE as its `refused` (the application's own catch of it), when
- *  its answer is `{ code, message }`. */
+ *  its answer is `{ code, message }`. `timeOrder` names native timestamp columns whose rows must be nondecreasing. */
 export type SqlStep = {
     name: string;
     sql: string;
     values?: Array<string | null>;
     refused?: string;
+    timeOrder?: string[];
     expect?: JourneyStep['expect'];
     capture?: JourneyStep['capture'];
 };

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

@@ -321,14 +321,18 @@ export function fill(template, captured, graphqlDocument = false) {
     // `{encoded:name}` is a capture percent-encoded (encodeURIComponent), as a URL's path segment or query value or a form
     // field carries it: a URN a vendor's page prints encoded in its paths (LinkedIn's /rest/posts/urn%3Ali%3Ashare%3A…), a
     // sign-in's return path holding `&` that a browser posts back
-    const encoded = basic.replace(/\{encoded:([A-Za-z0-9_.]+)\}/g, (_, k) => {
+    const encoded = basic.replace(/\{(encoded|base64|md5):([A-Za-z0-9_.]+)\}/g, (_, transform, k) => {
         if (captured[k] === undefined)
             throw new Error(`journey: step refers to {${k}}, which no earlier step captured`);
+        if (transform === 'base64')
+            return Buffer.from(captured[k], 'utf8').toString('base64');
+        if (transform === 'md5')
+            return digest('md5', captured[k], 'base64');
         return encodeURIComponent(captured[k]);
     });
     const selections = new Set();
     // Only request query documents opt into GraphQL grammar (their selection sets, found in the text the captures fill,
-    // which `{basic:…}` and `{encoded:…}` have already filled); variables remain ordinary captured JSON data.
+    // which the credential and byte transforms have already filled); variables remain ordinary captured JSON data.
     if (graphqlDocument && !Object.hasOwn(captured, /^\{([A-Za-z_][A-Za-z0-9_.]*)\}$/.exec(encoded)?.[1] ?? '')) {
         try {
             visit(parse(encoded), { SelectionSet(node) { if (node.loc)

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

@@ -0,0 +1,23 @@
+/** A received step, with verified native engine provenance outside its unchanged response body. */
+export type ReplayStep = {
+    name: string;
+    path: string;
+    status: number;
+    body: unknown;
+    sql?: {
+        clock: 'wall';
+        timeFields: Record<string, 1114 | 1184>;
+    };
+    connection?: {
+        kind: 'postgres';
+        field: string;
+        authenticated: true;
+    };
+};
+/** A journey's declared native timestamp columns are present, valid and nondecreasing down the returned rows. */
+export declare function timestampOrderFailures(body: unknown, timeFields: Record<string, 1114 | 1184>, columns: string[]): string[];
+/** Compare received traces by their selected engine declarations, retaining every undeclared byte. */
+export declare function compareReplays(first: ReadonlyArray<ReplayStep>, second: ReadonlyArray<ReplayStep>): {
+    equal: boolean;
+    diagnostics: string[];
+};