@volter/twin-standard 1.0.158 → 1.0.160

package/dist/src/tools/vendor-examples.js

@@ -43,8 +43,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // read for. `--sweep` prints, without changing done, every actor field (creator, user, *_by, ...) no `equals` pins and every
 // list no expect closes: advice for fixing a ruling as a class (its hits include lists a pinned text already fixes).
 //
-// Usage: twin-standard examples <vendor> [--sweep]   (from the pack repository's root; twin-world's
-//        bun scripts/vendor-examples.ts <vendor> runs the same)
+// Usage: twin-standard examples <vendor> [--sweep]   (from the pack repository's root)
 import { parseExactJson, exactInteger, isExactIntegerValue } from '@volter/world-core/exact-json';
 import { hasOwnSurface } from "../lanes.js";
 import { archiveSource } from "../archive-source.js";
@@ -56,7 +55,7 @@ import { basename, join } from 'node:path';
 import { gunzipSync } from 'node:zlib';
 import { inMemoryWorld, walk, usePacks } from "../walk/behavior-journey.js";
 import { vendorFetch, vendorStream } from "../walk/vendor-fetch.js";
-import { at as selectorAt, captureAt, expandFills, isResp, isGit, isLine, isSocket, isWait } from "../walk/journey-kit.js";
+import { at as selectorAt, captureAt, expandFills, isResp, isGit, isSocket, isWait } from "../walk/journey-kit.js";
 import { lanesOf, shapeChecker } from "../walk/shape.js";
 import { applySpecPatch, discoveryToOpenAPI, mergeDocuments, readSpecDocuments, slug } from "../spec.js";
 import { packsRoot } from "./packs-root.js";
@@ -70,6 +69,7 @@ let specSchemas = {};
 const schemasByOperation = {};
 /** Each operation's request-body schema and its JSON answers' schemas by status, as the served spec gives them. */
 const operationSchemas = {};
