@volter/twin-standard 1.0.158 → 1.0.160

package/src/tools/vendor-examples.ts

@@ -35,8 +35,7 @@
 // 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.ts';
 import { archiveSource } from '../archive-source.ts';
@@ -48,7 +47,7 @@ import { basename, join, resolve } from 'node:path';
 import { gunzipSync } from 'node:zlib';
 import { inMemoryWorld, walk, type Failure, usePacks } from '../walk/behavior-journey.ts';
 import { vendorFetch, vendorStream } from '../walk/vendor-fetch.ts';
-import { at as selectorAt, captureAt, expandFills, isResp, isGit, isLine, isSocket, isWait, type Journey, type JourneyStep, type LineStep } from '../walk/journey-kit.ts';
+import { at as selectorAt, captureAt, expandFills, isResp, isGit, isSocket, isWait, type Journey, type JourneyStep, type LineStep } from '../walk/journey-kit.ts';
 import { lanesOf, shapeChecker } from '../walk/shape.ts';
 import { applySpecPatch, discoveryToOpenAPI, mergeDocuments, readSpecDocuments, slug, type SpecPatch } from '../spec.ts';
 import { packsRoot } from './packs-root.ts';
@@ -63,7 +62,7 @@ usePacks(PACKS);
  *  still be the sample's type. `schema` is the served spec's schema of the answer, which says where null is allowed. */
 /** `placeholder`: strings of the published input matching it stand for ids the World mints (openai's `vs_abc123`), so the
  *  step sends a string there, not that one. */
-type Example = { names?: string[]; wire?: 'client'; patchRemoved?: boolean; id: string; operation: string; lane?: string; status?: number; output: unknown; input?: unknown; partial?: boolean; placeholder?: RegExp; target?: string; restXml?: string; lines?: string[]; sample?: boolean; schema?: SpecSchema; request?: { method: string; url: string; headers?: Record<string, string> }; authorizationAbsent?: boolean };
+type Example = { names?: string[]; wire?: 'client'; patchRemoved?: boolean; id: string; operation: string; lane?: string; status?: number; output: unknown; input?: unknown; partial?: boolean; placeholder?: RegExp; target?: string; restXml?: RestXml; lines?: string[]; sample?: boolean; schema?: SpecSchema; request?: { method: string; url: string; headers?: Record<string, string> }; authorizationAbsent?: boolean };
 /** A served spec's schema, its references resolved lazily (`resolveSchema`). */
 type SpecSchema = { $ref?: string; nullable?: boolean; properties?: Record<string, SpecSchema>; items?: SpecSchema; allOf?: SpecSchema[]; anyOf?: SpecSchema[]; oneOf?: SpecSchema[]; [k: string]: unknown };
 let specSchemas: Record<string, SpecSchema> = {};
@@ -71,6 +70,7 @@ let specSchemas: Record<string, SpecSchema> = {};
 const schemasByOperation: Record<string, Record<string, SpecSchema>> = {};
 /** Each operation's request-body schema and its JSON answers' schemas by status, as the served spec gives them. */
 const operationSchemas: Record<string, { request?: SpecSchema; responses: Record<string, SpecSchema> }> = {};
