@volter/twin-standard 1.0.149 → 1.0.151

package/src/tools/vendor-examples.ts

@@ -0,0 +1,1250 @@
+#!/usr/bin/env bun
+// vendor-examples — a pack's twin replayed against the examples its vendor published (docs/contributing/architecture.md,
+// "Protocol 3"). A customer life shows the twin behaves as a believable customer finds it; this shows it answers what the
+// vendor itself says it answers, with no judge reading docs in between.
+//
+// The examples are the spec's own (Smithy, OpenAPI, Swagger, OpenAI's x-oaiMeta, Stripe's fixtures, a line protocol's RFC
+// scenarios) and those the vendor's documentation pages publish, vendored with their URLs in `spec/doc-examples.json`.
+//
+// `journeys/vendor-examples.json` is a journey (the customer life's step format) whose example steps carry
+// `example: "<operation>#<title>"`: the steps before one make true what the example assumes exists, and the example step
+// sends the example's request as published. Its answer must hold every key path of the example's answer with the same
+// JSON type for structured generated values; literal text and complete RESP replies compare exactly. Setup values are the step's
+// own `expect`. A key the twin answers otherwise is either a twin defect, fixed with the vendor's doc cited, or listed in
+// the step's `exampleDiffers` (a key path, or `status`) with why the vendor's example is wrong, or why the server the
+// twin models answers otherwise where the vendor's text allows it (Postfix's 252 to a VRFY the RFC shows answered 250). An example no World can replay is listed in the
+// file's `notReplayed` with its reason.
+//
+// An example of an operation the twin does not serve is counted, not replayed: that operation is breadth's gap
+// (score-pack.ts), and serving it brings its examples in.
+//
+// What the script cannot check a judge rules on (setup steps each an example's precondition or read-back, every
+// decided value asserted, each exampleDiffers and notReplayed reason true against the vendor's documentation), in
+// `journeys/vendor-examples.verdict.json`: `{sha256, plausible, judge: {agent}, authors}`, stamped by the dispatcher as
+// a life's verdict is (score-pack.ts); a verdict whose judge is among the authors, or that names other content, rules nothing.
+//
+// Done: every published example of a served operation replayed or recorded, the published status answered, no check
+// failing, no mismatch unexplained, and a judge's plausible verdict naming the file as it is.
+//
+// Two of the judges' recurring rulings are checks: an example step's answer value that an earlier step of the file sent or
+// captured (a name, an email, an id the setup decided) is asserted, or named in the step's `undecided` with the reason it
+// only coincides (a default the vendor applies); and a write example whose own answer is thin (three keys or fewer) has its
+// subject, minted or in its path, read by a later step, where the vendor gives a GET of the subject or its collection (a
+// delete is read back by either; an RPC write naming its subject in its body is left to the judge). Neither sees what the
+// setup only causes (a count of clicks, a date a send was made, a status a verify leads to), which the author and the judge
+// 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)
+import { parseExactJson, exactInteger, isExactIntegerValue } from '@volter/world-core/exact-json';
+import { hasOwnSurface } from '../lanes.ts';
+import { archiveSource } from '../archive-source.ts';
+import { sourceHeld, type SourceRecord } from '../check-sources.ts';
+import { notIndependent } from '../verdict.ts';
+import { parse as parseYaml } from 'yaml';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+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 { lanesOf, shapeChecker } from '../walk/shape.ts';
+import { applySpecPatch, discoveryToOpenAPI, mergeDocuments, readSpecDocuments, slug, type SpecPatch } from '../spec.ts';
+import { packsRoot } from './packs-root.ts';
+import { renderedScalar, isRenderedScalar, matchesRenderedScalar } from '../walk/rendered-scalar.ts';
+import { sseExampleAnswer } from '../walk/sse-example.ts';
+import { parseBracketForm, multipartBoundary, multipartEnvelope, inferMultipartBoundary, multipartDelimiterPattern } from '@volter/world-core/runtime';
+const PACKS = packsRoot();
+usePacks(PACKS);
+
+/** `sample`: the example is what an object can hold (Stripe's fixtures), not the answer to one request, so a field the
+ *  twin answers null for the request it was sent passes where the served spec lets it be null; a field it fills must
+ *  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 };
+/** 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> = {};
+// A lane can use the same component names as the vendor API for different wire shapes.
+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> }> = {};
+
+/** 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: unknown, published: unknown, sent: unknown, placeholder: RegExp | undefined, rawBindings = false): unknown {
+  if (!placeholder) return output;
+  const bindings = new Map<string, string | undefined>();
+  const pair = (p: unknown, value: unknown, key?: string): void => {
+    if (typeof p === 'string' && typeof value === 'string' && isPlaceholder(placeholder, p, key)) {
+      const actual = rawBindings ? value : filled(value);
+      bindings.set(p, bindings.has(p) && bindings.get(p) !== actual ? undefined : actual);
+    } else if (Array.isArray(p) && Array.isArray(value)) {
+      p.forEach((x, i) => pair(x, value[i], key));
+    } else if (p && value && typeof p === 'object' && typeof value === 'object') {
+      Object.entries(p).forEach(([k, x]) => pair(x, (value as Record<string, unknown>)[k], k));
+    }
+  };
+  pair(published, sent);
+  const mapped = (value: unknown): unknown => renderedMarker(value) ? value : Array.isArray(value) ? value.map(mapped)
+    : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([k, v]) => [bindings.get(k) ?? k, mapped(v)]))
+    : 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
+ *  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 {
+  const patchPath = join(pkg, 'spec', 'patches.json');
+  if (!existsSync(patchPath)) return doc;
+  const patched = structuredClone(doc);
+  for (const p of (parseExactJson(readFileSync(patchPath, 'utf8')) as { patches: SpecPatch[] }).patches) applySpecPatch(patched, p);
+  return patched;
+}
+
+// ── 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;
+/** 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;
+  if (Array.isArray(published)) return published.every((p, i) => requestMapKeysHold(p, (translated as unknown[] | undefined)?.[i], (sent as unknown[] | undefined)?.[i], placeholder));
+  if (!sent || typeof sent !== 'object' || !translated || typeof translated !== 'object') return false;
+  const keys = Object.keys(published);
+  if (keys.some((k) => placeholder.test(k)) && canonical(Object.keys(translated).sort()) !== canonical(Object.keys(sent).sort())) return false;
+  return keys.every((k, i) => {
+    const mapped = Object.keys(translated)[i]!;
+    return requestMapKeysHold((published as Record<string, unknown>)[k], (translated as Record<string, unknown>)[mapped], (sent as Record<string, unknown>)[mapped], placeholder);
+  });
+}
+
+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 => {
+  if (typeof v !== 'string') return v;
+  const t = scalarType(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;
+};
+const arrayOf = (v: unknown): unknown[] => (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: string, v: unknown): unknown {
+  const shape = xmlModel?.shapes[target];
+  if (!shape || shape.type !== 'structure') return scalarOf(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 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 (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);
+  }
+  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 ?? ''];
+  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 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()]);
+    // 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]));
+  }
+  return answer;
+}
+
+/** 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 ?? ''];
+  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")
+  const raw = rawPath ? new URL(rawPath.replace(/\{([^}]+)\}/g, '%7B$1%7D'), 'http://twin.local') : undefined;
+  const captured = (v: string | null | undefined): boolean => typeof v === 'string' && /^\{[^}]+\}$/.test(v);
+  const lower = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+  const out: string[] = [];
+  // each path segment the step fills from a capture stands for one label the example names literally, never more: a
+  // label that is not on the path is excused only while such segments remain (a wrong Bucket beside a captured Key fails)
+  let capturedSegments = raw ? raw.pathname.split('/').map((x) => decodeURIComponent(x)).filter(captured).length : 0;
+  for (const [name, m] of Object.entries((shape?.members ?? {}) as Record<string, Json>)) {
+    const v = input[name];
+    if (v === undefined || (typeof v === 'string' && placeholder.test(v))) continue;
+    const t = m.traits ?? {};
+    const want = String(v);
+    // a label is a whole path segment, or (a greedy one, S3's Key) the path's whole tail; an empty one names nothing
+    if (t['smithy.api#httpLabel'] !== undefined) {
+      const segments = url.pathname.split('/').map((x) => decodeURIComponent(x));
+      const tail = (i: number): string => segments.slice(i).join('/');
+      const onPath = segments.some((seg, i) => seg === want || (i > 0 && tail(i) === want));
+      if (want === '' || (!onPath && !(capturedSegments-- > 0))) out.push(`${name} (${JSON.stringify(want)}) is not a segment of the path`);
+    }
+    else if (t['smithy.api#httpQuery'] !== undefined) { if (url.searchParams.get(String(t['smithy.api#httpQuery'])) !== want && !captured(raw?.searchParams.get(String(t['smithy.api#httpQuery'])))) out.push(`${name} is not the query's ${t['smithy.api#httpQuery']}=${want}`); }
+    else if (t['smithy.api#httpHeader'] !== undefined) { if (lower[String(t['smithy.api#httpHeader']).toLowerCase()] !== want) out.push(`${name} is not the header ${t['smithy.api#httpHeader']}: ${want}`); }
+  }
+  return out;
+}
+
+/** A page's JSON as typed: its elision lines (`...`) dropped, its bare keys quoted, its trailing commas removed. */
+function lenientJson(text: string): string {
+  return text.replace(/^\s*\.{3,},?\s*$/gm, '').replace(/([{,]\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:/g, '$1"$2":').replace(/,(\s*[}\]])/g, '$1');
+}
+
+/** Every example the vendor's spec publishes, by `<operation>#<title>`: Smithy's `smithy.api#examples`, an OpenAPI 3
+ *  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[] {
+  // 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) })))];
+}
+
+/** 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?}]`:
+ *  `source` is the page's URL, `input` and `output` its example as written, `means` its own words for what the example
+ *  does, which the example step's `expect` asserts. A rule the page states ("must have 0 in the minutes field") is one
+ *  too: `means` quotes the sentence, `input` is the case it forbids, and `status` the refusal the vendor answers. Each is
+ *  `<operation>#doc <title>`. A page that renders its example from the operation's schema (`rendered`: Vercel's
+ *  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[] {
+  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> } }>;
+  const authorizationAbsent = new Set<(typeof docs)[number]>();
+  const records: Record<string, SourceRecord> = existsSync(join(pkg, 'spec', 'sources.json')) ? parseExactJson(readFileSync(join(pkg, 'spec', 'sources.json'), 'utf8')) : {};
+  for (const d of docs) {
+    if (d.wire === 'client' && d.request) throw new Error(`${file}: client computation \"${d.title}\" has an HTTP request`);
+    const implementation = /\/(?:src|lib|worker|rust|posthog|ee)\//.test(d.source) || /\.(?:c|h|cc|cpp|hpp|rs|py|go|java|kt|swift|[cm]?js|tsx?)(?:[?#]|$)/i.test(d.source);
+    if (/raw\.githubusercontent\.com\//.test(d.source) && implementation && !/\/(?:tests?|docs|develop-docs|pages|examples)\//.test(d.source)) throw new Error(`${file}: implementation evidence belongs in decisions.json; published examples require a vendor page or quoted vendor test`);
+    if (/raw\.githubusercontent\.com\/.*\/tests?\//.test(d.source ?? '') && (!d.quote || !Object.hasOwn(d, 'output') || records[d.source]?.quotes?.[d.quote] !== true || !sourceHeld(d.source, records[d.source]))) throw new Error(`${file}: vendor tests require their checked literal assertion and expected output`);
+    const archive = archiveSource(d.source ?? '');
+    if (archive) {
+      if (!d.means || !d.quote?.trim() || !sourceHeld(d.source, records[d.source]) || records[d.source]?.quotes?.[d.quote] !== true) throw new Error(`${file}: \"${d.title}\" needs a checked quote from its pinned archive member (check-sources)`);
+      continue;
+    }
+    const recording = /^recording:([\w.-]+\.json(?:\.gz)?)$/.exec(d.source ?? '');
+    if ((!/^https:\/\//.test(d.source ?? '') && !recording) || !d.means) throw new Error(`${file}: "${d.title}" needs its page's URL or recording basename (source) and its meaning (means)`);
+    if (!recording) continue;
+    const path = join(pkg, 'spec', 'recordings', recording[1]!);
+    if (!existsSync(path)) throw new Error(`${file}: "${d.title}" names no retained recording`);
+    const bytes = readFileSync(path);
+    const held = parseExactJson((path.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString()) as { request?: { method?: string; url?: string; authorization?: string }; status?: number; body?: unknown };
+    if (!held.request?.method || !held.request.url || !Number.isInteger(held.status) || !Object.hasOwn(held, 'body')) throw new Error(`${file}: "${d.title}" needs a recording with its exact method, URL, status and body`);
+    if (!d.request || d.request.method !== held.request.method || d.request.url !== held.request.url || d.status !== held.status || canonical(d.output) !== canonical(held.body)) throw new Error(`${file}: "${d.title}" differs from its retained recording's request or answer`);
+    if (held.request.authorization === 'absent') authorizationAbsent.add(d);
+  }
+  // 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 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
+    const example = fromPage(d, typed(d.output, schema), d.input === undefined ? undefined : typed(d.input, schemas.request));
+    // (PlanetScale's renderer writes it `<string>`)
+    return { ...example, sample: true, schema };
+  });
+  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 } : {}) };
+  }
+}
+
+/** A rendered object the page does not fill: any object stands where it is. */
+const ANY_OBJECT = Symbol('rendered unfilled object');
+const ANY_STRING = Symbol('rendered unfilled string');
+const anyObject = (v: unknown): boolean => v === ANY_OBJECT;
+const anyString = (v: unknown): boolean => v === ANY_STRING;
+const renderedMarker = (v: unknown): boolean => anyObject(v) || anyString(v) || isRenderedScalar(v);
+const isObject = (v: unknown): boolean => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function hasEnum(schema: SpecSchema, depth = 0): boolean {
+  if (Array.isArray(schema.enum)) return true;
+  if (depth > 8) return false;
+  return [...(schema.allOf ?? []), ...(schema.anyOf ?? []), ...(schema.oneOf ?? [])].some(part => { const s = resolveSchema(part as SpecSchema).schema; return s ? hasEnum(s, depth + 1) : false; });
+}
+
+/** A rendered example's value with each string the schema types as a number, integer or boolean read as that type
+ *  (exactly: "123" is 123, "true" is true), and "null" as null where the schema admits null; any other string stays,
+ *  and the answer check names it. */
+function typed(value: unknown, schema: SpecSchema | undefined): unknown {
+  const { schema: s, nullable } = renderedSchema(schema);
+  if (!s) return value;
+  // the renderer writes null as "null" (gitBranch `example: null, nullable: true`; framework's enum begins with null)
+  if (value === 'null' && schema && (nullable || (Array.isArray(s.enum) && s.enum.includes(null)))) return null;
+  // the renderer writes an object it cannot fill as a word (`"value"`, `"string"`: a map keyed by ids, a free-form
+  // object): it stands for any object
+  if (typeof value === 'string' && (s.type === 'object' || s.properties || s.additionalProperties) && !s.enum) return ANY_OBJECT;
+  if (typeof value === 'string') {
+    // a union of scalars (`oneOf: [{type: boolean}]`) reads the string as the first alternative it parses as
+    const kinds = [s, ...((s.oneOf ?? s.anyOf ?? []) as SpecSchema[]).map((a) => resolveSchema(a).schema ?? {})].map((a) => a.type);
+    // (where a string is one of the alternatives, the string may be meant as written)
+    const marker = renderedScalar(value, kinds, hasEnum(s));
+    if (marker) return marker;
+    if (kinds.includes('string')) return !s.enum && (value === 'string' || value === '<string>') ? ANY_STRING : value;
+    if (kinds.some((t) => t === 'number' || t === 'integer') && /^-?\d+(\.\d+)?$/.test(value)) return /^-?\d+$/.test(value) ? exactInteger(value) : Number(value);
+    if (kinds.includes('boolean') && (value === 'true' || value === 'false')) return value === 'true';
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((v) => typed(v, s.items));
+  // a map with no declared keys (`additionalProperties`) is rendered with made-up keys (`property1`, `property2`): it
+  // stands for any object, which the map may hold none of
+  if (value && typeof value === 'object' && !s.properties && s.additionalProperties && Object.keys(value).every((k) => /^property\d+$/.test(k))) return ANY_OBJECT;
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, typed(v, s.properties?.[k])]));
+  return value;
+}
+
+/** A published id the World cannot mint as written: one starting with an id prefix the pack declares (`vs_`, `file-`,
+ *  `asst_`), a UUID where the pack's ids are UUIDs (`ids.template: '{uuid}'`), or the vendor's placeholder idioms
+ *  (`abc123`, `def456`, `call_001`, a rendered page's `example_id`). The step sends its own World's id there, in a spec's example or a page's. */
+let placeholderIds = /abc\d*|def\d+|ghi\d+|xyz\d*|_\d{3,}$|^example_id$/;
+/** A snowflake where the pack's ids are snowflakes (`ids.template: '{snowflake:E}'`): 17 to 20 digits, an id only under
+ *  an id-named key (`id`, `*_id`, `*Id`, or their plurals' elements), never another field's digits (Discord's
+ *  permission bitfields are strings of digits too), and never `custom_id`, a value the caller chooses. */
+let snowflakeIds: RegExp | undefined;
+const ID_KEY = /^(?!custom_ids?$)(?:ids?|.+_ids?|.+[a-z]Ids?)$/;
+/** Whether a published string stands for an id the World mints: by its form, or (a snowflake) by its form and its key. */
+const isPlaceholder = (placeholder: RegExp, value: string, key?: string): boolean =>
+  placeholder.test(value) || (snowflakeIds !== undefined && key !== undefined && ID_KEY.test(key) && snowflakeIds.test(value));
+async function loadPlaceholders(pkg: string): Promise<void> {
+  const manifestPath = join(pkg, 'src', 'manifest.ts');
+  if (!existsSync(manifestPath)) return;
+  const { manifest } = (await import(manifestPath)) as { manifest?: { resources?: Record<string, { idPrefix?: string }>; ids?: { template?: string } } };
+  const prefixes = [...new Set(Object.values(manifest?.resources ?? {}).map((r) => r.idPrefix?.replace(/[_:-]$/, '')).filter((p): p is string => !!p && /^[a-z]+$/.test(p)))];
+  if (prefixes.length) placeholderIds = new RegExp(`^(?:${prefixes.join('|')})[_-]|${placeholderIds.source}`);
+  snowflakeIds = manifest?.ids?.template?.startsWith('{snowflake:') ? /^\d{17,20}$/ : undefined;
+  if (manifest?.ids?.template === '{uuid}') placeholderIds = new RegExp(`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|${placeholderIds.source}`, 'i');
+}
+
+function decodedExample(media: string, value: unknown): unknown {
+  if (typeof value !== 'string' || !/^application\/(?:[a-z0-9.-]+\+)?json(?:;|$)/i.test(media)) return value;
+  try { return parseExactJson(value); } catch { return value; }
+}
+
+function fromSpec(pkg: string): 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));
+  // 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
+  if (!spec && existsSync(join(pkg, 'spec', 'commands'))) return [];
+  // a vendor's own client (client-ops.json) publishes no examples: its examples are its reference pages'
+  if (!spec && existsSync(join(pkg, 'spec', 'client-ops.json'))) return [];
+  // one API's several documents (spec/openapi/): each document's examples, judged against their patched union
+  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,
+  // 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[];
+  const servedDoc = (documents ? mergeDocuments(served(pkg, documents)).doc : discovery ? discoveryToOpenAPI(served(pkg, parseExactJson(text))) : served(pkg, docs[0]!)) as Doc;
+  // a Swagger 2 spec (PlanetScale's) keeps its schemas in `definitions`, referred to as `#/definitions/<name>`
+  specSchemas = servedDoc.components?.schemas ?? servedDoc.definitions ?? {};
+  // each operation's request and answer schemas as served (a patch that corrects an answer, Vercel's getEdgeConfigs
+  // a list, is what a sample is judged against)
+  const json = (content: unknown): SpecSchema | undefined => (content as Record<string, { schema?: SpecSchema }> | undefined)?.['application/json']?.schema;
+  // an operation the spec names no id for is the IR's `method_path` slug
+  const idOf = (op: Op, method: string, path: string): string => op.operationId || slug(method, path);
+  for (const [path, item] of Object.entries(servedDoc.paths ?? {})) {
+    for (const [method, op] of Object.entries(item)) {
+      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)] = {
+        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]] : []; })),
+      };
+    }
+  }
+  const refIn = (doc: Doc, v: unknown): unknown => {
+    const r = (v as { $ref?: string })?.$ref;
+    return r ? doc.components?.examples?.[r.split('/').pop()!]?.value : (v as { value?: unknown })?.value;
+  };
+  type Schema = { $ref?: string; properties?: { data?: { items?: { $ref?: string } } } };
+  const fixturesPath = join(pkg, 'spec', 'fixtures3.json.gz');
+  const fixtures = existsSync(fixturesPath) ? (parseExactJson(gunzipSync(readFileSync(fixturesPath)).toString('utf8')) as { resources: Record<string, unknown> }).resources : undefined;
+  // A removed route still published its examples: retain and count them without requiring replay.
+  // Trailing-slash aliases can publish the same id and content; keep one without changing the served spec.
+  const routeExamples = new Map<string, { path: string; method: string; example: Example }>();
+  const pointer = (part: string): string => part.replace(/~/g, '~0').replace(/\//g, '~1');
+  const patchPath = join(pkg, 'spec', 'patches.json');
+  const removed = new Set(existsSync(patchPath) ? (parseExactJson(readFileSync(patchPath, 'utf8')) as { patches: SpecPatch[] }).patches.filter((x) => x.op === 'remove').map((x) => x.path) : []);
+  for (const doc of docs) for (const [path, item] of Object.entries(doc.paths)) {
+    const ref = (v: unknown): unknown => refIn(doc, v);
+    for (const [method, op] of Object.entries(item)) {
+      if (!op || typeof op !== 'object' || !('responses' in op)) continue;
+      const patchRemoved = removed.has(`/paths/${pointer(path)}`) || removed.has(`/paths/${pointer(path)}/${method}`);
+      const firstExample = out.length;
+      const operation = idOf(op, method, path);
+      for (const [code, response] of Object.entries(op.responses ?? {})) {
+        const status = Number(code) || undefined;
+        // Swagger 2: examples by media type on the response itself
+        for (const [media, value] of Object.entries((response.examples ?? {}) as Record<string, unknown>)) out.push({ id: `${operation}#${code} ${media}`, operation, status, output: decodedExample(media, value) });
+        for (const [media, content] of Object.entries((response.content ?? {}) as Record<string, { example?: unknown; examples?: Record<string, unknown> }>)) {
+          if (content.example !== undefined) out.push({ id: `${operation}#${code} ${media}`, operation, status, output: decodedExample(media, content.example) });
+          // one example name may be published under several media types (a diff and a patch beside the JSON)
+          for (const [name, e] of Object.entries(content.examples ?? {})) out.push({ id: `${operation}#${code} ${name}${media === 'application/json' ? '' : ` (${media})`}`, operation, status, output: decodedExample(media, ref(e)) });
+        }
+      }
+      // Stripe publishes one sample object per resource beside its spec (fixtures3.json): an operation's example is the
+      // sample of what it answers, alone or as a list's page
+      if (fixtures) {
+        const schema = ((op.responses?.['200']?.content as Record<string, { schema?: Schema }> | undefined)?.['application/json']?.schema ?? {}) as Schema;
+        const one = schema.$ref?.split('/').pop();
+        const listed = schema.properties?.data?.items?.$ref?.split('/').pop();
+        if (one && fixtures[one]) out.push({ id: `${operation}#fixture ${one}`, operation, status: 200, output: fixtures[one], sample: true, schema: { $ref: `#/components/schemas/${one}` } });
+        else if (listed && fixtures[listed]) out.push({ id: `${operation}#fixture list of ${listed}`, operation, status: 200, output: { object: 'list', data: [fixtures[listed]], has_more: false }, sample: true, schema: { properties: { data: { items: { $ref: `#/components/schemas/${listed}` } } } } });
+      }
+      const meta = op['x-oaiMeta']?.examples;
+      for (const [i, e] of (Array.isArray(meta) ? meta : meta ? [meta] : []).entries() as Iterable<[number, { title?: string; response?: unknown; request?: { curl?: string } }]>) {
+        let output: unknown = e.response;
+        // JSON text, or JSON the page's typing broke: a trailing comma before a closing bracket (OpenAI's list of files,
+        // `"purpose": "assistants",}`), keys left unquoted (`id: "vs_abc123"`), a line of `...` eliding a list's middle
+        // items; else the published literal text, SSE included
+        if (typeof output === 'string') { const text = output; try { output = parseExactJson(text); } catch { try { output = parseExactJson(lenientJson(text)); } catch { /* retain the published literal text, including SSE */ } } }
+        // the request is published as a curl command: its `-d` JSON is the body (a form upload, `-F`, is not checked)
+        const data = /\s-d\s+'([\s\S]*?)'/m.exec(e.request?.curl ?? '')?.[1];
+        let input: unknown;
+        if (data) { try { input = parseExactJson(data); } catch { /* not JSON: not checked */ } }
+        out.push({ id: `${operation}#${e.title ?? (i ? String(i + 1) : 'default')}`, operation, output, ...(input !== undefined ? { input, placeholder: placeholderIds } : {}) });
+      }
+      const added = out.splice(firstExample);
+      for (const example of added) {
+        if (patchRemoved) example.patchRemoved = true;
+        const previous = routeExamples.get(example.id);
+        const normalized = (route: string): string => route.replace(/\/+$/, '') || '/';
+        if (previous && previous.method === method && previous.path !== path && normalized(previous.path) === normalized(path)
+          && canonical(previous.example) === canonical(example)) continue;
+        routeExamples.set(example.id, { path, method, example });
+        out.push(example);
+      }
+    }
+  }
+  // an operation two documents both publish (the same, or the union would not read) gives its examples once
+  return documents ? [...new Map(out.map((e) => [e.id, e])).values()] : out;
+}
+
+/** A line protocol's RFC publishes its examples as scenarios (RFC 5321, Appendix D): `S:` and `C:` lines under a
+ *  numbered heading. Each client turn (the lines sent before the server replies: a message's text is one turn) is an
+ *  example, `<scenario>#<n> <its first line>`, whose status is the code of the reply it draws; the greeting is turn 0. */
+function scenarios(text: string): Example[] {
+  const out: Example[] = [];
+  const appendix = text.slice(text.search(/^Appendix D\./m));
+  let scenario = '';
+  let turn = 0;
+  let sent: string[] | undefined;
+  let closed = false;
+  for (const line of appendix.split('\n')) {
+    const heading = /^(D\.\d+)\.\s+(.*)$/.exec(line);
+    if (heading) { scenario = `${heading[1]} ${heading[2].trim()}`; turn = 0; sent = undefined; closed = false; continue; }
+    const m = /^\s+([SC]):\s?(.*)$/.exec(line);
+    if (!m || !scenario) continue;
+    if (m[1] === 'C') { (sent ??= []).push(m[2]); continue; }
+    // the first line of a reply answers the turn before it; continuation lines (`250-…`) belong to that reply, and a
+    // reply after the channel closed (221) greets a new connection (a relay's next hop)
+    if (sent === undefined && turn > 0 && !closed) continue;
+    closed = m[2].startsWith('221');
+    const verb = sent ? sent[0].split(/[\s:]/)[0].toUpperCase() : 'CONNECT';
+    out.push({ id: `${scenario}#${turn} ${sent ? sent[0] : '(connect)'}`, operation: verb, status: Number(m[2].slice(0, 3)), output: undefined, lines: sent ?? [] });
+    turn++;
+    sent = undefined;
+  }
+  return out;
+}
+
+/** JSON with every object's keys sorted: two bodies that differ only in key order are the same body. */
+const canonical = (v: unknown): string => JSON.stringify(v, (_k, x) => (x && typeof x === 'object' && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => a.localeCompare(b))) : x));
+
+/** The published body selects JSON comparison; a malformed answer never falls back to text. */
+const jsonTexts = (sent: unknown, published: string): { valid: boolean; sent?: unknown; published: unknown } | undefined => {
+  let parsed: unknown;
+  try { parsed = parseExactJson(published); } catch { return undefined; }
+  if (typeof sent !== 'string') return { valid: false, published: parsed };
+  try { return { valid: true, sent: parseExactJson(sent), published: parsed }; }
+  catch { return { valid: false, published: parsed }; }
+};
+
+/** JSON bodies and framed text retain their structure before any placeholder inference. */
+function comparedText(sent: unknown, published: string, placeholder: RegExp, key?: string, names?: string[], contentType?: string, boundaries: string[] = [], outputJson?: (expected: unknown, actual: unknown) => boolean): { matches: boolean; problem?: string } | undefined {
+  let problem: string | undefined;
+  const record = (actual: string, expected: string, type?: string, enclosing = boundaries, framedJson = false): boolean => {
+    if (framedJson && outputJson) {
+      const json = jsonTexts(actual, expected);
+      if (json) {
+        if (!json.valid) problem ??= 'answer is not JSON';
+        return json.valid && outputJson(json.published, json.sent);
+      }
+    }
+    const comparison = comparedText(actual, expected, placeholder, key, names, type, enclosing, outputJson);
+    problem ??= comparison?.problem;
+    return comparison ? comparison.matches : same(actual, expected, placeholder, key, names, false, undefined, enclosing);
+  };
+  const lines = (text: string): string[] => text.split(/(\r\n|\n|\r)/);
+  // Recognize outer MIME framing before interpreting a part's JSON, SSE, or other payload.
+  const encode = (text: string): Uint8Array => new TextEncoder().encode(text);
+  const decode = (bytes: Uint8Array): string => new TextDecoder().decode(bytes);
+  const boundary = contentType && /^multipart\//i.test(contentType)
+    ? multipartBoundary(contentType) : inferMultipartBoundary(encode(published));
+  if (boundary || contentType && /^multipart\//i.test(contentType)) {
+    if (!boundary || typeof sent !== 'string') return { matches: false, problem: 'invalid multipart framing' };
+    const expected = multipartEnvelope(encode(published), boundary);
+    const actual = multipartEnvelope(encode(sent), boundary);
+    if (!expected.complete || !actual.complete) return { matches: false, problem: 'invalid multipart framing' };
+    const literal = (a: Uint8Array, b: Uint8Array): boolean => a.length === b.length && a.every((byte, i) => byte === b[i]);
+    const matches = literal(actual.preamble, expected.preamble) && literal(actual.epilogue, expected.epilogue)
+      && actual.delimiters.length === expected.delimiters.length
+      && expected.delimiters.every((line, i) => literal(actual.delimiters[i]!, line))
+      && actual.parts.length === expected.parts.length && expected.parts.every((e, i) => {
+        const a = actual.parts[i]!;
+        if (!literal(a.leading, e.leading) || !literal(a.separator, e.separator) || !literal(a.trailing, e.trailing)) return false;
+        const headers = lines(decode(e.headers));
+        const actualHeaders = lines(decode(a.headers));
+        const enclosing = [...boundaries, boundary];
+        return headers.length === actualHeaders.length
+          && headers.every((header, j) => j % 2 ? header === actualHeaders[j] : record(actualHeaders[j]!, header, undefined, enclosing))
+          && record(decode(a.body), decode(e.body), e.type ?? undefined, enclosing);
+      });
+    return { matches, ...(problem ? { problem } : {}) };
+  }
+  const json = jsonTexts(sent, published);
+  if (json) return json.valid ? { matches: same(json.sent, json.published, placeholder, key, names, true) }
+    : { matches: false, problem: 'answer is not JSON' };
+  // Preserve line separators and blank records, as well as each SSE field's literal prefix.
+  const expectedLines = lines(published);
+  const content = expectedLines.filter((_line, i) => i % 2 === 0).filter((line) => line.length);
+  const sse = content.some((line) => /^data:/.test(line));
+  const jsonLines = content.length > 1 && (/^\s*[\[{]/.test(content[0]!)
+    || content.every((line) => jsonTexts(undefined, line) !== undefined));
+  if (sse || jsonLines) {
+    if (typeof sent !== 'string') return { matches: false };
+    const actualLines = lines(sent);
+    const matches = actualLines.length === expectedLines.length && expectedLines.every((line, i) => {
+      if (i % 2 || !line) return actualLines[i] === line;
+      if (!sse) return record(actualLines[i]!, line, undefined, boundaries, true);
+      const field = /^(data|event|id|retry): ?/.exec(line)?.[0];
+      if (field === undefined) return record(actualLines[i]!, line);
+      return actualLines[i]!.startsWith(field) && record(actualLines[i]!.slice(field.length), line.slice(field.length), undefined, boundaries, field.startsWith('data:'));
+    });
+    return { matches, ...(problem ? { problem } : {}) };
+  }
+  return undefined;
+}
+
+/** Whether `sent` is the published input, preserving JSON keys, types and array lengths. */
+const same = (sent: unknown, published: unknown, placeholder: RegExp, key?: string, names?: string[], stringLeaf = false, contentType?: string, boundaries: string[] = [], outputJson?: (expected: unknown, actual: unknown) => boolean): boolean => {
+  if (!stringLeaf && typeof published === 'string') {
+    const text = comparedText(sent, published, placeholder, key, names, contentType, boundaries, outputJson);
+    if (text) return text.matches;
+  }
+  return anyObject(published) ? isObject(sent)
+    : anyString(published) ? typeof sent === 'string'
+    : isRenderedScalar(published) ? matchesRenderedScalar(published, sent)
+    : typeof published === 'string' && typeof sent === 'string' && textPattern(published, names, sent, stringLeaf, boundaries) ? textPattern(published, names, sent, stringLeaf, boundaries)!.test(filled(sent, requestCaptures))
+    : typeof published === 'string' && isPlaceholder(placeholder, published, key) ? typeof sent === 'string'
+    : Array.isArray(published) ? Array.isArray(sent) && sent.length === published.length && published.every((p, i) => same(sent[i], p, placeholder, key, names, true))
+    : published !== null && typeof published === 'object' ? sent !== null && typeof sent === 'object' && !Array.isArray(sent) && canonical(Object.keys(sent).sort()) === canonical(Object.keys(published).sort()) && Object.entries(published).every(([k, p]) => same((sent as Record<string, unknown>)[k], p, placeholder, k, names, true))
+    : sent === published;
+};
+
+/** A value with each dot path removed (`a.b`; `a[].b` in every element of the array `a`). */
+function withoutPaths(v: unknown, paths: string[]): unknown {
+  // Symbols cannot be forged by JSON or structured-cloned; preserve only the renderer's marker.
+  const clone = (value: unknown): unknown => renderedMarker(value) ? value : Array.isArray(value) ? value.map(clone)
+    : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([k, x]) => [k, clone(x)])) : value;
+  const out = clone(v);
+  const drop = (node: unknown, keys: string[]): void => {
+    if (!node || typeof node !== 'object' || !keys.length) return;
+    const [head, ...rest] = keys;
+    const every = head!.endsWith('[]');
+    const key = every ? head!.slice(0, -2) : head!;
+    const obj = node as Record<string, unknown>;
+    if (!rest.length && !every) { delete obj[key]; return; }
+    if (every) { for (const el of (Array.isArray(obj[key]) ? obj[key] : []) as unknown[]) drop(el, rest); return; }
+    drop(obj[key], rest);
+  };
+  for (const p of paths) drop(out, p.split('.'));
+  return out;
+}
+
+/** Whether a request schema requires the field at a dot path (`a[].b`: `b` of each item of `a`). */
+function requiredAt(schema: SpecSchema | undefined, path: string): boolean {
+  let at = resolveSchema(schema).schema;
+  const keys = path.split('.');
+  for (const [i, raw] of keys.entries()) {
+    const key = raw.replace(/\[\]$/, '');
+    if (!at) return false;
+    if (i === keys.length - 1) return Array.isArray(at.required) && (at.required as string[]).includes(key);
+    let next = resolveSchema(at.properties?.[key]).schema;
+    if (raw.endsWith('[]')) next = resolveSchema(next?.items).schema;
+    at = next;
+  }
+  return false;
+}
+
+/** Callers compare JSON text bodies by keys, types and array lengths, confining this pattern to corresponding string
+ *  leaves. In other text an unbound span excludes its following literal's first character, unescaped double quotes
+ *  inside a quoted value, record delimiter lines, and line breaks unless that published quoted value contains them. Adjacent unbound spans
+ *  coalesce; a final span reaches the end of its value. Known bindings constrain splitting first and compare literally;
+ *  surrounding literals and each whole string match exactly. */
+const textPattern = (text: string, names: string[] = [], sent?: string, stringLeaf = false, boundaries: string[] = []): RegExp | undefined => {
+  const escape = (s: string) => s.replace(/[.*+?^$(){}|[\]\\]/g, '\\$&');
+  const marker = new RegExp('<[A-Za-z_][\\w-]*>' + (names.length ? '|' + [...names].sort((a, b) => b.length - a.length).map(escape).join('|') : ''), 'g');
+  const hits = [...text.matchAll(marker)];
+  if (!hits.length) return undefined;
+  const valueContext = (index: number): { quoted: boolean; multiline: boolean } => {
+    let opening = -1;
+    let escaped = false;
+    for (let i = 0; i < index; i++) {
+      if (escaped) { escaped = false; continue; }
+      if (text[i] === '\\') { escaped = true; continue; }
+      if (text[i] === '"') opening = opening < 0 ? i : -1;
+    }
+    if (opening < 0) return { quoted: false, multiline: false };
+    let end = text.length;
+    escaped = false;
+    for (let i = index; i < text.length; i++) {
+      if (escaped) { escaped = false; continue; }
+      if (text[i] === '\\') { escaped = true; continue; }
+      if (text[i] === '"') { end = i; break; }
+    }
+    return { quoted: true, multiline: /[\r\n]/.test(text.slice(opening + 1, end)) };
+  };
+  const spans: Array<{ literal: string; value?: string; quoted: boolean; multiline: boolean }> = [];
+  for (const [i, hit] of hits.entries()) {
+    const literal = text.slice(i ? hits[i - 1]!.index! + hits[i - 1]![0].length : 0, hit.index);
+    const value = requestCaptures[hit[0].replace(/^<|>$/g, '')];
+    if (spans.length && !literal && value === undefined && spans.at(-1)!.value === undefined) continue;
+    spans.push({ literal, value, ...valueContext(hit.index!) });
+  }
+  const tail = text.slice(hits.at(-1)!.index! + hits.at(-1)![0].length);
+  // Unchanged published text needs no inferred replacements (angle-bracket markup can itself be literal text).
+  // Known bindings still take precedence: copying a bound placeholder's spelling is not sending its value.
+  if (sent === text && spans.every((span) => span.value === undefined)) return new RegExp('^' + escape(text) + '(?![\\s\\S])');
+  const character = (s: string) => s.replace(/[\\\]\-^]/g, '\\$&');
+  const excluding = (chars: string): string => chars ? '[^' + character(chars) + ']' : '[\\s\\S]';
+  // Guard every consumed character, including escaped characters: framing found anywhere in the published
+  // text cannot be swallowed by a multiline value even when the body is too incomplete for a framed reader.
+  const delimiterLines = text.split(/\r\n|\n|\r/).filter((line) => line.startsWith('--'));
+  const stops = delimiterLines.map((line) => multipartDelimiterPattern(line.slice(2).replace(/[ \t]+$/, '')));
+  stops.push(...boundaries.map(multipartDelimiterPattern));
+  if (/(?:^|[\r\n])data:/.test(text)) stops.push('(?:^|(?<=[\\r\\n]))data:');
+  if (/\r\n\r\n|\n\n|\r\r/.test(text)) stops.push('\\r\\n\\r\\n|\\n\\n|\\r\\r');
+  const guard = !stringLeaf && stops.length ? '(?!(?:' + stops.join('|') + '))' : '';
+  const guarded = (character: string): string => guard + character;
+  const unbound = spans.map((span, i) => {
+    const following = spans.slice(i + 1).find((next) => next.literal)?.literal ?? tail;
+    const delimiter = following[0] ?? '';
+    const breaks = !stringLeaf && !span.multiline ? '\r\n' : '';
+    if (stringLeaf || !span.quoted) return '(?:' + guarded(excluding(delimiter + breaks)) + ')*?';
+    // A backslash escape stays within this quoted value; an unescaped quote ends it.
+    const escaped = guarded('\\\\') + guarded(excluding((delimiter === '"' || delimiter === '\\' ? '' : delimiter) + breaks));
+    return '(?:' + escaped + '|' + guarded(excluding(delimiter + breaks + '"\\')) + ')*?';
+  });
+  // Resolve templates against values held before this request, not captures overwritten by its answer.
+  const end = escape(tail) + '(?![\\s\\S])';
+  const extraction = spans.map((span, i) => escape(span.literal) + '(' + (span.value === undefined ? unbound[i] : escape(span.value)) + ')').join('');
+  const inferred = sent === undefined ? undefined : new RegExp('^' + extraction + end).exec(filled(sent, requestCaptures));
+  const pattern = spans.map((span, i) => {
+    const value = span.value ?? inferred?.[i + 1];
+    return escape(span.literal) + (value === undefined ? unbound[i] : escape(value));
+  }).join('');
+  return new RegExp('^' + pattern + end);
+};
+/** Whether `whole` holds the published fields. Parseable JSON text bodies require the same complete structure;
+ *  placeholders compare only corresponding string leaves. Structured partial inputs retain their field subset rule. */
+const holds = (whole: unknown, part: unknown, placeholder?: RegExp, key?: string, names?: string[], stringLeaf = false, contentType?: string, boundaries: string[] = []): boolean => {
+  if (!stringLeaf && typeof part === 'string') {
+    const text = comparedText(whole, part, placeholder ?? /(?!)/, key, names, contentType, boundaries);
+    if (text) return text.matches;
+  }
+  return anyObject(part) ? isObject(whole)
+    : anyString(part) ? typeof whole === 'string'
+    : isRenderedScalar(part) ? matchesRenderedScalar(part, whole)
+    : typeof part === 'string' && typeof whole === 'string' && textPattern(part, names, whole, stringLeaf, boundaries) ? textPattern(part, names, whole, stringLeaf, boundaries)!.test(filled(whole, requestCaptures))
+    : typeof part === 'string' && placeholder && isPlaceholder(placeholder, part, key) ? typeof whole === 'string'
+    : Array.isArray(part) ? same(whole, part, placeholder ?? /(?!)/, key, names, true)
+    : part !== null && typeof part === 'object' && !Array.isArray(part)
+    ? whole !== null && typeof whole === 'object' && !Array.isArray(whole) && Object.entries(part).every(([k, v]) => holds((whole as Record<string, unknown>)[k], v, placeholder, k, names, true))
+    : whole === part;
+};
+
+/** Every string and number in a value, by its dot path (`a.0.b`), as `expect` paths name them. */
+const leaves = (v: unknown, prefix = ''): Array<[string, string | number]> =>
+  typeof v === 'string' || typeof v === 'number' ? [[prefix, v]]
+    : v && typeof v === 'object' ? Object.entries(v).flatMap(([k, x]) => leaves(x, prefix ? `${prefix}.${k}` : k)) : [];
+
+const kind = (v: unknown): string => (v === null ? 'null' : Array.isArray(v) ? 'array' : isExactIntegerValue(v) ? 'number' : typeof v);
+
+/** A schema with its reference followed; a union's object alternative stands for it (an expandable field is `anyOf:
+ *  [string, the object]`), and `nullable` says whether the schema or any alternative admits null. */
+function resolveSchema(schema: SpecSchema | undefined, depth = 0): { schema?: SpecSchema; nullable: boolean } {
+  if (!schema || depth > 8) return { nullable: true };
+  if (schema.$ref) return resolveSchema(specSchemas[schema.$ref.split('/').pop()!], depth + 1);
+  const alts = [...(schema.anyOf ?? []), ...(schema.oneOf ?? [])].map((a) => resolveSchema(a, depth + 1));
+  // (Swagger 2 says it with the `x-nullable` extension, OpenAPI 3.1 with `null` among its types)
+  const types = (schema as { type?: unknown }).type;
+  const nullable = schema.nullable === true || schema['x-nullable'] === true || types === 'null' || (Array.isArray(types) && types.includes('null')) || alts.some((a) => a.nullable);
+  const object = alts.find((a) => a.schema?.properties || a.schema?.items);
+  return { schema: alts.length ? (object?.schema ?? schema) : schema, nullable };
+}
+
+/** A rendered object may declare its fields through allOf references. Retain every required key. */
+function renderedSchema(schema: SpecSchema | undefined, depth = 0): { schema?: SpecSchema; nullable: boolean } {
+  const held = resolveSchema(schema);
+  if (!held.schema?.allOf || depth > 8) return held;
+  const parts = (held.schema.allOf as SpecSchema[]).map(part => renderedSchema(part, depth + 1).schema).filter((part): part is SpecSchema => Boolean(part));
+  return { ...held, schema: { ...held.schema,
+    properties: Object.fromEntries([...new Set([...parts.flatMap(part => Object.keys(part.properties ?? {})), ...Object.keys(held.schema.properties ?? {})])].map(key => {
+      const fields = [...parts.map(part => part.properties?.[key]), held.schema?.properties?.[key]].filter((field): field is SpecSchema => Boolean(field));
+      return [key, fields.length === 1 ? fields[0] : { allOf: fields }];
+    })),
+    required: [...new Set([...parts.flatMap(part => Array.isArray(part.required) ? part.required : []), ...(Array.isArray(held.schema.required) ? held.schema.required : [])])],
+  } };
+}
+
+/** Only output null/type and collection-length decisions use these schema readers. The legacy
+ * sample/placeholder readers above, request comparison and literal/framing checks stay unchanged. */
+function outputSchema(schema: SpecSchema | undefined, depth = 0): SpecSchema | undefined {
+  if (!schema || depth > 16) return undefined;
+  return schema.$ref ? outputSchema(specSchemas[schema.$ref.split('/').pop()!], depth + 1) : schema;
+}
+
+function outputChildSchema(schema: SpecSchema | undefined, key: string | undefined, depth = 0): SpecSchema | undefined {
+  const s = outputSchema(schema);
+  if (!s || depth > 16) return undefined;
+  const direct = key === undefined ? s.items : s.properties?.[key];
+  if (direct) return direct;
+  for (const union of ['allOf', 'anyOf', 'oneOf'] as const) {
+    const children = ((s[union] ?? []) as SpecSchema[]).map((part) => outputChildSchema(part, key, depth + 1)).filter((part): part is SpecSchema => part !== undefined);
+    if (children.length) return children.length === 1 ? children[0] : { [union]: children };
+  }
+  return key !== undefined && s.additionalProperties && typeof s.additionalProperties === 'object' ? s.additionalProperties as SpecSchema : undefined;
+}
+
+/** A published null supplies no object shape: require a declared type and any enum, but do
+ * not invent property, item or value constraints from the null illustration. */
+function outputTypeAdmits(schema: SpecSchema | undefined, value: unknown, depth = 0): boolean {
+  const s = outputSchema(schema);
+  if (!s || depth > 16) return false;
+  if (Array.isArray(s.enum) && !s.enum.some((member) => canonical(member) === canonical(value))) return false;
+  const alternatives = [...(s.anyOf ?? []), ...(s.oneOf ?? [])];
+  const types = Array.isArray(s.type) ? s.type : typeof s.type === 'string' ? [s.type] : [];
+  const admits = (type: unknown): boolean => type === 'integer' ? isExactIntegerValue(value) : type === kind(value);
+  if (types.length && !types.some(admits)) return false;
+  if (alternatives.length && !alternatives.some((part) => outputTypeAdmits(part, value, depth + 1))) return false;
+  const parts = (s.allOf ?? []) as SpecSchema[];
+  const declared = types.length > 0 || alternatives.length > 0 || parts.some((part) => outputTypeAdmits(part, value, depth + 1));
+  return declared && parts.every((part) => {
+      const held = outputSchema(part);
+      return held !== undefined && (held.type === undefined && !held.anyOf && !held.oneOf && !held.allOf
+        ? !Array.isArray(held.enum) || held.enum.some((member) => canonical(member) === canonical(value))
+        : outputTypeAdmits(part, value, depth + 1));
+    });
+}
+
+/** Further shape checks for a value admitted against a sample's null. These use the served
+ * schema, including each applicable union branch, rather than manufacturing an example object. */
+function outputSchemaMismatches(schema: SpecSchema | undefined, value: unknown, prefix: string, depth = 0): Array<{ path: string; detail: string }> {
+  const s = outputSchema(schema);
+  if (!s || depth > 16) return [{ path: prefix, detail: 'has no known served schema' }];
+  if (value === null && s.nullable) return [];
+  if ((s.type !== undefined || s.anyOf || s.oneOf) && !outputTypeAdmits(s, value)) return [{ path: prefix, detail: `is ${kind(value)}, not an admitted served schema type or enum value` }];
+  if (Array.isArray(s.enum) && !s.enum.some((member) => canonical(member) === canonical(value))) return [{ path: prefix, detail: 'is not in the served schema enum' }];
+  const out = ((s.allOf ?? []) as SpecSchema[]).flatMap((part) => outputSchemaMismatches(part, value, prefix, depth + 1));
+  for (const alternatives of [s.anyOf, s.oneOf]) {
+    if (!alternatives?.length) continue;
+    const choices = alternatives.map((part) => outputSchemaMismatches(part, value, prefix, depth + 1));
+    if (!choices.some((choice) => choice.length === 0)) out.push(...choices.reduce((best, choice) => choice.length < best.length ? choice : best));
+  }
+  if (isObject(value)) {
+    const object = value as Record<string, unknown>;
+    for (const key of (Array.isArray(s.required) ? s.required : []) as string[]) {
+      if (!Object.hasOwn(object, key)) out.push({ path: `${prefix}.${key}`, detail: 'is absent, and the served schema requires it' });
+    }
+    for (const [key, item] of Object.entries(object)) {
+      const field = s.properties?.[key] ?? (typeof s.additionalProperties === 'object' ? s.additionalProperties as SpecSchema : undefined);
+      if (field) out.push(...outputSchemaMismatches(field, item, `${prefix}.${key}`, depth + 1));
+      else if (s.additionalProperties === false) out.push({ path: `${prefix}.${key}`, detail: 'is not an admitted served schema property' });
+    }
+  } else if (Array.isArray(value) && s.items) {
+    const fixed = fixedOutputLength(s);
+    if (fixed !== undefined && value.length !== fixed) out.push({ path: prefix, detail: `has ${value.length} items, the served spec fixes the length at ${fixed}` });
+    value.forEach((item, i) => out.push(...outputSchemaMismatches(Array.isArray(s.items) ? s.items[i] : s.items, item, `${prefix}.${i}`, depth + 1)));
+  }
+  return out;
+}
+
+/** List fields not exposed as a resource list by the derived surface. Each is a read of
+ * existing state, not a request-minted collection; the pinned operation/field evidence is
+ * 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'] },
+  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: [''] },
+  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'] },
+  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'] },
+};
+let comparisonCollections: string[] = [];
+function storedCollection(prefix: string): boolean {
+  const path = prefix.replace(/^\./, '').split('.');
+  return comparisonCollections.some((pattern) => {
+    const parts = pattern.split('.');
+    return parts.length === path.length && parts.every((part, i) => part === '[]' ? /^\d+$/.test(path[i]!) : part === path[i]);
+  });
+}
+
+function fixedOutputLength(schema: SpecSchema | undefined, depth = 0): number | undefined {
+  const s = outputSchema(schema);
+  if (!s || depth > 16) return undefined;
+  if (typeof s.minItems === 'number' && s.minItems === s.maxItems) return s.minItems;
+  const parts = (s.allOf ?? []) as SpecSchema[];
+  const bounds = parts.map((part) => outputSchema(part)).filter((part): part is SpecSchema => part !== undefined);
+  const min = Math.max(Number(s.minItems ?? 0), ...bounds.map((part) => Number(part.minItems ?? 0)));
+  const max = Math.min(Number(s.maxItems ?? Infinity), ...bounds.map((part) => Number(part.maxItems ?? Infinity)));
+  if (min === max) return min;
+  const fixed = parts.map((part) => fixedOutputLength(part, depth + 1)).find((length) => length !== undefined);
+  if (fixed !== undefined) return fixed;
+  const alternatives = [...(s.anyOf ?? []), ...(s.oneOf ?? [])];
+  const lengths = alternatives.map((part) => fixedOutputLength(part, depth + 1));
+  return lengths.length > 0 && lengths.every((length) => length !== undefined && length === lengths[0]) ? lengths[0] : undefined;
+}
+
+/** Each key path of the example's answer the twin's answer lacks, or holds as another JSON type. A sample's field the
+ *  twin answers null is a mismatch only where the served spec does not let it be null (a payout's `destination`, a
+ *  preview invoice's `id`: each passed as a sample twice before a judge read the spec). */
+let comparisonPlaceholder: RegExp | undefined;
+let comparisonNames: string[] | undefined;
+function mismatches(example: unknown, got: unknown, prefix = '', sample = false, schema?: SpecSchema, literal = prefix === '' && (example === null || typeof example !== 'object'), contentType?: string, valueSchema = schema): Array<{ path: string; detail: string }> {
+  if (example === undefined) return [];
+  if (example === null) {
+    if (got === null) return [];
+    if (sample && outputTypeAdmits(valueSchema, got)) return outputSchemaMismatches(valueSchema, got, prefix || '(the answer)');
+    return [{ path: prefix || '(the answer)', detail: `is ${kind(got)}, the published answer is null` }];
+  }
+  if (sample && got === null) return schema && !resolveSchema(schema).nullable ? [{ path: prefix || '(the answer)', detail: 'is null, and the served spec does not let it be null' }] : [];
+  if (isRenderedScalar(example)) return matchesRenderedScalar(example, got) ? [] : [{ path: prefix || '(the answer)', detail: `is ${kind(got)}, unlike the published schema-rendered scalar` }];
+  if (anyObject(example)) return isObject(got) ? [] : [{ path: prefix || '(the answer)', detail: `is ${kind(got)}, the example's is an object` }];
+  if (anyString(example)) return typeof got === 'string' ? [] : [{ path: prefix || '(the answer)', detail: `is ${kind(got)}, the example's is a string` }];
+  if (kind(example) !== kind(got)) return [{ path: prefix || '(the answer)', detail: `is ${kind(got)}, the example's is ${kind(example)}` }];
+  if (Array.isArray(example)) {
+    const list = got as unknown[];
+    const fixed = fixedOutputLength(valueSchema);
+    const stored = storedCollection(prefix);
+    const collection = example.length > 0 && (stored ? example.every((item) => !Array.isArray(item)) : sample && example.every(isObject));
+    if (fixed !== undefined && list.length !== fixed) return [{ path: prefix, detail: `has ${list.length} items, the served spec fixes the length at ${fixed}` }];
+    // an array of unfilled type words (`["string"]`) is the schema renderer's, not an answer: its length is not data; and a
+    // spec's sample list of scalars (a tier's name) illustrates its items, never their count: each item the answer holds
+    // takes the sample's type, and an empty list is a state the sample does not deny
+    const scalars = sample && !stored && example.every((item) => item === null || typeof item !== 'object');
+    if ((example.length > 0 && example.every(renderedMarker)) || scalars) return list.flatMap((item, i) => mismatches(example[0], item, `${prefix}.${i}`, sample, resolveSchema(schema).schema?.items, literal, contentType, outputChildSchema(valueSchema, undefined)));
+    if (!collection && list.length !== example.length) return [{ path: prefix, detail: `has ${list.length} items, the published answer has ${example.length}` }];
+    if (!example.length) return [];
+    if (!list.length) return [{ path: prefix, detail: 'nothing to compare: the collection is empty' }];
+    const itemSchema = resolveSchema(schema).schema?.items;
+    const itemValueSchema = outputChildSchema(valueSchema, undefined);
+    if (collection && stored) return list.flatMap((item, i) => {
+      const choices = example.map((published) => mismatches(published, item, `${prefix}.${i}`, sample, itemSchema, literal, contentType, itemValueSchema));
+      return choices.some((choice) => choice.length === 0) ? [] : choices.reduce((best, choice) => choice.length < best.length ? choice : best);
+    });
+    return list.flatMap((item, i) => {
+      if (i < example.length) return mismatches(example[i], item, `${prefix}.${i}`, sample, itemSchema, literal, contentType, itemValueSchema);
+      return mismatches(example[0], item, `${prefix}.${i}`, sample, itemSchema, literal, contentType, itemValueSchema);
+    });
+  }
+  if (typeof example !== 'object') return !literal || same(got, example, comparisonPlaceholder ?? /(?!)/, prefix.split('.').at(-1), comparisonNames, false, contentType, [], (expected, actual) => mismatches(expected, actual, '', sample, schema, undefined, undefined, valueSchema).length === 0) ? [] : [{ path: prefix || '(the answer)', detail: `is ${JSON.stringify(got)}, the published value is ${JSON.stringify(example)}` }];
+  const out: Array<{ path: string; detail: string }> = [];
+  for (const [k, v] of Object.entries(example as Record<string, unknown>)) {
+    const p = prefix ? `${prefix}.${k}` : k;
+    const g = (got as Record<string, unknown>)[k];
+    // a sample's field the served spec does not require may be absent from one request's answer (a card's
+    // `extended_authorization` where the charge used none); anywhere else an absent key is a mismatch
+    // (a schema with no `required` list requires none of its properties)
+    const held = sample && schema ? renderedSchema(schema).schema : undefined;
+    const optional = Boolean(held?.properties?.[k]) && !(Array.isArray(held?.required) && (held.required as string[]).includes(k));
+    if (g === undefined) { if (!optional) out.push({ path: p, detail: 'is absent' }); }
+    else out.push(...mismatches(v, g, p, sample, renderedSchema(schema).schema?.properties?.[k], literal, contentType, outputChildSchema(valueSchema, k)));
+  }
+  return out;
+}
+
+const vendor = process.argv[2];
+if (!vendor || vendor.startsWith('-')) { console.error('usage: twin-standard examples <vendor> [--sweep]   (from the pack repository\'s root)'); process.exit(1); }
+const PKG = join(PACKS, vendor);
+const file = join(PKG, 'journeys', 'vendor-examples.json');
+await loadPlaceholders(PKG);
+const examples = published(PKG);
+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`);
+const journey = expandFills((existsSync(file) ? parseExactJson(readFileSync(file, 'utf8')) : { vendor, about: '', steps: [] }) as Journey & { notReplayed?: Record<string, string> });
+// The architecture allows the exact example id as a step's name. Normalize only the replay copy; verdict hashes
+// continue to name the authored file's bytes, and an explicit example field always wins.
+journey.steps = journey.steps.map((step) => {
+  const named = step as typeof step & { example?: string };
+  return named.example === undefined && byId.has(step.name) ? { ...step, example: step.name } : step;
+});
+
+const shape = await shapeChecker(PKG);
+// a page's example that names its request is the operation the spec routes that request to, never the author's guess
+// (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;
+  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 sweeping = process.argv.includes('--sweep');
+const sweepHits: string[] = [];
+const ACTOR = (k: string, parent: string): boolean => ['creator', 'user', 'inviter', 'inviter_id', 'actor_id', 'share_user_id', 'parent_user_id'].includes(k) || k.endsWith('_by') || (k === 'user' && parent.endsWith('edited'));
+const SKIP = /(^|\.)(blocks|attachments|elements|scopes|response_metadata|warnings)(\.|$)/;
+/** Actor fields no `equals` pins and lists no expect closes, in one answer. */
+function sweep(body: unknown, expects: NonNullable<JourneyStep['expect']>): string[] {
+  // an `equals`, `contains` or `members` pins its path and all under it (an empty path, the whole answer)
+  const pinned = (p: string): boolean => expects.some((e) => ('equals' in e || 'contains' in e || 'members' in e) && (!e.path || e.path === p || p.startsWith(`${e.path}.`)));
+  const closed = (p: string, n: number): boolean => expects.some((e) => e.exists === false && e.path === `${p}.${n}`);
+  const out: string[] = [];
+  const go = (v: unknown, p: string, parent: string): void => {
+    if (Array.isArray(v)) {
+      if (p && !SKIP.test(p) && !pinned(p) && !closed(p, v.length)) out.push(`list ${p} (${v.length})`);
+      v.forEach((x, i) => go(x, p ? `${p}.${i}` : String(i), p));
+    } else if (v && typeof v === 'object') {
+      for (const [k, x] of Object.entries(v)) {
+        const q = p ? `${p}.${k}` : k;
+        if (ACTOR(k, p) && (typeof x === 'string' || x === null) && !SKIP.test(q) && !pinned(q)) out.push(`actor ${q} = ${JSON.stringify(x)}`);
+        go(x, q, p);
+      }
+    }
+  };
+  go(body, '', '');
+  return out;
+}
+/** The example's actual request fields, including a multipart upload carried as raw journey bytes. */
+function exampleBody(step: JourneyStep, published?: unknown): unknown {
+  const decoded = (fields: Record<string, unknown>): Record<string, unknown> => {
+    for (const [key, expected] of Object.entries((published && typeof published === 'object' ? published : {}) as Record<string, unknown>)) {
+      const value = fields[key];
+      if (expected && typeof expected === 'object' && typeof value === 'string') {
+        try { fields[key] = parseExactJson(value); } catch { /* malformed structured field remains a mismatch */ }
+      } else if (typeof expected === 'string' && Array.isArray(value) && value.length === 1) fields[key] = value[0];
+    }
+    return fields;
+  };
+  const type = Object.entries({ ...journey.headers, ...step.headers }).find(([k]) => k.toLowerCase() === 'content-type')?.[1];
+  if (type?.split(';')[0]?.trim() === 'application/x-www-form-urlencoded' && typeof step.body === 'string') {
+    return decoded(parseBracketForm(step.body));
+  }
+  // a form the walk builds from its parts (journey-kit's `form`): its text fields, and each file by its name
+  if (step.form) {
+    const out: Record<string, unknown> = {};
+    // Match the form decoder: one text part is a scalar; repeated parts retain their order.
+    const append = (name: string, value: unknown, file = false): void => {
+      out[name] = Object.hasOwn(out, name) ? [...(Array.isArray(out[name]) ? out[name] as unknown[] : [out[name]]), value] : file ? [value] : value;
+    };
+    for (const field of step.form.fields === undefined ? [] : parseExactJson(filled(step.form.fields)) as Array<{ name: string; value: string }>) append(field.name, field.value);
+    for (const p of step.form.parts) {
+      if (!('filename' in p)) append(p.name, p.value);
+      else if (p.base64 || p.png || p.value) append(p.name, p.filename, true);
+    }
+    return decoded(out);
+  }
+  // Raw published MIME bytes retain part counts and headers instead of becoming a lossy field map.
+  if (/^multipart\//i.test(type ?? '') && typeof published === 'string') return step.bodyBase64 === undefined ? step.body : Buffer.from(step.bodyBase64, 'base64').toString('utf8');
+  const boundary = multipartBoundary(type ?? null);
+  if (!boundary || (step.bodyBase64 === undefined && typeof step.body !== 'string')) return step.body;
+  const envelope = multipartEnvelope(step.bodyBase64 !== undefined ? Uint8Array.from(Buffer.from(step.bodyBase64, 'base64')) : new TextEncoder().encode(step.body as string), boundary);
+  if (!envelope.complete) return undefined;
+  const out: Record<string, unknown> = {};
+  for (const part of envelope.parts) {
+    const value = part.filename === null ? new TextDecoder().decode(part.body) : part.body.length ? part.filename : undefined;
+    if (value === undefined) continue;
+    // OpenAPI's file arrays repeat the field name, even when one file is sent.
+    if (part.filename !== null) out[part.name] = [...(Array.isArray(out[part.name]) ? out[part.name] as unknown[] : Object.hasOwn(out, part.name) ? [out[part.name]] : []), value];
+    else out[part.name] = Object.hasOwn(out, part.name) ? [...(Array.isArray(out[part.name]) ? out[part.name] as unknown[] : [out[part.name]]), value] : value;
+  }
+  return decoded(out);
+}
+
+/** The values a request sends, its templates filled from the captures so far: its JSON leaves, or a form body's fields;
+ *  a template still unfilled is no value; one shorter than six characters is matched with its field's name (namedScalars). */
+const captures: Record<string, string> = {};
+let requestCaptures: Record<string, string> = {};
+const filled = (v: string, values = captures): string => v.replace(/\{([A-Za-z_][A-Za-z0-9_.]*)\}/g, (m, k: string) => values[k] ?? m);
+const sentValues = (body: unknown): string[] => {
+  const form = typeof body === 'string' && body.includes('=') && !body.trim().startsWith('{') ? [...new URLSearchParams(body).values()] : undefined;
+  return (form ?? leaves(body ?? {}).map(([, v]) => String(v))).map((v) => filled(v)).filter((v) => v.length >= 6 && !/^\d+$/.test(v) && !/\{\w+\}/.test(v));
+};
+/** A request's booleans and numbers by their field's name (`unsubscribed=true`): a flag or count the setup sent, which an
+ *  answer carries back under the same name; matched with the name, since a bare `true` is in every answer. */
+const namedScalars = (v: unknown, key = ''): string[] =>
+  typeof v === 'boolean' || typeof v === 'number' || isExactIntegerValue(v) || (typeof v === 'string' && v.length < 6 && v.length >= 2) ? (key && !/^\d+$/.test(key) ? [`${key}=${v}`] : [])
+    : Array.isArray(v) ? v.flatMap((x) => namedScalars(x, key))
+    : v && typeof v === 'object' ? Object.entries(v).flatMap(([k, x]) => namedScalars(x, k)) : [];
+const setupScalars = new Set<string>();
+/** The value at a dot path of an answer (`data.0.id`), as a capture reads it. */
+const at = selectorAt;
+// every value an earlier step sent, the setup's decisions an example's answer may carry back
+const setupSent = new Set<string>();
+const failures: Failure[] = [];
+const replayed = new Set<string>();
+const unknown: string[] = [];
+const world = inMemoryWorld(`examples-${vendor}`);
+// a write example whose own answer is thin (an id and little else) shows its effect only if a later step reads it: the
+// writes and the reads, by the resource each touched, for the sweep's read-back line
+const thinWrites: Array<{ step: string; base: string; id: string; from: number; deletes: boolean }> = [];
+const reads: Array<{ path: string; body: string }> = [];
+const bare = (p: string): string => p.replace(/^https?:\/\/[^/]+/, '').split('?')[0]!.replace(/\/+$/, '');
+await walk(journey, world.root(), failures, {
+  beats: false,
+  hooks: {
+    before: (step) => {
+      requestCaptures = { ...captures };
+      for (const [name, value] of Object.entries((step as JourneyStep).exampleBindings ?? {})) {
+        const bound = filled(value, captures);
+        if (requestCaptures[name] !== undefined && requestCaptures[name] !== bound) failures.push({ step: step.name, beat: 'EXAMPLE', detail: `binding ${name} contradicts an earlier capture` });
+        else requestCaptures[name] = bound;
+      }
+    },
+    after: (step, _path, answer, stepFailures) => {
+      if (isGit(step) || isWait(step) || isSocket(step)) return;
+      if (!isResp(step) && !isLine(step as JourneyStep & LineStep)) {
+        const st = step as JourneyStep;
+        const method = (st.method ?? 'GET').toUpperCase();
+        // 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 isRead = opClass ? ['retrieve', 'list', 'computed'].includes(opClass) : method === 'GET';
+        if (isRead) reads.push({ path: bare(_path), 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('/');
+          // 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 : '';
+          const idInPath = segs.some((x) => /\d/.test(x) && x.length >= 6);
+          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 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' });
+          }
+        }
+      }
+      const s = step as JourneyStep & LineStep;
+      const earlier = [...setupSent];
+      const earlierScalars = new Set(setupScalars);
+      for (const v of sentValues(exampleBody(s, byId.get(s.example ?? '')?.input) ?? s.send)) setupSent.add(v);
+      if (s.body && typeof s.body === 'object') for (const v of namedScalars(s.body)) setupScalars.add(v);
+      // what the step captures (an id the vendor minted) is the setup's from here on: a later answer carrying it decides nothing new
+      for (const [name, from] of Object.entries(s.capture ?? {})) {
+        const v = captureAt(answer.body, from, answer.headers, typeof answer.body === 'string' ? answer.body : undefined);
+        if (v !== undefined && v !== null) captures[name] = typeof v === 'object' ? JSON.stringify(v) : String(v);
+        if ((typeof v === 'string' || typeof v === 'number') && String(v).length >= 2) setupSent.add(String(v));
+      }
+      if (!s.example) return;
+      const ex = byId.get(s.example);
+      if (!ex) { unknown.push(s.example); return; }
+      specSchemas = schemasByOperation[ex.operation] ?? {};
+      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.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' });
+      // 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}` });
+      }
+      // 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` });
+      }
+      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];
+      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}` });
+      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];
+      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;
+      if (sweeping) for (const h of sweep(answer.body, s.expect ?? [])) sweepHits.push(`  SWEEP ${s.name.slice(0, 60)}  ${h}`);
+      {
+        // a value the setup decided, answered back, is asserted or named `undecided` with its reason (a check since every
+        // done pack read 0: the judges' recurring ruling, made mechanical)
+        const decided = new Set(earlier);
+        const pinned = (s.expect ?? []).map((e) => { const p = e.path ?? ''; return p.startsWith('/') ? p.slice(1).split('/').map((k) => k.replace(/~1/g, '/').replace(/~0/g, '~')).join('.') : p; });
+        const undecided = Object.keys((s as JourneyStep & { undecided?: Record<string, string> }).undecided ?? {});
+        const isPinned = (path: string): boolean => undecided.includes(path) || pinned.some((a) => a === '' || path === a || path.startsWith(`${a}.`));
+        for (const [path, v] of leaves(answer.body)) {
+          if (typeof v === 'number' || isExactIntegerValue(v) || !decided.has(String(v)) || isPinned(path) || /(^|\.)(type|object)$/.test(path)) continue;
+          failures.push({ step: s.name, beat: 'EXAMPLE', detail: `${path} answers ${JSON.stringify(v)}, which an earlier step sent or captured, and the step neither asserts it nor names it undecided` });
+        }
+        const scalars = (v: unknown, p: string): void => {
+          if (typeof v === 'boolean' || typeof v === 'number' || isExactIntegerValue(v) || (typeof v === 'string' && v.length < 6)) {
+            const key = p.split('.').at(-1) ?? '';
+            if (key === 'type' || key === 'object') return;
+            if (earlierScalars.has(`${key}=${v}`) && !isPinned(p)) failures.push({ step: s.name, beat: 'EXAMPLE', detail: `${p} answers ${JSON.stringify(v)}, which an earlier step sent under that name, and the step neither asserts it nor names it undecided` });
+          } else if (v && typeof v === 'object') for (const [k, x] of Object.entries(v)) scalars(x, p ? `${p}.${k}` : k);
+        };
+        scalars(answer.body, '');
+      }
+      comparisonPlaceholder = ex.placeholder; comparisonNames = ex.names;
+      const answerAs = isResp(s) ? (answer.body as { replies: unknown[] }).replies : ex.restXml && answer.status < 300 ? restXmlAnswer(ex.restXml, answer.body, answer.headers) : answer.body;
+      const publishedValue = answerKeys(ex.output, publishedBody, exampleBody(s, publishedInput), ex.placeholder);
+      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;
+      // 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;
+        if (Array.isArray(holder)) comparisonCollections.push(operation.answers.key ?? '');
+        else if (isObject(holder) && Array.isArray((holder as Record<string, unknown>).data)) comparisonCollections.push(operation.answers.key ? `${operation.answers.key}.data` : 'data');
+      }
+      const compared = sseExampleAnswer(published, answerAs, (frame) => mismatches(published, frame, '', ex.sample, ex.schema, literal, responseType, valueSchema).length === 0);
+      const explainedStatus = ex.status !== undefined && answer.status !== ex.status && s.exampleDiffers?.status;
+      for (const m of explainedStatus ? [] : mismatches(published, compared, '', ex.sample, ex.schema, literal, responseType, valueSchema)) {
+        // Existing declarations name array item paths with [] (scopes[].filter); inspect each actual
+        // index while retaining that explicit ruling, only where the published node is an array.
+        let node: unknown = published;
+        let declaredPath = '';
+        for (const key of m.path.split('.').filter(Boolean)) {
+          if (Array.isArray(node) && /^\d+$/.test(key)) {
+            declaredPath += '[]'; node = node[Number(key)] ?? node[0];
+          } else {
+            declaredPath += `${declaredPath ? '.' : ''}${key}`;
+            node = node && typeof node === 'object' ? (node as Record<string, unknown>)[key] : undefined;
+          }
+        }
+        if (s.exampleDiffers?.[m.path] || s.exampleDiffers?.[declaredPath]) continue;
+        failures.push({ step: s.name, beat: 'EXAMPLE', detail: `${m.path} ${m.detail}` });
+      }
+      // a value the step's own request decides, answered back, is asserted: an answer echoing the request is the
+      // cheapest place for a twin to be wrong unseen (each judge of the first two packs ruled on one left unasserted)
+      const sent = new Set(leaves(s.body ?? s.send ?? {}).map(([, v]) => String(v)).filter((v) => v.length >= 3));
+      const asserted = (s.expect ?? []).map((e) => e.path ?? '');
+      for (const [path, v] of leaves(answer.body)) {
+        // (or named undecided: a value the vendor generates that only coincides with what was sent, PostHog's `hogql`)
+        if (!sent.has(String(v)) || s.exampleDiffers?.[path] || (s as JourneyStep & { undecided?: Record<string, string> }).undecided?.[path]) continue;
+        if (asserted.some((a) => a === '' || path === a || path.startsWith(`${a}.`))) continue;
+        failures.push({ step: s.name, beat: 'EXAMPLE', detail: `${path} answers ${JSON.stringify(v)} from the request, and the step does not assert it` });
+      }
+    },
+  },
+});
+// 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 patchRemoved = examples.filter((e) => e.patchRemoved);
+const unserved = examples.filter((e) => !e.patchRemoved && ownerOf(e) === 'gap');
+const recorded = Object.keys(journey.notReplayed ?? {});
+const missing = examples.filter((e) => !e.patchRemoved && !replayed.has(e.id) && !recorded.includes(e.id) && ownerOf(e) !== 'gap');
+world.restore();
+const embeddedDeletionRead = (body: string, collection: string, id: string): boolean => {
+  const contains = (value: unknown): boolean => {
+    if (!value || typeof value !== 'object') return false;
+    if (Array.isArray(value)) return value.some(contains);
+    const object = value as Record<string, unknown>;
+    if (object.object === 'list' && typeof object.url === 'string' && bare(object.url) === collection && Array.isArray(object.data)) {
+      return !object.data.some((item) => item && typeof item === 'object' && (item as Record<string, unknown>).id === id);
+    }
+    return Object.values(object).some(contains);
+  };
+  try { return contains(parseExactJson(body)); } catch { return false; }
+};
+for (const w of thinWrites) {
+  // a delete is read back by a read of the subject (its not-found) or of its collection (no longer listing it)
+  const collection = w.base.split('/').slice(0, -1).join('/');
+  const readBack = reads.slice(w.from).some((r) => r.path === w.base || r.path.startsWith(`${w.base}/`) || (w.deletes && (r.path === collection || embeddedDeletionRead(r.body, collection, w.id))) || (w.id.length >= 6 && r.body.includes(`"${w.id}"`)));
+  if (!readBack) failures.push({ step: w.step, beat: 'EXAMPLE', detail: `a thin answer whose effect (${w.base}) no later step reads back` });
+}
+for (const h of sweepHits) console.log(h);
+if (sweeping) console.log(`  sweep: ${sweepHits.length} unpinned actor fields and unclosed lists (advisory)`);
+for (const f of failures) console.log(`  FAIL  ${f.step}  [${f.beat}] ${f.detail}`);
+for (const id of unknown) console.log(`  FAIL  ${id}  [EXAMPLE] the spec publishes no example of this name`);
+for (const e of missing) console.log(`  GAP   ${e.id}  neither replayed nor recorded`);
+const verdictPath = join(PKG, 'journeys', 'vendor-examples.verdict.json');
+const verdict = existsSync(verdictPath) ? (parseExactJson(readFileSync(verdictPath, 'utf8')) as { sha256?: string; plausible?: boolean; judge?: { agent?: string; session?: string }; authors?: string[] }) : undefined;
+const dependent = verdict ? notIndependent(verdict) : undefined;
+const judged = !existsSync(file) ? 'no file' : !verdict ? 'unjudged' : dependent ? dependent : verdict.plausible ? 'plausible' : 'rejected';
+const replayedAll = !failures.length && !unknown.length && !missing.length;
+const done = replayedAll && judged === 'plausible';
+console.log(`  replayed: ${replayedAll ? 'yes' : 'no'}`);
+console.log(`  verdict: ${judged}`);
+console.log(`${vendor}   examples: ${examples.length} published, ${patchRemoved.length} of patch-removed operations, ${unserved.length} of operations the twin does not serve, ${replayed.size} replayed, ${recorded.length} recorded; ${failures.length + unknown.length} failing   done: ${done ? 'yes' : 'no'}`);
+process.exit(done ? 0 : 1);