@volter/twin-standard 1.0.29 → 1.0.31

package/dist/src/walk/journey-kit.js

@@ -0,0 +1,743 @@
+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';
+function schemaFailures(schema, path = '$') {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema))
+        return [path + ' shape is not an object'];
+    const node = schema;
+    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, schema, path = '$') {
+    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 = [];
+    if (object) {
+        const row = value;
+        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 data journey's expectations against an answer: the failures, empty when all hold. */
+export function expectFailures(expect, body, captured, headers = {}, wireText) {
+    const out = [];
+    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) => 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) {
+    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) {
+    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) => {
+    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;
+        if (Object.keys(o).length === 1 && o.$fill && typeof o.$fill === 'object')
+            return filled(o.$fill);
+        const out = Object.entries(o).map(([k, x]) => [k, expandValue(x)]);
+        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(journey) {
+    const steps = journey.steps.map((st) => {
+        const step = st;
+        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 const isResp = (step) => 'connection' in step;
+export const isLine = (step) => 'on' in step;
+export const isSocket = (step) => 'socket' in step;
+export const isGit = (step) => 'git' in step;
+export const isWait = (step) => 'wait' in step;
+export const isSql = (step) => 'sql' in step;
+/** A wait's length in milliseconds; an unreadable one throws. */
+export function waitMs(wait) {
+    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]];
+}
+/** 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, spec, headers = {}, wireText) {
+    // `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 = [];
+        for (const frame of body.replace(/\r\n/g, '\n').split(/\n\n+/)) {
+            let event = 'message';
+            const data = [];
+            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;
+            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, path) {
+    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((v, k) => {
+        if (v === null || v === undefined)
+            return undefined;
+        if (Array.isArray(v))
+            return v[Number(k)];
+        if (typeof v === 'object')
+            return v[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, captured, graphqlDocument = false) {
+    // `{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, pw) => {
+        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) => {
+        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();
+    // 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, offset) => {
+        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, captured) {
+    const boundary = '----volterJourneyForm7MA4YWxkTrZu0gW';
+    const listed = form.fields === undefined ? [] : parseExactJson(fill(form.fields, captured));
+    const chunks = [];
+    const text = (s) => { 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) => 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, height) {
+    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) => { let c = 0xffffffff; for (const x of b)
+        c = crcTable[(c ^ x) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+    const chunk = (type, data) => {
+        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, captured, typed = {}, graphqlBody = false) {
+    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, got, except = [], prefix = '') {
+    if (sent === null || typeof sent !== 'object' || Array.isArray(sent))
+        return [];
+    const out = [];
+    for (const [k, v] of Object.entries(sent)) {
+        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) {
+    if (v === null || v === undefined)
+        return [];
+    if (Array.isArray(v))
+        return v.flatMap(flatten);
+    if (typeof v === 'object')
+        return Object.values(v).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, twinDir, fs) {
+    const dir = `${twinDir}/${vendor}/src`;
+    const out = [];
+    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;
+}
+/** 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) {
+    const lines = source.split('\n');
+    const indentOf = (t) => t.length - t.trimStart().length;
+    const out = [];
+    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, files, readSource = () => undefined) {
+    const records = new Map();
+    let current;
+    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 = 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) => { let name; for (const f of index) {
+            if (f.line > l)
+                break;
+            if (l <= f.end)
+                name = f.name;
+        } return name || undefined; };
+        const 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, n) {
+    const w = walked[n];
+    if (w.method !== 'GET' || w.status !== 404)
+        return false;
+    const base = (p) => 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) => {
+        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, method, url, body, contentType, at) {
+    const u = new URL(url);
+    const protocol = [
+        ['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]] : []),
+        ...(o.callback ? [['oauth_callback', o.callback]] : []),
+        ...(o.verifier ? [['oauth_verifier', o.verifier]] : []),
+        ['oauth_version', '1.0'],
+    ];
+    const query = [...u.searchParams];
+    const form = body !== undefined && /application\/x-www-form-urlencoded/i.test(contentType ?? '') ? [...new URLSearchParams(body)] : [];
+    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 ?? '')]];
+    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, captured) {
+    const claims = parseExactJson(fill(JSON.stringify(o.claims), captured));
+    const wallNow = Math.floor(Date.now() / 1000);
+    const now = typeof claims.iat === 'number' || isExactIntegerValue(claims.iat) ? claims.iat : 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, captured, method, url, headers, body, at) {
+    const f = parseExactJson(fill(JSON.stringify(o), captured));
+    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, captured, method, path, host, headers = {}) {
+    const f = parseExactJson(fill(JSON.stringify(o), captured));
+    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?:\/\/[^/]+/, '');
+}