@axorum/client 0.0.0-stage → 1.1.0

package/dist/client.js

@@ -0,0 +1,1303 @@
+/**
+ * The client, and the one request funnel every call goes through.
+ *
+ * @packageDocumentation
+ */
+import { ConfigError, DeadlineExceededError, DecodeError, EndpointsExhaustedError, MissingAttestationError, NoActivePolicyError, StalePolicyError, TransportError, ConnectError, RATE_LIMIT_EXCEEDED, RateLimitedError, UnexpectedResponseError, IdempotencyWindowError, errorFromBody, isErrorBody, } from "./errors.js";
+import { ensureFresh, mintedAtWire, readIdempotencyWindow } from "./idempotency.js";
+export { mintedAtWire } from "./idempotency.js";
+import { endedAfterRedrive, redrivePause, redrives, runAuthorize, } from "./authorize.js";
+import { Failover, describeRefusal, endpointSet, onEndpoint, outcomeOfStatus, outcomeOfTransport, } from "./failover.js";
+import { pinIntent, settleDraft } from "./intent.js";
+import { parseJson, stringifyJson } from "./json.js";
+import { AUTHORIZE_DEADLINE_MS, AUTHORIZE_RESENT_STATUSES, AUTHORIZE_RETRY_POLICY, SUBMIT_ATTEMPT_FALLBACK_MS, SUBMIT_TIMEOUT_HEADER, advertisedCommitWait, attemptTimeout, liftedSubmitTimeout, checkRetryPolicy, isConnectFailure, parseRetryAfter, submitAttemptTimeout, } from "./retry.js";
+/**
+ * How many policies {@link AxorumClient.submitPinned} will pin against before giving up.
+ *
+ * A bound, not a retry budget: each attempt pins against the policy the service *just
+ * told us* is in force, so a second failure means the policy moved again in the
+ * microseconds since. Three is generous; a service changing policy faster than that is
+ * not one a client can chase, and looping forever would turn a hot policy rotation into
+ * a self-inflicted denial of service.
+ */
+export const MAX_PINS = 3;
+/** The agent plane's mount point. Not configurable — it is part of the frozen contract. */
+const BASE_PATH = "/api/v1";
+/** The default per-request timeout, in milliseconds. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * The statuses the agent plane documents as answers. A client's retry policy never
+ * re-sends one: the identical request would be answered identically, or (`421`, `503
+ * commit_unavailable`) the answer is the caller's to act on. The Rust SDK registers the
+ * same set with `acton-service-client` as accepted statuses, which is what keeps them
+ * out of its retry loop. `authorize` has the transport re-send `421` regardless
+ * ({@link AUTHORIZE_RESENT_STATUSES}), and sends a `503` again itself, its body read.
+ */
+const CONTRACT_STATUSES = new Set([400, 401, 403, 404, 409, 421, 422, 500, 503, 507]);
+/**
+ * A typed client for the Axorum agent plane.
+ *
+ * # Writes carry their credential; so do reads
+ *
+ * An intent authenticates **in the envelope**: the draft names the `agent://` URI and the
+ * PASETO attestation, and the service verifies them before it proposes anything. The
+ * reads used to carry nothing at all, and were answered anyway — so any party's
+ * obligations were enumerable, and any observed transaction id disclosed another tenant's
+ * record.
+ *
+ * They are credentialed now, with the **same token**: the party-scoped reads present the
+ * agent's attestation as `Authorization: Bearer …`, the service takes the reader's
+ * identity from that token's verified `agent_uri` claim, and answers only within the
+ * party it is bound to. There is no second credential to obtain — an agent that can
+ * submit can already read.
+ *
+ * So a client that reads must hold an attestation:
+ *
+ * ```ts
+ * const axorum = new AxorumClient({ baseUrl: "http://127.0.0.1:8080", attestation: paseto });
+ *
+ * const outcome = await axorum.submitPinned(draft);
+ *
+ * // A refusal RESOLVES. Branch on the verdict, never on a status code.
+ * if (outcome.posted) {
+ *   console.log("permitted, and the entries posted");
+ * } else {
+ *   console.log("refused, and the refusal is on the ledger:", outcome.verdict);
+ * }
+ *
+ * // Reads are scoped to the party the attestation is bound to.
+ * const owed = await axorum.obligations();
+ * ```
+ *
+ * A client built **without** one still submits and still reads {@link activePolicy} —
+ * both carry their own credential or need none — but any party-scoped read is a
+ * {@link MissingAttestationError}, raised locally, without a wasted round trip.
+ *
+ * An {@link AxorumError} means the ledger never got to answer at all.
+ */
+export class AxorumClient {
+    #baseUrl;
+    /** The failover URLs as given, handed on by {@link withAttestation}. */
+    #failoverUrls;
+    /** Every endpoint's origin, `scheme://host:port`: the base URL's first. */
+    #endpoints;
+    #onRotation;
+    #onRetry;
+    /**
+     * The endpoint the next call starts at: the last one that gave a definitive answer.
+     * Shared with every client {@link withAttestation} derives.
+     */
+    #preferred = { value: 0 };
+    #timeoutMs;
+    /** Whether {@link #timeoutMs} is the SDK's default, which a plain submission may lift. */
+    #defaultTimeout;
+    #fetch;
+    /**
+     * The caller's PASETO attestation, presented on the party-scoped reads.
+     *
+     * Held here rather than baked into the funnel's default headers for one reason:
+     * **attestations expire**. A token welded on at construction would mean rebuilding the
+     * client — and with it whatever the `fetch` it was handed is holding open — to rotate
+     * one. Kept beside it, it can be swapped with {@link withAttestation} for the price of
+     * a string.
+     */
+    #attestation;
+    #retry;
+    /** The budget of one {@link authorize} call, at most {@link AUTHORIZE_DEADLINE_MS}. */
+    #authorizeDeadlineMs;
+    /** Whether {@link authorize} re-sends an unanswered request. */
+    #authorizeRetries;
+    /**
+     * The policy {@link authorize} last pinned, shared with every client
+     * {@link withAttestation} derives, so one rotation costs one `409` for all of them.
+     */
+    #pin = { value: undefined };
+    /**
+     * What the service advertised about itself (its contract version and, when clustered,
+     * its commit wait), once read, shared with every client {@link withAttestation}
+     * derives. A deployment does not change contract under a running client without a
+     * restart; a commit wait changed by a restart is picked up by a new client.
+     */
+    /**
+     * The idempotency window the service stated with a wall-clock length, once read,
+     * shared with every client {@link withAttestation} derives. Kept only when clocked:
+     * the window only ever grows, and an unclocked or unstated one is read again.
+     */
+    #window = { value: undefined };
+    /**
+     * The commit wait the service advertised ({@link SUBMIT_TIMEOUT_HEADER}), in
+     * milliseconds, once read, shared with every client {@link withAttestation} derives:
+     * `null` when it advertises none, as a standalone service does.
+     */
+    #commitWait = { value: undefined };
+    /** Whether the commit-wait fallback has been noted to {@link #debug}, shared as {@link #commitWait} is. */
+    #fallbackNoted = { value: false };
+    #debug;
+    /**
+     * Builds a client for the service rooted at `baseUrl`.
+     *
+     * @throws {ConfigError} If `baseUrl` is not an absolute `http`/`https` URL, a failover
+     *   URL is not a bare origin of the same scheme or repeats one, the timeout is not a
+     *   positive number, the retry policy is not whole numbers, or the authorize deadline
+     *   is not a whole number of milliseconds from 1 to 15 000.
+     */
+    constructor(options) {
+        this.#baseUrl = normalizeBaseUrl(options.baseUrl);
+        this.#failoverUrls = Object.freeze([...(options.failoverUrls ?? [])]);
+        const set = endpointSet(this.#baseUrl, this.#failoverUrls);
+        if ("refusal" in set) {
+            throw new ConfigError(`the Axorum client could not be built: ${describeRefusal(set.refusal)}`);
+        }
+        this.#endpoints = set.endpoints;
+        this.#onRotation = options.onRotation;
+        this.#onRetry = options.onRetry;
+        this.#attestation = options.attestation;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#defaultTimeout = options.timeoutMs === undefined;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#retry = options.retry === undefined ? undefined : Object.freeze({ ...options.retry });
+        this.#authorizeDeadlineMs = options.authorizeDeadlineMs ?? AUTHORIZE_DEADLINE_MS;
+        this.#authorizeRetries = options.authorizeRetries ?? true;
+        this.#debug = options.debug;
+        if (!Number.isFinite(this.#timeoutMs) || this.#timeoutMs <= 0) {
+            throw new ConfigError(`the timeout must be a positive number of milliseconds, not ${options.timeoutMs}`);
+        }
+        if (this.#retry !== undefined) {
+            try {
+                checkRetryPolicy(this.#retry);
+            }
+            catch (error) {
+                throw new ConfigError(`retry: ${error.message}`);
+            }
+        }
+        if (!validAuthorizeDeadline(this.#authorizeDeadlineMs)) {
+            throw new ConfigError(`the authorize deadline must be a whole number of milliseconds from 1 to ` +
+                `${AUTHORIZE_DEADLINE_MS}, not ${options.authorizeDeadlineMs}`);
+        }
+        if (this.#endpoints.length === 1) {
+            warnOneEndpoint(this.#baseUrl);
+        }
+    }
+    /**
+     * The same client, reading as the bearer of a **different** attestation.
+     *
+     * Attestations expire, so an agent that outlives one of its tokens must be able to
+     * re-credential without rebuilding — and this hands the new client the *same* `fetch`,
+     * so whatever connections that `fetch` is keeping alive stay alive. Rotating a token
+     * costs a string, not a reconnect.
+     *
+     * It is also the honest way for one process to act for several agents: each gets its
+     * own view, and no view can see another's data, because the service scopes every read
+     * to the party the presented token names.
+     */
+    withAttestation(attestation) {
+        const client = new AxorumClient({
+            baseUrl: this.#baseUrl,
+            failoverUrls: this.#failoverUrls,
+            ...(this.#onRotation === undefined ? {} : { onRotation: this.#onRotation }),
+            ...(this.#onRetry === undefined ? {} : { onRetry: this.#onRetry }),
+            attestation,
+            timeoutMs: this.#timeoutMs,
+            ...(this.#retry === undefined ? {} : { retry: this.#retry }),
+            authorizeDeadlineMs: this.#authorizeDeadlineMs,
+            authorizeRetries: this.#authorizeRetries,
+            ...(this.#debug === undefined ? {} : { debug: this.#debug }),
+            fetch: this.#fetch,
+        });
+        client.#pin = this.#pin;
+        client.#window = this.#window;
+        client.#defaultTimeout = this.#defaultTimeout;
+        client.#commitWait = this.#commitWait;
+        client.#fallbackNoted = this.#fallbackNoted;
+        client.#preferred = this.#preferred;
+        return client;
+    }
+    /**
+     * Asks the ledger whether `agent` may make `payment`, in one call.
+     *
+     * Proposes `purchase(amount, payee)` with the payee bound as **text**, debiting the
+     * default chart's spend account and crediting its payable account in the amount's
+     * currency. The policy in force must declare
+     * `action purchase(amount: amount, payee: text)`, and an operator must have opened the
+     * default chart in that currency. A rail governed by the same policy must be set to
+     * `payee_binding = "text"`; one left on `"party"` binds a different type.
+     *
+     * ```ts
+     * import { Agent, AxorumClient, AuthorizeError, payment } from "@axorum/client";
+     *
+     * const axorum = new AxorumClient({ baseUrl: "https://ledger.acme.com" });
+     * const buyer = new Agent("agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q", paseto);
+     * const lunch = payment({ amount: { minor: 1_250n, currency: "USD" }, payee: "api.openai.com" });
+     *
+     * const answer = await axorum.authorize(buyer, lunch);
+     * if (answer.allowed) {
+     *   await pay();
+     * } else {
+     *   console.log(answer.refusal.explanation);
+     * }
+     * ```
+     *
+     * # A refusal resolves
+     *
+     * A payment the policy forbids resolves as `{ allowed: false, refusal }`: it was judged
+     * and recorded, and nothing posted. A rejected promise ({@link AuthorizeError}) means the
+     * ledger never answered.
+     *
+     * # Retries and time
+     *
+     * One call has one budget, {@link AUTHORIZE_DEADLINE_MS} (15 s, or less with
+     * {@link AxorumClientOptions.authorizeDeadlineMs}), counted from the call and shared by
+     * the idempotency window and policy reads, every submission (the first, and each
+     * re-pin), every attempt and every pause. Each submission attempt waits the commit
+     * wait the service advertises plus 1 s ({@link submitAttemptTimeout}), so a clustered
+     * service's own `503 commit_unavailable` is heard rather than cut off, or 6 s
+     * ({@link SUBMIT_ATTEMPT_FALLBACK_MS}) when it advertises none; each read waits 6 s.
+     * Every attempt is also clamped to what is left of the budget. When that clamp cuts a
+     * submission attempt below the commit wait plus 1 s, the service may still be deciding
+     * when the client stops waiting, so a call that ends there is honestly
+     * `indeterminate`. The advertisement is read once per client, from
+     * `GET /api/openapi.json`.
+     * Re-sends follow {@link AUTHORIZE_RETRY_POLICY}: as many as the budget allows, full
+     * jitter floored at 100 ms and capped at 1.6 s, honouring `Retry-After` within the
+     * budget. The client's own `retry` and `timeoutMs` govern its other calls, not this one;
+     * {@link AxorumClientOptions.authorizeRetries} turns re-sending off.
+     *
+     * | Re-sent until the deadline | Not re-sent |
+     * |---|---|
+     * | connection failures and timeouts | refusals (they are answers) |
+     * | `429`, `502`, `503`, `504` (and `423` with `Retry-After`) | `422`, including a missing chart or an unknown payee |
+     * | `421 not_primary`, on the next {@link AxorumClientOptions.failoverUrls} URL | `409 transaction_reused` |
+     * | `409` stale pin: re-pinned to `active`, at most 3 times | `400` / `401` / `403` / `404` / `507` |
+     *
+     * Every send carries the payment's transaction id, so one that did commit replays its
+     * answer instead of paying twice. A connection failure, a timeout or a `421` moves the
+     * next attempt to the next failover URL at once; a `503` is sent again to the same URL,
+     * its body read. Whatever is still unanswered
+     * when the budget runs out (a `421` and a `503` included) is `indeterminate`: re-drive
+     * the same {@link Payment} to learn what happened. A call that proves it wrote nothing
+     * is `not_submitted`. `primaryApiAddr` is a hint, never followed.
+     *
+     * Once an attempt ends without a definite answer (a timeout, or a re-sent status other
+     * than `429`), it may have committed, so a later failure that is not the ledger's own
+     * answer about the transaction id (a `403`, a `401`, a `429` or `502` once retries are
+     * spent) is `indeterminate` too, with cause `earlier_attempt_in_doubt`. A
+     * `409 transaction_reused` and a `422 substrate_rejected` stay what they are.
+     *
+     * # Time
+     *
+     * The attestation is read once per submission (the first, and each re-pin), and its
+     * `exp` bounds that submission too: every send, and every wait between sends
+     * (`Retry-After` included), ends 30 seconds (`ATTESTATION_CLOCK_ALLOWANCE_MS`) before
+     * `exp` when that comes before the call's deadline. No send starts past that point, each
+     * send's timeout is cut to the time left, and a wait that would reach it ends the
+     * re-sends.
+     *
+     * @throws {AuthorizeError} Carrying the transaction id and a `failure` that says what to
+     *   do next.
+     * @throws The caller's own abort reason, as-is, when `options.signal` fires.
+     */
+    async authorize(agent, payment, options) {
+        const lane = {
+            deadline: performance.now() + this.#authorizeDeadlineMs,
+            retries: this.#authorizeRetries,
+        };
+        const withSignal = (signal) => signal === undefined ? undefined : { signal };
+        return runAuthorize({
+            activePolicy: (signal) => this.#activePolicy(withSignal(signal), lane),
+            submit: (envelope, signal, bound) => this.#submitIntent(envelope, withSignal(signal), lane, bound),
+            pin: this.#pin,
+            keptWindow: () => this.#keptWindow(),
+            readWindow: (signal) => this.#readWindow(withSignal(signal), lane),
+        }, agent, payment, options?.signal);
+    }
+    /**
+     * Attaches the caller's attestation to a party-scoped read.
+     *
+     * The single choke point for read credentials: every scoped read goes through it, so
+     * none can forget. A client with no attestation fails **here**, locally, naming the
+     * omission — rather than sending a bare request and relaying the service's inevitable
+     * `401` as though the service had found fault with a credential that was never sent.
+     *
+     * @throws {MissingAttestationError} If this client holds none.
+     */
+    #authorize(operation) {
+        if (this.#attestation === undefined) {
+            throw new MissingAttestationError(operation);
+        }
+        return { authorization: `Bearer ${this.#attestation}` };
+    }
+    /**
+     * The id of the policy currently in force, or `null` if none is.
+     *
+     * `null` is **not an error** — the service answers `200` with `{"policy": null}`, and
+     * "no policy is in force" is a true and useful fact about a ledger, not a failure to
+     * report one.
+     *
+     * This is the endpoint to re-read after a `409`; {@link submitPinned} does it for you.
+     *
+     * @throws {TransportError} If the service cannot be reached.
+     */
+    /**
+     * The commit wait the service advertises, read once on `lane` when one is given and
+     * then kept for this client and the clients {@link withAttestation} derives.
+     * `undefined` when it advertises none, or when this read failed (the next submission
+     * reads again).
+     */
+    async #commitWaitMs(options, lane) {
+        return (await this.#readCommitWait(options, lane)).ms;
+    }
+    /** {@link #commitWaitMs}, and the read's failure when it failed. */
+    async #readCommitWait(options, lane) {
+        if (this.#commitWait.value === undefined) {
+            try {
+                await this.#send({
+                    method: "GET",
+                    path: "api/openapi.json",
+                    root: true,
+                    options,
+                    ...(lane === undefined ? {} : { lane }),
+                    headersOnly: true,
+                    onHeaders: (headers) => this.#keepCommitWait(headers),
+                });
+            }
+            catch (error) {
+                // The caller's own cancellation is not a failed read: it ends the call.
+                if (options?.signal?.aborted === true) {
+                    throw error;
+                }
+                return { ms: undefined, failure: error };
+            }
+        }
+        return { ms: this.#commitWait.value ?? undefined };
+    }
+    /** Keeps the commit wait `headers` state, unless one is kept already. */
+    #keepCommitWait(headers) {
+        this.#commitWait.value ??= advertisedCommitWait(headers.get(SUBMIT_TIMEOUT_HEADER)) ?? null;
+    }
+    /**
+     * The bound on a plain submission in place of the SDK's default timeout, when that is
+     * too short to outlast the commit wait the service advertises. A timeout the caller set
+     * is theirs, and nothing is read for it.
+     */
+    async #liftedSubmit(options) {
+        if (!this.#defaultTimeout) {
+            return {};
+        }
+        const lifted = liftedSubmitTimeout(this.#timeoutMs, await this.#commitWaitMs(options, undefined));
+        return lifted === undefined ? {} : { attemptMs: lifted };
+    }
+    /**
+     * How long one submission attempt on `lane` may wait: {@link submitAttemptTimeout} of
+     * the advertised commit wait. The advertisement is read once per client; if that read
+     * fails, this attempt waits {@link SUBMIT_ATTEMPT_FALLBACK_MS} and the next submission
+     * reads again. The lane's deadline still clamps the attempt.
+     *
+     * The first time an attempt waits the fallback, this says why on the
+     * {@link AxorumClientOptions.debug} sink ({@link fallbackNote}), once per client.
+     */
+    async #submitAttemptMs(options, lane) {
+        const { ms, failure } = await this.#readCommitWait(options, lane);
+        if (ms === undefined && !this.#fallbackNoted.value) {
+            this.#fallbackNoted.value = true;
+            this.#debug?.(fallbackNote(failure));
+        }
+        return submitAttemptTimeout(ms);
+    }
+    async activePolicy(options) {
+        return this.#activePolicy(options, undefined);
+    }
+    /** {@link activePolicy}, on `lane` when one is given. */
+    async #activePolicy(options, lane) {
+        const response = await this.#send({
+            method: "GET",
+            path: "policies/active",
+            options,
+            ...(lane === undefined ? {} : { lane }),
+        });
+        return response.policy;
+    }
+    /**
+     * The ledger's currency registry: every declared currency and its minor-unit exponent,
+     * in canonical (sorted) code order.
+     *
+     * Requires an attestation, like every agent-plane read of ledger state, but is not
+     * owner-scoped: any bound agent reads the whole registry. From contract 5.0.0 an intent
+     * in any currency not listed here is refused with `422` and
+     * `cause: "undeclared_currency"`, so this is what to read to learn what the ledger will
+     * take. An empty list means nothing is declared.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation. Nothing is sent.
+     * @throws {AttestationError} If the service refuses the attestation.
+     * @throws {TransportError} If the service cannot be reached.
+     */
+    async currencies(options) {
+        return this.#send({
+            method: "GET",
+            path: "currencies",
+            headers: this.#authorize("the currency registry"),
+            options,
+        });
+    }
+    /**
+     * How long this service answers a retry of a committed transaction id with the
+     * original outcome: its idempotency window (contract 5.0.0).
+     *
+     * Read from the three response headers on `GET /api/openapi.json`
+     * ({@link IDEMPOTENCY_WINDOW_HEADERS}); the document itself is the frozen contract and
+     * is not parsed. Needs no attestation. `window_seconds` is the window's wall-clock
+     * length (24 hours at least, rounded down), or `null` when the service runs no
+     * heartbeat and its window has no length in seconds. Read it once and hand it to
+     * {@link submitKeyed} or {@link ensureFresh}; it only ever grows.
+     *
+     * ```ts
+     * const window = await client.idempotencyWindow();
+     * window.window_seconds; // 86400n
+     * ```
+     *
+     * @throws {IdempotencyWindowError} If the headers state no window: a service older
+     *   than contract 5.0.0, a writer that could not answer, or a rewritten header.
+     * @throws {UnexpectedResponseError} If the spec fetch does not answer `2xx`.
+     * @throws {TransportError} If the service cannot be reached.
+     */
+    async idempotencyWindow(options) {
+        return this.#idempotencyWindow(options, undefined);
+    }
+    /** {@link idempotencyWindow}, on `lane` when one is given. */
+    async #idempotencyWindow(options, lane) {
+        let window;
+        await this.#send({
+            method: "GET",
+            path: "api/openapi.json",
+            root: true,
+            options,
+            ...(lane === undefined ? {} : { lane }),
+            headersOnly: true,
+            onHeaders: (headers, status) => {
+                window = readIdempotencyWindow(headers, status);
+                this.#keepCommitWait(headers);
+            },
+        });
+        if (window === undefined) {
+            throw new IdempotencyWindowError(null, "not_advertised", null, null);
+        }
+        return window;
+    }
+    /**
+     * The wall-clock window this client last read, if it read one.
+     *
+     * The copy is a safe bound to hold a key to because the service never shrinks its
+     * window in ticks: boot raises the standing window to the configured one and never
+     * lowers it (`axorum-serve`'s `idempotency::boot_policy`), and the admin route refuses
+     * a shorter one with `409 idempotency_window_shrink`. What the copy can miss is served
+     * by the service's own check: a submission whose `minted_at_ms` is past its window,
+     * less a 5-minute skew margin, is refused with `409 stale_idempotency_key` and nothing
+     * is written. And the window can grow after the copy was taken, so a key the copy
+     * refuses is held to a fresh read before it is refused ({@link #readWindow}).
+     */
+    #keptWindow() {
+        return this.#window.value;
+    }
+    /**
+     * Reads the service's window, and keeps it when it states a wall-clock length. An
+     * unclocked window is returned but not kept, so a heartbeat turned on is seen.
+     */
+    async #readWindow(options, lane) {
+        const window = await this.#idempotencyWindow(options, lane);
+        if (window.window_seconds !== null) {
+            this.#window.value = window;
+        }
+        return window;
+    }
+    /**
+     * Submits an envelope under a retry key, refusing the key first if the service's
+     * window no longer covers it.
+     *
+     * Use this for every resubmission you make on your own schedule: a queue that
+     * redelivers, a job that restarts. Within the window a resubmission of the identical
+     * intent answers the original outcome (`replayed: true`); past it, the answer is
+     * undefined and the intent might commit twice, so a stale key is never sent.
+     *
+     * The envelope goes out with the key's `minted_at_ms`, so a contract 5.0.0 service
+     * that runs a heartbeat refuses it too (`409 stale_idempotency_key`, an
+     * {@link ApiError}) once it is older than the window less a 5-minute clock-skew
+     * margin. A caller-chosen id restated with its true mint time passes that check
+     * exactly as a freshly minted one does.
+     *
+     * # Why re-sending is sound
+     *
+     * The service looks a transaction id up before it applies anything. A re-send inside
+     * the idempotency window returns what the first send committed, and one whose content
+     * differs is refused as `409 transaction_reused`, never applied.
+     *
+     * # Retries and time
+     *
+     * It runs on {@link authorize}'s transport: one budget of `authorizeDeadlineMs`
+     * ({@link AUTHORIZE_DEADLINE_MS} by default), shared by the read of the service's
+     * commit wait and every attempt, each bounded by {@link submitAttemptTimeout} of that
+     * wait, moving across the `failoverUrls` on a connection failure, a timeout and `421`,
+     * and sending a `503` again itself, its body read. `authorizeRetries: false` turns
+     * re-sending off here too.
+     *
+     * | Call | Re-sent? | Moves to the next URL? |
+     * |---|---|---|
+     * | {@link submitIntent} | no | no |
+     * | {@link submitPinned} | only to re-pin after a `409` | no |
+     * | `submitKeyed` | yes, until the deadline | yes |
+     *
+     * ```ts
+     * const window = await client.idempotencyWindow();
+     * const key = IdempotencyKey.mint();
+     * const envelope = pinIntent({ ...draft, transaction: key.transaction }, policy);
+     * const outcome = await client.submitKeyed(key, window, envelope);
+     * ```
+     *
+     * @throws {StaleIdempotencyKeyError} If the key is past the window, or the service
+     *   advertises no wall-clock window. Nothing was sent.
+     * @throws {ConfigError} If the envelope's `transaction` is not the key's. Nothing was
+     *   sent.
+     * @throws {TransactionReusedError} If the id committed with different content.
+     * @throws {EndpointsExhaustedError | DeadlineExceededError} When no endpoint answered
+     *   in time. Otherwise as {@link submitIntent}.
+     */
+    async submitKeyed(key, window, envelope, options) {
+        checkKeyed(key, window, envelope, Date.now());
+        const lane = {
+            deadline: performance.now() + this.#authorizeDeadlineMs,
+            retries: this.#authorizeRetries,
+        };
+        return this.#submitIntent({ ...envelope, minted_at_ms: mintedAtWire(key) }, options, lane);
+    }
+    /**
+     * Submits an intent envelope and returns the ledger's outcome.
+     *
+     * # A refusal resolves
+     *
+     * If the policy in force forbids the action, this **resolves** with
+     * `{ posted: false, verdict: "ForbiddenRejected", … }` — a `200`. The intent reached
+     * the commit point, was judged, and the refusal was *recorded*. That record is the
+     * product. Branch on `posted`/`verdict`; a rejected promise means the ledger never got
+     * to answer at all.
+     *
+     * Re-submitting the identical intent under a `transaction` id that already committed
+     * replays its stored outcome, marked `replayed: true`, rather than double-posting: the
+     * id is the substrate's idempotency key, which is what makes retrying a submission
+     * safe within the service's window ({@link idempotencyWindow}). Different content
+     * under a committed id is a {@link TransactionReusedError}. A replay also carries
+     * `content_verified`: `true` when the resubmitted content matched the stored intent,
+     * `false` when the service had no stored content to compare with (an id committed
+     * before 1.0.0 whose content hash the old log never recorded, retried inside the
+     * window after the upgrade). A `false` replay posted nothing, but it did not check
+     * your content either. To have the key's age checked before sending, use
+     * {@link submitKeyed}.
+     *
+     * @throws {ConfigError} If the envelope carries no `minted_at_ms` (a non-negative
+     *   `bigint` of milliseconds since the Unix epoch). Nothing was sent.
+     * @throws {StalePolicyError} If the pin did not hold. Use {@link submitPinned} to
+     *   handle that automatically.
+     * @throws {UnknownAgentError | AttestationError} On an identity or authority failure.
+     * @throws {NotPrimaryError} If a follower turned the mutation away. Not followed
+     *   automatically — see the class docs.
+     * @throws {CommitUnavailableError} If a cluster commit could not be confirmed.
+     * @throws {TransportError} If the service cannot be reached.
+     */
+    async submitIntent(envelope, options) {
+        return this.#submitIntent(envelope, options, undefined);
+    }
+    /**
+     * {@link submitIntent}, on `lane` and within `bound` when they are given. On the lane,
+     * with retries on, a `503` is sent again by this loop, its body read ({@link redrives}),
+     * under {@link AUTHORIZE_RETRY_POLICY} until the deadline; `bound` hears each, and so
+     * does {@link AxorumClientOptions.onRetry}.
+     *
+     * The loop exists only because a transport re-send reports a `503`'s status and not its
+     * code, so an observer cannot tell `idempotency_unseeded`, which wrote nothing, from
+     * `commit_unavailable` (https://github.com/Govcraft/acton-service-client/issues/9, which
+     * the TypeScript port mirrors). Once the retried response's code reaches the observer,
+     * it collapses into retry-policy configuration.
+     */
+    async #submitIntent(envelope, options, lane, bound) {
+        checkMinted(envelope);
+        const deadline = earliest(lane?.deadline, bound?.deadline);
+        let pausedAfter;
+        for (let redriven = 0;; redriven += 1) {
+            let endpoint;
+            try {
+                return await this.#send({
+                    method: "POST",
+                    path: "intents",
+                    body: envelope,
+                    options,
+                    ...(bound === undefined ? {} : { bound }),
+                    onEnded: (at) => {
+                        endpoint = at;
+                    },
+                    // Each attempt outlasts the service's commit wait, so its `503 commit_unavailable`
+                    // is heard rather than cut off; on `authorize`'s lane the deadline still clamps it.
+                    ...(lane === undefined
+                        ? await this.#liftedSubmit(options)
+                        : { lane, attemptMs: await this.#submitAttemptMs(options, lane) }),
+                });
+            }
+            catch (thrown) {
+                const ended = endedAfterRedrive(pausedAfter, thrown);
+                if (ended.heard) {
+                    throw ended.error;
+                }
+                const error = ended.error;
+                const wait = lane?.retries === true && deadline !== undefined && redrives(error)
+                    ? redrivePause(redriven, Math.random(), Math.max(0, deadline - performance.now()))
+                    : undefined;
+                if (wait === undefined) {
+                    if (endpoint !== undefined) {
+                        bound?.onEnded?.(endpoint);
+                    }
+                    throw error;
+                }
+                if (endpoint !== undefined) {
+                    bound?.onRedrive?.(endpoint, error);
+                    this.#observe({ kind: "retry", reason: { kind: "status", status: 503 } }, this.#endpoints.indexOf(endpoint), redriven + 2);
+                }
+                pausedAfter = error;
+                await pause(wait, options?.signal);
+            }
+        }
+    }
+    /**
+     * Fetches the active policy, pins the draft to it, submits — and if the pin did not
+     * hold, re-pins and submits again.
+     *
+     * This is the loop every correct agent writes, so it ships in the client rather than
+     * in each caller. It is the *only* method that recovers automatically, and it is safe
+     * to do so for one specific reason: the `transaction` id is minted **once**, before
+     * the first attempt, and is the substrate's idempotency key. Every retry carries the
+     * same id, so if an earlier attempt in fact landed, the retry replays its stored
+     * outcome. The loop cannot double-post.
+     *
+     * A refusal still resolves (see {@link submitIntent}), and a `421` still rejects:
+     * following a redirect to another replica is the caller's decision, not the client's.
+     *
+     * @throws {NoActivePolicyError} If no policy is in force — there is nothing to pin to.
+     * @throws {StalePolicyError} If the policy kept moving out from under {@link MAX_PINS}
+     *   attempts.
+     */
+    async submitPinned(draft, options) {
+        const policy = await this.activePolicy(options);
+        if (policy === null) {
+            throw new NoActivePolicyError("no policy is in force, so an intent cannot be pinned to one");
+        }
+        return this.submitPinnedFrom(draft, policy, options);
+    }
+    /**
+     * {@link submitPinned}, but starting from a policy you already believe is in force —
+     * and recovering if you are wrong.
+     *
+     * This is the shape a long-running agent actually wants. Reading the active policy
+     * before *every* submission is a round trip spent re-learning something that changes
+     * rarely; an agent can hold the last policy it saw, submit straight against it, and
+     * let the `409` tell it when its belief went stale. The recovery is the same loop
+     * either way, so caching costs nothing in correctness — the service remains the
+     * authority, it is simply consulted only when it disagrees.
+     *
+     * On a `409` it re-pins against the policy **the rejection itself named**, rather than
+     * re-reading the active policy. That is not a shortcut: the rejection is the service's
+     * own statement of what is in force as of the moment it refused — strictly fresher
+     * than anything a follow-up read could return, and one round trip cheaper. Bounded at
+     * {@link MAX_PINS} attempts.
+     *
+     * @param draft - The intent, minus the pin. Its transaction id and mint time are
+     *   settled once, here, before the first attempt, and every re-pin carries both.
+     * @param policyId - The policy you believe is in force.
+     * @throws {StalePolicyError} If the policy kept moving out from under {@link MAX_PINS}
+     *   attempts — the policy is churning faster than a client can chase it, and looping
+     *   on would turn a hot rotation into a denial of service.
+     */
+    async submitPinnedFrom(draft, policyId, options) {
+        // Once, before the first attempt — never inside the loop. This single line is what
+        // makes every retry below a replay rather than a second posting, and what makes every
+        // retry carry the same mint time.
+        const settled = settleDraft(draft);
+        let policy = policyId;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                // The refusal path returns from here too, as a resolved value — as it should.
+                return await this.submitIntent(pinIntent(settled, policy), options);
+            }
+            catch (error) {
+                // Not a pin problem, so not ours to fix: an attestation failure, a 421, an
+                // unreachable service. Hand it straight back. And out of attempts is out of
+                // attempts: report the last rejection as the service stated it.
+                if (!(error instanceof StalePolicyError) || attempt >= MAX_PINS) {
+                    throw error;
+                }
+                // The service named the policy now in force. Pin to it and go again.
+                policy = error.active;
+            }
+        }
+    }
+    /**
+     * The stored record for a committed transaction — **if your party proposed it**.
+     *
+     * Reading it is the idempotent replay lookup: it tells you what a previously-submitted
+     * `transaction` id did, without resubmitting it. A recorded refusal is here like any
+     * other record, with `posted: false`.
+     *
+     * The record is {@link TransactionRecord | contractually opaque} in this version of
+     * the wire contract.
+     *
+     * # A transaction id is not a capability
+     *
+     * Ids are client-minted, and a counterparty may well know one. Holding an id therefore
+     * grants nothing: a transaction another party proposed answers `404`, *identically* to
+     * an id that never existed. The two are deliberately indistinguishable — a
+     * distinguishable "forbidden" would turn any id into an existence oracle against
+     * another tenant's ledger.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With code `unknown_transaction` (404) if there is no such
+     *   transaction **or it belongs to another party**.
+     */
+    async transaction(txnId, options) {
+        return this.#send({
+            method: "GET",
+            path: `transactions/${encodeURIComponent(txnId)}`,
+            headers: this.#authorize("a transaction"),
+            options,
+        });
+    }
+    /**
+     * The **signed receipt** for a transaction your party proposed — an
+     * `axorum.evidence.v0` envelope whose base64 `payload` is the
+     * `axorum.receipt.v0` facts of the applied record (contract 4.1.0).
+     *
+     * Re-minted deterministically from the stored record on every call:
+     * byte-identical across fetches and to the inline `receipt` the original
+     * submission's outcome carried. Verify it **offline** against the key list
+     * published at `GET /api/verification-keys.json` — no credential, no server,
+     * no SDK required (see `spec/schemas/` and `spec/evidence-signing.md`).
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With `unknown_transaction` (404) if there is no such
+     *   transaction, it belongs to another party, **or** its record has been
+     *   archived out of the live tail — deliberately indistinguishable. With
+     *   `signing_not_configured` / `signing_unavailable` (503) when the
+     *   deployment does not sign or its signing service is down (the
+     *   transaction itself is committed and unaffected — retry later).
+     */
+    async receipt(txnId, options) {
+        return this.#send({
+            method: "GET",
+            path: `transactions/${encodeURIComponent(txnId)}/receipt`,
+            headers: this.#authorize("a receipt"),
+            options,
+        });
+    }
+    /**
+     * The open obligations **your party** owes.
+     *
+     * Whose duties these are is decided by the attestation, never by an argument. That is
+     * the whole of the fix: `?actor=` used to *select* the party — through a deterministic,
+     * public hash of a name — so every party's duties were enumerable by anyone who could
+     * guess a name, with no credential at all.
+     *
+     * `actor` is now an assertion the service **checks** rather than obeys. Leave it out and
+     * you are answered for the party your token names. Supply it — a party id (`party_…`) or
+     * a DSL party name — and the service confirms it resolves to that same party, answering
+     * `403` if it does not. It is there so a caller can be explicit about who it believes it
+     * is, and be told when it is wrong; it can no longer be used to ask about somebody else.
+     *
+     * A duty-free party is not an error — it answers with an empty list.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With `403` if `actor` names a party other than the one your
+     *   attestation is bound to.
+     */
+    async obligations(actor, options) {
+        return this.#send({
+            method: "GET",
+            path: "obligations",
+            ...(actor === undefined ? {} : { query: { actor } }),
+            headers: this.#authorize("obligations"),
+            options,
+        });
+    }
+    /**
+     * An account's net balance, in minor units.
+     *
+     * The balance is a **`bigint`**: the ledger's minor units are 128-bit integers, and
+     * decoding one as a JavaScript `number` would truncate it silently. See `src/json.ts`.
+     *
+     * # Scope
+     *
+     * Requires an attestation **and is scoped to the account's owning party**: the service
+     * answers only when the attested party is the recorded owner of the account. An account
+     * owned by another party — or one opened with no owner at all — answers exactly like an
+     * account that does not exist (`404 unknown_account`), fail-closed and deliberately
+     * indistinguishable: an account id is never an existence oracle across a tenant boundary.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With code `unknown_account` (404) if there is no such account *or*
+     *   the attested party does not own it (the caller cannot tell which).
+     */
+    async balance(accountId, options) {
+        return this.#send({
+            method: "GET",
+            path: `accounts/${encodeURIComponent(accountId)}/balance`,
+            headers: this.#authorize("a balance"),
+            options,
+        });
+    }
+    /**
+     * A usage balance's three running totals — **if your party owns it**.
+     *
+     * The report carries `consumed`, `metered` and `billed`, the two headrooms derived from
+     * them (`unmetered`, `unbilled`), whether the chain has `reconciled`, and `text` — the
+     * balance narrated in compliance English with exact figures. Prefer `text` when you have
+     * a human to show: it is the service's own sentence, not a rendering you assemble.
+     *
+     * # Every counter is a `bigint`
+     *
+     * More so here than anywhere else on the plane. `consumed` is the top of the chain and
+     * takes **no ceiling** — a busy meter can lawfully outgrow `u64` — so decoding a counter
+     * as a JavaScript `number` would eventually truncate a real figure silently. This client
+     * parses them as `bigint`s; see `src/json.ts`.
+     *
+     * # Scope
+     *
+     * Owner-scoped, and fail-closed. A balance owned by another party, one opened with no
+     * owner at all, and one that was never opened all answer the **same** `404 unknown_usage`
+     * — deliberately indistinguishable, so that a usage id is never an existence oracle
+     * across a tenant boundary. The refusal names no owner and does not disclose whether the
+     * balance exists; surface it as it stands rather than inferring more from it than it says.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With code `unknown_usage` (404) if there is no such usage balance
+     *   *or* the attested party does not own it (the caller cannot tell which), or
+     *   `invalid_usage_id` (400) if that is not a usage-balance id.
+     */
+    async usage(usageId, options) {
+        return this.#send({
+            method: "GET",
+            path: `usages/${encodeURIComponent(usageId)}`,
+            headers: this.#authorize("a usage balance"),
+            options,
+        });
+    }
+    /**
+     * The one funnel every call goes through: build, send, then decode.
+     *
+     * The whole of this client's wire handling lives here — which is the point. A success
+     * body decodes into `T`; a failure body decodes through {@link errorFromBody} into the
+     * class that says what to do about it, with its **extras intact**. A generic client
+     * would flatten those extras away, and without `pinned`/`active` no client can re-pin,
+     * and without `primary_api_addr` none can tell which replica holds the primary.
+     *
+     * It does **not** decide who the caller is. The `Authorization` header arrives already
+     * built, from {@link #authorize}, and only the party-scoped reads ask for it: a submit
+     * carries its attestation *inside* the envelope, and `policies/active` discloses no
+     * party's data and needs none. A funnel that credentialed everything by default is the
+     * mechanism this replaced.
+     *
+     * The body is read as **text** before being parsed, so that a body which fails to
+     * parse can be handed to a human verbatim. An unreadable failure is exactly the moment
+     * you need to see the actual bytes.
+     *
+     * On `authorize`'s lane, or for a read under a {@link AxorumClientOptions.retry | retry}
+     * policy, a send that failed in transit is re-sent with the same bytes and the same
+     * `x-request-id`, to the same endpoint or the next, exactly as `acton-service-client`
+     * 0.2.1 does for the Rust SDK; `retry.ts` and `failover.ts` hold the rules. When the
+     * budget stops the loop, the last answer or failure is what the call ends on, or an
+     * {@link EndpointsExhaustedError} carrying every attempt once the call has moved
+     * endpoints; a request the deadline left no time to send is a
+     * {@link DeadlineExceededError}.
+     */
+    async #send(request) {
+        const url = this.#url(request.path, request.query, request.root === true);
+        const headers = {
+            accept: "application/json",
+            // Always present, generated when not supplied: a request you cannot correlate with
+            // a log line is a request you cannot debug. The same id rides every re-send.
+            "x-request-id": request.options?.requestId ?? crypto.randomUUID(),
+            ...request.headers,
+        };
+        if (request.body !== undefined) {
+            headers["content-type"] = "application/json";
+        }
+        // `stringifyJson`, not `JSON.stringify`: the envelope carries 128-bit money as
+        // `bigint`, which `JSON.stringify` refuses outright.
+        const body = request.body === undefined ? undefined : stringifyJson(request.body);
+        const caller = request.options?.signal;
+        const { bound, lane } = request;
+        const policy = sendPolicy(request.method, lane, this.#retry);
+        // A submission on the lane re-sends `421` too; its reads, being reads, need not.
+        const retryOn = lane !== undefined && request.method === "POST" ? AUTHORIZE_RESENT_STATUSES : [];
+        const attemptMs = lane === undefined ? request.attemptMs : (request.attemptMs ?? SUBMIT_ATTEMPT_FALLBACK_MS);
+        const started = performance.now();
+        // Whichever comes first: the call's, the submission's own, the policy's.
+        const deadline = earliest(earliest(lane?.deadline, bound?.deadline), policy?.deadlineMs === undefined ? undefined : started + policy.deadlineMs);
+        const remaining = () => deadline === undefined ? undefined : Math.max(0, deadline - performance.now());
+        const failover = new Failover(this.#endpoints.length, this.#preferred.value);
+        // The previous attempt's failure, ended on if the budget runs out before the next,
+        // and whether its status was a documented answer.
+        let last;
+        // `listed`: the loop gave up on `final` while it still asked for another try, so the
+        // trace ends with it. On `authorize`'s lane such an answer is returned with every
+        // attempt before it, as the Rust SDK reads `AttemptTrace` off the response, so
+        // `authorize` can tell a call that reached nothing able to apply it from one that
+        // may have committed. The caller's lane keeps the plain error.
+        const finish = (stop, final, listed) => {
+            const elapsedMs = performance.now() - started;
+            if (final === undefined) {
+                throw new DeadlineExceededError(failover.attempts, elapsedMs);
+            }
+            if (stop === "exhausted" && !final.accepted) {
+                throw new EndpointsExhaustedError(failover.trace(this.#endpoints), final.error, elapsedMs);
+            }
+            if (listed && final.accepted && lane !== undefined) {
+                throw new EndpointsExhaustedError(failover.trace(this.#endpoints), final.error, elapsedMs);
+            }
+            throw final.error;
+        };
+        // The endpoint of the attempt sent last.
+        let sentTo;
+        const ended = () => {
+            const at = sentTo === undefined ? undefined : this.#endpoints[sentTo];
+            if (at !== undefined) {
+                request.onEnded?.(at);
+            }
+        };
+        for (;;) {
+            const step = failover.begin(remaining());
+            if ("stop" in step) {
+                ended();
+                return finish(step.stop, last, false);
+            }
+            // A re-send is heard as it goes out, so a pause that reaches the deadline ends the
+            // loop unheard, as acton's does.
+            if (step.resend !== undefined) {
+                const { resend } = step;
+                const at = this.#endpoints[resend.kind === "rotation" ? resend.from : step.endpoint];
+                if (at !== undefined) {
+                    bound?.onResend({ endpoint: at, outcome: resend.reason, rotated: resend.kind === "rotation" });
+                }
+                this.#observe(resend, step.endpoint, step.number);
+            }
+            sentTo = step.endpoint;
+            const timeoutMs = attemptTimeout(undefined, attemptMs, this.#timeoutMs, remaining()) ?? this.#timeoutMs;
+            const target = this.#endpoints.length === 1 ? url : onEndpoint(url, this.#endpoints[step.endpoint] ?? url);
+            const exchanged = await this.#exchange(target, request.method, headers, body, caller, timeoutMs);
+            let outcome;
+            let failed;
+            if ("failure" in exchanged) {
+                outcome = outcomeOfTransport(exchanged.connect, exchanged.timeout);
+                failed = { error: exchanged.failure, accepted: false };
+            }
+            else {
+                const { status, text } = exchanged;
+                if (status >= 200 && status < 300) {
+                    request.onHeaders?.(exchanged.headers, status);
+                    this.#preferred.value = step.endpoint;
+                    if (request.headersOnly === true) {
+                        return undefined;
+                    }
+                    try {
+                        return parseJson(text);
+                    }
+                    catch (error) {
+                        throw new DecodeError(status, describe(error), text);
+                    }
+                }
+                const accepted = CONTRACT_STATUSES.has(status);
+                outcome = outcomeOfStatus(status, exchanged.retryAfterMs, accepted, retryOn);
+                if (outcome.kind !== "rotate") {
+                    this.#preferred.value = step.endpoint;
+                }
+                failed = { error: failure(status, text, exchanged.retryAfterMs ?? null), accepted };
+            }
+            const next = failover.after(outcome, policy, Math.random, remaining());
+            if ("stop" in next) {
+                ended();
+                return finish(next.stop, failed, outcome.kind !== "final");
+            }
+            last = failed;
+            if (next.kind === "after") {
+                await pause(next.pauseMs, caller);
+            }
+        }
+    }
+    /**
+     * Tells {@link AxorumClientOptions.onRotation} or {@link AxorumClientOptions.onRetry}
+     * about a re-send as it goes out, if either listens. What they throw is ignored: an
+     * observer's failure is not the call's.
+     */
+    #observe(resend, endpoint, attempt) {
+        try {
+            if (resend.kind === "rotation") {
+                const left = this.#endpoints[resend.from];
+                if (left !== undefined) {
+                    this.#onRotation?.(left, resend.reason);
+                }
+            }
+            else {
+                const at = this.#endpoints[endpoint];
+                if (at !== undefined) {
+                    this.#onRetry?.(at, resend.reason, attempt);
+                }
+            }
+        }
+        catch {
+            // Documented as ignored.
+        }
+    }
+    /**
+     * One send, bounded by `timeoutMs`: the status and body text, or the transport failure
+     * and how it ended (a connection that never opened, or the timeout).
+     */
+    async #exchange(url, method, headers, body, caller, timeoutMs) {
+        // Whole milliseconds: a timer takes no fraction, and rounding up never cuts an
+        // attempt short of its budget.
+        const timeout = AbortSignal.timeout(Math.ceil(timeoutMs));
+        const signal = caller === undefined ? timeout : AbortSignal.any([caller, timeout]);
+        let response;
+        try {
+            response = await this.#fetch(url, {
+                method,
+                headers,
+                ...(body === undefined ? {} : { body }),
+                // A redirect could lead out of the endpoint set; none is followed with more
+                // than one endpoint, and the 3xx ends the call.
+                ...(this.#endpoints.length > 1 ? { redirect: "manual" } : {}),
+                signal,
+            });
+        }
+        catch (error) {
+            // A cancellation the caller asked for is not a failure of the ledger, and is not
+            // dressed up as one — it is rethrown exactly as it was raised.
+            if (caller?.aborted === true) {
+                throw error;
+            }
+            if (!timeout.aborted && isConnectFailure(error)) {
+                return {
+                    failure: new ConnectError(`no connection to the Axorum ledger service could be opened, so nothing was sent: ${describe(error)}`, error),
+                    connect: true,
+                    timeout: false,
+                };
+            }
+            return {
+                failure: new TransportError(`the Axorum ledger service could not be reached: ${describe(error)}`, error),
+                connect: false,
+                timeout: timeout.aborted,
+            };
+        }
+        const status = response.status;
+        try {
+            const text = await response.text();
+            return {
+                status,
+                text,
+                headers: response.headers,
+                retryAfterMs: parseRetryAfter(response.headers.get("retry-after")),
+            };
+        }
+        catch (error) {
+            if (caller?.aborted === true) {
+                throw error;
+            }
+            return {
+                failure: new TransportError(`the Axorum ledger service's ${status} response body could not be read: ${describe(error)}`, error),
+                connect: false,
+                timeout: false,
+            };
+        }
+    }
+    /**
+     * Builds the absolute URL for a route: `{baseUrl}/api/v1/{path}[?query]`, or
+     * `{baseUrl}/{path}` for a route at the application root.
+     */
+    #url(path, query, root = false) {
+        const url = new URL(root ? `${this.#baseUrl}/${path}` : `${this.#baseUrl}${BASE_PATH}/${path}`);
+        if (query !== undefined) {
+            for (const [key, value] of Object.entries(query)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url.toString();
+    }
+}
+/**
+ * The error a non-2xx answer raises: the documented class its agent-plane error body
+ * names, {@link RateLimitedError} for the service's own limiter's `429`, or
+ * {@link UnexpectedResponseError} carrying the bytes verbatim when the body is neither
+ * (a proxy, a gateway, a load balancer).
+ */
+function failure(status, text, retryAfterMs) {
+    let body;
+    try {
+        body = parseJson(text);
+    }
+    catch {
+        return new UnexpectedResponseError(status, text);
+    }
+    const limited = limiterMessage(status, body);
+    if (limited !== undefined) {
+        return new RateLimitedError(limited);
+    }
+    if (!isErrorBody(body)) {
+        return new UnexpectedResponseError(status, text);
+    }
+    return errorFromBody(status, body, retryAfterMs);
+}
+/**
+ * The limiter's `error` text when `body` is the `429` the service's own rate limiter
+ * answers with (`code: "RATE_LIMIT_EXCEEDED"`), or `undefined`. Pure.
+ */
+function limiterMessage(status, body) {
+    if (status !== 429 || typeof body !== "object" || body === null) {
+        return undefined;
+    }
+    const { code, error } = body;
+    if (code !== RATE_LIMIT_EXCEEDED) {
+        return undefined;
+    }
+    return typeof error === "string" ? error : "";
+}
+/**
+ * The local checks {@link AxorumClient.submitKeyed} makes before anything is sent: the
+ * envelope carries the key's id, and the window still covers the key.
+ *
+ * @internal Exported for tests.
+ * @throws {ConfigError | StaleIdempotencyKeyError}
+ */
+export function checkKeyed(key, window, envelope, nowMs) {
+    if (envelope.transaction !== key.transaction) {
+        throw new ConfigError(`the envelope's transaction '${envelope.transaction}' is not the key's '${key.transaction}': ` +
+            `a key vouches only for its own id. Build the envelope with transaction: key.transaction.`);
+    }
+    ensureFresh(key, window, nowMs);
+}
+/**
+ * Refuses an envelope that carries no mint time, before it is sent: `minted_at_ms` must
+ * be a non-negative `bigint` of milliseconds since the Unix epoch, as the wire type says. The type
+ * requires it; this holds a caller the type cannot reach (plain JavaScript, a cast).
+ * Pure.
+ *
+ * @internal Exported for tests.
+ * @throws {ConfigError}
+ */
+export function checkMinted(envelope) {
+    const minted = envelope.minted_at_ms;
+    if (typeof minted !== "bigint" || minted < 0n) {
+        throw new ConfigError(`the envelope for transaction '${envelope.transaction}' carries no minted_at_ms: ` +
+            `build it with pinIntent, or set the time its transaction id was first issued`);
+    }
+}
+/**
+ * Validates the base URL and strips any trailing slash, so that joining `/api/v1` to it
+ * never produces a double slash.
+ *
+ * @throws {ConfigError} If it is not an absolute `http`/`https` URL.
+ */
+function normalizeBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new ConfigError(`the Axorum client could not be built: '${baseUrl}' is not a URL`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new ConfigError(`the Axorum client could not be built: '${baseUrl}' is not an http or https URL`);
+    }
+    return baseUrl.replace(/\/+$/, "");
+}
+/** The best available prose for a thrown value, without assuming it is an `Error`. */
+function describe(error) {
+    if (error instanceof Error) {
+        return error.message === "" ? error.name : error.message;
+    }
+    return String(error);
+}
+/**
+ * Why a submission attempt waits {@link SUBMIT_ATTEMPT_FALLBACK_MS}: the service
+ * advertises no commit wait (`failure` absent), or reading it failed with `failure`.
+ * Pure. Internal: exported for this package's tests, never from its index.
+ */
+export function fallbackNote(failure) {
+    return failure === undefined
+        ? `the service advertises no ${SUBMIT_TIMEOUT_HEADER}; each submission attempt waits the ` +
+            `${SUBMIT_ATTEMPT_FALLBACK_MS} ms fallback`
+        : `reading the service's commit wait failed (${describe(failure)}); this submission attempt ` +
+            `waits the ${SUBMIT_ATTEMPT_FALLBACK_MS} ms fallback`;
+}
+/** The earlier of two deadlines, either of which may be absent. Pure. */
+export function earliest(a, b) {
+    return a === undefined ? b : b === undefined ? a : Math.min(a, b);
+}
+/**
+ * The retry policy a request is sent under, or `undefined` to send it once. Pure.
+ *
+ * `authorize`'s lane re-sends every request of the call, its `POST /intents` included:
+ * the service answers a resubmitted transaction id with the stored outcome, never
+ * applying it twice (`POST /intents`, crates/axorum-serve/src/routes/agent.rs), so a
+ * re-send to the same endpoint or the next is safe. Off the lane only reads are
+ * re-sent: a caller's own envelope is sent once, to one endpoint.
+ */
+export function sendPolicy(method, lane, retry) {
+    if (lane !== undefined) {
+        return lane.retries ? AUTHORIZE_RETRY_POLICY : undefined;
+    }
+    return method === "GET" ? retry : undefined;
+}
+/** What a client built with one endpoint logs, once per process. */
+export const ONE_ENDPOINT_WARNING = "one endpoint configured: an LB routing to the primary is assumed";
+/** Whether {@link ONE_ENDPOINT_WARNING} has been emitted in this process. */
+const oneEndpoint = { warned: false };
+/** Emits {@link ONE_ENDPOINT_WARNING} for the first client built with one endpoint. */
+function warnOneEndpoint(baseUrl) {
+    warnOnce(oneEndpoint, emitWarning, baseUrl);
+}
+/**
+ * Emits {@link ONE_ENDPOINT_WARNING}, naming `baseUrl`, unless `state` says it already
+ * was. The testable seam of {@link warnOneEndpoint}.
+ */
+export function warnOnce(state, emit, baseUrl) {
+    if (state.warned) {
+        return;
+    }
+    state.warned = true;
+    emit(`${ONE_ENDPOINT_WARNING} (${baseUrl}); name every replica in failoverUrls otherwise`);
+}
+/**
+ * A process warning where the runtime has them (Node's `process.emitWarning`, which
+ * `--no-warnings` silences and `process.on("warning")` observes), `console.warn`
+ * elsewhere.
+ */
+function emitWarning(message) {
+    const process = globalThis
+        .process;
+    if (typeof process?.emitWarning === "function") {
+        process.emitWarning(message, { type: "AxorumWarning", code: "AXORUM_ONE_ENDPOINT" });
+    }
+    else {
+        console.warn(message);
+    }
+}
+/** Waits `ms` before a re-send, or rejects with the caller's reason if it cancels first. */
+async function pause(ms, caller) {
+    caller?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(caller?.reason);
+        };
+        const timer = setTimeout(() => {
+            caller?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        caller?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Whether `ms` is a budget `authorizeDeadlineMs` accepts: whole, positive, at most 15 000. Pure. */
+export function validAuthorizeDeadline(ms) {
+    return Number.isSafeInteger(ms) && ms > 0 && ms <= AUTHORIZE_DEADLINE_MS;
+}
+//# sourceMappingURL=client.js.map