@volter/twin-standard 1.0.30 → 1.0.32

package/dist/src/walk/git-client.d.ts

@@ -0,0 +1,26 @@
+import type { GitFile } from './journey-kit.js';
+type Fetch = (request: Request) => Promise<Response>;
+export type GitAnswer = {
+    status: number;
+    body: unknown;
+    text: string;
+};
+/** `git clone`: the ref's tip (HEAD by default) and the paths of its tree. */
+export declare function gitClone(fetch: Fetch, base: string, step: {
+    ref?: string;
+}, headers: Record<string, string>): Promise<GitAnswer>;
+export type GitPush = {
+    ref: string;
+    /** a path's new content, or null to delete it */
+    files?: Record<string, GitFile>;
+    message?: string;
+    author?: string;
+    /** rewrite the tip instead of building on it (`git commit --amend`), which only a force push lands */
+    amend?: boolean;
+    /** delete the ref (`git push origin :<ref>`) */
+    delete?: boolean;
+};
+/** `git push`: a commit of `files` on the ref's tip (a new ref starts from HEAD's), sent with the pack of what it made.
+ *  The answer is the server's report: `unpack`, the ref's `result` (`ok`, or its `ng` reason) and the pushed `sha`. */
+export declare function gitPush(fetch: Fetch, base: string, step: GitPush, headers: Record<string, string>): Promise<GitAnswer>;
+export {};

package/dist/src/walk/git-client.js

