@axorum/client 0.0.0-stage → 1.0.0

package/dist/errors.js

@@ -0,0 +1,928 @@
+/**
+ * Why a call to the Axorum agent plane failed — and what to do about it.
+ *
+ * # A refusal is not in here
+ *
+ * The single most important thing to know about this module is what it does **not**
+ * contain. An intent the policy in force forbids is not an error: it reaches the
+ * commit point, is judged, and is *recorded*, and that recording is the product. It
+ * resolves as an {@link AgentOutcome} with `posted: false` and
+ * `verdict: "ForbiddenRejected"`, over a `200`. A client that threw on a refusal would
+ * be throwing away the very artifact the ledger exists to produce.
+ *
+ * What *is* in here are the cases where the ledger never got to answer: the caller was
+ * not who they said they were, the pin did not hold, the cluster could not confirm,
+ * the wire broke.
+ *
+ * # Discriminating
+ *
+ * Two ways, both first-class — use whichever reads better where you are:
+ *
+ * ```ts
+ * // `instanceof`, when you want the narrowed fields:
+ * if (error instanceof StalePolicyError) {
+ *   console.log(error.pinned, error.active); // both typed `string`
+ * }
+ *
+ * // `switch` on `code`, when you want exhaustiveness:
+ * switch (error.code) {
+ *   case "commit_unavailable":   // proposed; may or may not have landed — retry is safe
+ *   case "idempotency_unseeded": // this request was not written and will not be; an
+ *                                // earlier attempt with the same transaction id may
+ *                                // still land — retry is safe
+ *   case "idempotency_window_full": // no ledger state changed and the id is not
+ *                                   // recorded; retry the same request after
+ *                                   // `Retry-After`
+ *   case "not_primary":        // may or may not have landed; re-send the same id
+ *                              // through the configured endpoints
+ * }
+ * ```
+ *
+ * # Recovering
+ *
+ * Three accessors say what to do next, and they are deliberately distinct:
+ *
+ * - {@link AxorumError.isRetriable} — re-send the **identical** request. Safe even for
+ *   a submission, because the client-minted `transaction` id is the substrate's
+ *   idempotency key: a replay returns the stored outcome rather than double-posting.
+ * - {@link AxorumError.requiresRepin} — the policy moved. Re-pin against the policy now
+ *   in force and submit again; {@link AxorumClient.submitPinned} does this for you.
+ * - {@link NotPrimaryError.primaryApiAddr}: you reached a follower. It names the
+ *   primary's API origin as the follower last knew it, a hint that can name a primary
+ *   that has just died. The client does not route on it; re-send the same transaction
+ *   id through the configured endpoints.
+ *
+ * @packageDocumentation
+ */
+import { describeAttempt } from "./failover.js";
+/**
+ * The stable `snake_case` codes the frozen contract documents.
+ *
+ * An **open vocabulary**: a newer service may invent a code this client has never
+ * heard of, and must still be readable. So {@link AxorumErrorCode} does not close the
+ * set — this array is what {@link isKnownErrorCode} tests against.
+ */
+export const WIRE_ERROR_CODES = [
+    "invalid_transaction_id",
+    "invalid_account_id",
+    "invalid_usage_id",
+    // `unauthorized` is what a party-scoped read earns when no `Authorization` header reaches
+    // the service at all. This client normally refuses that read locally — see
+    // {@link MissingAttestationError} — but a caller driving the wire another way will see it,
+    // and the contract documents it on every scoped read.
+    "unauthorized",
+    "unknown_agent",
+    "attestation",
+    // `forbidden` is `?actor=` naming a party other than the one the attestation is bound to.
+    // The only 403 on the plane that is not an attestation failure.
+    "forbidden",
+    "unknown_transaction",
+    "unknown_account",
+    "unknown_usage",
+    "stale_policy",
+    "policy_pin_mismatch",
+    "no_active_policy",
+    "not_primary",
+    "invalid_agent_uri",
+    "capability_mapping",
+    "multi_currency_mandate_charge",
+    "substrate_rejected",
+    "invalid_fulfillment",
+    "gateway_error",
+    "commit_unavailable",
+    // The post-upgrade idempotency seed (contract 5.0.0), on which nothing was written:
+    // `503 idempotency_unseeded` is retriable once the primary seeds its index; `500
+    // idempotency_seed_refused` is not, until the primary changes.
+    "idempotency_unseeded",
+    "idempotency_seed_refused",
+    // A replica that refused a proposal before making it (cluster mode): `503 not_normal`
+    // while it is in a view change or a recovery, `503 archive_pressure` while the primary's
+    // local archive is past its hold ceiling. Nothing was written; both are retriable.
+    "not_normal",
+    "archive_pressure",
+    // `503 quarantined`: replay verification found a divergence on the node, which refuses
+    // every request until an operator resolves it. `500 proposal_refused`: the node refused
+    // the proposal for a reason this build does not name. Nothing was written; neither is
+    // retriable.
+    "quarantined",
+    "proposal_refused",
+    // `transaction_reused` is a committed transaction id resubmitted with different content
+    // (contract 5.0.0). Nothing was written; the committer sees both content hashes, anyone else neither.
+    "transaction_reused",
+    // `stale_idempotency_key` is a retry key older than the window less the skew margin
+    // (contract 5.0.0). Nothing was written. The client raises the same code itself
+    // (StaleIdempotencyKeyError) when it refuses a key before sending, so one `switch`
+    // arm covers both.
+    "stale_idempotency_key",
+    // `invalid_key_mint` is a retry key whose mint time is more than the skew margin ahead of
+    // the service's clock, or disagrees with the time its UUIDv7 id records (contract 5.0.0).
+    // Nothing was written; the message names the check and its bound.
+    "invalid_key_mint",
+    // A body refused before the handler ran (contract 5.0.0). Nothing was written:
+    // `invalid_envelope` (422) names the field's path and a short reason, never the value
+    // sent; `unsupported_media_type` (415) is a body without `application/json`;
+    // `body_too_large` (413) exceeds the route's size limit.
+    "invalid_envelope",
+    "unsupported_media_type",
+    "body_too_large",
+    // `idempotency_window_full` is a `507`: the idempotency index is at its byte budget
+    // (contract 6.0.0). Refused at apply: no ledger state changed and the id is not
+    // recorded. Ids already held still replay, and the same request succeeds once a sweep
+    // evicts aged ids, so it is retriable.
+    "idempotency_window_full",
+    // `snapshot_capacity` is a `507`: cluster mode, the primary's next snapshot frame would
+    // not fit (contract 6.0.0). Nothing was written; retriable once a sweep or an operator
+    // makes room.
+    "snapshot_capacity",
+];
+/**
+ * The codes this client raises on its own behalf, when the service never spoke.
+ *
+ * They are not wire codes and never appear in an error body — they are here so that
+ * every {@link AxorumError} has a `code` you can `switch` on, whether or not the
+ * failure got as far as an HTTP response.
+ */
+export const CLIENT_ERROR_CODES = [
+    "config",
+    "missing_attestation",
+    // A connection that never opened: nothing was sent.
+    "connect",
+    "transport",
+    // The service's own rate limiter shed the request before any handler ran.
+    "rate_limited",
+    // A request whose deadline passed before it was sent.
+    "deadline_exceeded",
+    "endpoints_exhausted",
+    "unexpected_response",
+    "decode",
+    // A spec fetch whose headers stated no idempotency window.
+    "idempotency_window",
+    "invalid_payment",
+    "invalid_agent",
+    "authorize",
+];
+/** Whether `code` is one this version of the contract documents. */
+export function isKnownErrorCode(code) {
+    return WIRE_ERROR_CODES.includes(code);
+}
+/**
+ * The base class of every failure this client raises.
+ *
+ * Abstract on purpose: you never construct one, you catch one. Every subclass carries
+ * a stable {@link AxorumError.code}, so `instanceof` and `switch (error.code)` are both
+ * available and both correct.
+ */
+export class AxorumError extends Error {
+    /** The HTTP status, or `null` when there was no HTTP answer to have one. */
+    status;
+    /** The service's structured error body, when it sent one. */
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = new.target.name;
+        this.status = status;
+        this.body = body;
+    }
+    /**
+     * Whether re-sending the **identical** request may succeed.
+     *
+     * True for a transport failure, for an unconfirmed commit, and for
+     * `503 idempotency_unseeded` (see {@link ApiError.isRetriable}). It is safe to retry a
+     * *submission* on any of them, because the `transaction` id in the envelope is
+     * client-minted and is the substrate's idempotency key: an identical resubmission of
+     * a transaction that already committed returns its stored outcome, marked
+     * `replayed: true`. You cannot double-post by retrying **within the service's
+     * idempotency window** ({@link AxorumClient.idempotencyWindow}, 24 hours at least);
+     * past it the answer is undefined, which is what {@link AxorumClient.submitKeyed}
+     * guards against.
+     *
+     * False for a stale pin (the identical request would fail identically — see
+     * {@link requiresRepin}) and for `not_primary` (the identical request to the *same*
+     * replica would fail identically; it has to go to the primary).
+     */
+    get isRetriable() {
+        return false;
+    }
+    /**
+     * Whether the fix is to re-pin the envelope against the policy now in force.
+     *
+     * True exactly for the `409` pin failures. {@link AxorumClient.submitPinned} acts on
+     * this for you.
+     */
+    get requiresRepin() {
+        return false;
+    }
+    /**
+     * Whether this answer proves the attempt that received it changed nothing a retry
+     * could duplicate: no ledger state, and no record of its transaction id.
+     *
+     * Not whether the call failed, nor what an earlier attempt did. An answer qualifies in
+     * one of two ways:
+     *
+     * - **Refused before it was proposed.** Nothing reached the log. Every member below is
+     *   this kind.
+     * - **Refused when it was applied.** The operation is in the log, but the ledger's
+     *   state did not change and the id was not recorded, so a retry once the window has
+     *   room commits fresh rather than replaying. A `507` code of this kind joins
+     *   {@link WROTE_NOTHING_507} with its contract row.
+     *
+     * The members, each with what proves it:
+     *
+     * | Class | Why it changed nothing |
+     * |---|---|
+     * | {@link ConnectError} | no connection opened, so no byte of the request left the process |
+     * | {@link RateLimitedError} | the service's limiter answers before any handler runs; rate-shed requests never reached the ledger (`docs/export-and-portability.md`) |
+     * | {@link ApiError} `503 idempotency_unseeded`, `500 idempotency_seed_refused`, `503 not_normal` or `503 archive_pressure`, its body read ({@link WROTE_NOTHING_UNPROPOSED}) | the replica turned the request away before proposing it: the contract row for each code |
+     * | {@link ApiError} with status `507` and a code in {@link WROTE_NOTHING_507} | the contract row for that code (`idempotency_window_full`, `snapshot_capacity`) |
+     * | {@link ConfigError}, {@link MissingAttestationError}, {@link InvalidPaymentError}, {@link InvalidAgentError}, {@link StaleIdempotencyKeyError}, {@link IdempotencyWindowError} | raised by this client before the request was sent |
+     * | {@link DeadlineExceededError} with `attempts: 0` | the deadline passed before the first attempt |
+     *
+     * Everything else is `false`, a status this version does not know included: a timeout
+     * or a broken connection after the request went out ({@link TransportError}), a `429`
+     * in any shape but the limiter's ({@link UnexpectedResponseError}), `421`, `423`, a
+     * `503` whose body is not listed (`commit_unavailable`, or one re-sent on its
+     * status alone, whose body no one read), and a `507` whose code is not listed. The same
+     * members as the Rust SDK's `AxorumError::wrote_nothing`.
+     *
+     * ```ts
+     * new ConnectError("connection refused").wroteNothing; // true
+     * new TransportError("timed out").wroteNothing; // false
+     * new UnexpectedResponseError(429, "<html>").wroteNothing; // false
+     * ```
+     */
+    get wroteNothing() {
+        return false;
+    }
+}
+/**
+ * The `507` error codes the agent-plane contract lists as changing **nothing a retry
+ * could duplicate**, so {@link AxorumError.wroteNothing} reads them as definite. A `507`
+ * with any other code may have written.
+ *
+ * A code qualifies either way {@link AxorumError.wroteNothing} describes: refused before
+ * it was proposed, or refused when applied with no state change and its id not recorded.
+ *
+ * The contract lists two: `idempotency_window_full`, refused at apply with no state
+ * change and its id not recorded, and `snapshot_capacity`, refused before it was
+ * proposed. The capacity `507`, `substrate_rejected` with `kind: "capacity"`, is not
+ * listed. A code joins this list with the contract row that says so.
+ */
+export const WROTE_NOTHING_507 = [
+    "idempotency_window_full",
+    "snapshot_capacity",
+];
+/**
+ * The codes a replica answers when it turned the request away before proposing it, each
+ * with the status it arrives on, so nothing reached the log: `503 idempotency_unseeded`,
+ * the primary's index is not seeded yet; `500 idempotency_seed_refused`, the ledger
+ * refused its seed; `503 not_normal`, the replica is in a view change or a recovery;
+ * `503 archive_pressure`, the primary's local archive is past its hold ceiling;
+ * `503 quarantined`, replay verification found a divergence on the node; `500
+ * proposal_refused`, the node refused the proposal for a reason this build does not
+ * name. Definite only with the body read: a `503` re-sent on its status alone may have been
+ * `commit_unavailable`.
+ */
+export const WROTE_NOTHING_UNPROPOSED = [
+    [503, "idempotency_unseeded"],
+    [500, "idempotency_seed_refused"],
+    [503, "not_normal"],
+    [503, "archive_pressure"],
+    [503, "quarantined"],
+    [500, "proposal_refused"],
+];
+/**
+ * Whether an answer with `status` and `code` is a `507` whose code `listed` names as
+ * changing nothing a retry could duplicate. Split on the code, never the status alone.
+ * Pure.
+ *
+ * @internal Exported for tests; {@link ApiError.wroteNothing} passes
+ * {@link WROTE_NOTHING_507}.
+ */
+export function listedAsWritingNothing(status, code, listed) {
+    return status === 507 && listed.includes(code);
+}
+/** The `code` `acton-service`'s rate limiter puts in its `429` body. */
+export const RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED";
+/**
+ * The client could not be built — a base URL that is not a URL, for instance.
+ *
+ * Thrown by the {@link AxorumClient} constructor, before any request exists.
+ */
+export class ConfigError extends AxorumError {
+    code = "config";
+    constructor(message) {
+        super(message, null, null);
+    }
+    /** Raised before the request was sent. */
+    get wroteNothing() {
+        return true;
+    }
+}
+/**
+ * A party-scoped read was attempted on a client that holds no attestation.
+ *
+ * Raised **before any request leaves the process**, and that is the point. The agent
+ * plane's reads are credentialed: without a token the service would answer `401`, and
+ * relaying that would tell the caller the *service* rejected their credential when in
+ * truth this client never sent one. So the failure names the actual mistake — the client
+ * was built without an `attestation` — and costs no round trip to discover.
+ *
+ * Fix it at construction, or hand an existing client a token with
+ * {@link AxorumClient.withAttestation}.
+ */
+export class MissingAttestationError extends AxorumError {
+    code = "missing_attestation";
+    /** What was being read: `"a balance"`, `"a transaction"`, `"obligations"`. */
+    operation;
+    constructor(operation) {
+        super(`cannot read ${operation}: this client holds no attestation. The agent plane's reads are ` +
+            `answered only in the scope of the party the caller's PASETO attestation is bound to — ` +
+            `build the client with \`new AxorumClient({ baseUrl, attestation })\`, or re-credential ` +
+            `an existing one with \`withAttestation\`.`, null, null);
+        this.operation = operation;
+    }
+    /** Raised before the request was sent. */
+    get wroteNothing() {
+        return true;
+    }
+}
+/**
+ * A {@link Payment} could not be created: a non-positive amount, an unusable payee, or a
+ * timeout that is not a positive number. Raised locally, before any request.
+ *
+ * ```ts
+ * try {
+ *   payment({ amount: { minor: 0n, currency: "USD" }, payee: "api.openai.com" });
+ * } catch (error) {
+ *   if (error instanceof InvalidPaymentError) console.log(error.message);
+ * }
+ * ```
+ */
+export class InvalidPaymentError extends AxorumError {
+    code = "invalid_payment";
+    constructor(message) {
+        super(message, null, null);
+    }
+    /** Raised before the request was sent. */
+    get wroteNothing() {
+        return true;
+    }
+}
+/**
+ * An {@link Agent} could not be created: its URI is not an `agent://` URI in canonical
+ * form, or its attestation is not a PASETO v4.public token. Raised locally, before any
+ * request.
+ *
+ * ```ts
+ * try {
+ *   new Agent("agent://ACME.com/agent/buyer_01h455vb4pex5vsknk084sn02q", token);
+ * } catch (error) {
+ *   if (error instanceof InvalidAgentError && error.canonical !== undefined) {
+ *     console.log(`pass ${error.canonical}`); // agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q
+ *   }
+ * }
+ * ```
+ */
+export class InvalidAgentError extends AxorumError {
+    code = "invalid_agent";
+    /**
+     * The canonical form of a refused URI, with any query or fragment stripped, when that
+     * parses: the string to pass instead.
+     */
+    canonical;
+    constructor(message, canonical) {
+        super(message, null, null);
+        this.canonical = canonical;
+    }
+    /** Raised before the request was sent. */
+    get wroteNothing() {
+        return true;
+    }
+}
+/**
+ * No connection to the service could be opened: connection refused, DNS failure, an
+ * unreachable host. No byte of the request was sent, so it
+ * {@link AxorumError.wroteNothing | wrote nothing}.
+ *
+ * {@link isRetriable} — a dead socket may come back.
+ */
+export class ConnectError extends AxorumError {
+    code = "connect";
+    /** The underlying `fetch` failure, kept so a diagnosis is not a guess. */
+    cause;
+    constructor(message, cause) {
+        super(message, null, null);
+        this.cause = cause;
+    }
+    get isRetriable() {
+        return true;
+    }
+    get wroteNothing() {
+        return true;
+    }
+}
+/**
+ * The request failed after its connection opened: it timed out, or the connection
+ * broke. Some or all of it may have reached the service, so it may have committed.
+ *
+ * {@link isRetriable} — a dead socket may come back.
+ */
+export class TransportError extends AxorumError {
+    code = "transport";
+    /** The underlying `fetch` failure, kept so a diagnosis is not a guess. */
+    cause;
+    constructor(message, cause) {
+        super(message, null, null);
+        this.cause = cause;
+    }
+    get isRetriable() {
+        return true;
+    }
+}
+/**
+ * A request under a deadline was not sent, because the deadline had passed: for
+ * `authorize`, the call's time budget (`AUTHORIZE_DEADLINE_MS`, shared by all of its
+ * requests), or 30 seconds before its attestation's `exp` when that is sooner; or a retry
+ * policy's `deadlineMs`. Nothing was sent by the attempt that raised it.
+ *
+ * {@link isRetriable}: re-drive the same payment; a fresh call has a fresh budget.
+ */
+export class DeadlineExceededError extends AxorumError {
+    code = "deadline_exceeded";
+    /** How many attempts of the request were sent before the deadline passed. */
+    attempts;
+    /** How long the request had run, in milliseconds. */
+    elapsedMs;
+    constructor(attempts, elapsedMs) {
+        super(`the request's deadline passed after ${Math.round(elapsedMs)} ms and ${attempts} attempt(s), ` +
+            `so it was not sent again; re-drive it with the same transaction id`, null, null);
+        this.attempts = attempts;
+        this.elapsedMs = elapsedMs;
+    }
+    get isRetriable() {
+        return true;
+    }
+    /** True when the deadline passed before the first attempt. */
+    get wroteNothing() {
+        return this.attempts === 0;
+    }
+}
+/**
+ * Every endpoint of a {@link AxorumClientOptions.failoverUrls | failover} set failed within
+ * the call's budget, after at least one move to the next endpoint: every attempt, in
+ * order, and the error the last one ended on.
+ *
+ * Any attempt may have been applied, so it never {@link AxorumError.wroteNothing | wrote
+ * nothing}: re-send under the same transaction id and the service replays it.
+ *
+ * {@link isRetriable} — a fresh call has a fresh budget.
+ */
+export class EndpointsExhaustedError extends AxorumError {
+    code = "endpoints_exhausted";
+    /** Every attempt of the call, in the order sent. */
+    attempts;
+    /** The error the last attempt ended on. */
+    last;
+    /** Milliseconds from the call's start to giving up. */
+    elapsedMs;
+    cause;
+    constructor(attempts, last, elapsedMs) {
+        const advice = "an attempt may have been recorded; re-send under the same transaction id and the service replays it";
+        super(`every endpoint failed within the call's time budget (${attempts.length} attempt(s) in ` +
+            `${elapsedMs} ms: ${attempts.map(describeAttempt).join(", ")}); ${advice}. Last: ${last.message}`, last.status, last.body);
+        this.attempts = Object.freeze([...attempts]);
+        this.last = last;
+        this.cause = last;
+        this.elapsedMs = elapsedMs;
+    }
+    get isRetriable() {
+        return true;
+    }
+}
+/**
+ * `409` — the policy pin did not hold, and **nothing was written**.
+ *
+ * Covers both codes that mean it, because the recovery is identical: re-pin against
+ * {@link active} and resubmit. `stale_policy` is the pre-propose fast path;
+ * `policy_pin_mismatch` is the race-closing apply-time check. Which one it was is in
+ * {@link code}, if you care — and for choosing what to do next, you do not.
+ */
+export class StalePolicyError extends AxorumError {
+    code;
+    /** The policy the request pinned. */
+    pinned;
+    /** The policy actually in force. **Re-pin against this one.** */
+    active;
+    constructor(code, message, pinned, active, body) {
+        super(`the policy pin did not hold and nothing was recorded: the request pinned policy '${pinned}', but policy '${active}' is in force — re-pin and resubmit (${message})`, 409, body);
+        this.code = code;
+        this.pinned = pinned;
+        this.active = active;
+    }
+    get requiresRepin() {
+        return true;
+    }
+}
+/**
+ * `409 no_active_policy` — no policy is in force at all.
+ *
+ * Not a pin problem: re-pinning cannot help, because there is nothing to pin to. An
+ * operator has to activate a policy.
+ */
+export class NoActivePolicyError extends AxorumError {
+    code = "no_active_policy";
+    constructor(message, body = null) {
+        super(`no policy is in force on the Axorum ledger service: ${message}`, 409, body);
+    }
+}
+/**
+ * `401 unknown_agent` — the `agent://` URI is not bound to a party.
+ *
+ * An **authentication** failure at the gateway. It never reached the ledger and was
+ * never recorded, which is exactly why it is an error and a refusal is not.
+ */
+export class UnknownAgentError extends AxorumError {
+    code = "unknown_agent";
+    /** The URI that is not bound, when the service named it. */
+    uri;
+    constructor(message, uri, body) {
+        super(uri === null
+            ? `the agent is not bound to a party: ${message}`
+            : `the agent '${uri}' is not bound to a party: ${message}`, 401, body);
+        this.uri = uri;
+    }
+}
+/**
+ * `403 attestation` — the PASETO v4.public capability attestation was rejected: bad
+ * signature, expired, wrong audience, or an untrusted issuer.
+ */
+export class AttestationError extends AxorumError {
+    code = "attestation";
+    constructor(message, body) {
+        super(`the capability attestation was rejected: ${message}`, 403, body);
+    }
+}
+/**
+ * `421 not_primary` — cluster mode: this mutation reached a non-primary replica.
+ *
+ * The attempt may or may not have been recorded: a primary stepping down can answer
+ * `421` after proposing it. The primary's API origin, as the follower last knew it, is
+ * in {@link primaryApiAddr}: a hint, and **this client does not route on it**. Re-send
+ * the same transaction id through the configured endpoints; the ledger applies it at
+ * most once.
+ */
+export class NotPrimaryError extends AxorumError {
+    code = "not_primary";
+    /**
+     * The primary's API origin as the follower last knew it, or none. Informational: it
+     * can name a primary that has just died. The client does not route on it; it rotates
+     * its configured endpoints.
+     *
+     * A `null` in the body and an absent key collapse to the same thing here.
+     */
+    primaryApiAddr;
+    /** Why this replica is not the primary, when it said. */
+    reason;
+    constructor(message, primaryApiAddr, reason, body) {
+        super(primaryApiAddr === null
+            ? `this replica is not the primary, and this attempt may or may not have been recorded: a primary stepping down can answer so after proposing it. It did not know which replica is. Re-send the same transaction id through the configured endpoints: ${message}`
+            : `this replica is not the primary, and this attempt may or may not have been recorded: a primary stepping down can answer so after proposing it. It named '${primaryApiAddr}' as the primary's API origin, a hint that may be stale. Re-send the same transaction id through the configured endpoints: ${message}`, 421, body);
+        this.primaryApiAddr = primaryApiAddr;
+        this.reason = reason;
+    }
+}
+/**
+ * `503 commit_unavailable` — cluster mode: the request was proposed and its commit could
+ * not be confirmed (timeout, node gone, or an ambiguous view change).
+ *
+ * **The mutation may or may not have landed.** {@link isRetriable} is `true`, and
+ * genuinely safe: submission is idempotent by `transaction` id, so re-sending the same
+ * envelope either lands it or replays the outcome it already has. Or read the
+ * transaction back with {@link AxorumClient.transaction} to find out which happened.
+ *
+ * A request stopped before it was proposed is never this error (contract 5.0.0): the
+ * service answers `503 idempotency_unseeded` when its idempotency index is not seeded
+ * yet (this request was not written and will not be; an earlier attempt with the same
+ * transaction id may still land; retriable), and `500 idempotency_seed_refused` when the
+ * ledger refused the seed (nothing written; do not retry). Both arrive as
+ * {@link ApiError}.
+ */
+export class CommitUnavailableError extends AxorumError {
+    code = "commit_unavailable";
+    /** Why the commit is unconfirmed, when the service said. */
+    reason;
+    constructor(message, reason, body) {
+        super(`the commit could not be confirmed, so it may or may not have been recorded; retry or read the transaction back: ${message}`, 503, body);
+        this.reason = reason;
+    }
+    get isRetriable() {
+        return true;
+    }
+}
+/**
+ * `409 transaction_reused` — the transaction id already committed, carrying **different**
+ * content, and **nothing was written**.
+ *
+ * A transaction id is the retry key: resubmitting the identical intent under it answers
+ * the original outcome (`replayed: true`). Anything else under a committed id is a
+ * different transaction wearing an old name, and the ledger refuses to guess which one
+ * the caller meant. To the party that committed the id, both content hashes are here, so
+ * it can see the two are not the same intent without the service echoing any content
+ * back. Any other party is shown neither: the stored hash would tell it what the
+ * committer intended, so both fields are `undefined` and the id is simply taken.
+ *
+ * The fix is one of two, and only the caller knows which: mint a new transaction id for
+ * a genuinely new intent, or resubmit the identical intent to read the original answer.
+ */
+export class TransactionReusedError extends AxorumError {
+    code = "transaction_reused";
+    /**
+     * The SHA-256 of the intent committed under the id, as 64 lowercase hex digits.
+     * Present only to the party that committed the id.
+     */
+    storedContentHash;
+    /**
+     * The SHA-256 of the rejected submission, as 64 lowercase hex digits. Present only to
+     * the party that committed the id, with {@link storedContentHash}.
+     */
+    submittedContentHash;
+    constructor(message, storedContentHash, submittedContentHash, body) {
+        const hashes = storedContentHash !== undefined && submittedContentHash !== undefined
+            ? ` (stored ${storedContentHash}, submitted ${submittedContentHash})`
+            : "";
+        super(`the transaction id already committed with different content and nothing was recorded; ` +
+            `mint a new transaction id for a new intent, or resubmit the identical intent to read ` +
+            `the original outcome${hashes}: ${message}`, 409, body);
+        this.storedContentHash = storedContentHash;
+        this.submittedContentHash = submittedContentHash;
+    }
+}
+/**
+ * A retry key the service's idempotency window no longer covers, refused **before any
+ * request left the process**.
+ *
+ * Within the window, resubmitting a committed transaction id replays the original
+ * outcome. Past it the id may have been forgotten, and the service refuses the
+ * resubmission `409 stale_idempotency_key` rather than commit it a second time. So a
+ * key older than `window_seconds` is not sent. Nothing was written, and nothing can
+ * have been.
+ *
+ * The fix is always the same: **mint a new transaction id**. If the original may have
+ * committed, read it back with {@link AxorumClient.transaction} first.
+ *
+ * `reason: "unclocked"` means the service advertises no wall-clock window (its
+ * heartbeat is disabled, so its window is counted in ticks that have no length in
+ * seconds). No key can be vouched for there, however young.
+ */
+export class StaleIdempotencyKeyError extends AxorumError {
+    code = "stale_idempotency_key";
+    /** The transaction id the key was minted for. */
+    transaction;
+    /** Why the key was refused. */
+    reason;
+    /** The key's age in milliseconds, or `null` when the reason is `"unclocked"`. */
+    ageMs;
+    /** The advertised window in seconds, or `null` when the reason is `"unclocked"`. */
+    windowSeconds;
+    /** The advertised window in server ticks. */
+    windowTicks;
+    constructor(transaction, reason, ageMs, windowSeconds, windowTicks) {
+        super(reason === "unclocked"
+            ? `the retry key for transaction '${transaction}' cannot be vouched for: the service runs ` +
+                `no heartbeat, so its idempotency window is ${windowTicks} ticks with no wall-clock ` +
+                `length. Nothing was sent; mint a new transaction id, or submit without a key check.`
+            : `the retry key for transaction '${transaction}' is ${Math.floor((ageMs ?? 0) / 1000)} ` +
+                `seconds old, past the service's ${windowSeconds} second idempotency window, so a ` +
+                `resubmission might commit twice. Nothing was sent; mint a new transaction id (read ` +
+                `the original back with \`transaction\` if it may have committed).`, null, null);
+        this.transaction = transaction;
+        this.reason = reason;
+        this.ageMs = ageMs;
+        this.windowSeconds = windowSeconds;
+        this.windowTicks = windowTicks;
+    }
+    /** Raised before the request was sent. */
+    get wroteNothing() {
+        return true;
+    }
+}
+/**
+ * The spec fetch answered, but its headers did not state an idempotency window
+ * (contract 5.0.0).
+ *
+ * `reason: "not_advertised"`: the ticks or capacity header is absent, because the
+ * service predates contract 5.0.0 or its writer could not answer. Upgrade the service,
+ * or retry once it is healthy. `reason: "malformed"`: a header is present but states no
+ * count from 1 to `2^64 - 1`; {@link header} and {@link value} name it, and something
+ * (the service or a proxy in front of it) rewrote it.
+ *
+ * Until a window is read no key can be aged, so {@link AxorumClient.submitKeyed} cannot
+ * be used safely.
+ */
+export class IdempotencyWindowError extends AxorumError {
+    code = "idempotency_window";
+    /** Why no window was read. */
+    reason;
+    /** The malformed header's name, or `null` when the reason is `"not_advertised"`. */
+    header;
+    /** The malformed header's value, or `null` when the reason is `"not_advertised"`. */
+    value;
+    constructor(status, reason, header, value) {
+        super(reason === "not_advertised"
+            ? "the Axorum ledger service advertises no idempotency window (it predates contract " +
+                "5.0.0, or its writer could not answer); upgrade the service or retry once it is healthy"
+            : `the Axorum ledger service's \`${header}\` header carries ${JSON.stringify(value)}, which ` +
+                "is not a count from 1 to 18446744073709551615; the service or a proxy in front of it " +
+                "rewrote the header", status, null);
+        this.reason = reason;
+        this.header = header;
+        this.value = value;
+    }
+    /** Raised before the request was sent. */
+    get wroteNothing() {
+        return true;
+    }
+}
+/**
+ * A documented agent-plane error with no more specific class: a bad id, an unknown
+ * account, an unknown transaction, a substrate rejection, a capability-mapping failure.
+ *
+ * These keep their whole {@link body}, extras and all. A class per code would be a
+ * bigger surface that told a caller nothing more — there is only one thing to do about
+ * an unknown account, and it is not a recovery.
+ */
+export class ApiError extends AxorumError {
+    code;
+    /** The full structured body, extras and all. Never `null` on this class. */
+    body;
+    /**
+     * The wait the answer's `Retry-After` asked for, in milliseconds, or `null` when it
+     * named none. Read only: nothing in this client re-sends a `503` or a `507` on it.
+     */
+    retryAfterMs;
+    constructor(status, body, retryAfterMs = null) {
+        super(`the Axorum ledger service returned ${status}: ${body.message} (${body.error})`, status, body);
+        this.code = body.error;
+        this.body = body;
+        this.retryAfterMs = retryAfterMs;
+    }
+    /**
+     * True for `503 idempotency_unseeded`, `503 not_normal`, `503 archive_pressure`,
+     * `507 idempotency_window_full` and `507 snapshot_capacity`: the service had not seeded
+     * its idempotency index, the replica was in a view change, the primary's archive was
+     * behind, the index was at its byte budget, or the primary's snapshot store could not
+     * take the commit. None of them changed ledger state or recorded the id:
+     * `not_normal`, `archive_pressure` and `snapshot_capacity` are refused before they are
+     * proposed, `idempotency_window_full` at apply, and `idempotency_unseeded` at either. Re-sending the identical request is safe (the
+     * `transaction` id is the idempotency key); after a `507`, wait at least
+     * {@link retryAfterMs}. False for every other code here, the generic
+     * `507 substrate_rejected`, `500 idempotency_seed_refused`, `503 quarantined` and
+     * `500 proposal_refused` included: those need an operator.
+     */
+    get isRetriable() {
+        return ((this.status === 503 &&
+            (this.code === "idempotency_unseeded" ||
+                this.code === "not_normal" ||
+                this.code === "archive_pressure")) ||
+            (this.status === 507 &&
+                (this.code === "idempotency_window_full" || this.code === "snapshot_capacity")));
+    }
+    /**
+     * True for an unproposed code on its own status ({@link WROTE_NOTHING_UNPROPOSED}), and for a `507`
+     * whose code is in {@link WROTE_NOTHING_507}.
+     */
+    get wroteNothing() {
+        return (WROTE_NOTHING_UNPROPOSED.some(([status, code]) => this.status === status && this.code === code) ||
+            listedAsWritingNothing(this.status, this.code, WROTE_NOTHING_507));
+    }
+}
+/**
+ * A non-2xx whose body is not an agent-plane error body at all — a proxy's 502 page, a
+ * load balancer's 429, a gateway timeout.
+ *
+ * The bytes are kept **verbatim** in {@link rawBody}: an unreadable failure is exactly
+ * the moment a human needs to see what actually came back, so this class does not
+ * pretend to have understood it.
+ */
+export class UnexpectedResponseError extends AxorumError {
+    code = "unexpected_response";
+    /** The response body, exactly as it arrived. */
+    rawBody;
+    constructor(status, rawBody) {
+        super(`the Axorum ledger service returned an unexpected ${status}: ${rawBody}`, status, null);
+        this.rawBody = rawBody;
+    }
+}
+/**
+ * `429` in the shape the service's own rate limiter answers with
+ * (`{"error": ..., "code": "RATE_LIMIT_EXCEEDED", "status": 429}`): the request was shed
+ * before any handler ran, so it {@link AxorumError.wroteNothing | wrote nothing}. A `429`
+ * in any other shape (a proxy's, a load balancer's) is an
+ * {@link UnexpectedResponseError}, and proves nothing.
+ *
+ * {@link isRetriable} — send it again later.
+ */
+export class RateLimitedError extends AxorumError {
+    code = "rate_limited";
+    /** The limiter's own text, its body's `error`. */
+    detail;
+    constructor(detail) {
+        super(`the Axorum ledger service's rate limiter turned the request away before it was handled ` +
+            `(${detail}); send it again later`, 429, null);
+        this.detail = detail;
+    }
+    get isRetriable() {
+        return true;
+    }
+    get wroteNothing() {
+        return true;
+    }
+}
+/**
+ * A success body that did not decode — the service and this client disagree about the
+ * contract.
+ *
+ * The bytes are kept verbatim in {@link rawBody}, for the same reason as
+ * {@link UnexpectedResponseError}.
+ */
+export class DecodeError extends AxorumError {
+    code = "decode";
+    /** The response body, exactly as it arrived. */
+    rawBody;
+    constructor(status, reason, rawBody) {
+        super(`the Axorum ledger service's ${status} response was not understood: ${reason} (body: ${rawBody})`, status, null);
+        this.rawBody = rawBody;
+    }
+}
+/** Whether `value` is a failure this client raised. A type guard, for a bare `catch`. */
+export function isAxorumError(value) {
+    return value instanceof AxorumError;
+}
+/**
+ * Lifts a parsed agent-plane error body into the class that says what to do about it.
+ *
+ * **A pure function of `(status, body)`** — the whole of this client's error semantics,
+ * testable without a socket, and the reason the taxonomy can be trusted.
+ *
+ * @param status - The HTTP status.
+ * @param body - The parsed error body.
+ * @param retryAfterMs - The answer's `Retry-After`, in milliseconds, when it named one;
+ *   an {@link ApiError} carries it.
+ * @returns The most specific {@link AxorumError} the pair identifies.
+ */
+export function errorFromBody(status, body, retryAfterMs = null) {
+    const { error: code, message } = body;
+    if (status === 409 && (code === "stale_policy" || code === "policy_pin_mismatch")) {
+        // Requires both ids to actually be present. A pin failure that names no policies is
+        // a malformed body, and falls through to `ApiError` rather than being invented: a
+        // client cannot re-pin against a policy id it made up.
+        if (body.pinned !== undefined && body.active !== undefined) {
+            return new StalePolicyError(code, message, body.pinned, body.active, body);
+        }
+        return new ApiError(status, body);
+    }
+    if (status === 409 && code === "transaction_reused") {
+        // Both hashes (the committer's answer) or neither (anyone else's); exactly one is a
+        // malformed body: a caller comparing content cannot compare against a hash the client
+        // invented.
+        const { stored_content_hash: stored, submitted_content_hash: submitted } = body;
+        if ((stored === undefined) === (submitted === undefined)) {
+            return new TransactionReusedError(message, stored, submitted, body);
+        }
+        return new ApiError(status, body);
+    }
+    if (status === 409 && code === "no_active_policy") {
+        return new NoActivePolicyError(message, body);
+    }
+    if (status === 401 && code === "unknown_agent") {
+        return new UnknownAgentError(message, body.uri ?? null, body);
+    }
+    if (status === 403 && code === "attestation") {
+        return new AttestationError(message, body);
+    }
+    if (status === 421 && code === "not_primary") {
+        // The key is present-but-`null` when the follower does not know the primary, and
+        // absent on every other code. Neither gives a caller an address to act on, so both
+        // become `null`.
+        return new NotPrimaryError(message, body.primary_api_addr ?? null, body.reason ?? null, body);
+    }
+    if (status === 503 && code === "commit_unavailable") {
+        return new CommitUnavailableError(message, body.reason ?? null, body);
+    }
+    return new ApiError(status, body, retryAfterMs);
+}
+/**
+ * Whether a parsed JSON value is an agent-plane error body.
+ *
+ * The contract requires exactly two fields of every error body — `error` and `message`
+ * — so those two are what identify one. A non-2xx body without them did not come from
+ * the agent plane; it came from something in front of it.
+ */
+export function isErrorBody(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate["error"] === "string" && typeof candidate["message"] === "string";
+}
+//# sourceMappingURL=errors.js.map