@volter/twin-standard 1.0.158 → 1.0.160

package/src/spec-documents.ts

@@ -10,24 +10,113 @@ import { parse as parseYaml } from 'yaml';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { gunzipSync } from 'node:zlib';
+import { applySpecPatch, type SpecPatch } from './spec-patches.ts';
+import { slug } from './spec-ir.ts';
 
 type Json = any;
 export type SpecDocuments = { documents: Record<string, Json> };
 
+function readDocument(file: string): Json {
+  const bytes = readFileSync(file);
+  const text = (file.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
+  return /\.ya?ml(\.gz)?$/.test(file) ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_, value) => typeof value === 'bigint' ? exactInteger(String(value)) : value)) : parseExactJson(text);
+}
+
 /** The documents of `spec/openapi/`, by name, or undefined when the pack vendors one spec file. */
 export function readSpecDocuments(specDir: string): SpecDocuments | undefined {
   const dir = join(specDir, 'openapi');
   if (!existsSync(dir)) return undefined;
   const documents: Record<string, Json> = {};
   for (const f of readdirSync(dir).filter((f) => /\.(json|ya?ml)(\.gz)?$/.test(f)).sort()) {
-    const bytes = readFileSync(join(dir, f));
-    const text = (f.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
-    documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = /\.ya?ml(\.gz)?$/.test(f) ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_, v) => typeof v === 'bigint' ? exactInteger(String(v)) : v)) : parseExactJson(text);
+    documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = readDocument(join(dir, f));
   }
   if (Object.keys(documents).length < 2) throw new Error(`${dir}: one API in several documents needs at least two; a single document is spec/openapi.{json,yaml}`);
   return { documents };
 }
 
+const openapiFiles = ['openapi.json.gz', 'openapi.json', 'openapi.yaml.gz', 'openapi.yaml'];
+
+function readPatchedDocument(specDir: string, filenames: string[]): Json | undefined {
+  const file = filenames.map((name) => join(specDir, name)).find(existsSync);
+  const documents = file === undefined ? readSpecDocuments(specDir) : undefined;
+  let doc = file === undefined ? documents : readDocument(file);
+  if (doc === undefined) return undefined;
+  const patches = join(specDir, 'patches.json');
+  if (existsSync(patches)) for (const patch of (readDocument(patches) as { patches: SpecPatch[] }).patches) applySpecPatch(doc, patch);
+  if (documents !== undefined) {
+    const merged = mergeDocuments(doc);
+    if (merged.contradictions.length) throw new Error(`OpenAPI response declarations conflict: ${merged.contradictions.join('; ')}`);
+    doc = merged.doc;
+  }
+  return doc;
+}
+
+/** Response declarations as served, independent of their representation media or generated surface version. */
+export function declaredResponseStatuses(specDir: string): Map<string, Set<string>> {
+  const doc = readPatchedDocument(specDir, openapiFiles);
+  const statuses = new Map<string, Set<string>>();
+  if (doc === undefined) return statuses;
+  for (const [path, item] of Object.entries(doc.paths ?? {}) as Array<[string, Record<string, { operationId?: string; responses?: Record<string, unknown> }>]>) {
+    for (const [method, operation] of Object.entries(item)) {
+      if (!operation || typeof operation !== 'object' || !operation.responses) continue;
+      statuses.set(operation.operationId || slug(method, path), new Set(Object.keys(operation.responses)));
+    }
+  }
+  return statuses;
+}
+
+/** Declared schema fields, including nested objects that are not inferred as generated resources. */
+export function schemaFieldNames(specDir: string): Set<string> {
+  const doc = readPatchedDocument(specDir, ['smithy.json.gz', 'smithy.json', ...openapiFiles, 'discovery.json.gz', 'discovery.json']);
+  const fields = new Set<string>();
+  if (doc === undefined) return fields;
+  for (const shape of Object.values(doc.shapes ?? {}) as Json[]) {
+    if (shape.type !== 'structure' && shape.type !== 'union') continue;
+    for (const [name, member] of Object.entries(shape.members ?? {}) as Array<[string, Json]>) {
+      fields.add(name);
+      for (const trait of ['smithy.api#jsonName', 'smithy.api#xmlName']) {
+        const wireName = member.traits?.[trait];
+        if (typeof wireName === 'string') fields.add(wireName);
+      }
+    }
+  }
+  const schema = (node: Json): void => {
+    if (Array.isArray(node)) { for (const item of node) schema(item); return; }
+    if (!node || typeof node !== 'object') return;
+    for (const [name, property] of Object.entries(node.properties ?? {}) as Array<[string, Json]>) {
+      fields.add(name);
+      if (typeof property?.xml?.name === 'string') fields.add(property.xml.name);
+      schema(property);
+    }
+    for (const keyword of ['$defs', 'definitions', 'patternProperties', 'dependentSchemas']) {
+      for (const child of Object.values(node[keyword] ?? {})) schema(child);
+    }
+    for (const keyword of ['items', 'additionalItems', 'additionalProperties', 'unevaluatedProperties', 'unevaluatedItems', 'not', 'contains', 'propertyNames', 'if', 'then', 'else', 'allOf', 'anyOf', 'oneOf', 'prefixItems']) schema(node[keyword]);
+  };
+  for (const catalog of [doc.components?.schemas, doc.definitions, doc.schemas]) {
+    for (const node of Object.values(catalog ?? {})) schema(node);
+  }
+  const body = (node: Json): void => {
+    schema(node?.schema);
+    for (const media of Object.values(node?.content ?? {}) as Json[]) schema(media?.schema);
+  };
+  for (const catalog of [doc.components?.responses, doc.components?.requestBodies, doc.components?.parameters, doc.components?.headers, doc.responses, doc.parameters]) {
+    for (const node of Object.values(catalog ?? {})) body(node);
+  }
+  for (const paths of [doc.paths, doc.webhooks, doc.components?.pathItems]) {
+    for (const item of Object.values(paths ?? {}) as Json[]) {
+      for (const parameter of item.parameters ?? []) body(parameter);
+      for (const method of ['get', 'put', 'post', 'delete', 'patch', 'head', 'options', 'trace']) {
+        const operation = item[method];
+        for (const parameter of operation?.parameters ?? []) body(parameter);
+        body(operation?.requestBody);
+        for (const response of Object.values(operation?.responses ?? {})) body(response);
+      }
+    }
+  }
+  return fields;
+}
+
 /** A node without its words (description, summary, examples, and the tags a document files it under): what two
  *  documents must agree on. */
 const substance = (n: Json): string => JSON.stringify(n, (k, v) => (['description', 'summary', 'example', 'examples', 'x-mint', 'tags'].includes(k) ? undefined : v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b))) : v));