+const operationKey = (operation: string, lane: string | undefined): string => 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. */
@@ -94,7 +94,7 @@ function answerKeys(output: unknown, published: unknown, sent: unknown, placehol
   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<T extends object>(pkg: string, doc: T): T {
@@ -107,7 +107,9 @@ function served<T extends object>(pkg: string, doc: T): T {
 
 // ── a restXml service's examples (S3's): the input where each member's binding puts it, the answer read by its shape ──
 type Json = any;
-let xmlModel: { shapes: Record<string, Json> } | undefined;
+type SmithyModel = { shapes: Record<string, Json> };
+type RestXml = { id: string; model: SmithyModel };
+const restXmlService = (model: SmithyModel): boolean => 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: unknown, translated: unknown, sent: unknown, placeholder?: RegExp): boolean {
   if (!placeholder || !published || typeof published !== 'object') return true;
@@ -122,10 +124,10 @@ function requestMapKeysHold(published: unknown, translated: unknown, sent: unkno
 }
 
 const PRELUDE: Record<string, string> = { Boolean: 'boolean', PrimitiveBoolean: 'boolean', Integer: 'integer', PrimitiveInteger: 'integer', Long: 'long', PrimitiveLong: 'long', Float: 'float', Double: 'double' };
-const scalarType = (target: string): string => xmlModel?.shapes[target]?.type ?? PRELUDE[target.split('#')[1] ?? ''] ?? 'string';
-const scalarOf = (target: string, v: unknown): unknown => {
+const scalarType = (model: SmithyModel, target: string): string => model.shapes[target]?.type ?? PRELUDE[target.split('#')[1] ?? ''] ?? 'string';
+const scalarOf = (model: SmithyModel, target: string, v: unknown): unknown => {
   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)) return /^[+-]?\d+$/.test(v) ? exactInteger(v) : v;
   return ['float', 'double'].includes(t) && v !== '' && !Number.isNaN(Number(v)) ? Number(v) : v;
@@ -134,39 +136,39 @@ const arrayOf = (v: unknown): unknown[] => (v === undefined || v === '' ? [] : A
 
 /** 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: string, v: unknown): unknown {
-  const shape = xmlModel?.shapes[target];
-  if (!shape || shape.type !== 'structure') return scalarOf(target, v);
+function typedXml(model: SmithyModel, target: string, v: unknown): unknown {
+  const shape = model.shapes[target];
+  if (!shape || shape.type !== 'structure') return scalarOf(model, target, v);
   if (!v || typeof v !== 'object') return v === '' ? {} : v;
   const obj = v as Record<string, unknown>;
   const out: Record<string, unknown> = {};
   for (const [name, m] of Object.entries((shape.members ?? {}) as Record<string, Json>)) {
     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)); continue; }
+      if (m.traits?.['smithy.api#xmlFlattened'] !== undefined) { if (raw !== undefined) 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 as Record<string, unknown>)[memberEl]).map((i) => typedXml(ts.member.target, i));
-    } else if (raw !== undefined) out[name] = typedXml(m.target, raw);
+      out[name] = arrayOf(raw === '' ? undefined : (raw as Record<string, unknown>)[memberEl]).map((i) => typedXml(model, ts.member.target, i));
+    } else if (raw !== undefined) 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: string, body: unknown, headers: Record<string, string> = {}): unknown {
-  const out = xmlModel!.shapes[xmlModel!.shapes[opId]?.output?.target ?? ''];
+function restXmlAnswer({ id: opId, model }: RestXml, body: unknown, headers: Record<string, string> = {}): unknown {
+  const out = model.shapes[model.shapes[opId]?.output?.target ?? ''];
   if (!out) return body;
   const members = Object.entries((out.members ?? {}) as Record<string, Json>);
   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)) as Record<string, unknown>;
+  const answer = (payload ? { [payload[0]]: typedXml(model, payload[1].target, body) } : typedXml(model, model.shapes[opId].output.target, body)) as Record<string, unknown>;
   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()]);
+    if (h !== undefined && lower[String(h).toLowerCase()] !== undefined) 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) answer[name] = Object.fromEntries(Object.entries(lower).filter(([k]) => k.startsWith(String(prefix).toLowerCase())).map(([k, v]) => [k.slice(String(prefix).length), v]));
@@ -176,8 +178,8 @@ function restXmlAnswer(opId: string, body: unknown, headers: Record<string, stri
 
 /** 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: string, input: Record<string, unknown>, path: string, headers: Record<string, string>, placeholder: RegExp, rawPath?: string): string[] {
-  const shape = xmlModel!.shapes[xmlModel!.shapes[opId]?.input?.target ?? ''];
+function restXmlInputProblems({ id: opId, model }: RestXml, input: Record<string, unknown>, path: string, headers: Record<string, string>, placeholder: RegExp, rawPath?: string): string[] {
+  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")
@@ -215,11 +217,13 @@ function lenientJson(text: string): string {
  *  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: string): Example[] {
+function published(pkg: string, lane: string | undefined): Example[] {
   // 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')) as SmithyModel : 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
@@ -231,7 +235,7 @@ function published(pkg: string): Example[] {
  *  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: string): Example[] {
+function fromDocs(pkg: string, lane: string | undefined, model: SmithyModel | undefined): Example[] {
   const file = join(pkg, 'spec', 'doc-examples.json');
   if (!existsSync(file)) return [];
   const docs = parseExactJson(readFileSync(file, 'utf8')) as Array<{ wire?: 'client'; title: string; source: string; quote?: string; operation: string; input?: unknown; output?: unknown; means: string; status?: number; rendered?: boolean; placeholders?: { names: string[]; quote: string }; request?: { method: string; url: string; headers?: Record<string, string> } }>;
@@ -261,11 +265,10 @@ function fromDocs(pkg: string): Example[] {
   // a page that names its own variables for the reader to fill ("Make sure to fill in the … BRANCH_NAME … variables")
   // lists them with that sentence quoted: each stands for any value, and the published text stays as written
   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})`);
     // the renderer writes any string it cannot fill as the word "string": in a rendered input it stands for any string
@@ -276,7 +279,13 @@ function fromDocs(pkg: string): Example[] {
   function fromPage(d: (typeof docs)[number], output: unknown, input: unknown): Example {
     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: RestXml | undefined;
+    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 } : {}) };
   }
 }
 
@@ -351,11 +360,23 @@ function decodedExample(media: string, value: unknown): unknown {
   try { return parseExactJson(value); } catch { return value; }
 }
 
-function fromSpec(pkg: string): Example[] {
+function fromSpec(pkg: string, lane: string | undefined, model: SmithyModel | undefined): Example[] {
   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: Example[] = [];
+  if (model) {
+    const restXml = restXmlService(model);
+    for (const [id, shape] of Object.entries(model.shapes)) {
+      const examples = shape.traits?.['smithy.api#examples'] as Array<{ title: string; input?: unknown; output?: unknown; error?: { content?: unknown } }> | undefined;
+      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 [];
   // a command table (Redis's src/commands/*.json) publishes no examples either: its examples are its documentation's
@@ -366,23 +387,9 @@ function fromSpec(pkg: string): Example[] {
   const documents = spec ? undefined : readSpecDocuments(join(pkg, 'spec'));
   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: Example[] = [];
-  if (spec && /smithy\.json(\.gz)?$/.test(spec)) {
-    const model = parseExactJson(text) as { shapes: Record<string, { type?: string; traits?: Record<string, unknown> }> };
-    const restXml = Object.values(model.shapes).some((sh) => sh.type === 'service' && sh.traits?.['aws.protocols#restXml'] !== undefined);
-    if (restXml) xmlModel = model as { shapes: Record<string, Json> };
-    for (const [id, shape] of Object.entries(model.shapes)) {
-      const examples = shape.traits?.['smithy.api#examples'] as Array<{ title: string; input?: unknown; output?: unknown; error?: { content?: unknown } }> | undefined;
-      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;
-  }
   type Op = { operationId?: string; responses?: Record<string, Record<string, unknown>>; 'x-oaiMeta'?: { examples?: unknown } };
   type Doc = { paths: Record<string, Record<string, Op>>; components?: { examples?: Record<string, { value?: unknown }>; schemas?: Record<string, SpecSchema> }; definitions?: Record<string, SpecSchema> };
-  // 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)]) as Doc[];
@@ -399,8 +406,9 @@ function fromSpec(pkg: string): Example[] {
       if (!op || typeof op !== 'object' || !('responses' in op)) continue;
       // Swagger 2: the request is the `in: body` parameter's schema, an answer its response's `schema`
       const bodyParam = ((op as { parameters?: Array<{ in?: string; schema?: SpecSchema }> }).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 as { requestBody?: { content?: unknown } }).requestBody?.content) ?? bodyParam?.schema,
         responses: Object.fromEntries(Object.entries(op.responses ?? {}).flatMap(([code, r]) => { const sch = json(r.content) ?? (r as { schema?: SpecSchema }).schema; return sch ? [[code, sch]] : []; })),
       };
@@ -829,17 +837,17 @@ function outputSchemaMismatches(schema: SpecSchema | undefined, value: unknown,
  * recorded with the per-example classification. Request echoes and generated output are absent. */
 const storedCollectionFields: Record<string, Record<string, string[]>> = {
   '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'] },
 };
@@ -931,7 +939,7 @@ if (!vendor || vendor.startsWith('-')) { console.error('usage: twin-standard exa
 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`);
@@ -948,9 +956,11 @@ const shape = await shapeChecker(PKG);
 // (a page of an operation the spec lacks can match another's route)
 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: string[] = [];
@@ -1065,17 +1075,19 @@ await walk(journey, world.root(), failures, {
     },
     after: (step, _path, answer, stepFailures) => {
       if (isGit(step) || isWait(step) || isSocket(step)) return;
-      if (!isResp(step) && !isLine(step as JourneyStep & LineStep)) {
+      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 as JourneyStep;
-        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 ?? '') });
+        if (isRead) 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 as Record<string, unknown>;
-          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 : '';
@@ -1083,8 +1095,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: string): boolean => shape?.operationOf('GET', at, hdrs)?.op.method.toUpperCase() === 'GET';
+            const gets = (at: string): boolean => 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' });
           }
@@ -1104,38 +1115,40 @@ await walk(journey, world.root(), failures, {
       if (!s.example) return;
       const ex = byId.get(s.example);
       if (!ex) { 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) failures.push({ step: s.name, beat: 'EXAMPLE', detail: 'the unknown request differs from its recorded method or 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')) failures.push({ step: s.name, beat: 'EXAMPLE', detail: 'the recording has no Authorization header, but the replay sends one' });
+      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
       // be one the operation's request schema does not require
       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)) failures.push({ step: s.name, beat: 'EXAMPLE', detail: `unsent ${path} is required by the operation's request schema` });
+        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 ?? {}) as Record<string, unknown>, shape?.pathOf?.(_path) ?? _path, { ...(journey.headers ?? {}), ...(s.headers ?? {}) }, placeholderIds, (s as { path?: string }).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 ?? {}) as Record<string, unknown>, shape?.pathOf(request.method, request.url, request.headers) ?? request.url, request.headers, placeholderIds, (s as { path?: string }).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) failures.push({ step: s.name, beat: 'EXAMPLE', detail: `answered ${answer.status}, the example ${ex.status}` });
       if (stepFailures.length) return;
@@ -1166,9 +1179,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 as Record<string, unknown>)?.[operation.answers.key] : published;
@@ -1209,7 +1221,7 @@ await walk(journey, world.root(), failures, {
 // an example of an operation the twin does not serve is breadth's gap (score-pack), counted here and not replayed
 type Owned = { owners?: () => Record<string, string> } | undefined;
 const owners = ((await vendorFetch(PACKS, vendor))?.(world.root()) as Owned)?.owners?.() ?? ((await vendorStream(PACKS, vendor))?.(world.root()) as Owned)?.owners?.() ?? {};
-const ownerOf = (e: Example): string | undefined => e.wire === 'client' ? 'gap' : owners[e.lane ? `${e.lane}:${e.operation}` : e.operation];
+const ownerOf = (e: Example): string | undefined => 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/src/verdict.ts

@@ -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. */