@@ -0,0 +1,139 @@
+// The git client a journey's git steps are: what `git clone` and `git push` send over smart HTTP (protocol v0),
+// built on the kernel's git library, so a life reaches a pack's git plane with a client's own bytes. It keeps no
+// working copy between steps: a push fetches the ref's tip as a clone would have, writes its files on top and
+// sends the ref command with a pack of what it made.
+import { MemoryBlobStore, git } from '@volter/world-core/runtime';
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+const cat = (...parts) => git.concat(...parts);
+/** The refs a smart-HTTP advertisement names, and the World's date the server answered at. */
+async function advertised(fetch, base, service, headers) {
+    const res = await fetch(new Request(`${base}/info/refs?service=${service}`, { headers }));
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const refs = new Map();
+    if (res.status !== 200)
+        return { status: res.status, refs, date: 0, text: DEC.decode(bytes) };
+    const first = git.readPktLines(bytes);
+    for (const line of git.readPktLines(first.rest).lines) {
+        const [sha, name] = line.split('\0')[0].trim().split(' ');
+        if (sha && name && sha !== git.ZERO_SHA)
+            refs.set(name, sha);
+    }
+    return { status: res.status, refs, date: Date.parse(res.headers.get('date') ?? '') || 0, text: '' };
+}
+/** Fetch `sha` and everything it reaches into `store`, as upload-pack sends it. */
+async function fetchInto(fetch, base, sha, store, headers) {
+    const body = cat(git.pktLine(`want ${sha} ofs-delta no-progress\n`), git.FLUSH, git.pktLine('done\n'));
+    const res = await fetch(new Request(`${base}/git-upload-pack`, { method: 'POST', headers: { ...headers, 'content-type': 'application/x-git-upload-pack-request' }, body: body }));
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const nak = git.readPktLines(bytes.subarray(0, 8));
+    if (!nak.lines[0]?.startsWith('NAK'))
+        throw new Error(`upload-pack answered ${DEC.decode(bytes.subarray(0, 120)).trim()}`);
+    await git.readPack(bytes.subarray(8), store);
+}
+/** Every file under `tree`, by path. */
+async function flatten(store, tree, prefix = '', out = new Map()) {
+    const obj = await store.read(tree);
+    for (const e of obj ? git.decodeTree(obj.payload) : []) {
+        if (e.mode === '40000')
+            await flatten(store, e.sha, `${prefix}${e.name}/`, out);
+        else
+            out.set(`${prefix}${e.name}`, { mode: e.mode, sha: e.sha });
+    }
+    return out;
+}
+/** The tree of `files`, nested by directory; each object it writes is pushed onto `made`. */
+async function build(store, files, made) {
+    const here = [];
+    const dirs = new Map();
+    for (const [path, e] of files) {
+        const slash = path.indexOf('/');
+        if (slash < 0) {
+            here.push({ mode: e.mode, name: path, sha: e.sha });
+            continue;
+        }
+        const dir = path.slice(0, slash);
+        if (!dirs.has(dir))
+            dirs.set(dir, new Map());
+        dirs.get(dir).set(path.slice(slash + 1), e);
+    }
+    for (const [dir, inner] of dirs)
+        here.push({ mode: '40000', name: dir, sha: await build(store, inner, made) });
+    const sha = await store.write('tree', git.encodeTree(git.sortTreeEntries(here)));
+    made.push(sha);
+    return sha;
+}
+/** `git clone`: the ref's tip (HEAD by default) and the paths of its tree. */
+export async function gitClone(fetch, base, step, headers) {
+    const ad = await advertised(fetch, base, 'git-upload-pack', headers);
+    if (ad.status !== 200)
+        return { status: ad.status, body: ad.text, text: ad.text };
+    const ref = step.ref ?? 'HEAD';
+    const sha = ad.refs.get(ref);
+    if (!sha) {
+        const text = `fatal: Remote branch ${ref} not found in upstream origin`;
+        return { status: 404, body: text, text };
+    }
+    const store = new git.GitObjectStore(new MemoryBlobStore(), 'clone');
+    await fetchInto(fetch, base, sha, store, headers);
+    const commit = git.decodeCommit((await store.read(sha)).payload);
+    const files = await flatten(store, commit.tree);
+    const body = { sha, message: commit.message.trim(), paths: [...files.keys()].sort(), refs: [...ad.refs.keys()].sort() };
+    return { status: 200, body, text: JSON.stringify(body) };
+}
+/** `git push`: a commit of `files` on the ref's tip (a new ref starts from HEAD's), sent with the pack of what it made.
+ *  The answer is the server's report: `unpack`, the ref's `result` (`ok`, or its `ng` reason) and the pushed `sha`. */
+export async function gitPush(fetch, base, step, headers) {
+    const ad = await advertised(fetch, base, 'git-receive-pack', headers);
+    if (ad.status !== 200)
+        return { status: ad.status, body: ad.text, text: ad.text };
+    const old = ad.refs.get(step.ref) ?? git.ZERO_SHA;
+    const store = new git.GitObjectStore(new MemoryBlobStore(), 'push');
+    let next = git.ZERO_SHA;
+    const made = [];
+    if (!step.delete) {
+        const tip = old !== git.ZERO_SHA ? old : ad.refs.get('HEAD');
+        let files = new Map();
+        let parents = [];
+        if (tip) {
+            await fetchInto(fetch, base, tip, store, headers);
+            const commit = git.decodeCommit((await store.read(tip)).payload);
+            files = await flatten(store, commit.tree);
+            parents = step.amend ? commit.parents : [tip];
+        }
+        for (const [path, content] of Object.entries(step.files ?? {})) {
+            if (content === null) {
+                files.delete(path);
+                continue;
+            }
+            if (typeof content === 'object' && content.mode === '160000') {
+                files.set(path, { mode: content.mode, sha: content.sha });
+                continue;
+            }
+            const sha = await store.write('blob', ENC.encode(typeof content === 'string' ? content : content.content));
+            made.push(sha);
+            files.set(path, { mode: typeof content === 'string' ? '100644' : content.mode, sha });
+        }
+        const tree = await build(store, files, made);
+        const [name, email] = (step.author ?? 'octocat <octocat@github.com>').split(/\s*<|>/);
+        // the commit is dated by the World's clock, as the server's Date header reads it
+        const who = { name: name.trim(), email: (email ?? '').trim(), time: Math.floor(ad.date / 1000), tz: '+0000' };
+        next = await store.write('commit', git.encodeCommit({ tree, parents, author: who, committer: who, message: `${step.message ?? 'Update'}\n` }));
+        made.push(next);
+    }
+    const objects = await Promise.all([...new Set(made)].map(async (sha) => ({ ...(await store.read(sha)) })));
+    const command = git.pktLine(`${old} ${next} ${step.ref}\0report-status\n`);
+    const body = step.delete ? cat(command, git.FLUSH) : cat(command, git.FLUSH, await git.writePack(objects));
+    const res = await fetch(new Request(`${base}/git-receive-pack`, { method: 'POST', headers: { ...headers, 'content-type': 'application/x-git-receive-pack-request' }, body: body }));
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (res.status !== 200) {
+        const text = DEC.decode(bytes);
+        return { status: res.status, body: text, text };
+    }
+    const lines = git.readPktLines(bytes).lines.map((l) => l.trim());
+    const unpack = lines.find((l) => l.startsWith('unpack '))?.slice(7) ?? '';
+    const verdict = lines.find((l) => l.startsWith('ok ') || l.startsWith('ng '));
+    const result = verdict?.startsWith('ok ') ? 'ok' : verdict?.slice(4 + step.ref.length).trim() ?? '';
+    const answer = { unpack, result, sha: next, before: old };
+    return { status: res.status, body: answer, text: JSON.stringify(answer) };
+}