package/src/spec-ir-client.ts

@@ -6,7 +6,7 @@
 // `spec/`, Creating a pack, step 2): its method, its URL as the client
 // builds it (a label is the Python expression the client interpolates), the query keys it sends (literal, or the keys
 // of the dict it urlencodes) and its body's keys, each typed by the client's own annotation of the value (`null`
-// where the client does not say). A spec patch corrects the table as it corrects a JSON spec (derive-pack): what the
+// where the client does not say). A spec patch corrects the table as it corrects a JSON spec (twin-standard derive): what the
 // client builds as a raw string (a token's scopes) comes from the vendor's reference page that way.
 //
 // The calls at one method and path are one operation, their query and body keys together. The client says nothing

package/src/spec-ir-commands.ts

@@ -3,7 +3,7 @@
 // its group, the version it arrived in, its arity, its arguments, its flags and its reply's schema); a pack whose wire
 // carries Redis commands (Upstash's REST API: a command and its arguments in the path or the body) vendors the files of
 // the commands its vendor serves and derives its command surface from them, as a line protocol's surface is its RFC's
-// command table (spec-ir-lines.ts). A spec patch corrects the data as it corrects a JSON spec (derive-pack).
+// command table (spec-ir-lines.ts). A spec patch corrects the data as it corrects a JSON spec (twin-standard derive).
 
 export type CommandArgument = { name: string; type: string; optional?: boolean; multiple?: boolean; token?: string; arguments?: CommandArgument[] };
 /** A command: `id` as a client names it (`SET`, `CLIENT GETNAME` for a container's subcommand); `arity` as Redis gives

package/src/spec-ir-lines.ts

@@ -1,6 +1,6 @@
 // A line protocol's spec as data: the commands a client sends and the replies each may be answered,
 // read from the RFC's own table of them. The IR a byte-stream pack derives its surface from, as an HTTP
-// pack derives its from an OpenAPI document; a spec patch corrects it the same way (derive-pack).
+// pack derives its from an OpenAPI document; a spec patch corrects it the same way (twin-standard derive).
 //
 // SMTP's table is RFC 5321 §4.3.2 "Command-Reply Sequences": each command, then its intermediate (I),
 // success (S) and error (E) codes, where `I: 354 -> data -> S: 250` says what answers the lines that

package/src/spec-ir-proto.ts

@@ -161,7 +161,7 @@ export function parseProto(path: string, text: string): ProtoFile {
   return file;
 }
 
-/** The vendored tree (path → text) as data, so a spec patch corrects it as it corrects a JSON spec (derive-pack). */
+/** The vendored tree (path → text) as data, so a spec patch corrects it as it corrects a JSON spec (twin-standard derive). */
 export type ProtoSpec = { format: 'proto'; files: ProtoFile[] };
 export function readProtoFiles(files: Record<string, string>): ProtoSpec {
   return { format: 'proto', files: Object.entries(files).sort(([a], [b]) => a.localeCompare(b)).map(([path, text]) => parseProto(path, text)) };

package/src/spec-patches.ts

@@ -1,6 +1,6 @@
 // A pack's corrections to its vendor's spec (spec/patches.json): RFC 6902 operations (add, replace, remove, move, copy),
-// applied to the parsed spec so the vendored file stays the vendor's own bytes. derive-pack.ts applies them before the
-// IR; vendor-examples.ts reads the patched schemas, which are what the twin is derived from.
+// applied to the parsed spec so the vendored file stays the vendor's own bytes. the derivation applies them before the
+// IR; `twin-standard examples` reads the patched schemas, which are what the twin is derived from.
 
 export type SpecPatch = { op: string; path: string; from?: string; value?: unknown };
 

package/src/tools/judge-brief.ts

@@ -3,8 +3,7 @@
 // runtime). The verdict names its judge and the authors; the grade refuses one whose judge is an author
 // (packages/twin-standard/src/verdict.ts). One judging per pack: the verdict stands through later changes.
 //
-//   twin-standard judge-brief <vendor> --authors <author name>[,<agent>...]   (from the pack repository's root; twin-world's
-//   bun scripts/judge-brief.ts runs the same)
+//   twin-standard judge-brief <vendor> --authors <author name>[,<agent>...]   (from the pack repository's root)
 import { attributionName } from '../verdict.ts';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';

package/src/tools/life-coverage-walk.ts

@@ -6,9 +6,9 @@ import { parseExactJson } from '@volter/world-core/exact-json';
 // is its precondition, not what it measures. This module is no test file itself, so a published package holds it.
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { listActions, observeTransitions, stateOf, type Actor, type DerivedManifest, type Transition } from '@volter/world-core/runtime';
+import { listActions, observeTransitions, stateOf, type Actor, type DerivedManifest, type ErrorSpec, type Transition } from '@volter/world-core/runtime';
 import { inMemoryWorld, walk, type Failure, usePacks } from '../walk/behavior-journey.ts';
-import { lanesOf, shapeChecker } from '../walk/shape.ts';
+import { lanesOf, lineShape, shapeChecker } from '../walk/shape.ts';
 import { sharingLanesIn } from '../lanes.ts';
 
 /** Registers, in the `bun test` run that imports it, the walks of `vendor` in the pack repository at `PACKS`. */
@@ -30,9 +30,12 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
   const { manifest } = (await import(join(PACKS, vendor, 'src', 'manifest.ts'))) as { manifest: DerivedManifest };
   // the lanes over the vendor's state its serve factory serves are walked by this life, their machines with the vendor's
   // ("Pack layout"); two manifests naming one resource's field would collide in the keys below, so that refuses
-  const laneManifests = await Promise.all(sharingLanes(vendor).map(async (l) => ((await import(join(PACKS, vendor, l, 'src', 'manifest.ts'))) as { manifest: DerivedManifest }).manifest));
+  const units = [{ dir: join(PACKS, vendor), manifest, lane: undefined }, ...await Promise.all(sharingLanes(vendor).map(async (l) => {
+    const dir = join(PACKS, vendor, l);
+    return { dir, lane: l, manifest: ((await import(join(dir, 'src', 'manifest.ts'))) as { manifest: DerivedManifest }).manifest };
+  }))];
   // a vendor of lanes' root (a VendorManifest) declares no resources of its own: its lanes do
-  const allResources = [manifest, ...laneManifests].flatMap((mf) => Object.entries(mf.resources ?? {}));
+  const allResources = units.flatMap(({ manifest: mf }) => Object.entries(mf.resources ?? {}));
   const machines = new Map<string, unknown>();
   for (const [resource, decl] of allResources) for (const [field, machine] of Object.entries(decl.state ?? {})) {
     const name = `${resource}.${field}`;
@@ -42,20 +45,25 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
     machines.set(name, machine);
   }
   const where = new Map<Transition, Array<{ at: string; field: string; type: string; service: string }>>();
-  for (const mf of [manifest, ...laneManifests]) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
-    for (const [field, m] of Object.entries(decl.state ?? {})) m.transitions.forEach((t, i) => {
-      const place = { at: `${resource}.${field}#${i}`, field, type: decl.storedAs ?? resource, service: mf.service ?? mf.vendor };
-      const places = where.get(t) ?? [];
-      if (!places.some((p) => p.at === place.at && p.type === place.type && p.service === place.service)) where.set(t, [...places, place]);
-    });
+  const httpTransitions = new Set<Transition>();
+  for (const { dir, manifest: mf } of units) {
+    const http = !lineShape(dir);
+    for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
+      for (const [field, m] of Object.entries(decl.state ?? {})) m.transitions.forEach((t, i) => {
+        if (http) httpTransitions.add(t);
+        const place = { at: `${resource}.${field}#${i}`, field, type: decl.storedAs ?? resource, service: mf.service ?? mf.vendor };
+        const places = where.get(t) ?? [];
+        if (!places.some((p) => p.at === place.at && p.type === place.type && p.service === place.service)) where.set(t, [...places, place]);
+      });
+    }
   }
   const moves = new Map<string, Array<{ transition: Transition; from: string; field: string; actor: Actor; subject: string }>>();
   const subjectKey = (service: string, type: string, id: string): string => JSON.stringify([service, type, id]);
   observeTransitions((_decl, t, outcome, from, entry) => {
     const places = where.get(t) ?? [];
     if (outcome === 'refused') {
-      // A failed check on an already committed write is no refusal the application received.
-      if (entry) return;
+      // HTTP refusals are credited from their received status and body; a line protocol owns its session's replies.
+      if (entry || httpTransitions.has(t)) return;
       const groups = new Set(places.map((p) => JSON.stringify([p.service, p.type, p.field])));
       if (groups.size === 1) for (const p of places) seen.add(`${p.at}|refused|${from}`);
       return;
@@ -79,12 +87,14 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
   const root = world.root();
   // what each step was answered, by the spec operation it called: a refusal is seen at the wire, whichever code gave it
   const shape = await shapeChecker(join(PACKS, vendor));
-  const answered: Array<{ op: string; text: string; body: unknown }> = [];
+  const answered: Array<{ op: string; lane?: string; status: number; body: unknown }> = [];
   try {
-    await walk(life, root, failures, { beats: w.beats, hooks: { after: (step, path, answer) => {
+    await walk(life, root, failures, { beats: w.beats, hooks: { after: (_step, _path, answer) => {
       // a line step's refusals are the machine's own (observeTransitions); a request's are read off its answer
-      const op = 'method' in step ? shape?.operationOf(step.method, path, { ...(life.headers ?? {}), ...(step.headers ?? {}) })?.op.id : undefined;
-      if (op) answered.push({ op, text: JSON.stringify(answer.body ?? ''), body: answer.body });
+      const request = answer.request;
+      if (!request) return;
+      const hit = shape?.operationOf(request.method, request.url, request.headers);
+      if (hit) answered.push({ op: hit.op.id, lane: hit.lane, status: answer.status, body: answer.wireBody });
     } } });
     // a declared refusal is reached when a step on its operation was answered with it: its code, or its message
     // up to the first placeholder
@@ -92,13 +102,13 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
     const holds = (value: unknown, code: string): boolean => (value !== null && typeof value === 'object'
       ? Object.values(value as Record<string, unknown>).some((v) => holds(v, code))
       : (typeof value === 'string' || typeof value === 'number') && String(value) === code);
-    const answers = (a: { text: string; body: unknown }, r: { code?: string | number; message: string }): boolean =>
-      r.code !== undefined ? holds(a.body, String(r.code)) : a.text.includes(r.message.split('{')[0]!.trim());
-    for (const [resource, decl] of allResources) {
+    const answers = (a: { status: number; body: unknown }, r: ErrorSpec): boolean =>
+      a.status === r.status && (r.code !== undefined ? holds(a.body, String(r.code)) : JSON.stringify(a.body)?.includes(r.message.split('{')[0]!.trim()) === true);
+    for (const { manifest: mf, lane } of units) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
       for (const [field, m] of Object.entries(decl.state ?? {})) {
         m.transitions.forEach((t, i) => {
           if (!t.operation) return;
-          const on = answered.filter((a) => a.op === t.operation);
+          const on = answered.filter((a) => a.op === t.operation && a.lane === lane);
           if (t.refusal && on.some((a) => answers(a, t.refusal!))) seen.add(`${resource}.${field}#${i}|refused|*`);
           for (const [from, r] of Object.entries(t.refusals ?? {})) if (on.some((a) => answers(a, r))) seen.add(`${resource}.${field}#${i}|refused|${from}`);
         });
@@ -108,13 +118,13 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
     // transition that allows it (from its state to the next, by its operation when both name one); a change no
     // transition allows is an undeclared move
     const fieldsOf = new Map<string, Array<[string, string, (typeof manifest.resources)[string]['state'] extends infer S ? S extends Record<string, infer F> ? F : never : never]>>();
-    for (const mf of [manifest, ...laneManifests]) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
+    for (const { manifest: mf } of units) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
       const key = JSON.stringify([mf.service ?? mf.vendor, decl.storedAs ?? resource]);
       for (const [field, m] of Object.entries(decl.state ?? {})) fieldsOf.set(key, [...(fieldsOf.get(key) ?? []), [resource, field, m]]);
     }
     const current = new Map<string, Record<string, unknown>>();
     // the services the life wrote: the vendor's, or its lanes' (a vendor of lanes' root names none of its own)
-    const services = [...new Set([manifest, ...laneManifests].map((mf) => mf.service).filter((x): x is string => typeof x === 'string'))];
+    const services = [...new Set(units.map(({ manifest: mf }) => mf.service).filter((x): x is string => typeof x === 'string'))];
     if (!services.length) services.push(manifest.vendor);
     for (const a of services.flatMap((service) => listActions(service, root))) {
       if (a.op !== 'set' || !a.fields) continue;

package/src/tools/life-coverage.ts

@@ -24,8 +24,8 @@
 // A walk that fails, and a file in scope (the pack's src/ on disk, its sharing lanes' too) that declares code yet
 // measures no line, stop the measurement: neither is a file with nothing to reach.
 //
-// Usage: twin-standard coverage <vendor> [--write | --out <file>] [--prune]   (from the pack repository's root; twin-world's
-//        bun scripts/life-coverage.ts runs the same)   (--prune removes the stale records)   (--write keeps journeys/coverage.json)
+// Usage: twin-standard coverage <vendor> [--write | --out <file>] [--prune]   (from the pack repository's root)
+//        (--prune removes the stale records)   (--write keeps journeys/coverage.json)
 import { spawnSync } from 'node:child_process';
 import ts from 'typescript';
 import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';

package/src/tools/packs-root.ts

@@ -1,8 +1,8 @@
 // Where the contributor's tools (walk, examples, coverage, judge-brief) find the pack they are given: a vendor's directory
 // under the pack repository they run from. A contributor runs them from their own repository's root (`twin-standard walk
-// <vendor>`), so that root is the working directory; twin-world's scripts, which find Volter's pack repository beside
-// their checkout, name it before loading a tool (setPacksRoot), and the kernel checkout a walk must measure
-// (setKernelCheckout). Each tool reads both once, when it loads.
+// <vendor>`), so that root is the working directory; a tool that runs another in a process of its own (run-tool.ts)
+// names it before loading the tool (setPacksRoot), with the kernel checkout a walk must measure (setKernelCheckout).
+// Each tool reads both once, when it loads.
 import { join } from 'node:path';
 
 let packs = process.cwd();

package/src/tools/score-pack.ts

@@ -3,7 +3,7 @@
 // life per pack is walked through the pack's own fetch on the in-memory World, and the report says:
 //   - the life: whether a judge's plausible verdict names its current content (a verdict its author wrote is not one);
 //   - correctness: every check on every step (status, expectations, captures, SHAPE, the beats) and the life
-//     answering byte for byte the same on a second fresh World;
+//     answering the same on a second fresh World under its declared engine outputs;
 //   - coverage: the hand-written code the life and the vendor's published examples run and the declared state logic
 //     they reach (life-coverage.ts), with what they never reach;
 //   - the vendor's published examples: replayed and judged (vendor-examples.ts);
@@ -12,8 +12,7 @@
 // This is source-journey evidence, not installed readiness or pack completion. pack-done owns completion and consumes
 // this report alongside the exact artifact's installed customer assessment in the one final run.
 //
-// Usage: twin-standard walk <vendor> [--write] [--report <path>]   (from the pack repository's root; twin-world's
-//        bun scripts/score-pack.ts <vendor> runs the same)
+// Usage: twin-standard walk <vendor> [--write] [--report <path>]   (from the pack repository's root)
 //   --write keeps journeys/score.json and journeys/coverage.json; --report writes the report and what it lacks for done
 //   to <path> as JSON and changes nothing in the checkout
 
@@ -27,6 +26,7 @@ import { dirname, join, sep } from 'node:path';
 import { inMemoryWorld, walk, withPinnedWorldDraws, type Failure, usePacks } from '../walk/behavior-journey.ts';
 import { expandFills, waitMs, type Journey } from '../walk/journey-kit.ts';
 import { vendorFetch, vendorStream } from '../walk/vendor-fetch.ts';
+import { compareReplays, type ReplayStep } from '../walk/replay.ts';
 import { existenceProbe } from '../walk/journey-kit.ts';
 import { kernelCheckout, packsRoot, toolPath } from './packs-root.ts';
 const PACKS = packsRoot();
@@ -73,10 +73,10 @@ const judged = life.steps.length === 0 || !verdict ? 'unjudged' : dependent ? de
 const world = inMemoryWorld(`score-${vendor}`);
 const failures: Failure[] = [];
 await walk(life, world.root(), failures, { beats: true });
-const answers = async (): Promise<string[]> => {
-  const seen: string[] = [];
+const answers = async (): Promise<ReplayStep[]> => {
+  const seen: ReplayStep[] = [];
   // the World's own draws (its seed, its keys) are the same in both: two Worlds differ only by what is beyond them (R9)
-  await withPinnedWorldDraws(() => walk(life, world.root(), [], { beats: false, hooks: { after: (step, p, a) => seen.push(`${(step as { name?: string }).name ?? ''}\u0000${p} ${a.status} ${JSON.stringify(a.body)}`) } }));
+  await withPinnedWorldDraws(() => walk(life, world.root(), failures, { beats: false, hooks: { after: (step, path, answer) => seen.push({ name: step.name ?? '', path, status: answer.status, body: answer.body, ...(answer.sql ? { sql: answer.sql } : {}), ...(answer.connection ? { connection: answer.connection } : {}) }) } }));
   return seen;
 };
 const [first, second] = [await answers(), await answers()];
@@ -166,8 +166,8 @@ const flags: Flag[] = [];
     }
   }
 }
-const differs = first.findIndex((line, i) => line !== second[i]);
-if (differs >= 0 || first.length !== second.length) failures.push({ step: '(whole life)', beat: 'REPLAYABLE', detail: `a second fresh World answered differently at "${(first[differs] ?? second[differs] ?? first.at(-1) ?? '').split('\u0000')[0]}" (the ${differs + 1}th answered step; waits are not counted)` });
+const replayComparison = compareReplays(first, second);
+for (const detail of replayComparison.diagnostics) failures.push({ step: '(whole life)', beat: 'REPLAYABLE', detail });
 
 // ── breadth ──────────────────────────────────────────────────────────────────────────────────
 const factory = await vendorFetch(PACKS, vendor);