+const operationKey = (operation, lane) => lane ? `${lane}:${operation}` : operation;
 /** A page's placeholder id in an answer-map key is the id sent at the corresponding published request position.
  *  Only declared placeholders bind, and an ambiguous repeated placeholder cannot stand for a guessed map key. */
 function answerKeys(output, published, sent, placeholder, rawBindings = false) {
@@ -94,7 +94,7 @@ function answerKeys(output, published, sent, placeholder, rawBindings = false) {
             : value;
     return mapped(output);
 }
-/** The schemas the twin serves: the vendor's, with the pack's spec patches (spec/patches.json) applied as derive-pack
+/** The schemas the twin serves: the vendor's, with the pack's spec patches (spec/patches.json) applied as the derivation
  *  applies them. A sample is checked against what the twin is derived from; the published examples themselves stay the
  *  vendor's bytes. */
 function served(pkg, doc) {
@@ -106,7 +106,7 @@ function served(pkg, doc) {
         applySpecPatch(patched, p);
     return patched;
 }
-let xmlModel;
+const restXmlService = (model) => Object.values(model.shapes).some((shape) => shape.type === 'service' && shape.traits?.['aws.protocols#restXml'] !== undefined);
 /** A translated placeholder-key map is a complete map even when its surrounding documented request is partial. */
 function requestMapKeysHold(published, translated, sent, placeholder) {
     if (!placeholder || !published || typeof published !== 'object')
@@ -124,11 +124,11 @@ function requestMapKeysHold(published, translated, sent, placeholder) {
     });
 }
 const PRELUDE = { Boolean: 'boolean', PrimitiveBoolean: 'boolean', Integer: 'integer', PrimitiveInteger: 'integer', Long: 'long', PrimitiveLong: 'long', Float: 'float', Double: 'double' };
-const scalarType = (target) => xmlModel?.shapes[target]?.type ?? PRELUDE[target.split('#')[1] ?? ''] ?? 'string';
-const scalarOf = (target, v) => {
+const scalarType = (model, target) => model.shapes[target]?.type ?? PRELUDE[target.split('#')[1] ?? ''] ?? 'string';
+const scalarOf = (model, target, v) => {
     if (typeof v !== 'string')
         return v;
-    const t = scalarType(target);
+    const t = scalarType(model, target);
     if (t === 'boolean')
         return v === 'true';
     if (['integer', 'long', 'short', 'byte'].includes(t))
@@ -138,10 +138,10 @@ const scalarOf = (target, v) => {
 const arrayOf = (v) => (v === undefined || v === '' ? [] : Array.isArray(v) ? v : [v]);
 /** An answer's XML members (xml-view) read by the model's shape: each member under its xmlName, a flattened list the
  *  repeated element, a wrapped list its container's member elements, scalars as their shape's type. */
-function typedXml(target, v) {
-    const shape = xmlModel?.shapes[target];
+function typedXml(model, target, v) {
+    const shape = model.shapes[target];
     if (!shape || shape.type !== 'structure')
-        return scalarOf(target, v);
+        return scalarOf(model, target, v);
     if (!v || typeof v !== 'object')
         return v === '' ? {} : v;
     const obj = v;
@@ -150,38 +150,38 @@ function typedXml(target, v) {
         if (Object.keys(m.traits ?? {}).some((t) => /^smithy\.api#http(Header|PrefixHeaders|ResponseCode)$/.test(t)))
             continue;
         const el = String(m.traits?.['smithy.api#xmlName'] ?? name);
-        const ts = xmlModel.shapes[m.target];
+        const ts = model.shapes[m.target];
         const raw = obj[el];
         if (ts?.type === 'list') {
             if (m.traits?.['smithy.api#xmlFlattened'] !== undefined) {
                 if (raw !== undefined)
-                    out[name] = arrayOf(raw).map((i) => typedXml(ts.member.target, i));
+                    out[name] = arrayOf(raw).map((i) => typedXml(model, ts.member.target, i));
                 continue;
             }
             if (raw === undefined)
                 continue;
             const memberEl = String(ts.member.traits?.['smithy.api#xmlName'] ?? 'member');
-            out[name] = arrayOf(raw === '' ? undefined : raw[memberEl]).map((i) => typedXml(ts.member.target, i));
+            out[name] = arrayOf(raw === '' ? undefined : raw[memberEl]).map((i) => typedXml(model, ts.member.target, i));
         }
         else if (raw !== undefined)
-            out[name] = typedXml(m.target, raw);
+            out[name] = typedXml(model, m.target, raw);
     }
     return out;
 }
 /** A restXml operation's success answer as its output structure: the body's members by shape (or its payload
  *  member's), and the members its headers carry. */
-function restXmlAnswer(opId, body, headers = {}) {
-    const out = xmlModel.shapes[xmlModel.shapes[opId]?.output?.target ?? ''];
+function restXmlAnswer({ id: opId, model }, body, headers = {}) {
+    const out = model.shapes[model.shapes[opId]?.output?.target ?? ''];
     if (!out)
         return body;
     const members = Object.entries((out.members ?? {}));
     const payload = members.find(([, m]) => m.traits?.['smithy.api#httpPayload'] !== undefined);
-    const answer = (payload ? { [payload[0]]: typedXml(payload[1].target, body) } : typedXml(xmlModel.shapes[opId].output.target, body));
+    const answer = (payload ? { [payload[0]]: typedXml(model, payload[1].target, body) } : typedXml(model, model.shapes[opId].output.target, body));
     const lower = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
     for (const [name, m] of members) {
         const h = m.traits?.['smithy.api#httpHeader'];
         if (h !== undefined && lower[String(h).toLowerCase()] !== undefined)
-            answer[name] = scalarOf(m.target, lower[String(h).toLowerCase()]);
+            answer[name] = scalarOf(model, m.target, lower[String(h).toLowerCase()]);
         // a map bound to a header prefix (S3's Metadata, `x-amz-meta-*`): every header under it, by the rest of its name
         const prefix = m.traits?.['smithy.api#httpPrefixHeaders'];
         if (prefix !== undefined)
@@ -191,8 +191,8 @@ function restXmlAnswer(opId, body, headers = {}) {
 }
 /** Where a restXml example's input is not what the step sends: each member the example gives, at its binding (a path
  *  label, a query key, a header; a payload or body member is the step's body and is not compared). */
-function restXmlInputProblems(opId, input, path, headers, placeholder, rawPath) {
-    const shape = xmlModel.shapes[xmlModel.shapes[opId]?.input?.target ?? ''];
+function restXmlInputProblems({ id: opId, model }, input, path, headers, placeholder, rawPath) {
+    const shape = model.shapes[model.shapes[opId]?.input?.target ?? ''];
     const url = new URL(path, 'http://twin.local');
     // the step as written, its captures unfilled: a value it takes from a capture is the World's own id (an S3 upload's
     // UploadId), which stands for the example's literal as a spec's ids stand for the World's (architecture, "Published examples")
@@ -236,11 +236,13 @@ function lenientJson(text) {
  *  response's `example`/`examples` (a `$ref` to `components.examples` followed), a Swagger 2 response's `examples`, Stripe's
  *  fixtures (one sample per resource, beside its spec), and OpenAI's `x-oaiMeta.examples` (its `response` is JSON text; one that is not JSON, a stream or an abridged answer, is
  *  kept as text and compared with the published framing and payload). */
-function published(pkg) {
+function published(pkg, lane) {
     // Both the vendor API and its lanes publish examples; a root spec must not hide a lane. A lane's example names its
     // lane, the operation being the lane's own (its owner is `<lane>:<id>` in the vendor's owners)
-    const own = [...(hasOwnSurface(pkg) ? fromSpec(pkg) : []), ...fromDocs(pkg)];
-    return [...own, ...lanesOf(pkg).flatMap((lane) => published(lane).map((e) => ({ ...e, lane: e.lane ? `${basename(lane)}:${e.lane}` : basename(lane) })))];
+    const smithy = ['smithy.json.gz', 'smithy.json'].map((name) => join(pkg, 'spec', name)).find(existsSync);
+    const model = smithy ? parseExactJson((smithy.endsWith('.gz') ? gunzipSync(readFileSync(smithy)) : readFileSync(smithy)).toString('utf8')) : undefined;
+    const own = [...(hasOwnSurface(pkg) ? fromSpec(pkg, lane, model) : []), ...fromDocs(pkg, lane, model)].map((e) => ({ ...e, lane }));
+    return [...own, ...lanesOf(pkg).flatMap((dir) => published(dir, lane ? `${lane}:${basename(dir)}` : basename(dir)))];
 }
 /** The examples a vendor's documentation pages publish beside its spec (a schedule page's expressions, each with what
  *  it means), vendored in `spec/doc-examples.json` as `[{title, source, operation, request?, input?, output?, means, status?}]`:
@@ -251,7 +253,7 @@ function published(pkg) {
  *  reference writes every property, and every scalar as a string, `"verified": "true"` beside a schema saying boolean)
  *  shows what the answer can hold, not one request's answer: its example is a sample against the served schema, and a
  *  string where the schema says number, integer or boolean is read as that type, in the answer and the request body. */
-function fromDocs(pkg) {
+function fromDocs(pkg, lane, model) {
     const file = join(pkg, 'spec', 'doc-examples.json');
     if (!existsSync(file))
         return [];
@@ -294,12 +296,11 @@ function fromDocs(pkg) {
     for (const d of docs)
         if (d.placeholders && (!d.placeholders.names?.length || !d.placeholders.quote?.trim()))
             throw new Error(`${file}: "${d.title}" names placeholders without the page's words for them (placeholders.quote)`);
-    const smithy = ['smithy.json.gz', 'smithy.json'].some((f) => existsSync(join(pkg, 'spec', f)));
     // a page's example is a fragment (an expression, not the request that carries it): the body holds it
     return docs.map((d) => {
         if (!d.rendered)
             return fromPage(d, d.output, d.input);
-        const schemas = operationSchemas[d.operation];
+        const schemas = operationSchemas[operationKey(d.operation, lane)];
         const schema = schemas?.responses[String(d.status ?? 200)];
         if (!schema)
             throw new Error(`${file}: "${d.title}" is rendered from a schema the served spec does not give (${d.operation}, ${d.status ?? 200})`);
@@ -311,7 +312,14 @@ function fromDocs(pkg) {
     function fromPage(d, output, input) {
         const named = d.placeholders?.names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
         const placeholder = named ? new RegExp(`${placeholderIds.source}|^(?:${named})$`, placeholderIds.flags) : placeholderIds;
-        return { names: d.placeholders?.names, ...(d.wire ? { wire: d.wire } : {}), id: `${d.operation}#doc ${d.title}`, operation: d.operation, output, ...(d.status ? { status: d.status } : {}), ...(input !== undefined ? { input, partial: true, placeholder } : {}), ...(smithy ? (xmlModel ? { restXml: Object.keys(xmlModel.shapes).find((k) => k.endsWith(`#${d.operation}`)) } : { target: d.operation }) : {}), ...(d.request ? { request: d.request } : {}), ...(authorizationAbsent.has(d) ? { authorizationAbsent: true } : {}) };
+        let restXml;
+        if (model && restXmlService(model)) {
+            const id = Object.keys(model.shapes).find((key) => key.endsWith(`#${d.operation}`));
+            if (!id)
+                throw new Error(`${file}: "${d.title}" names no operation in its XML service (${d.operation})`);
+            restXml = { id, model };
+        }
+        return { names: d.placeholders?.names, ...(d.wire ? { wire: d.wire } : {}), id: `${d.operation}#doc ${d.title}`, operation: d.operation, output, ...(d.status ? { status: d.status } : {}), ...(input !== undefined ? { input, partial: true, placeholder } : {}), ...(model ? (restXml ? { restXml } : { target: d.operation }) : {}), ...(d.request ? { request: d.request } : {}), ...(authorizationAbsent.has(d) ? { authorizationAbsent: true } : {}) };
     }
 }
 /** A rendered object the page does not fill: any object stands where it is. */
@@ -400,12 +408,25 @@ function decodedExample(media, value) {
         return value;
     }
 }
-function fromSpec(pkg) {
+function fromSpec(pkg, lane, model) {
     const rfc = existsSync(join(pkg, 'spec')) ? readdirSync(join(pkg, 'spec')).find((f) => /^rfc\d+\.txt$/.test(f)) : undefined;
     if (rfc)
         return scenarios(readFileSync(join(pkg, 'spec', rfc), 'utf8'));
-    // a spec vendored as published or gzipped, as derive-pack reads it
-    const spec = ['smithy.json.gz', 'smithy.json', 'openapi.json.gz', 'openapi.json', 'openapi.yaml.gz', 'openapi.yaml', 'discovery.json.gz', 'discovery.json'].map((f) => join(pkg, 'spec', f)).find((p) => existsSync(p));
+    const out = [];
+    if (model) {
+        const restXml = restXmlService(model);
+        for (const [id, shape] of Object.entries(model.shapes)) {
+            const examples = shape.traits?.['smithy.api#examples'];
+            const operation = id.split('#')[1];
+            // an awsJson operation is named by its x-amz-target header, `<service>.<operation>`; its body is the input. A
+            // restXml operation (S3's) is named by its method and path, and its input is where each member's binding puts it
+            for (const e of examples ?? [])
+                out.push({ id: `${operation}#${e.title}`, operation, output: e.error ? e.error.content : e.output, input: e.input ?? {}, ...(restXml ? { restXml: { id, model } } : { target: operation }) });
+        }
+        return out;
+    }
+    // a spec vendored as published or gzipped, as the derivation reads it
+    const spec = ['openapi.json.gz', 'openapi.json', 'openapi.yaml.gz', 'openapi.yaml', 'discovery.json.gz', 'discovery.json'].map((f) => join(pkg, 'spec', f)).find((p) => existsSync(p));
     // a Protocol Buffers service publishes no examples in its .proto files: its examples are its documentation's alone
     if (!spec && existsSync(join(pkg, 'spec', 'proto')))
         return [];
@@ -420,23 +441,7 @@ function fromSpec(pkg) {
     if (!spec && !documents)
         throw new Error(`${pkg}: no published-example reader for this spec yet`);
     const text = spec ? (spec.endsWith('.gz') ? gunzipSync(readFileSync(spec)) : readFileSync(spec)).toString('utf8') : '';
-    const out = [];
-    if (spec && /smithy\.json(\.gz)?$/.test(spec)) {
-        const model = parseExactJson(text);
-        const restXml = Object.values(model.shapes).some((sh) => sh.type === 'service' && sh.traits?.['aws.protocols#restXml'] !== undefined);
-        if (restXml)
-            xmlModel = model;
-        for (const [id, shape] of Object.entries(model.shapes)) {
-            const examples = shape.traits?.['smithy.api#examples'];
-            const operation = id.split('#')[1];
-            // an awsJson operation is named by its x-amz-target header, `<service>.<operation>`; its body is the input. A
-            // restXml operation (S3's) is named by its method and path, and its input is where each member's binding puts it
-            for (const e of examples ?? [])
-                out.push({ id: `${operation}#${e.title}`, operation, output: e.error ? e.error.content : e.output, input: e.input ?? {}, ...(restXml ? { restXml: id } : { target: operation }) });
-        }
-        return out;
-    }
-    // a Google API Discovery document publishes no examples; it is read as the OpenAPI document derive-pack reads it as,
+    // a Google API Discovery document publishes no examples; it is read as the OpenAPI document the derivation reads it as,
     // its patches applied to the Discovery document first (spec-ir-discovery.ts)
     const discovery = spec !== undefined && /discovery\.json(\.gz)?$/.test(spec);
     const docs = (documents ? Object.values(documents.documents) : [discovery ? discoveryToOpenAPI(parseExactJson(text)) : /\.yaml(\.gz)?$/.test(spec) ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_key, value) => typeof value === 'bigint' ? exactInteger(String(value)) : value)) : parseExactJson(text)]);
@@ -454,8 +459,9 @@ function fromSpec(pkg) {
                 continue;
             // Swagger 2: the request is the `in: body` parameter's schema, an answer its response's `schema`
             const bodyParam = (op.parameters ?? []).find((x) => x.in === 'body');
-            schemasByOperation[idOf(op, method, path)] = specSchemas;
-            operationSchemas[idOf(op, method, path)] = {
+            const key = operationKey(idOf(op, method, path), lane);
+            schemasByOperation[key] = specSchemas;
+            operationSchemas[key] = {
                 request: json(op.requestBody?.content) ?? bodyParam?.schema,
                 responses: Object.fromEntries(Object.entries(op.responses ?? {}).flatMap(([code, r]) => { const sch = json(r.content) ?? r.schema; return sch ? [[code, sch]] : []; })),
             };
@@ -978,17 +984,17 @@ function outputSchemaMismatches(schema, value, prefix, depth = 0) {
  * recorded with the per-example classification. Request echoes and generated output are absent. */
 const storedCollectionFields = {
     'ai-gateway': { listModels: ['data'] },
-    aws: { ListBuckets: ['Buckets'], ListMultipartUploads: ['Uploads'], ListObjects: ['Contents', 'CommonPrefixes'], ListObjectsV2: ['Contents', 'CommonPrefixes'] },
-    cloudflare: { ListBuckets: ['Buckets'], ListMultipartUploads: ['Uploads'], ListObjects: ['Contents', 'CommonPrefixes'], ListObjectsV2: ['Contents', 'CommonPrefixes'] },
+    aws: { 's3:ListBuckets': ['Buckets'], 's3:ListMultipartUploads': ['Uploads'], 's3:ListObjects': ['Contents', 'CommonPrefixes'], 's3:ListObjectsV2': ['Contents', 'CommonPrefixes'] },
+    cloudflare: { 'r2:ListBuckets': ['Buckets'], 'r2:ListMultipartUploads': ['Uploads'], 'r2:ListObjects': ['Contents', 'CommonPrefixes'], 'r2:ListObjectsV2': ['Contents', 'CommonPrefixes'] },
     discord: { oauth2_token: ['guild.roles'], get_my_oauth2_authorization: ['scopes'] },
     github: { 'repos/get-branch': ['commit.parents'], 'repos/get-commit': ['parents', 'files'], 'repos/get-content': ['', 'entries'], 'repos/compare-commits': ['commits', 'files'], 'git/get-tree': ['tree'], 'git/list-matching-refs': [''], 'repos/get-repo-rulesets': [''] },
-    hackernews: { getItem: ['kids'], getUser: ['submitted'], getUpdates: ['items', 'profiles'], getTopStories: [''], getNewStories: [''], getBestStories: [''], getAskStories: [''], getShowStories: [''], getJobStories: [''] },
+    hackernews: { 'api:getItem': ['kids'], 'api:getUser': ['submitted'], 'api:getUpdates': ['items', 'profiles'], 'api:getTopStories': [''], 'api:getNewStories': [''], 'api:getBestStories': [''], 'api:getAskStories': [''], 'api:getShowStories': [''], 'api:getJobStories': [''] },
     linkedin: { findOrganizationAclsByRoleAssignee: ['elements'] },
     'npm-registry': { 'libnpmsearch.searchStream': ['objects', 'objects.[].package.maintainers'] },
     openrouter: { getCurrentKey: ['data.allowed_data_regions'], getModels: ['data'] },
     redis: { SCAN: ['[].1'] },
     resend: { 'domains/get': ['records'], 'emails/list-receiving': ['data', 'data.[].attachments'] },
-    sentry: { listOrganizations: ['', '[].features'] },
+    sentry: { 'api:listOrganizations': ['', '[].features'] },
     slack: { conversations_rename: ['channel.previous_names'], conversations_invite: ['channel.previous_names'], conversations_members: ['members'], conversations_list: ['channels', 'channels.[].previous_names'], users_conversations: ['channels', 'channels.[].previous_names'], conversations_info: ['channel.previous_names'], conversations_replies: ['messages'], conversations_history: ['messages'], usergroups_list: ['usergroups'] },
     tinybird: { datasources: ['datasources'], jobs: ['jobs'], pipes: ['pipes'], tokens: ['tokens'], token_get: ['scopes'], token_refresh: ['scopes'], pipe_set_endpoint: ['nodes'] },
 };
@@ -1104,7 +1110,7 @@ if (!vendor || vendor.startsWith('-')) {
 const PKG = join(PACKS, vendor);
 const file = join(PKG, 'journeys', 'vendor-examples.json');
 await loadPlaceholders(PKG);
-const examples = published(PKG);
+const examples = published(PKG, undefined);
 const byId = new Map(examples.map((e) => [e.id, e]));
 if (byId.size !== examples.length)
     throw new Error(`${vendor}: ${examples.length - byId.size} published examples share an id`);
@@ -1121,11 +1127,13 @@ const shape = await shapeChecker(PKG);
 for (const e of examples) {
     if (e.patchRemoved || !e.request || !shape)
         continue;
-    const routed = shape.operationOf(e.request.method, e.request.url, {})?.op.id;
+    const hit = shape.operationOf(e.request.method, new URL(e.request.url, `http://${journey.host ?? 'twin.local'}`).href, e.request.headers);
+    const routed = hit ? operationKey(hit.op.id, hit.lane) : undefined;
     if (e.operation === 'gap' && routed === undefined)
         continue;
-    if (routed !== e.operation)
-        throw new Error(`spec/doc-examples.json: "${e.id}" sends ${e.request.method} ${e.request.url}, which the spec routes to ${routed ?? 'no operation'}, not ${e.operation}`);
+    const expected = operationKey(e.operation, e.lane);
+    if (routed !== expected)
+        throw new Error(`spec/doc-examples.json: "${e.id}" sends ${e.request.method} ${e.request.url}, which the spec routes to ${routed ?? 'no operation'}, not ${expected}`);
 }
 const sweeping = process.argv.includes('--sweep');
 const sweepHits = [];
@@ -1258,18 +1266,20 @@ await walk(journey, world.root(), failures, {
         after: (step, _path, answer, stepFailures) => {
             if (isGit(step) || isWait(step) || isSocket(step))
                 return;
-            if (!isResp(step) && !isLine(step)) {
+            const request = answer.request;
+            const hit = request ? shape?.operationOf(request.method, request.url, request.headers) : undefined;
+            const operation = hit?.op;
+            if (request) {
                 const st = step;
-                const method = (st.method ?? 'GET').toUpperCase();
+                const method = request.method;
                 // a read by what the operation does (an RPC wire POSTs its reads), else by its verb
-                const op = shape?.operationOf(method, _path, { ...(journey.headers ?? {}), ...(st.headers ?? {}) })?.op;
-                const opClass = op?.class;
+                const opClass = operation?.class;
                 const isRead = opClass ? ['retrieve', 'list', 'computed'].includes(opClass) : method === 'GET';
                 if (isRead)
-                    reads.push({ path: bare(_path), body: JSON.stringify(answer.body ?? '') });
+                    reads.push({ path: bare(request.url), body: JSON.stringify(answer.body ?? '') });
                 else if (st.example && answer.status < 300 && answer.body && typeof answer.body === 'object' && !Array.isArray(answer.body) && Object.keys(answer.body).length <= 3) {
                     const body = answer.body;
-                    const segs = bare(_path).split('/');
+                    const segs = bare(request.url).split('/');
                     // an action on a subject (`/emails/{id}/cancel`) touches the subject; a create touches the new id under the collection;
                     // a write whose subject is neither minted nor in its path (an RPC call naming it in its body) is left to the judge
                     const minted = typeof body.id === 'string' ? body.id : '';
@@ -1277,8 +1287,7 @@ await walk(journey, world.root(), failures, {
                     if (minted || idInPath) {
                         const base = minted && !segs.includes(minted) ? `${segs.join('/')}/${minted}` : /^[a-z_-]+$/.test(segs.at(-1) ?? '') && segs.length > 2 ? segs.slice(0, -1).join('/') : segs.join('/');
                         // only an effect the vendor gives a door to read: a GET of the subject or of its collection (a moderation has neither)
-                        const hdrs = { ...(journey.headers ?? {}), ...(st.headers ?? {}) };
-                        const gets = (at) => shape?.operationOf('GET', at, hdrs)?.op.method.toUpperCase() === 'GET';
+                        const gets = (at) => shape?.operationOf('GET', new URL(at, request.url).href, request.headers)?.op.method.toUpperCase() === 'GET';
                         const door = !shape || gets(base) || gets(base.split('/').slice(0, -1).join('/'));
                         if (door)
                             thinWrites.push({ step: st.name, base, id: base.split('/').at(-1) ?? '', from: reads.length, deletes: method === 'DELETE' || opClass === 'delete' });
@@ -1308,20 +1317,20 @@ await walk(journey, world.root(), failures, {
                 unknown.push(s.example);
                 return;
             }
-            specSchemas = schemasByOperation[ex.operation] ?? {};
+            const key = operationKey(ex.operation, ex.lane);
+            specSchemas = schemasByOperation[key] ?? {};
             replayed.add(s.example);
-            if (ex.operation === 'gap' && ex.request) {
-                const sent = new URL(_path, `https://${journey.host}`);
-                if (s.method !== ex.request.method || sent.href !== ex.request.url)
+            if (ex.operation === 'gap' && ex.request && request) {
+                if (request.method !== ex.request.method || request.url !== ex.request.url)
                     failures.push({ step: s.name, beat: 'EXAMPLE', detail: 'the unknown request differs from its recorded method or URL' });
             }
-            if (ex.authorizationAbsent && Object.keys({ ...(journey.headers ?? {}), ...(s.headers ?? {}) }).some((key) => key.toLowerCase() === 'authorization'))
+            if (ex.authorizationAbsent && request && new Headers(request.headers).has('authorization'))
                 failures.push({ step: s.name, beat: 'EXAMPLE', detail: 'the recording has no Authorization header, but the replay sends one' });
             // the step calls the example's operation (the spec's, as the walk's SHAPE check reads the request)
-            if (!isResp(step) && !isLine(step) && shape) {
-                const called = shape.operationOf(s.method, _path, { ...(journey.headers ?? {}), ...(s.headers ?? {}) })?.op.id;
-                if (called && called !== ex.operation)
-                    failures.push({ step: s.name, beat: 'EXAMPLE', detail: `calls ${called}, not the example's operation ${ex.operation}` });
+            if (request && shape) {
+                const called = hit ? operationKey(hit.op.id, hit.lane) : undefined;
+                if (called && called !== key)
+                    failures.push({ step: s.name, beat: 'EXAMPLE', detail: `calls ${called}, not the example's operation ${key}` });
             }
             // the example is sent as published: its input as the body, to its operation
             // a published field the step leaves out (`unsent`: a rendered value naming an object the World does not hold) must
@@ -1329,26 +1338,28 @@ await walk(journey, world.root(), failures, {
             for (const [path, why] of Object.entries(s.unsent ?? {})) {
                 if (!why)
                     failures.push({ step: s.name, beat: 'EXAMPLE', detail: `unsent ${path} gives no reason` });
-                if (requiredAt(operationSchemas[ex.operation]?.request, path))
+                if (requiredAt(operationSchemas[key]?.request, path))
                     failures.push({ step: s.name, beat: 'EXAMPLE', detail: `unsent ${path} is required by the operation's request schema` });
             }
             const publishedBody = exampleBody({ ...s, body: ex.input, form: undefined, bodyBase64: undefined }, ex.input);
             const inputType = Object.entries(ex.request?.headers ?? {}).find(([k]) => k.toLowerCase() === 'content-type')?.[1]
-                ?? Object.entries({ ...journey.headers, ...s.headers }).find(([k]) => k.toLowerCase() === 'content-type')?.[1];
+                ?? (request ? new Headers(request.headers).get('content-type') ?? undefined : undefined);
             const publishedInput = s.unsent && publishedBody !== undefined ? withoutPaths(publishedBody, Object.keys(s.unsent)) : publishedBody;
             // the body the step sends, every check below reading it alike: no body (a GET) is the empty input a page publishes for it
             const body = isResp(s) ? s.resp : exampleBody(s, publishedInput) ?? {};
             // A placeholder used as a request-map key is bound by its scalar request position, just as an answer key is.
             const input = answerKeys(publishedInput, publishedInput, body, ex.placeholder, true);
-            if (ex.restXml)
-                for (const p of restXmlInputProblems(ex.restXml, (input ?? {}), shape?.pathOf?.(_path) ?? _path, { ...(journey.headers ?? {}), ...(s.headers ?? {}) }, placeholderIds, s.path))
-                    failures.push({ step: s.name, beat: 'EXAMPLE', detail: `the request is not the example's published input: ${p}` });
+            if (ex.restXml) {
+                if (request)
+                    for (const p of restXmlInputProblems(ex.restXml, (input ?? {}), shape?.pathOf(request.method, request.url, request.headers) ?? request.url, request.headers, placeholderIds, s.path))
+                        failures.push({ step: s.name, beat: 'EXAMPLE', detail: `the request is not the example's published input: ${p}` });
+            }
             else if (input !== undefined && (!requestMapKeysHold(publishedInput, input, body, ex.placeholder) || (ex.partial ? !holds(body, input, ex.placeholder, undefined, ex.names, false, inputType) : !same(body, input, ex.placeholder ?? /(?!)/, undefined, ex.names, false, inputType))))
                 failures.push({ step: s.name, beat: 'EXAMPLE', detail: typeof input === 'string' ? comparedText(body, input, ex.placeholder ?? /(?!)/, undefined, ex.names, inputType)?.problem ?? "the body is not the example's published input" : "the body is not the example's published input" });
             // a scenario's turn is sent as the RFC writes it: its client lines (none for the greeting, a connect)
             if (ex.lines && JSON.stringify([s.send ?? []].flat()) !== JSON.stringify(ex.lines))
                 failures.push({ step: s.name, beat: 'EXAMPLE', detail: `sends ${JSON.stringify(s.send ?? null)}, not the scenario's ${JSON.stringify(ex.lines)}` });
-            const target = Object.entries({ ...journey.headers, ...s.headers }).find(([k]) => k.toLowerCase() === 'x-amz-target')?.[1];
+            const target = request ? new Headers(request.headers).get('x-amz-target') : undefined;
             if (ex.target && !target?.endsWith(`.${ex.target}`))
                 failures.push({ step: s.name, beat: 'EXAMPLE', detail: `x-amz-target is ${target}, not the example's operation ${ex.target}` });
             if (ex.status && answer.status !== ex.status && !s.exampleDiffers?.status)
@@ -1391,9 +1402,8 @@ await walk(journey, world.root(), failures, {
             const published = isResp(s) && publishedValue !== undefined ? (Array.isArray(s.resp?.[0]) ? publishedValue : [publishedValue]) : publishedValue;
             const responseType = answer.headers?.['content-type'];
             const literal = isResp(s) || (published !== null && typeof published !== 'object');
-            const valueSchema = ex.schema ?? operationSchemas[ex.operation]?.responses[String(answer.status)];
-            comparisonCollections = [...(storedCollectionFields[vendor]?.[ex.operation] ?? [])];
-            const operation = shape?.operationOf((s.method ?? 'GET').toUpperCase(), _path, { ...(journey.headers ?? {}), ...(s.headers ?? {}) })?.op;
+            const valueSchema = ex.schema ?? operationSchemas[key]?.responses[String(answer.status)];
+            comparisonCollections = [...(storedCollectionFields[vendor]?.[key] ?? [])];
             // A derived resource list names its holder; never treat every array under a read as a list.
             if (operation?.class === 'list' && operation.answers?.list) {
                 const holder = operation.answers.key ? published?.[operation.answers.key] : published;
@@ -1439,7 +1449,7 @@ await walk(journey, world.root(), failures, {
     },
 });
 const owners = (await vendorFetch(PACKS, vendor))?.(world.root())?.owners?.() ?? (await vendorStream(PACKS, vendor))?.(world.root())?.owners?.() ?? {};
-const ownerOf = (e) => e.wire === 'client' ? 'gap' : owners[e.lane ? `${e.lane}:${e.operation}` : e.operation];
+const ownerOf = (e) => e.wire === 'client' ? 'gap' : owners[operationKey(e.operation, e.lane)];
 const patchRemoved = examples.filter((e) => e.patchRemoved);
 const unserved = examples.filter((e) => !e.patchRemoved && ownerOf(e) === 'gap');
 const recorded = Object.keys(journey.notReplayed ?? {});

package/dist/src/verdict.js

@@ -1,7 +1,7 @@
 // A JUDGE'S INDEPENDENCE (the grade's outline-judged and life-judged, the published examples' verdict): a verdict rules
 // only when it names its judge (`judge.agent`) and the authors of what it judges (`authors`), and the judge is none of
 // them. The dispatcher stamps author names consistently; a judge started independently
-// (scripts/judge-brief.ts prints its brief) names its reviewer role (`judge.name`). One judging per pack: the
+// (`twin-standard judge-brief` prints its brief) names its reviewer role (`judge.name`). One judging per pack: the
 // verdict stands, and later changes to what it judged keep it (architecture, "Writing a life", Judge).
 /** Committed attribution names people or author roles, never execution identities. */
 export function attributionName(name) {

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

@@ -1,5 +1,8 @@
 import { type TwinStream } from '@volter/world-core/runtime';
 import { type Captured, type GitStep, type Journey, type JourneyStep, type LineStep, type RespStep } from './journey-kit.js';
+import { type ReplayStep } from './replay.js';
+import type { ManagedDatabaseWalk } from './walk-database.js';
+export { leaked } from './shape.js';
 export declare function usePacks(dir: string, options?: {
     dependenciesFrom?: string;
 }): void;
@@ -13,26 +16,31 @@ export declare function inMemoryWorld(label: string): {
     root: () => string;
     restore: () => void;
 };
+type SentRequest = {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+};
+type StepAnswer = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+    request?: SentRequest;
+    wireBody?: unknown;
+    sql?: ReplayStep['sql'];
+    connection?: ReplayStep['connection'];
+};
 export type Failure = {
     step: string;
     beat: string;
     detail: string;
 };
-/** 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 declare function leaked(v: unknown, vendorFields: Set<string>, at?: string, unshaped?: boolean): string[];
 /** What a caller that scores a walk observes around each step: the step, its resolved path and body,
- *  and (after) the answer and the failures the step produced. */
+ *  and (after) the answer and the failures the step produced. HTTP answers include the constructed request and
+ *  decoded wire body separately from the capture view. */
 export type StepHooks = {
     before?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, body: unknown) => void;
-    after?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, answer: {
-        status: number;
-        body: unknown;
-        headers?: Record<string, string>;
-    }, failures: Failure[]) => void;
+    after?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, answer: StepAnswer, failures: Failure[]) => void;
 };
 /** A pack served for a walk the way a World runs it (its server.ts on a port, the World's root and scenario its options):
  *  the walk's requests go to it over HTTP, the vendor's host in their Host header, instead of to the fetch in process;
@@ -42,9 +50,9 @@ export type ServedTwin = (root: string, options: {
     application?: import('@volter/world-core').PackFetchOptions['application'];
 }) => Promise<{
     scheme?: 'http' | 'https';
-    fetch: (request: Request, options?: {
+    fetch: ((request: Request, options?: {
         credentials?: RequestCredentials;
-    }) => Promise<Response>;
+    }) => Promise<Response>) & ManagedDatabaseWalk;
     stop: () => void | Promise<void>;
     socket?: (url: string, headers: Record<string, string>) => WebSocket;
     stream?: TwinStream;