@volter/twin-standard 1.0.157 → 1.0.159

package/dist/src/tools/life-coverage-walk.js

@@ -16,7 +16,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { listActions, observeTransitions, stateOf } from '@volter/world-core/runtime';
 import { inMemoryWorld, walk, usePacks } from "../walk/behavior-journey.js";
-import { lanesOf, shapeChecker } from "../walk/shape.js";
+import { lanesOf, lineShape, shapeChecker } from "../walk/shape.js";
 import { sharingLanesIn } from "../lanes.js";
 /** Registers, in the `bun test` run that imports it, the walks of `vendor` in the pack repository at `PACKS`. */
 export async function coverageWalks(PACKS, vendor) {
@@ -36,9 +36,12 @@ export async function coverageWalks(PACKS, vendor) {
             const { manifest } = (await import(__rewriteRelativeImportExtension(join(PACKS, vendor, 'src', 'manifest.ts'))));
             // the lanes over the vendor's state its serve factory serves are walked by this life, their machines with the vendor's
             // ("Pack layout"); two manifests naming one resource's field would collide in the keys below, so that refuses
-            const laneManifests = await Promise.all(sharingLanes(vendor).map(async (l) => (await import(__rewriteRelativeImportExtension(join(PACKS, vendor, l, 'src', 'manifest.ts')))).manifest));
+            const units = [{ dir: join(PACKS, vendor), manifest, lane: undefined }, ...await Promise.all(sharingLanes(vendor).map(async (l) => {
+                    const dir = join(PACKS, vendor, l);
+                    return { dir, lane: l, manifest: (await import(__rewriteRelativeImportExtension(join(dir, 'src', 'manifest.ts')))).manifest };
+                }))];
             // a vendor of lanes' root (a VendorManifest) declares no resources of its own: its lanes do
-            const allResources = [manifest, ...laneManifests].flatMap((mf) => Object.entries(mf.resources ?? {}));
+            const allResources = units.flatMap(({ manifest: mf }) => Object.entries(mf.resources ?? {}));
             const machines = new Map();
             for (const [resource, decl] of allResources)
                 for (const [field, machine] of Object.entries(decl.state ?? {})) {
@@ -50,23 +53,28 @@ export async function coverageWalks(PACKS, vendor) {
                     machines.set(name, machine);
                 }
             const where = new Map();
-            for (const mf of [manifest, ...laneManifests])
+            const httpTransitions = new Set();
+            for (const { dir, manifest: mf } of units) {
+                const http = !lineShape(dir);
                 for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
                     for (const [field, m] of Object.entries(decl.state ?? {}))
                         m.transitions.forEach((t, i) => {
+                            if (http)
+                                httpTransitions.add(t);
                             const place = { at: `${resource}.${field}#${i}`, field, type: decl.storedAs ?? resource, service: mf.service ?? mf.vendor };
                             const places = where.get(t) ?? [];
                             if (!places.some((p) => p.at === place.at && p.type === place.type && p.service === place.service))
                                 where.set(t, [...places, place]);
                         });
                 }
+            }
             const moves = new Map();
             const subjectKey = (service, type, id) => JSON.stringify([service, type, id]);
             observeTransitions((_decl, t, outcome, from, entry) => {
                 const places = where.get(t) ?? [];
                 if (outcome === 'refused') {
-                    // A failed check on an already committed write is no refusal the application received.
-                    if (entry)
+                    // HTTP refusals are credited from their received status and body; a line protocol owns its session's replies.
+                    if (entry || httpTransitions.has(t))
                         return;
                     const groups = new Set(places.map((p) => JSON.stringify([p.service, p.type, p.field])));
                     if (groups.size === 1)
@@ -100,11 +108,14 @@ export async function coverageWalks(PACKS, vendor) {
             const shape = await shapeChecker(join(PACKS, vendor));
             const answered = [];
             try {
-                await walk(life, root, failures, { beats: w.beats, hooks: { after: (step, path, answer) => {
+                await walk(life, root, failures, { beats: w.beats, hooks: { after: (_step, _path, answer) => {
                             // a line step's refusals are the machine's own (observeTransitions); a request's are read off its answer
-                            const op = 'method' in step ? shape?.operationOf(step.method, path, { ...(life.headers ?? {}), ...(step.headers ?? {}) })?.op.id : undefined;
-                            if (op)
-                                answered.push({ op, text: JSON.stringify(answer.body ?? ''), body: answer.body });
+                            const request = answer.request;
+                            if (!request)
+                                return;
+                            const hit = shape?.operationOf(request.method, request.url, request.headers);
+                            if (hit)
+                                answered.push({ op: hit.op.id, lane: hit.lane, status: answer.status, body: answer.wireBody });
                         } } });
                 // a declared refusal is reached when a step on its operation was answered with it: its code, or its message
                 // up to the first placeholder
@@ -112,26 +123,27 @@ export async function coverageWalks(PACKS, vendor) {
                 const holds = (value, code) => (value !== null && typeof value === 'object'
                     ? Object.values(value).some((v) => holds(v, code))
                     : (typeof value === 'string' || typeof value === 'number') && String(value) === code);
-                const answers = (a, r) => r.code !== undefined ? holds(a.body, String(r.code)) : a.text.includes(r.message.split('{')[0].trim());
-                for (const [resource, decl] of allResources) {
-                    for (const [field, m] of Object.entries(decl.state ?? {})) {
-                        m.transitions.forEach((t, i) => {
-                            if (!t.operation)
-                                return;
-                            const on = answered.filter((a) => a.op === t.operation);
-                            if (t.refusal && on.some((a) => answers(a, t.refusal)))
-                                seen.add(`${resource}.${field}#${i}|refused|*`);
-                            for (const [from, r] of Object.entries(t.refusals ?? {}))
-                                if (on.some((a) => answers(a, r)))
-                                    seen.add(`${resource}.${field}#${i}|refused|${from}`);
-                        });
+                const answers = (a, r) => a.status === r.status && (r.code !== undefined ? holds(a.body, String(r.code)) : JSON.stringify(a.body)?.includes(r.message.split('{')[0].trim()) === true);
+                for (const { manifest: mf, lane } of units)
+                    for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
+                        for (const [field, m] of Object.entries(decl.state ?? {})) {
+                            m.transitions.forEach((t, i) => {
+                                if (!t.operation)
+                                    return;
+                                const on = answered.filter((a) => a.op === t.operation && a.lane === lane);
+                                if (t.refusal && on.some((a) => answers(a, t.refusal)))
+                                    seen.add(`${resource}.${field}#${i}|refused|*`);
+                                for (const [from, r] of Object.entries(t.refusals ?? {}))
+                                    if (on.some((a) => answers(a, r)))
+                                        seen.add(`${resource}.${field}#${i}|refused|${from}`);
+                            });
+                        }
                     }
-                }
                 // every change the life made to a declared state field, from the World's log in order: a move is the declared
                 // transition that allows it (from its state to the next, by its operation when both name one); a change no
                 // transition allows is an undeclared move
                 const fieldsOf = new Map();
-                for (const mf of [manifest, ...laneManifests])
+                for (const { manifest: mf } of units)
                     for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
                         const key = JSON.stringify([mf.service ?? mf.vendor, decl.storedAs ?? resource]);
                         for (const [field, m] of Object.entries(decl.state ?? {}))
@@ -139,7 +151,7 @@ export async function coverageWalks(PACKS, vendor) {
                     }
                 const current = new Map();
                 // the services the life wrote: the vendor's, or its lanes' (a vendor of lanes' root names none of its own)
-                const services = [...new Set([manifest, ...laneManifests].map((mf) => mf.service).filter((x) => typeof x === 'string'))];
+                const services = [...new Set(units.map(({ manifest: mf }) => mf.service).filter((x) => typeof x === 'string'))];
                 if (!services.length)
                     services.push(manifest.vendor);
                 for (const a of services.flatMap((service) => listActions(service, root))) {

package/dist/src/tools/score-pack.js

@@ -3,7 +3,7 @@
 // life per pack is walked through the pack's own fetch on the in-memory World, and the report says:
 //   - the life: whether a judge's plausible verdict names its current content (a verdict its author wrote is not one);
 //   - correctness: every check on every step (status, expectations, captures, SHAPE, the beats) and the life
-//     answering byte for byte the same on a second fresh World;
+//     answering the same on a second fresh World under its declared engine outputs;
 //   - coverage: the hand-written code the life and the vendor's published examples run and the declared state logic
 //     they reach (life-coverage.ts), with what they never reach;
 //   - the vendor's published examples: replayed and judged (vendor-examples.ts);
@@ -26,6 +26,7 @@ import { dirname, join, sep } from 'node:path';
 import { inMemoryWorld, walk, withPinnedWorldDraws, usePacks } from "../walk/behavior-journey.js";
 import { expandFills, waitMs } from "../walk/journey-kit.js";
 import { vendorFetch, vendorStream } from "../walk/vendor-fetch.js";
+import { compareReplays } from "../walk/replay.js";
 import { existenceProbe } from "../walk/journey-kit.js";
 import { kernelCheckout, packsRoot, toolPath } from "./packs-root.js";
 const PACKS = packsRoot();
@@ -85,7 +86,7 @@ await walk(life, world.root(), failures, { beats: true });
 const answers = async () => {
     const seen = [];
     // the World's own draws (its seed, its keys) are the same in both: two Worlds differ only by what is beyond them (R9)
-    await withPinnedWorldDraws(() => walk(life, world.root(), [], { beats: false, hooks: { after: (step, p, a) => seen.push(`${step.name ?? ''}\u0000${p} ${a.status} ${JSON.stringify(a.body)}`) } }));
+    await withPinnedWorldDraws(() => walk(life, world.root(), failures, { beats: false, hooks: { after: (step, path, answer) => seen.push({ name: step.name ?? '', path, status: answer.status, body: answer.body, ...(answer.sql ? { sql: answer.sql } : {}), ...(answer.connection ? { connection: answer.connection } : {}) }) } }));
     return seen;
 };
 const [first, second] = [await answers(), await answers()];
@@ -184,9 +185,9 @@ const flags = [];
         }
     }
 }
-const differs = first.findIndex((line, i) => line !== second[i]);
-if (differs >= 0 || first.length !== second.length)
-    failures.push({ step: '(whole life)', beat: 'REPLAYABLE', detail: `a second fresh World answered differently at "${(first[differs] ?? second[differs] ?? first.at(-1) ?? '').split('\u0000')[0]}" (the ${differs + 1}th answered step; waits are not counted)` });
+const replayComparison = compareReplays(first, second);
+for (const detail of replayComparison.diagnostics)
+    failures.push({ step: '(whole life)', beat: 'REPLAYABLE', detail });
 // ── breadth ──────────────────────────────────────────────────────────────────────────────────
 const factory = await vendorFetch(PACKS, vendor);
 const fetch = factory?.(world.root());

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

@@ -56,7 +56,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 +70,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) {
@@ -106,7 +107,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 +125,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 +139,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 +151,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 +192,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 +237,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 +254,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 +297,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 +313,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 +409,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'));
+    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 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 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,22 +442,6 @@ 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,
     // its patches applied to the Discovery document first (spec-ir-discovery.ts)
     const discovery = spec !== undefined && /discovery\.json(\.gz)?$/.test(spec);
@@ -454,8 +460,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 +985,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 +1111,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 +1128,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 +1267,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 +1288,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 +1318,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 +1339,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 +1403,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 +1450,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 ?? {});