package/dist/src/walk/journey-kit.d.ts

@@ -0,0 +1,445 @@
+/** 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;
+};
+/** 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 declare function expectFailures(expect: NonNullable<JourneyStep['expect']>, body: unknown, captured: Captured, headers?: Record<string, string>, wireText?: string): string[];
+/** 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 declare function expandFills<J extends {
+    steps: unknown[];
+}>(journey: J): J;
+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 declare const isResp: (step: Step) => step is RespStep;
+/** 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 declare const isLine: (step: Step) => step is LineStep;
+/** 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 declare const isSocket: (step: Step) => step is SocketStep;
+/** 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 declare const isGit: (step: Step) => step is GitStep;
+/** 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 declare const isWait: (step: Step) => step is WaitStep;
+/** 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 declare const isSql: (step: Step) => step is SqlStep;
+/** A wait's length in milliseconds; an unreadable one throws. */
+export declare function waitMs(wait: string): number;
+/** 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 declare function captureAt(body: unknown, spec: string, headers?: Record<string, string>, wireText?: string): unknown;
+export declare function at(body: unknown, path: string): unknown;
+/** 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 declare function fill(template: string, captured: Captured, graphqlDocument?: boolean): string;
+/** 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 declare function formBody(form: JourneyForm, captured: Captured): {
+    contentType: string;
+    bytes: Uint8Array<ArrayBuffer>;
+};
+/** 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 declare function gradientPng(width: number, height: number): Uint8Array;
+/** Build JSON values before serialization: captured text is data, including quotes and braces, not JSON source. */
+export declare function fillJson(value: unknown, captured: Captured, typed?: Record<string, unknown>, graphqlBody?: boolean): unknown;
+/** 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 declare function echoFailures(sent: unknown, got: unknown, except?: string[], prefix?: string): string[];
+/** The state-simulation module of a pack, as repo-relative paths. */
+export declare function stateModuleFiles(vendor: string, twinDir: string, fs: {
+    readdirSync: (d: string) => string[];
+    readFileSync: (p: string, e: 'utf8') => string;
+}): string[];
+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 declare function functionIndex(source: string): Array<{
+    line: number;
+    end: number;
+    name: string;
+}>;
+/** 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 declare function stateCoverage(lcov: string, files: string[], readSource?: (file: string) => string | undefined): StateCoverage[];
+/** 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 declare function existenceProbe(walked: Array<{
+    method: string;
+    path: string;
+    body: string;
+    status: number;
+    refused: boolean;
+    sitting: number;
+}>, n: number): boolean;
+/** 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 declare function oauth1Authorization(o: NonNullable<JourneyStep['oauth1']>, method: string, url: string, body: string | undefined, contentType: string | undefined, at: number): string;
+/** 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 declare function jwtAuthorization(o: NonNullable<JourneyStep['jwt']>, captured: Captured): string;
+/** The headers of a step's SigV4 signature (`sigv4`), captures filled, over the URL, headers and body it sends. */
+export declare 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>;
+/** 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 declare function presignedPath(o: NonNullable<JourneyStep['presign']>, captured: Captured, method: string, path: string, host: string, headers?: Record<string, string>): string;