@volter/twin-standard 1.0.30 → 1.0.31

package/src/walk/journey-kit.ts

@@ -0,0 +1,858 @@
+import { parseExactJson, exactInteger, isExactIntegerValue } from '@volter/world-core/exact-json';
+// THE BEHAVIOURAL JOURNEY KIT — the declaration a pack makes about how it BEHAVES over time.
+//
+// The census answers "is this operation mapped?" and R9 answers "does it answer identically
+// twice?". Neither asks whether the twin is RIGHT. A capability's verify does, but it is written
+// by the author who already knew which path worked, and it is a few calls long: github's SDK
+// parity test creates an issue with a title and lists it back, which is why nobody noticed that
+// `labels` is dropped on create and that `?state=open` returns closed issues too.
+//
+// A JOURNEY is the other thing: one long walk through a pack, the way a consumer actually uses
+// it — build state up, refer back to it, change it, and check it still holds many steps later.
+// It is the API-level sibling of this repo's blind-walk doctrine, and its job is to prove the
+// twin's internal logic and state persistence are basically functional, not to unit-test a
+// handler.
+//
+// A journey is ORDERED and STATEFUL. Each step names what a person is doing, issues one request,
+// and may capture values out of the response for later steps (`capture`) and assert things about
+// it (`expect`). The runner adds beats no pack should have to write:
+//
+//   ECHO         every scalar and array field a create sends comes back on the create AND on a
+//                later read — the beat github fails on `labels`
+//   PERSISTS     everything created early is still readable at the END of the walk, after every
+//                other write has happened
+//   ISOLATED     a second world, walked nowhere, sees none of it
+//   REPLAYABLE   the whole walk on a fresh root produces byte-identical answers
+//   UNKNOWN      an id never created answers the vendor's own not-found shape, not a 200
+//
+// Steps are data, not code, so the runner can re-order, re-run and re-check them; assertions that
+// need real logic go in `check`, which receives the response and everything captured so far.
+//
+// ONE RULE ABOUT SHAPE, and it is the rule that earns a journey its length: A STORY MUST RETURN
+// SOMETHING TO A STATE IT ALREADY HELD. Close the issue and reopen it. Add the label, take it off,
+// put it back. Bugs do not live in a transition, they live between two of them, and a walk that
+// only ever moves forward cannot see the ones that matter. Both of the deepest defects found so
+// far are of exactly this shape: github's timeline forgot `closed` and `reopened` (the story
+// reopens), and the kernel drops a write that returns a value to what it was one instant earlier
+// (slack's story does NOT re-add a reaction, so its walk was green while the defect was live).
+
+import { parse, visit } from 'graphql';
+import { digest, jwtSign, oauth1BaseString, oauth1Encode, oauth1Signature, presignSigV4, signSigV4 } from '@volter/world-core';
+
+/** A value captured from an earlier step, written `{step.field}` — resolved in paths and bodies. */
+export type Captured = Record<string, string>;
+
+export type JourneyStep = {
+  /** What a PERSON is doing, in their words — this is what a failure report reads back. */
+  name: string;
+  method: string;
+  /** `{capture}` placeholders are substituted from earlier steps. */
+  path: string;
+  /** Start HTTP without waiting; a later step with await and the same method/path checks its answer. */
+  defer?: string;
+  /** Collect a previously deferred request once, with all ordinary response checks. */
+  await?: string;
+  body?: unknown;
+  /** A body of raw bytes (a gzip'd package, an image, an audio file), base64 in the journey and sent decoded: a
+   *  string body is sent as UTF-8, which no binary format survives. A step carries `body` or `bodyBase64`, never both. */
+  bodyBase64?: string;
+  /** A large raw body written short: `text` repeated to `bytes` bytes (a part of several MiB, a body over a size limit),
+   *  expanded before the step is sent, signed or compared (expandFills); never beside `body`, `bodyBase64` or `form`.
+   *  Inside `body`, a value `{ "$fill": { text, bytes } }` is the same string written short. */
+  bodyFill?: { text: string; bytes: number };
+  /** How the client encodes `body` as it sends it, after its captures are filled: `gzip` (posthog-js's `gzip-js`, a
+   *  Node SDK's gzip) or `base64-form` (a form whose `data` is the body's base64). */
+  encode?: 'gzip' | 'base64-form';
+  /** An HTML form the client posts as multipart/form-data (RFC 7578; `formBody`), as a browser posts a composer with a
+   *  file from the person's machine or an SDK posts a POST-policy upload: `fields`, a template whose captures fill to a
+   *  JSON `[{name, value}]` list (`"{vFields}"`), sent first and in its order (every field an S3 lease named), then
+   *  `parts` in the form's order, each a text
+   *  field (its `value`, captures filled: a value the page showed, read off it) or a file (`filename`, its `type`, and its
+   *  bytes as `base64`, as text in `value`, or a real PNG of the size given, `png`). The walk builds the body and its boundary. A step carries
+   *  one of `body`, `bodyBase64` and `form`. */
+  form?: JourneyForm;
+  headers?: Record<string, string>;
+  /** The status this step must answer. Defaults to "any 2xx". */
+  status?: number;
+  /** Values for later steps: name → a dot path into the answer, `text:<pattern>` for a value read off a page's or mail's
+   *  text, `header:<name>[:<pattern>]` for a response header (a session cookie), or `view:<path>` for a path into the
+   *  pack's view of the answer (`view`: a value the client decodes before it uses it). `sse:<event>:<path>` joins
+   *  matching SSE string values; `sse-json:<event>:<path>` also decodes fragmented JSON tool input. */
+  capture?: Record<string, string>;
+  /** Marks this step as creating a resource: the runner applies the ECHO and PERSISTS beats,
+   *  reading it back at `readBack` (a path, `{capture}` allowed) both now and at the end.
+   *  `echoOn: 'read'` when the vendor's own create answer is thin by design — Jira's returns
+   *  only `{id, key, self}`, so demanding the fields echo THERE would be testing a fiction; the
+   *  read-back still has to carry them. */
+  creates?: {
+    readBack: string;
+    echoOn?: 'both' | 'read';
+    /** Where the created object sits in the response, when the vendor wraps it — Slack answers
+     *  `{ok, channel:{…}}` on both the create and the read, so the ECHO beat looks under
+     *  `channel` rather than at the envelope. Defaults to the whole body. */
+    at?: string;
+    /** fields the vendor legitimately transforms or drops */
+    echoExcept?: string[];
+  };
+  /** This write must VISIBLY CHANGE what `GET <changes>` returns (a path, `{capture}` allowed).
+   *  The runner reads that path before and after the step and fails if the answer is unchanged.
+   *
+   *  This is the LANDED beat, and it exists because of the worst defect class this repo has a
+   *  name for: a write that answers the vendor's own success shape and stores nothing. Jira's
+   *  `PUT .../issue/{key}/assignee` answered 204 — correct, per the vendor — while writing an
+   *  empty field set, and the only reason the walk caught it was that a later step happened to
+   *  read the field back. Declared here, every write is asked the question. */
+  changes?: string;
+  /** An OAuth 1.0a signed request (RFC 5849, HMAC-SHA1), as twitter-api-v2 signs X's: the walk builds the
+   *  `Authorization: OAuth …` header over the method, the URL the step sends to (an absolute URL, the vendor's own, is
+   *  what the client signs), its query and a form-encoded body. Each value may carry `{capture}`s; `token` and
+   *  `tokenSecret` are the user's, `callback` the request-token leg's and `verifier` the access-token leg's. */
+  oauth1?: { consumerKey: string; consumerSecret: string; token?: string; tokenSecret?: string; callback?: string; verifier?: string };
+  /** A JWT the client signs itself and sends as `Authorization: Bearer` (a GitHub App's, with the private key its
+   *  registration handed it): RS256 over `claims`, with the PEM `privatePem` names (a `{capture}`); claims may carry
+   *  captures too. */
+  jwt?: { privatePem: string; claims: Record<string, unknown> };
+  /** A SigV4-signed request (an AWS SDK's): the walk adds `authorization` and `x-amz-date` (and S3's payload hash),
+   *  signed over the URL it sends to, its headers and body, at the World clock's instant, with an access key a
+   *  `{capture}` names. */
+  sigv4?: { accessKeyId: string; secretAccessKey: string; region: string; service: string };
+  /** A presigned URL (the step's path) signed again with an access key a `{capture}` names: its date, expiry and scope
+   *  are the URL's, its credential and signature the key's (the kernel's presignSigV4). */
+  presign?: { accessKeyId: string; secretAccessKey: string };
+  /** A real assertion. Return true, or a string saying what was wrong. Hand-written journeys only:
+   *  a derived pack's journeys are data and say what they expect in `expect`. */
+  check?: (res: { status: number; body: unknown }, captured: Captured) => true | string;
+  /** What the answer must hold, as data: the value at a dot path of the body, or of the response header `header`
+   *  names (an answer that is a file, not JSON, says what it is in its Content-Type), equals one given, is one of
+   *  several, or exists (`{capture}` placeholders allowed in `equals`). */
+  expect?: Array<{ path?: string; header?: string; equals?: unknown; oneOf?: unknown[]; members?: unknown[]; exists?: boolean; contains?: string; notContains?: string; matches?: string; shape?: JsonShape }>;
+  /** The pack's named view of the answer the step's `expect` paths read (`answerViews` in the pack's index): an answer
+   *  whose values the wire encodes (a psdb result's rows, base64 values sliced by per-column lengths) is asserted by
+   *  what it holds. Captures read the answer as it came. */
+  view?: string;
+  /** This step sends a vendor's published example, `<operation>#<title>` (scripts/vendor-examples.ts): its answer
+   *  must hold every key path of the example's answer with the same JSON type. */
+  example?: string;
+  /** Caller-chosen values of the example's named placeholders, compared literally; captures may fill them.
+   *  A binding never overrides an earlier capture with a different value. */
+  exampleBindings?: Record<string, string>;
+  /** A key path of the example's answer (or `status`) the twin answers otherwise → why the vendor's example is wrong, or
+   *  why the server the twin models answers otherwise where the vendor's text allows it. */
+  exampleDiffers?: Record<string, string>;
+  /** A published body field this step leaves out (a dot path; `a[].b` in each item) → why: a rendered value naming an
+   *  object the World does not hold (a Git repository behind an integration). Only a field the request schema does not
+   *  require may be left out (scripts/vendor-examples.ts). */
+  unsent?: Record<string, string>;
+  /** answer paths whose value equals something the setup sent without the setup deciding it (a default the vendor applies
+   *  that coincides), each with the reason: `vendor-examples.ts --sweep` does not ask them asserted, and the judge reads the reason */
+  undecided?: Record<string, string>;
+};
+
+export type JsonShape = { type?: string; properties?: Record<string, JsonShape>; required?: string[]; items?: JsonShape; additionalProperties?: boolean; [key: string]: unknown };
+
+function schemaFailures(schema: unknown, path = '$'): string[] {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return [path + ' shape is not an object'];
+  const node = schema as JsonShape;
+  const supported = new Set(['type', 'properties', 'required', 'items', 'additionalProperties', 'title', 'description', '$schema']);
+  const failures = Object.keys(node).filter(key => !supported.has(key)).map(key => path + ' unsupported shape keyword ' + key);
+  if (node.type !== undefined && !['object', 'array', 'string', 'boolean', 'null', 'number', 'integer'].includes(node.type)) failures.push(path + ' unsupported shape type');
+  if (node.required !== undefined && (!Array.isArray(node.required) || node.required.some(key => typeof key !== 'string'))) failures.push(path + ' required is not an array of strings');
+  if (node.additionalProperties !== undefined && typeof node.additionalProperties !== 'boolean') failures.push(path + ' additionalProperties is not boolean');
+  if (node.properties !== undefined) {
+    if (!node.properties || typeof node.properties !== 'object' || Array.isArray(node.properties)) failures.push(path + ' properties is not an object');
+    else for (const [key, child] of Object.entries(node.properties)) failures.push(...schemaFailures(child, path + '.properties.' + key));
+  }
+  if (node.items !== undefined) failures.push(...schemaFailures(node.items, path + '.items'));
+  return failures;
+}
+
+function shapeFailures(value: unknown, schema: JsonShape, path = '$'): string[] {
+  if (value === undefined) return [path + ' value is absent or could not be decoded'];
+  const object = value !== null && typeof value === 'object' && !Array.isArray(value);
+  const typed = schema.type === undefined || schema.type === 'object' && object || schema.type === 'array' && Array.isArray(value) || schema.type === 'string' && typeof value === 'string' || schema.type === 'boolean' && typeof value === 'boolean' || schema.type === 'null' && value === null || schema.type === 'number' && (typeof value === 'number' && Number.isFinite(value) || isExactIntegerValue(value)) || schema.type === 'integer' && isExactIntegerValue(value);
+  if (!typed) return [path + ' does not have shape type ' + schema.type];
+  const failures: string[] = [];
+  if (object) {
+    const row = value as Record<string, unknown>;
+    for (const key of schema.required ?? []) if (!Object.hasOwn(row, key)) failures.push(path + '.' + key + ' is required');
+    for (const [key, child] of Object.entries(schema.properties ?? {})) if (Object.hasOwn(row, key)) failures.push(...shapeFailures(row[key], child, path + '.' + key));
+    if (schema.additionalProperties === false) for (const key of Object.keys(row)) if (!Object.hasOwn(schema.properties ?? {}, key)) failures.push(path + '.' + key + ' is an additional property');
+  }
+  if (Array.isArray(value) && schema.items) value.forEach((item, i) => failures.push(...shapeFailures(item, schema.items!, path + '.' + i)));
+  return failures;
+}
+/** A step's form (`JourneyStep.form`): its listed fields, then its parts. */
+export type JourneyForm = { fields?: string; parts: FormPart[] };
+/** A part of a step's form: a text field and its value, or a file, its bytes as base64, as text (`value`, captures
+ *  filled, sent as UTF-8: a CSV, a script) or a PNG of a stated size (an uncompressed RGB gradient, as heavy as an
+ *  uncompressed export of that size). */
+export type FormPart = { name: string; value: string } | { name: string; filename: string; type?: string; base64?: string; value?: string; png?: { width: number; height: number } };
+
+/** A data journey's expectations against an answer: the failures, empty when all hold. */
+export function expectFailures(expect: NonNullable<JourneyStep['expect']>, body: unknown, captured: Captured, headers: Record<string, string> = {}, wireText?: string): string[] {
+  const out: string[] = [];
+  for (const e0 of expect) {
+    const e = { ...e0, path: e0.header ? `header ${e0.header}` : e0.path ?? '' };
+    // `path: ""` asserted as text is the whole body as it came (an XML answer's document, not its decoded members)
+    const asText = e.path === '' && wireText !== undefined && (typeof e.equals === 'string' || typeof e.contains === 'string' || typeof e.notContains === 'string' || e.matches !== undefined);
+    const v = e0.header ? headers[e0.header.toLowerCase()] : asText ? wireText : captureAt(body, e.path, headers, wireText);
+    if (e.shape !== undefined) {
+      const invalid = schemaFailures(e.shape);
+      out.push(...(invalid.length ? invalid : shapeFailures(v, e.shape)).map(f => (e.path || 'the answer') + ': ' + f));
+    }
+    if (e.exists !== undefined && (v !== undefined && v !== null) !== e.exists) out.push(`${e.path} ${e.exists ? 'is absent' : 'is present'}`);
+    if ('equals' in e) {
+      // captures fill an expected value wherever they sit in it (a list of ids, a nested object)
+      const want = typeof e.equals === 'string' ? fill(e.equals, captured) : e.equals !== undefined && e.equals !== null && typeof e.equals === 'object' ? parseExactJson(fill(JSON.stringify(e.equals), captured)) : e.equals;
+      // a capture is text, so a number the vendor answers equals the capture it was taken as
+      const same = JSON.stringify(v) === JSON.stringify(want) || (typeof v === 'number' && typeof want === 'string' && String(v) === want);
+      if (!same) out.push(`${e.path} is ${JSON.stringify(v)}, not ${JSON.stringify(want)}`);
+    }
+    // `contains`: the value (a page's whole text at path "", a string field) holds the given text, captures filled;
+    // a step that follows a form or link a hosted page shows first checks the page shows it
+    if (e.contains !== undefined) {
+      const want = fill(e.contains, captured);
+      const text = typeof v === 'string' ? v : JSON.stringify(v ?? '');
+      if (!text.includes(want)) out.push(`${e.path || 'the answer'} does not contain ${JSON.stringify(want)}`);
+    }
+    // `notContains`: the value does not hold the text (a list that omits what the caller may not see)
+    if (e.notContains !== undefined) {
+      const unwanted = fill(e.notContains, captured);
+      const text = typeof v === 'string' ? v : JSON.stringify(v ?? '');
+      if (text.includes(unwanted)) out.push(`${e.path || 'the answer'} contains ${JSON.stringify(unwanted)}`);
+    }
+    // `matches`: the value's text matches the regular expression (a key's form, a URL's scheme), captures filled
+    if (e.matches !== undefined) {
+      const text = typeof v === 'string' ? v : JSON.stringify(v ?? '');
+      if (!new RegExp(fill(e.matches, captured)).test(text)) out.push(`${e.path || 'the answer'} is ${JSON.stringify(text).slice(0, 80)}, which does not match /${e.matches}/`);
+    }
+    // `members`: the value is an array holding exactly these, in any order (a Redis SCAN or SMEMBERS, whose order the
+    // vendor does not promise), captures filled wherever they sit in a member (an object's id, as `equals` fills them)
+    if (e.members !== undefined) {
+      const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, canonical(v)])) : value;
+      const want = e.members.map((m) => fillJson(m, captured)).map((m) => JSON.stringify(canonical(m))).sort();
+      const got = Array.isArray(v) ? v.map((m) => JSON.stringify(canonical(m))).sort() : undefined;
+      if (!got || JSON.stringify(got) !== JSON.stringify(want)) out.push(`${e.path} is ${JSON.stringify(v)}, not the members ${JSON.stringify(e.members)} in any order`);
+    }
+    if (e.oneOf) {
+      const allowed = e.oneOf.map((o) => fillJson(o, captured));
+      if (!allowed.some((o) => JSON.stringify(o) === JSON.stringify(v))) out.push(`${e.path} is ${JSON.stringify(v)}, not one of ${JSON.stringify(allowed)}`);
+    }
+  }
+  return out;
+}
+
+/** `text`'s UTF-8 bytes repeated, cut to exactly `bytes` of them: a cut may fall inside a character. */
+function filledBytes(f: { text: string; bytes: number }): Buffer {
+  if (!f.text || !Number.isInteger(f.bytes) || f.bytes < 0) throw new Error('a fill names its text and a whole number of bytes');
+  const unit = Buffer.byteLength(f.text);
+  return Buffer.from(f.text.repeat(Math.ceil(f.bytes / unit))).subarray(0, f.bytes);
+}
+/** A fill inside a body, a string: its cut must land between characters, since a cut character would be sent as
+ *  U+FFFD's three bytes and the body would not be `bytes` long. */
+function filled(f: { text: string; bytes: number }): string {
+  const cut = filledBytes(f);
+  // the byte after the cut is the text's byte at the same place in its repetition: a UTF-8 continuation byte
+  // (10xxxxxx) there means the cut fell inside a character
+  const text = Buffer.from(f.text);
+  if ((text[f.bytes % text.length]! & 0xc0) === 0x80) throw new Error(`a $fill of ${JSON.stringify(f.text)} cut at ${f.bytes} bytes falls inside a character`);
+  return cut.toString('utf8');
+}
+/** `v` with its `{ $fill }` values written out; `v` itself (the same object) when it holds none, so a caller that
+ *  finds a step by identity in the journey it passed (score-pack's sittings, round-trip's positions) still finds it. */
+const expandValue = (v: unknown): unknown => {
+  if (Array.isArray(v)) {
+    const out = v.map(expandValue);
+    return out.some((x, i) => x !== v[i]) ? out : v;
+  }
+  if (v && typeof v === 'object') {
+    const o = v as Record<string, unknown>;
+    if (Object.keys(o).length === 1 && o.$fill && typeof o.$fill === 'object') return filled(o.$fill as { text: string; bytes: number });
+    const out = Object.entries(o).map(([k, x]) => [k, expandValue(x)] as const);
+    return out.some(([k, x]) => x !== o[k]) ? Object.fromEntries(out) : v;
+  }
+  return v;
+};
+/** A journey with its fills written out (a step's `bodyFill`, a `{ $fill }` inside a body): what is sent, signed and
+ *  compared is the whole body, while the file keeps it short. A step with no fill is the journey's own object, and a
+ *  journey with none is returned itself. */
+export function expandFills<J extends { steps: unknown[] }>(journey: J): J {
+  const steps = journey.steps.map((st) => {
+    const step = st as JourneyStep;
+    if (!step || typeof step !== 'object' || !('method' in step)) return st;
+    if (step.bodyFill && (step.body !== undefined || step.bodyBase64 !== undefined || step.form !== undefined)) throw new Error(`${step.name}: a step carries one of body, bodyBase64, bodyFill and form`);
+    const { bodyFill, ...rest } = step;
+    if (bodyFill) return { ...rest, bodyBase64: filledBytes(bodyFill).toString('base64') };
+    const body = step.body === undefined ? undefined : expandValue(step.body);
+    return body === step.body ? step : { ...step, body };
+  });
+  return steps.some((x, i) => x !== journey.steps[i]) ? { ...journey, steps } : journey;
+}
+
+export type Journey = {
+  vendor: string;
+  /** The session that wrote it: a verdict from this session is no verdict (score-pack.ts). */
+  author?: string;
+  /** The host the pack serves this walk on (several packs route by host). */
+  host?: string;
+  /** Headers every step carries — auth, an API version. */
+  headers?: Record<string, string>;
+  /** The instant the story begins, where it is before the World's day one (2026-01-01): an account whose story starts
+   *  while an API it used still made what it no longer makes. Its waits move the clock on from there. */
+  startsAt?: string;
+  /** The World's scenario for a generative pack's turns (a file beside the life, `journeys/<name>.json`, as a World
+   *  loads `handlers/<vendor>.json`): the walk loads it, so the scripted turns and the pack's scenario code are walked. */
+  scenario?: string;
+  /** The packs of the same catalog, by vendor, that the vendor calls as its own behaviour (`ctx.vendorFetch`: a sign-in
+   *  trading a code at its provider): the walk loads each over the walk's own World and root, the vendor's calls reach
+   *  them in process, and a step to an absolute URL a companion's host rules claim is served by it (architecture,
+   *  "Journeys"). */
+  companions?: string[];
+  /** The application's answers to what the vendor asks it (`ctx.ask`, or a `ctx.vendorFetch` URL read of an
+   *  application-held file: an LLM endpoint an agent was configured with, a real-time authorization endpoint): each a
+   *  request it takes (its method, POST by default, and a URL prefix; the request headers it must carry,
+   *  `requestHeaders`) and the answer it gives (its status, its headers and its body), used in order among those that
+   *  take the request; a question none takes is unreachable, as in a sealed World. They are given to this walk's fetch
+   *  alone. `bodyError` returns the headers but fails body consumption, modeling a source disconnect. */
+  application?: Array<{ method?: string; url: string; requestHeaders?: Record<string, string>; status: number; headers?: Record<string, string>; body?: unknown; bodyError?: string }>;
+  /** What this walk is about, in one sentence: read by whoever gets the failure. */
+  about: string;
+  /** What "I don't have that" looks like for this vendor. The ISOLATED beat asks an untouched
+   *  world for an id it never minted and this says whether it was refused. The default is "not
+   *  2xx", which is right for REST; Slack answers HTTP 200 with `{ok:false,error:…}` for every
+   *  refusal, so a pack in that family declares its own or the beat reads a refusal as a hit. */
+  refused?: (res: { status: number; body: unknown }) => boolean;
+  steps: Step[];
+};
+
+export type Step = JourneyStep | WaitStep | LineStep | GitStep | SocketStep | SqlStep | RespStep;
+
+/** A typed request/reply stream step. `resp` is one command or a pipeline of commands, on a named connection.
+ * Captures and expectations see `{ replies, last, error }`; binary arguments use `{ base64 }`.
+ * `read` drains pushes or a blocking command's answer without sending bytes. */
+export type RespStep = {
+  name: string; connection: string; connect?: Record<string, unknown>; resp?: Array<string | { base64: string }> | Array<Array<string | { base64: string }>>; read?: boolean; close?: boolean; pending?: boolean;
+  refused?: string; capture?: Record<string, string>; expect?: JourneyStep['expect']; example?: string; exampleDiffers?: Record<string, string>;
+};
+export const isResp = (step: Step): step is RespStep => 'connection' in step;
+
+/** A step on a byte-stream wire (a line protocol, SMTP): lines sent on a named connection, answered by the
+ *  replies they drew. `connect` opens the connection, with the options the operator started the server with
+ *  (the pack's `create<Name>TwinStream`); its answer is the server's greeting. The answer is the last reply
+ *  (`code`, its `lines`, their `text`) and every reply the step drew (`replies`). */
+export type LineStep = {
+  name: string;
+  on: string;
+  connect?: Record<string, unknown>;
+  send?: string | string[];
+  /** the last reply's code; any below 400 by default */
+  status?: number;
+  capture?: Record<string, string>;
+  expect?: JourneyStep['expect'];
+  /** as a request step's: this step sends a vendor's published example */
+  example?: string;
+  exampleDiffers?: Record<string, string>;
+};
+export const isLine = (step: Step): step is LineStep => 'on' in step;
+
+/** A step on a vendor's socket (the manifest's `sockets`, the kernel's sockets.ts: Discord's Gateway): `open` opens
+ *  a named connection at a path (or an absolute `ws(s)://` url, on that host: a client that dials the vendor's socket
+ *  host itself), `send` sends frames on it (an object as JSON, captures filled), `close` closes it.
+ *  Its answer is every frame the server sent since the connection's last step (`frames`, each parsed from JSON when
+ *  it is JSON), the last of them (`last`), and how the server closed it (`closed`: its `code` and `reason`, or null);
+ *  its status is the close code, or 101 while it is open. */
+export type SocketStep = {
+  name: string;
+  socket: string;
+  open?: string;
+  /** the opening request's own headers (a key the vendor reads at the upgrade: OpenAI Realtime's `Authorization`), filled
+   *  from the captures as a request's are */
+  headers?: Record<string, string>;
+  send?: unknown;
+  close?: boolean;
+  /** 101 (open) by default; a close code when the server is to close it */
+  status?: number;
+  capture?: Record<string, string>;
+  expect?: JourneyStep['expect'];
+};
+export const isSocket = (step: Step): step is SocketStep => 'socket' in step;
+
+/** A step a git client takes on the pack's smart-HTTP plane (packages/twin-standard/src/walk/git-client.ts): `clone` reads `ref`'s tip (HEAD by
+ *  default) — its `sha`, `message` and tree `paths`; `push` commits `files` (a path's content, or null to delete it) on
+ *  `ref`'s tip, or rewrites the tip (`amend`), or deletes the ref (`delete`), and answers the server's report — `unpack`,
+ *  the ref's `result` (`ok`, or the reason it was refused) and the pushed `sha`. `repo` is `owner/name`. */
+export type GitFile = string | null | { mode: '100644' | '100755' | '120000'; content: string } | { mode: '160000'; sha: string };
+export type GitStep = {
+  name: string;
+  git: 'clone' | 'push';
+  repo: string;
+  ref?: string;
+  files?: Record<string, GitFile>;
+  message?: string;
+  author?: string;
+  amend?: boolean;
+  delete?: boolean;
+  headers?: Record<string, string>;
+  /** the HTTP status; 200 by default */
+  status?: number;
+  capture?: Record<string, string>;
+  expect?: JourneyStep['expect'];
+};
+export const isGit = (step: Step): step is GitStep => 'git' in step;
+
+/** Time passing in the story, with no request: the World clock moves on by `wait` (`25m`, `2h`, `3d`), so a
+ *  move the vendor or the clock makes (a container idling out, a code expiring) happens as it would. */
+export type WaitStep = { name: string; wait: string };
+export const isWait = (step: Step): step is WaitStep => 'wait' in step;
+
+/** What an application sends the World's managed database over the database's own wire, not through the vendor's API (a
+ *  pack whose data plane is the World's Postgres, the descriptor's `managedDatabase`): its migrations as its deploy applies
+ *  them and the queries it sends, each on the application's one connection to the walked World's database (world-core
+ *  `databaseSession`), so a transaction it begins stays open into its next steps, as on its own connection. `sql` alone is
+ *  one simple Query (a migration file, a `BEGIN`); with `values` it is one extended-protocol statement, the values bind
+ *  parameters (a client's `query(text, values)`), captures filled in them; the SQL itself is the application's text, sent
+ *  as written. Its answer is the last statement's `{ command, rows }`, each row its
+ *  columns by name in Postgres's text format, which `expect` reads; a refusal fails the step with
+ *  Postgres's SQLSTATE, unless the step names that SQLSTATE as its `refused` (the application's own catch of it), when
+ *  its answer is `{ code, message }`. */
+export type SqlStep = { name: string; sql: string; values?: Array<string | null>; refused?: string; expect?: JourneyStep['expect']; capture?: JourneyStep['capture'] };
+export const isSql = (step: Step): step is SqlStep => 'sql' in step;
+
+/** A wait's length in milliseconds; an unreadable one throws. */
+export function waitMs(wait: string): number {
+  const m = /^(\d+)(s|m|h|d)$/.exec(wait.trim());
+  if (!m) throw new Error(`journey: wait "${wait}" is not a number of s, m, h or d`);
+  return Number(m[1]) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as 's' | 'm' | 'h' | 'd'];
+}
+
+/** Dot-path read that tolerates arrays (`items.0.id`) and missing links. */
+/** What a capture takes from an answer: a dot path into it, or `text:<pattern>` — the first match of a regular expression
+ *  over the answer's text (a page's HTML, a mail's body), its first group if it has one. A value a page shows a person
+ *  (a token shown once, a link) is read off the page this way, never assumed from the twin's sequence. `header:<name>`
+ *  takes a response header, and `header:<name>:<pattern>` the first match in it: a sign-in's session cookie is kept this
+ *  way and sent back on the person's later requests, as their browser does. `sse:<event>:<path>` assembles SSE values,
+ *  and `sse-json:<event>:<path>` decodes the assembled JSON input. */
+export function captureAt(body: unknown, spec: string, headers: Record<string, string> = {}, wireText?: string): unknown {
+  // `next:<path>`: the integer there plus one, as a client computes what it asks for next (a poll's offset: the last
+  // update_id it read plus one)
+  if (spec.startsWith('next:')) {
+    const value = captureAt(body, spec.slice(5), headers, wireText);
+    return (typeof value === 'number' && Number.isSafeInteger(value) || typeof value === 'string' && /^-?\d+$/.test(value)) ? exactInteger(String(BigInt(value) + 1n)) : undefined;
+  }
+  if (spec.startsWith('json:')) {
+    const text = at(body, spec.slice(5));
+    if (typeof text !== 'string') return undefined;
+    try { return parseExactJson(text); } catch { return undefined; }
+  }
+  const sse = /^sse(-json)?:([^:]+):(.+)$/.exec(spec);
+  if (sse) {
+    if (typeof body !== 'string') return undefined;
+    const values: unknown[] = [];
+    for (const frame of body.replace(/\r\n/g, '\n').split(/\n\n+/)) {
+      let event = 'message'; const data: string[] = [];
+      for (const line of frame.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim();
+        if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''));
+      }
+      if (event !== sse[2] || !data.length || data.join('\n').trim() === '[DONE]') continue;
+      let value: unknown;
+      try { value = at(parseExactJson(data.join('\n')), sse[3]!); } catch { return undefined; }
+      if (value !== undefined && value !== null) values.push(value);
+    }
+    if (!values.length) return undefined;
+    const joined = values.every(v => typeof v === 'string') ? values.join('') : values.length === 1 ? values[0] : values;
+    if (!sse[1]) return joined;
+    if (typeof joined !== 'string') return undefined;
+    try { return parseExactJson(joined); } catch { return undefined; }
+  }
+  if (spec.startsWith('header:')) {
+    const [name = '', ...pattern] = spec.slice('header:'.length).split(':');
+    const value = headers[name.toLowerCase()];
+    if (value === undefined || !pattern.length) return value;
+    const m = new RegExp(pattern.join(':')).exec(value);
+    return m ? (m[1] ?? m[0]) : undefined;
+  }
+  if (!spec.startsWith('text:')) return at(body, spec);
+  // a `text:` capture reads the body as it came, when the walk has it (an XML answer's `<UploadId>`)
+  const text = wireText ?? (typeof body === 'string' ? body : JSON.stringify(body ?? ''));
+  const m = new RegExp(spec.slice('text:'.length)).exec(text);
+  return m ? (m[1] ?? m[0]) : undefined;
+}
+
+export function at(body: unknown, path: string): unknown {
+  if (path === '') return body; // the whole answer: a page's text, a bare list
+  const keys = path.startsWith('/') ? path.slice(1).split('/').map((k) => k.replace(/~1/g, '/').replace(/~0/g, '~')) : path.split('.');
+  return keys.reduce<unknown>((v, k) => {
+    if (v === null || v === undefined) return undefined;
+    if (Array.isArray(v)) return v[Number(k)];
+    if (typeof v === 'object') return (v as Record<string, unknown>)[k];
+    return undefined;
+  }, body);
+}
+
+
+/** Substitute `{name}` placeholders from captured values; throws on an unknown name so a typo
+ *  in a journey fails loudly rather than requesting a literal `{oops}`. */
+export function fill(template: string, captured: Captured, graphqlDocument = false): string {
+  // `{basic:user:password}` is HTTP Basic credentials (RFC 7617) from two captures: `Basic ` and the base64 of
+  // `user:password`, as a client sends a username and password it was issued (a PlanetScale password's)
+  const basic = template.replace(/\{basic:([A-Za-z0-9_.]+):([A-Za-z0-9_.]+)\}/g, (_, u: string, pw: string) => {
+    for (const k of [u, pw]) if (captured[k] === undefined) throw new Error(`journey: step refers to {${k}}, which no earlier step captured`);
+    return `Basic ${Buffer.from(`${captured[u]}:${captured[pw]}`).toString('base64')}`;
+  });
+  // `{encoded:name}` is a capture percent-encoded (encodeURIComponent), as a URL's path segment or query value or a form
+  // field carries it: a URN a vendor's page prints encoded in its paths (LinkedIn's /rest/posts/urn%3Ali%3Ashare%3A…), a
+  // sign-in's return path holding `&` that a browser posts back
+  const encoded = basic.replace(/\{encoded:([A-Za-z0-9_.]+)\}/g, (_, k: string) => {
+    if (captured[k] === undefined) throw new Error(`journey: step refers to {${k}}, which no earlier step captured`);
+    return encodeURIComponent(captured[k]!);
+  });
+  const selections = new Set<number>();
+  // Only request query documents opt into GraphQL grammar (their selection sets, found in the text the captures fill,
+  // which `{basic:…}` and `{encoded:…}` have already filled); variables remain ordinary captured JSON data.
+  if (graphqlDocument && !Object.hasOwn(captured, /^\{([A-Za-z_][A-Za-z0-9_.]*)\}$/.exec(encoded)?.[1] ?? '')) {
+    try { visit(parse(encoded), { SelectionSet(node) { if (node.loc) selections.add(node.loc.start); } }); } catch { /* invalid documents still reach the vendor's own syntax error */ }
+  }
+  // a doubled brace is the vendor's own template syntax ({{sample.output_text}} in an OpenAI grader), not a capture; a
+  // capture's name starts with a letter, so a pattern's count (`[A-Za-z0-9]{40}` in an expectation) is no capture
+  return encoded.replace(/\{\{[^{}]*\}\}|\{([A-Za-z_][A-Za-z0-9_.]*)\}/g, (m, key: string | undefined, offset: number) => {
+    if (selections.has(offset)) return m;
+    if (key === undefined) return m;
+    const v = captured[key];
+    // an UPPER_SNAKE name no step captured is the vendor's own placeholder ({CHECKOUT_SESSION_ID} in a
+    // Stripe success_url), filled by the vendor, not by the journey
+    if (v === undefined && /^[A-Z][A-Z0-9_]*$/.test(key)) return m;
+    if (v === undefined) throw new Error(`journey: step refers to {${key}}, which no earlier step captured`);
+    return v;
+  });
+}
+
+/** A step's `form` as the bytes a browser or an SDK's form encoder sends (RFC 7578), behind one fixed boundary so a
+ *  walk sends the same bytes each time; its fields and text values filled from the captures. */
+export function formBody(form: JourneyForm, captured: Captured): { contentType: string; bytes: Uint8Array<ArrayBuffer> } {
+  const boundary = '----volterJourneyForm7MA4YWxkTrZu0gW';
+  const listed = form.fields === undefined ? [] : (parseExactJson(fill(form.fields, captured)) as Array<{ name: string; value: string }>);
+  const chunks: Uint8Array[] = [];
+  const text = (s: string): void => { chunks.push(new TextEncoder().encode(s)); };
+  // a name or filename in a part's header escaped as a browser escapes it (the HTML standard's multipart/form-data
+  // encoding: `"` as %22, CR as %0D, LF as %0A), so a captured name never breaks the part
+  const quoted = (v: string): string => v.replace(/"/g, '%22').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+  for (const f of listed) text(`--${boundary}\r\nContent-Disposition: form-data; name="${quoted(f.name)}"\r\n\r\n${f.value}\r\n`);
+  for (const p of form.parts) {
+    if (!('filename' in p)) { text(`--${boundary}\r\nContent-Disposition: form-data; name="${quoted(p.name)}"\r\n\r\n${fill(p.value, captured)}\r\n`); continue; }
+    text(`--${boundary}\r\nContent-Disposition: form-data; name="${quoted(p.name)}"; filename="${quoted(p.filename)}"\r\n${p.type ? `Content-Type: ${p.type.replace(/[\r\n]/g, '')}\r\n` : ''}\r\n`);
+    chunks.push(p.png ? gradientPng(p.png.width, p.png.height) : p.value !== undefined ? new TextEncoder().encode(fill(p.value, captured)) : Uint8Array.from(Buffer.from(p.base64 ?? '', 'base64')));
+    text('\r\n');
+  }
+  text(`--${boundary}--\r\n`);
+  const bytes = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+  let at = 0;
+  for (const c of chunks) { bytes.set(c, at); at += c.length; }
+  return { contentType: `multipart/form-data; boundary=${boundary}`, bytes };
+}
+
+/** A real PNG (8-bit RGB) of `width` × `height`, a gradient over the image, its rows stored uncompressed (zlib's stored
+ *  blocks, RFC 1950/1951): the bytes an export without compression is, for a step that sends an image of a given weight. */
+export function gradientPng(width: number, height: number): Uint8Array {
+  const crcTable = Array.from({ length: 256 }, (_, n) => { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; return c >>> 0; });
+  const crc = (b: Uint8Array): number => { let c = 0xffffffff; for (const x of b) c = crcTable[(c ^ x) & 0xff]! ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+  const chunk = (type: string, data: Uint8Array): Uint8Array => {
+    const out = new Uint8Array(12 + data.length);
+    const v = new DataView(out.buffer);
+    v.setUint32(0, data.length);
+    out.set([...type].map((c) => c.charCodeAt(0)), 4);
+    out.set(data, 8);
+    v.setUint32(8 + data.length, crc(out.subarray(4, 8 + data.length)));
+    return out;
+  };
+  const row = 1 + width * 3;
+  const raw = new Uint8Array(row * height);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    const at = y * row + 1 + x * 3;
+    raw[at] = Math.floor((x * 255) / Math.max(1, width - 1)); raw[at + 1] = Math.floor((y * 255) / Math.max(1, height - 1)); raw[at + 2] = 128;
+  }
+  const blocks = Math.max(1, Math.ceil(raw.length / 65535));
+  const z = new Uint8Array(2 + raw.length + blocks * 5 + 4);
+  z[0] = 0x78; z[1] = 0x01;
+  let o = 2;
+  for (let i = 0; i < blocks; i++) {
+    const part = raw.subarray(i * 65535, Math.min(raw.length, (i + 1) * 65535));
+    z[o++] = i === blocks - 1 ? 1 : 0; z[o++] = part.length & 0xff; z[o++] = part.length >> 8; z[o++] = ~part.length & 0xff; z[o++] = (~part.length >> 8) & 0xff;
+    z.set(part, o); o += part.length;
+  }
+  let a = 1; let b = 0;
+  for (const byte of raw) { a = (a + byte) % 65521; b = (b + a) % 65521; }
+  new DataView(z.buffer).setUint32(o, ((b << 16) | a) >>> 0);
+  const ihdr = new Uint8Array(13);
+  new DataView(ihdr.buffer).setUint32(0, width); new DataView(ihdr.buffer).setUint32(4, height);
+  ihdr.set([8, 2, 0, 0, 0], 8);
+  const parts = [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk('IHDR', ihdr), chunk('IDAT', z), chunk('IEND', new Uint8Array())];
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}
+
+/** Build JSON values before serialization: captured text is data, including quotes and braces, not JSON source. */
+export function fillJson(value: unknown, captured: Captured, typed: Record<string, unknown> = {}, graphqlBody = false): unknown {
+  if (typeof value === 'string') {
+    const exact = /^\{([A-Za-z0-9_.]+)\}$/.exec(value);
+    if (exact && Object.hasOwn(typed, exact[1]!)) return typed[exact[1]!];
+    return fill(value, captured);
+  }
+  if (Array.isArray(value)) return value.map((item) => fillJson(item, captured, typed));
+  if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [fill(key, captured), graphqlBody && key === 'query' && typeof item === 'string' ? fill(item, captured, true) : fillJson(item, captured, typed)]));
+  return value;
+}
+
+/** The ECHO beat, as a pure function so its rule is testable on its own. Every scalar and every
+ *  array of scalars the request sent must appear in the response. An object-valued field is
+ *  compared field by field. A field the vendor is KNOWN to transform is named in `echoExcept`;
+ *  anything else that vanishes is the defect this beat exists to find. */
+export function echoFailures(sent: unknown, got: unknown, except: string[] = [], prefix = ''): string[] {
+  if (sent === null || typeof sent !== 'object' || Array.isArray(sent)) return [];
+  const out: string[] = [];
+  for (const [k, v] of Object.entries(sent as Record<string, unknown>)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (except.includes(key) || v === undefined || v === null) continue;
+    const actual = at(got, key);
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) { out.push(...echoFailures(v, got, except, key)); continue; }
+    if (Array.isArray(v)) {
+      // an array of scalars must come back with the same members, in any shape the vendor wraps
+      // them in: github returns labels as [{name}], stripe returns them verbatim
+      const flat = flatten(actual);
+      for (const member of v) {
+        if (member === null || typeof member === 'object') continue; // nested objects: not this beat's job
+        if (!flat.includes(String(member))) out.push(`sent ${key} containing ${JSON.stringify(member)}, and it is not in the response (${JSON.stringify(actual)})`);
+      }
+      continue;
+    }
+    if (actual === undefined) { out.push(`sent ${key}=${JSON.stringify(v)}, and the response has no ${key}`); continue; }
+    // A vendor may EXPAND a scalar reference into the object it names — GitHub takes `head:
+    // "my-branch"` and answers `head: {label, ref, sha}`. That is the vendor being faithful, not
+    // dropping the field, so a scalar is satisfied by appearing anywhere inside the expansion.
+    if (actual !== null && typeof actual === 'object') {
+      if (!flatten(actual).includes(String(v))) out.push(`sent ${key}=${JSON.stringify(v)}, and the response expands ${key} into ${JSON.stringify(actual)}, which does not mention it`);
+      continue;
+    }
+    if (String(actual) !== String(v)) out.push(`sent ${key}=${JSON.stringify(v)}, and the response says ${JSON.stringify(actual)}`);
+  }
+  return out;
+}
+
+/** Every scalar anywhere inside a value, as strings — so `[{name:'bug'}]` answers for `'bug'`. */
+function flatten(v: unknown): string[] {
+  if (v === null || v === undefined) return [];
+  if (Array.isArray(v)) return v.flatMap(flatten);
+  if (typeof v === 'object') return Object.values(v as Record<string, unknown>).flatMap(flatten);
+  return [String(v)];
+}
+
+// ── COVERAGE ────────────────────────────────────────────────────────────────────────────────
+// "Did the walk exercise every state?" is the completeness question a journey has to answer,
+// and its unit is the pack's STATE-SIMULATION MODULE: the sources under `src/` that write the
+// world's state (they call `applyTwinWrite`), minus pull and push (`-connector`),
+// which are the reconciler's business and not a story's. That set is DERIVED, per pack, never
+// hand-listed — github's is `github-twin.ts` and `github-git-http.ts`; the second stays at 0%
+// for a story that never speaks git-over-http, and that is a true sentence about the story.
+//
+// The measure is line and function coverage of those files WHILE THE STORY RUNS. Lines, not
+// the names of the transitions the walk emitted: a state bug lives inside a transition, in the
+// branch that only runs when the thing was already closed — github's timeline forgot `closed`
+// and `reopened` while every transition NAME was emitted — and only line coverage can see that
+// branch. A never-run range is reported with the function it sits in, so the reader gets "the
+// story never took the reopen branch of updateIssue", not a line number.
+//
+// Read it as "what has this story never done", never as a score to raise: a line running
+// proves it was reached, not that what it did was right. Right is what the beats and the
+// checks are for.
+
+/** The state-simulation module of a pack, as repo-relative paths. */
+export function stateModuleFiles(vendor: string, twinDir: string, fs: { readdirSync: (d: string) => string[]; readFileSync: (p: string, e: 'utf8') => string }): string[] {
+  const dir = `${twinDir}/${vendor}/src`;
+  const out: string[] = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    if (!f.endsWith('.ts') || f.endsWith('.test.ts') || f.endsWith('.uitest.ts') || f.includes('-connector')) continue;
+    if (/\bapplyTwinWrite(Atomic)?\(/.test(fs.readFileSync(`${dir}/${f}`, 'utf8'))) out.push(`${vendor}/src/${f}`);
+  }
+  return out;
+}
+
+export type StateCoverage = {
+  file: string;
+  lines: { found: number; hit: number };
+  functions: { found: number; hit: number };
+  /** Never-run line ranges, each with the declaration it sits under (nearest preceding
+   *  function, arrow or method in the source), so a gap reads as "the reopen branch of
+   *  updateIssue" and not as a line number. */
+  never: Array<{ from: number; to: number; fn?: string }>;
+  /** The declarations that ran: those whose first line ran (a never-run function reads 0 there). With a never-run
+   *  range inside, such a declaration ran in part. */
+  ran?: string[];
+};
+
+/** Where functions live in a TypeScript source — `function name(`, `const name = (…) =>`,
+ *  `const name = async (`, `  name(args) {` methods — at any depth, each with the line its
+ *  block ENDS on: the first later non-blank line indented no deeper than the declaration (that
+ *  line is the closer when it opens with `}`, `)` or `]`, and is included; a `)` that goes on to
+ *  open a block is a multi-line parameter list and the scan continues). A one-line arrow
+ *  spans one line. The declaration a line sits under is the innermost span containing it —
+ *  which is what makes the names honest in a file whose handlers declare small helpers
+ *  inline: a never-run branch at the bottom of `applyRepoWrite` is reported under
+ *  `applyRepoWrite`, not under the one-line `commentExists` declared above it. */
+export function functionIndex(source: string): Array<{ line: number; end: number; name: string }> {
+  const lines = source.split('\n');
+  const indentOf = (t: string): number => t.length - t.trimStart().length;
+  const out: Array<{ line: number; end: number; name: string }> = [];
+  lines.forEach((text, i) => {
+    const m =
+      /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)\s*[<(]/.exec(text) ??
+      /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::\s*[^=]+)?=>/.exec(text) ??
+      /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s+)?function\b/.exec(text) ??
+      /^\s+(?:public\s+|private\s+|protected\s+|static\s+)*(?:async\s+)?([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?::\s*[^{]+)?\{\s*$/.exec(text);
+    if (!m || ['if', 'for', 'while', 'switch', 'catch', 'return', 'function', 'constructor'].includes(m[1]!)) return;
+    const indent = indentOf(text);
+    let end = i;
+    for (let j = i + 1; j < lines.length; j++) {
+      const t = lines[j]!;
+      if (t.trim() === '') continue;
+      if (indentOf(t) <= indent) {
+        // a `)` that goes on to open a block (`): Foo {`) is the end of a multi-line parameter
+        // list, still inside the declaration; a bare closer ends the span and is part of it
+        if (/^\s*[})\]]/.test(t) && /\{\s*$/.test(t)) { end = j; continue; }
+        end = /^\s*[})\]]/.test(t) ? j : end;
+        break;
+      }
+      end = j;
+    }
+    out.push({ line: i + 1, end: end + 1, name: m[1]! });
+  });
+  return out;
+}
+
+/** Read an lcov report (bun's `--coverage-reporter=lcov`) for exactly `files`, matched by
+ *  path suffix so an absolute or a cwd-relative `SF:` both resolve. Function totals come from
+ *  the report (`FNF`/`FNH`); names for never-run ranges come from `FN` records when the
+ *  producer writes them and otherwise from the source (`readSource`), since bun writes none.
+ *  A file the report does not mention was never loaded by the walk: it is reported at 0 of
+ *  0, which is its own finding (the story never reached that module at all). */
+export function stateCoverage(lcov: string, files: string[], readSource: (file: string) => string | undefined = () => undefined): StateCoverage[] {
+  type Rec = { fns: Array<{ line: number; name: string }>; hits: Map<number, number>; fnf?: number; fnh?: number };
+  const records = new Map<string, Rec>();
+  let current: Rec | undefined;
+  for (const raw of lcov.split('\n')) {
+    const line = raw.trim();
+    if (line.startsWith('SF:')) { current = { fns: [], hits: new Map() }; records.set(line.slice(3), current); continue; }
+    if (!current) continue;
+    if (line.startsWith('FN:')) { const [l, ...name] = line.slice(3).split(','); current.fns.push({ line: Number(l), name: name.join(',') }); continue; }
+    if (line.startsWith('FNF:')) { current.fnf = Number(line.slice(4)); continue; }
+    if (line.startsWith('FNH:')) { current.fnh = Number(line.slice(4)); continue; }
+    if (line.startsWith('DA:')) { const [l, c] = line.slice(3).split(','); current.hits.set(Number(l), Number(c)); continue; }
+    if (line === 'end_of_record') current = undefined;
+  }
+  return files.map((file) => {
+    const key = [...records.keys()].find((k) => k === file || k.endsWith(`/${file}`));
+    const rec = key ? records.get(key)! : undefined;
+    if (!rec) return { file, lines: { found: 0, hit: 0 }, functions: { found: 0, hit: 0 }, never: [] };
+    const lines = [...rec.hits.entries()].sort((a, b) => a[0] - b[0]);
+    const source = rec.fns.length === 0 ? readSource(file) : undefined;
+    const index: Array<{ line: number; end: number; name: string }> = rec.fns.length > 0
+      ? rec.fns.map((f) => ({ ...f, end: Number.MAX_SAFE_INTEGER }))
+      : source !== undefined ? functionIndex(source) : [];
+    // innermost span containing the line: the latest start among spans that still contain it
+    const enclosing = (l: number): string | undefined => { let name: string | undefined; for (const f of index) { if (f.line > l) break; if (l <= f.end) name = f.name; } return name || undefined; };
+    const never: StateCoverage['never'] = [];
+    // whether a declaration ran (life-coverage.ts's header): bun reads a never-run `function`'s first line 0, but a
+    // `const f = (…) =>` line runs when the module loads, and the last line of a block that never ran can read as run
+    // once; so a declaration ran when it is a `function` whose first line ran, or when a line of its body before its
+    // last one ran
+    const sourceLines = (source ?? readSource(file) ?? '').split('\n');
+    const ran = new Set(index.filter((f) => {
+      if (/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\b/.test(sourceLines[f.line - 1] ?? '') && (rec.hits.get(f.line) ?? 0) > 0) return true;
+      const body = [...rec.hits.entries()].filter(([l]) => l > f.line && l <= f.end).sort((x, y) => x[0] - y[0]);
+      return body.slice(0, -1).some(([, c]) => c > 0);
+    }).map((f) => f.name));
+    for (const [l, c] of lines) {
+      if (c > 0) continue;
+      const last = never[never.length - 1];
+      if (last && last.to === l - 1 && last.fn === enclosing(l)) last.to = l; else never.push({ from: l, to: l, fn: enclosing(l) });
+    }
+    return {
+      file,
+      lines: { found: lines.length, hit: lines.filter(([, c]) => c > 0).length },
+      functions: { found: rec.fnf ?? rec.fns.length, hit: rec.fnh ?? 0 },
+      never,
+      ran: [...ran].sort(),
+    };
+  });
+}
+
+/** A client asking whether something exists before it makes it (a CLI's `get` answering 404, then its create): the 404
+ *  is the answer it branches on, not a refusal. A GET answering 404 is that probe when a later successful write of the
+ *  same sitting makes its subject: at the same path, or at its collection naming the subject exactly (a query value, or
+ *  a top-level string of its JSON body). */
+export function existenceProbe(walked: Array<{ method: string; path: string; body: string; status: number; refused: boolean; sitting: number }>, n: number): boolean {
+  const w = walked[n]!;
+  if (w.method !== 'GET' || w.status !== 404) return false;
+  const base = (p: string): string => p.split(/[?\s[]/)[0]!.replace(/\/$/, '');
+  const at = base(w.path);
+  const name = decodeURIComponent(at.split('/').pop() ?? '');
+  const parent = at.slice(0, at.lastIndexOf('/'));
+  const names = (x: { path: string; body: string }): string[] => {
+    const query = /\?([^\s[]*)/.exec(x.path)?.[1] ?? '';
+    const out = [...new URLSearchParams(query).values()];
+    try { const b = parseExactJson(x.body); if (b && typeof b === 'object' && !Array.isArray(b)) for (const v of Object.values(b)) if (typeof v === 'string') out.push(v); } catch { /* not JSON */ }
+    return out;
+  };
+  return walked.slice(n + 1).some((x) => x.sitting === w.sitting && !x.refused && /^(POST|PUT)$/.test(x.method)
+    && (base(x.path) === at || (base(x.path) === parent && names(x).includes(name))));
+}
+
+/** The `Authorization` header an OAuth 1.0a client sends (RFC 5849 §3.5.1), signed over the request (§3.4): its protocol
+ *  parameters, the URL's query and a form-encoded body. The nonce and timestamp are drawn from the request itself and
+ *  the instant given, so a walk sends the same bytes each time. */
+export function oauth1Authorization(o: NonNullable<JourneyStep['oauth1']>, method: string, url: string, body: string | undefined, contentType: string | undefined, at: number): string {
+  const u = new URL(url);
+  const protocol: Array<[string, string]> = [
+    ['oauth_consumer_key', o.consumerKey],
+    ['oauth_nonce', digest('sha256', `${method} ${url} ${body ?? ''} ${at}`).slice(0, 32)],
+    ['oauth_signature_method', 'HMAC-SHA1'],
+    ['oauth_timestamp', String(Math.floor(at / 1000))],
+    ...(o.token ? [['oauth_token', o.token] as [string, string]] : []),
+    ...(o.callback ? [['oauth_callback', o.callback] as [string, string]] : []),
+    ...(o.verifier ? [['oauth_verifier', o.verifier] as [string, string]] : []),
+    ['oauth_version', '1.0'],
+  ];
+  const query = [...u.searchParams] as Array<[string, string]>;
+  const form = body !== undefined && /application\/x-www-form-urlencoded/i.test(contentType ?? '') ? ([...new URLSearchParams(body)] as Array<[string, string]>) : [];
+  const base = oauth1BaseString(method, `${u.protocol}//${u.host.toLowerCase()}${u.pathname}`, [...protocol, ...query, ...form]);
+  const signed = [...protocol, ['oauth_signature', oauth1Signature(base, o.consumerSecret, o.tokenSecret ?? '')] as [string, string]];
+  return `OAuth ${signed.map(([k, v]) => `${oauth1Encode(k)}="${oauth1Encode(v)}"`).join(', ')}`;
+}
+
+/** The `Authorization` header of a step's own JWT (`jwt`): RS256 with the PEM it names, over its claims, captures filled.
+ *  A PEM is filled as text (its line breaks would not survive a JSON round trip); the claims through JSON, so a claim
+ *  that is exactly one capture of a number stays a number. */
+export function jwtAuthorization(o: NonNullable<JourneyStep['jwt']>, captured: Captured): string {
+  const claims = parseExactJson(fill(JSON.stringify(o.claims), captured)) as Record<string, unknown>;
+  const wallNow = Math.floor(Date.now() / 1000);
+  const now = typeof claims.iat === 'number' || isExactIntegerValue(claims.iat) ? claims.iat as number | string : wallNow;
+  // Supply defaults as claims, so an exact NumericDate also governs nbf and the default expiry.
+  const exp = typeof now === 'string' ? exactInteger(String(BigInt(now) + 60n)) : now + 60;
+  return `Bearer ${jwtSign({ iat: now, nbf: now, exp, ...claims }, { alg: 'RS256', privatePem: fill(o.privatePem, captured) }, { now: wallNow })}`;
+}
+
+/** The headers of a step's SigV4 signature (`sigv4`), captures filled, over the URL, headers and body it sends. */
+export function sigv4Headers(o: NonNullable<JourneyStep['sigv4']>, captured: Captured, method: string, url: string, headers: Record<string, string>, body: string | Uint8Array | undefined, at: number): Record<string, string> {
+  const f = parseExactJson(fill(JSON.stringify(o), captured)) as NonNullable<JourneyStep['sigv4']>;
+  return signSigV4({ method, url, headers, ...(body !== undefined ? { body } : {}), keyId: f.accessKeyId, secret: f.secretAccessKey, region: f.region, service: f.service, at: new Date(at) });
+}
+
+/** A step's presigned path (`presign`) signed with its key, captures filled: a header the URL names among its signed
+ *  ones is signed with the value the step sends (its `headers`), as the client that presigned it bound it. */
+export function presignedPath(o: NonNullable<JourneyStep['presign']>, captured: Captured, method: string, path: string, host: string, headers: Record<string, string> = {}): string {
+  const f = parseExactJson(fill(JSON.stringify(o), captured)) as NonNullable<JourneyStep['presign']>;
+  const absolute = /^https?:\/\//.test(path);
+  const signed = presignSigV4({ method, url: absolute ? path : `http://${host}${path}`, keyId: f.accessKeyId, secret: f.secretAccessKey, headers });
+  return absolute ? signed : signed.replace(/^https?:\/\/[^/]+/, '');
+}