@axorum/client 0.0.0-stage → 1.0.0

package/dist/authorize.d.ts

@@ -0,0 +1,671 @@
+/**
+ * The one-call `authorize`: who is paying, whether they may, and the pin loop that gets
+ * the ledger's answer.
+ *
+ * Everything here but {@link runAuthorize} is a pure function, testable without a
+ * socket. Re-sending a request that failed in transit is the client's job, under
+ * `authorize`'s own policy and one deadline for the call; see `retry.ts`.
+ *
+ * @packageDocumentation
+ */
+import { AxorumError, IdempotencyWindowError, type StaleKeyReason, type WindowHeaderReason } from "./errors.js";
+import { type EndpointAttempt } from "./failover.js";
+import { pinIntent } from "./intent.js";
+import { type IdempotencyKey } from "./idempotency.js";
+import { type RetryReason } from "./retry.js";
+import { type Payment } from "./payment.js";
+import type { AgentOutcome, Envelope, ErrorBody, IdempotencyWindow, ObligationInstance, Refusal } from "./types.js";
+/**
+ * Where the agent's attestation comes from: a token, or a function asked for one on
+ * **every submission** (the first, and each re-pin), so a token that expired meanwhile
+ * is replaced rather than resent. A transport re-send carries the same bytes.
+ */
+export type AttestationSource = string | (() => Promise<string>);
+/**
+ * The paying agent: its `agent://` URI and where its attestation comes from.
+ *
+ * The URI must be in **canonical form**: the complete grammar the service parses, with a
+ * lowercase host, a port without leading zeros, an IPv6 address as RFC 5952 writes it,
+ * and no query or fragment. A keyed payment derives its id from these exact bytes, so
+ * one spelling per agent is what makes this SDK and the Rust one derive the same id. The
+ * service answers `unknown_agent` for a well-formed URI no party is bound to.
+ *
+ * ```ts
+ * import { Agent } from "@axorum/client";
+ *
+ * // A static token:
+ * const buyer = new Agent("agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q", paseto);
+ *
+ * // Or a source asked on every submission, so an expiring token is refreshed:
+ * const refreshing = new Agent(
+ *   "agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q",
+ *   () => issuer.mint(),
+ * );
+ * ```
+ */
+export declare class Agent {
+    #private;
+    /** The `agent://` URI, in canonical form: exactly the string the constructor accepted. */
+    readonly uri: string;
+    /**
+     * @throws {InvalidAgentError} If `uri` is not an `agent://` URI in canonical form (its
+     *   `canonical` then names the form to pass, when there is one), or a static
+     *   attestation is not a PASETO v4.public token.
+     */
+    constructor(uri: string, attestation: AttestationSource);
+    /**
+     * The attestation for one submission: the token, or a fresh one from the source,
+     * with at least {@link ATTESTATION_MIN_REMAINING_MS} left before its `exp`.
+     *
+     * The service allows no leeway on `exp`, and a submission may be re-sent for up to
+     * its budget, so a token with less left could expire between two sends of the same
+     * payment. A source whose token is that close is asked once more; nothing is sent
+     * unless a token is fresh.
+     *
+     * @param now - The current time in epoch milliseconds; the system clock by default.
+     * @throws {AuthorizeError} Of kind `attestation_expiring` if no token had enough time
+     *   left, or `attestation_unavailable` if the source failed or returned a token whose
+     *   claims cannot be read.
+     */
+    attestation(transaction: string, now?: () => number): Promise<string>;
+}
+/** Why `token` is not a usable PASETO v4.public token, or `undefined`. Pure. */
+export declare function attestationProblem(token: string): string | undefined;
+/** The policy allowed the payment, and its legs posted. Pay. */
+export interface Allowed {
+    readonly allowed: true;
+    /** The payment's transaction id. */
+    readonly transaction: string;
+    /** Duties the agent now owes, such as filing a receipt. */
+    readonly obligations: readonly ObligationInstance[];
+    /** The signed receipt, when the deployment signs. */
+    readonly receipt: Envelope | undefined;
+    /**
+     * Whether this answer is the stored one for a transaction that had already committed
+     * (a re-drive), rather than a fresh judgement. A replay carries the **original**
+     * `justification_hash`; see {@link justificationMatches}.
+     */
+    readonly replayed: boolean;
+    /** The ledger's full answer. */
+    readonly outcome: AgentOutcome;
+}
+/** The policy refused the payment. It is recorded, nothing posted. Do not pay. */
+export interface Refused {
+    readonly allowed: false;
+    /** The payment's transaction id. */
+    readonly transaction: string;
+    /** Why: branch on `code` or `rule.name`, show `explanation` to a human. */
+    readonly refusal: Refusal;
+    /** The signed receipt of the refusal, when the deployment signs. */
+    readonly receipt: Envelope | undefined;
+    /** Whether this is the stored answer of an already-committed transaction. */
+    readonly replayed: boolean;
+    /** The ledger's full answer. */
+    readonly outcome: AgentOutcome;
+}
+/**
+ * The ledger's answer to a payment: {@link Allowed} or {@link Refused}. A refusal is an
+ * answer, not an error.
+ *
+ * ```ts
+ * const answer = await axorum.authorize(buyer, lunch);
+ * if (answer.allowed) {
+ *   await pay();
+ * } else {
+ *   console.log(answer.refusal.rule?.name, answer.refusal.explanation);
+ * }
+ * ```
+ */
+export type Authorization = Allowed | Refused;
+/**
+ * The answer an outcome gives, or `undefined` for one no agent payment can produce (a
+ * posted `ForbiddenRecorded`, an unposted allowing verdict, or a refusal that does not
+ * say why). Pure; fails closed: the refusal is always the service's, never invented.
+ */
+export declare function judge(outcome: AgentOutcome): Authorization | undefined;
+/**
+ * Whether the justification recorded for this answer's transaction is `text`: its
+ * SHA-256 equals the answer's `justification_hash`. On a replay the recorded
+ * justification is the one the first submission carried, so a re-drive that reworded
+ * it resolves `false` here. Async only because it hashes with WebCrypto.
+ *
+ * ```ts
+ * const answer = await axorum.authorize(buyer, order);
+ * if (answer.replayed && !(await justificationMatches(answer, order.justification))) {
+ *   log.warn("the ledger kept the first justification, not this one");
+ * }
+ * ```
+ */
+export declare function justificationMatches(answer: Authorization, text: string): Promise<boolean>;
+/** The lowercase-hex SHA-256 of `text`'s UTF-8 bytes, as the service hashes it. */
+export declare function justificationHash(text: string): Promise<string>;
+/**
+ * Why no answer was received. Every cause is safe to re-drive: the same payment carries
+ * the same transaction id, so a committed one replays.
+ */
+export type Cause = 
+/** No connection opened, so nothing was sent. */
+{
+    readonly kind: "connect";
+    readonly message: string;
+}
+/** The service's own rate limiter shed the request before any handler ran. */
+ | {
+    readonly kind: "rate_limited";
+    readonly message: string;
+} | {
+    readonly kind: "transport";
+    readonly message: string;
+} | {
+    readonly kind: "not_primary";
+    readonly reason: string | null;
+} | {
+    readonly kind: "commit_unavailable";
+    readonly reason: string | null;
+}
+/**
+ * A `502`, `503` or `504`. `code` is the error code its body named (`idempotency_unseeded`,
+ * or one this SDK does not know yet), or `null` when the body was not the service's: a
+ * proxy's page.
+ */
+ | {
+    readonly kind: "unavailable";
+    readonly status: number;
+    readonly code: string | null;
+}
+/**
+ * The call's time budget ran out before its next request could be sent: the call's
+ * deadline, or its submission's (the attestation's `exp` less 30 s) when that is sooner.
+ */
+ | {
+    readonly kind: "deadline_exceeded";
+    readonly elapsedMs: number;
+}
+/**
+ * An earlier attempt of the call ended without a definite answer (`earlier`: its
+ * status, or `"timeout"`), so it may have committed. The failure the call then ended
+ * with, `last`, is not the ledger's answer about this transaction id and cannot say
+ * otherwise.
+ */
+ | {
+    readonly kind: "earlier_attempt_in_doubt";
+    readonly earlier: string;
+    readonly last: string;
+};
+/**
+ * What went wrong in an authorize call. Branch on `kind`.
+ *
+ * Every kind but `indeterminate` fails identically on a re-drive until something
+ * outside the call changes (a token, a policy, a chart, the registry).
+ */
+export type AuthorizeFailure = 
+/** `403 attestation`: the token was rejected. Refresh it. */
+{
+    readonly kind: "attestation_rejected";
+}
+/**
+ * The attestation source failed (`cause` holds what it threw), or gave a token whose
+ * claims cannot be read. Nothing was sent.
+ */
+ | {
+    readonly kind: "attestation_unavailable";
+}
+/**
+ * The token expires too soon to outlast a submission's re-sends, and the source gave
+ * no fresher one. Nothing was sent.
+ */
+ | {
+    readonly kind: "attestation_expiring";
+    readonly expiresAt: string;
+}
+/** `401 unknown_agent`: no party is bound to this `agent://` URI. */
+ | {
+    readonly kind: "unknown_agent";
+}
+/** `409 no_active_policy`: nothing can judge the payment. */
+ | {
+    readonly kind: "no_active_policy";
+}
+/**
+ * The payment's currency was never declared by this deployment (a `422
+ * substrate_rejected` with cause `undeclared_currency`). Nothing was recorded. The
+ * operator must declare it, then open the default chart in it.
+ */
+ | {
+    readonly kind: "currency_not_declared";
+    readonly currency: string;
+}
+/**
+ * The default chart is not open in the payment's currency (a `422 substrate_rejected`
+ * with cause `unknown_account`). The service refuses an undeclared currency before it
+ * looks any account up ({@link currency_not_declared}), so the currency is declared and
+ * only the chart is missing. Nothing was recorded. The operator must open the chart.
+ */
+ | {
+    readonly kind: "chart_not_provisioned";
+    readonly currency: string;
+}
+/** The payee is not in the counterparty registry a policy aggregate reads. */
+ | {
+    readonly kind: "unknown_payee";
+    readonly payee: string;
+}
+/** The policy in force does not declare the default chart's action. */
+ | {
+    readonly kind: "policy_contract";
+}
+/**
+ * `409 transaction_reused`: this id committed with different content. The hashes
+ * cover agent, entries, action and bindings, rail and usage moves; justification,
+ * evidence, attestation and policy are not content, so changing only those replays.
+ */
+ | {
+    readonly kind: "transaction_reused";
+    readonly storedContentHash: string | null;
+    readonly submittedContentHash: string | null;
+}
+/**
+ * The payment's key came from your records and the service states no idempotency
+ * window (`reason` `"not_advertised"`: its writer could not answer; `"malformed"`: `header` carries `value`, which states no count), so no
+ * key from your records can be aged against it. Nothing was sent.
+ */
+ | {
+    readonly kind: "key_window_unstated";
+    readonly reason: WindowHeaderReason;
+    readonly header: string | null;
+    readonly value: string | null;
+}
+/**
+ * The payment's key came from your records (its `origin` is not `minted`) and the service's idempotency window no longer covers it, so the ledger
+ * may have forgotten the id and would apply it again. `reason` `"expired"`: the key is
+ * `ageMs` old, at or past the `windowSeconds` window; read the transaction to learn
+ * whether it landed, and authorize a new payment only if it did not. `"unclocked"`: the
+ * service runs no heartbeat (`tick_interval_ms` is 0), so its `windowTicks` window has
+ * no wall-clock length and vouches for no key from your records; reconcile the same
+ * way first. A new `payment()` goes ahead there, as a key minted in this process
+ * was never sent before. Nothing was sent.
+ */
+ | {
+    readonly kind: "stale_key";
+    readonly reason: StaleKeyReason;
+    readonly ageMs: number | null;
+    readonly windowSeconds: bigint | null;
+    readonly windowTicks: bigint;
+}
+/** The payment was keyed for another agent. Nothing was sent. */
+ | {
+    readonly kind: "keyed_for_another_agent";
+    readonly keyedFor: string;
+    readonly agent: string;
+}
+/**
+ * `507`: a ledger capacity bound is full. `retryAfterMs` is the answer's `Retry-After`:
+ * when it names a wait, a sweep may make room by then; otherwise an operator must act.
+ */
+ | {
+    readonly kind: "capacity";
+    readonly retryAfterMs: number | null;
+}
+/** The policy changed {@link MAX_AUTHORIZE_PINS} times under the call. */
+ | {
+    readonly kind: "stale_policy";
+    readonly pinned: string;
+    readonly active: string;
+}
+/** The answer was not received. **It may or may not have committed.** */
+ | {
+    readonly kind: "indeterminate";
+    readonly lastCause: Cause;
+}
+/**
+ * Nothing from this call was written: its last answer {@link AxorumError.wroteNothing |
+ * wrote nothing}, and no earlier attempt of the call left doubt. `cause` names that
+ * answer. `tried` lists every attempt of the call, in order, the last included, and is
+ * empty when the budget ran out before the first request was sent; a re-sent status is
+ * listed by its status only. A `421` is always doubt, so a call that met one is never
+ * `not_submitted`. Never a refusal. Authorize the same {@link Payment} again.
+ * {@link NOT_SUBMITTED_CAVEAT}: "If an earlier call with this key was ambiguous, the
+ * transaction may still commit; retry with the same key and the server will replay."
+ */
+ | {
+    readonly kind: "not_submitted";
+    readonly tried: readonly EndpointAttempt[];
+    readonly cause: NotSubmittedCause;
+}
+/**
+ * The ledger answered with an outcome no agent payment can produce: a posted
+ * `ForbiddenRecorded`, or a refusal that does not say why. Do not pay.
+ */
+ | {
+    readonly kind: "unexpected_verdict";
+    readonly outcome: AgentOutcome;
+}
+/** Any other documented refusal to process the request. */
+ | {
+    readonly kind: "rejected";
+    readonly status: number;
+    readonly body: ErrorBody;
+}
+/** A `200` that did not decode: it may have committed. Read it back. */
+ | {
+    readonly kind: "undecodable";
+}
+/** A non-Axorum non-2xx (a proxy's `429`, an HTML page). */
+ | {
+    readonly kind: "unexpected";
+    readonly status: number | null;
+};
+/**
+ * The answer a {@link AuthorizeFailure | `not_submitted`} call ended on, which wrote
+ * nothing. The Rust SDK's `NotSubmittedCause`, kind for kind.
+ */
+export type NotSubmittedCause = 
+/** No connection to the service could be opened. */
+{
+    readonly kind: "connect";
+    readonly message: string;
+}
+/** The service's rate limiter turned the attempt away before it was handled. */
+ | {
+    readonly kind: "rate_limited";
+    readonly message: string;
+}
+/**
+ * `503 idempotency_unseeded`: the primary had not seeded its idempotency index, and
+ * turned the payment away before proposing it, on every attempt the budget allowed.
+ */
+ | {
+    readonly kind: "unseeded";
+    readonly message: string;
+}
+/**
+ * `500 idempotency_seed_refused`: the ledger refused the primary's seed, and the
+ * primary turns every payment away before proposing it until the primary changes.
+ */
+ | {
+    readonly kind: "seed_refused";
+    readonly message: string;
+}
+/**
+ * `503 not_normal`: the replica was in a view change or a recovery, and turned the
+ * payment away before proposing it, on every attempt the budget allowed.
+ */
+ | {
+    readonly kind: "not_normal";
+    readonly message: string;
+}
+/**
+ * `503 archive_pressure`: the primary's local archive was past its hold ceiling, and
+ * the primary turned the payment away before proposing it, on every attempt the budget
+ * allowed.
+ */
+ | {
+    readonly kind: "archive_pressure";
+    readonly message: string;
+}
+/**
+ * `503 quarantined`: replay verification found a divergence on the node, and the node
+ * turned the payment away before proposing it, on every attempt the budget allowed. It
+ * does not clear on its own.
+ */
+ | {
+    readonly kind: "quarantined";
+    readonly message: string;
+}
+/**
+ * `500 proposal_refused`: the node refused the proposal for a reason this build does
+ * not name, before proposing it.
+ */
+ | {
+    readonly kind: "proposal_refused";
+    readonly message: string;
+}
+/** The call's time budget ran out before the payment was sent. */
+ | {
+    readonly kind: "deadline_exceeded";
+    readonly elapsedMs: number;
+}
+/** Another answer that {@link AxorumError.wroteNothing | wrote nothing}. */
+ | {
+    readonly kind: "other";
+    readonly message: string;
+};
+/**
+ * What a {@link AuthorizeFailure | `not_submitted`} failure always says: this call sent
+ * nothing, but an earlier ambiguous one may still land.
+ */
+export declare const NOT_SUBMITTED_CAVEAT = "If an earlier call with this key was ambiguous, the transaction may still commit; retry with the same key and the server will replay.";
+/** How many policy rotations one call absorbs by re-pinning. */
+export declare const MAX_AUTHORIZE_PINS = 3;
+/**
+ * An authorize call that got no answer. Carries the payment's transaction id, which is
+ * what makes recovery safe: re-drive the **same** {@link Payment} and a payment that
+ * already committed replays its answer instead of paying twice.
+ *
+ * ```ts
+ * try {
+ *   const answer = await axorum.authorize(buyer, lunch);
+ * } catch (error) {
+ *   if (error instanceof AuthorizeError && error.retryable) {
+ *     queue.later(lunch); // same Payment, same transaction id
+ *   } else if (error instanceof AuthorizeError && error.needsFreshAttestation) {
+ *     await refreshToken();
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export declare class AuthorizeError extends AxorumError {
+    readonly code = "authorize";
+    /** The payment's transaction id. */
+    readonly transaction: string;
+    /** What went wrong. */
+    readonly failure: AuthorizeFailure;
+    /** The underlying failure, when there was one. */
+    readonly cause: unknown;
+    constructor(transaction: string, failure: AuthorizeFailure, cause?: unknown);
+    /** The failure's kind, for a `switch`. */
+    get kind(): AuthorizeFailure["kind"];
+    /**
+     * Whether re-driving the same payment later may get an answer: after `indeterminate`,
+     * when the answer was not received, and after `not_submitted`, when this call
+     * submitted nothing. Every other kind fails identically on a re-drive until something
+     * outside the call changes.
+     */
+    get retryable(): boolean;
+    /** Whether the fix is a fresh attestation. */
+    get needsFreshAttestation(): boolean;
+}
+/** What the pin loop does about one failed request. */
+export type Disposition = {
+    readonly action: "unanswered";
+    readonly cause: Cause;
+} | {
+    readonly action: "repin";
+    readonly active: string;
+    readonly pinned: string;
+} | {
+    readonly action: "fail";
+    readonly failure: AuthorizeFailure;
+};
+/**
+ * Decides what to do about a failed request. Pure: the whole table.
+ *
+ * Re-pinned: a `409` stale pin. Unanswered (`indeterminate`): transport failures, `421`,
+ * `502`/`503`/`504`, and a request the deadline left no time to send. Everything else is
+ * a typed failure.
+ */
+export declare function classify(error: unknown, pay: Payment): Disposition;
+/**
+ * The cause of a `not_submitted` call that ended on `error`, or `undefined` when `error`
+ * does not prove its attempt {@link AxorumError.wroteNothing | wrote nothing}. A call
+ * that moved between URLs ended on its last attempt's failure. Pure.
+ */
+export declare function unsent(error: unknown): NotSubmittedCause | undefined;
+/**
+ * What to do about a failed request of the call, given the first attempt of the call
+ * left in doubt, if any, and every attempt `tried`, the last included: `not_submitted`
+ * exactly when `error` wrote nothing ({@link unsent}) and nothing was in doubt;
+ * {@link classify} otherwise, which the caller reads {@link afterDoubt}. Pure.
+ */
+export declare function dispose(error: unknown, pay: Payment, earlier: string | undefined, tried: readonly EndpointAttempt[]): Disposition;
+/**
+ * How a call ends on a request that failed with `error`, given the first attempt of the
+ * call left in doubt, if any, and every attempt `tried`, the last included: its
+ * {@link dispose | disposition}, a failure read {@link afterDoubt | after the doubt}.
+ * Pure.
+ */
+export declare function conclude(error: unknown, pay: Payment, earlier: string | undefined, tried: readonly EndpointAttempt[]): AuthorizeFailure;
+/**
+ * Whether an attempt the transport sent again after `reason` may have committed: unless
+ * what it saw {@link AxorumError.wroteNothing | wrote nothing}. Only a connection that
+ * never opened is definite: a re-sent status arrives without its body, so even a `429`,
+ * a `421` or a `507` cannot show the code that would make it definite. Every other
+ * outcome, a status this version does not know included, is doubt. Pure; the same rule
+ * as the Rust SDK.
+ */
+export declare function leavesDoubt(reason: RetryReason): boolean;
+/**
+ * Whether `error` is the ledger's own answer about this transaction id, given after it
+ * looked the id up: `409 transaction_reused`, or a `422 substrate_rejected` whose cause
+ * is decided after that lookup (every cause but `undeclared_currency` and
+ * `amount_overflow`; `unknown_account`, `unknown_counterparty` and the action-contract
+ * causes are among them). Had an earlier attempt committed, the service would have
+ * answered with its replay instead, so the answer stands after an attempt in doubt.
+ * Pure.
+ */
+export declare function settlesTheId(error: unknown): boolean;
+/**
+ * `failure`, given the first attempt of the call left in doubt, if any, and the error it
+ * came from. Once an earlier attempt is in doubt, an end that read alone says the payment
+ * did not land becomes `indeterminate`, cause `earlier_attempt_in_doubt`: a failure whose
+ * error does not {@link settlesTheId | settle the id}, and an `indeterminate` end whose
+ * error {@link AxorumError.wroteNothing | wrote nothing}. A re-pin, and an
+ * `indeterminate` end that is itself in doubt, are unchanged. Pure.
+ */
+export declare function afterDoubt(failure: AuthorizeFailure, earlier: string | undefined, cause?: unknown): AuthorizeFailure;
+/**
+ * Whether the call sends a submission again after `error` itself, rather than through
+ * the transport: every `503`, read with its body. The transport re-sends on the status
+ * alone and cannot tell a `503 idempotency_unseeded`, which wrote nothing, from a
+ * `503 commit_unavailable`, which may commit. Pure.
+ */
+export declare function redrives(error: unknown): boolean;
+/**
+ * The pause before the call sends a submission again for the `redriven + 1`th time, under
+ * {@link AUTHORIZE_RETRY_POLICY} with `draw`, or `undefined` when it would reach the
+ * deadline `remainingMs` away. Pure.
+ */
+export declare function redrivePause(redriven: number, draw: number, remainingMs: number): number | undefined;
+/**
+ * What the call ends on when the send after a re-drive pause fails with `error`: the
+ * `503` it paused after, `pausedAfter`, when the budget ran out before that send could
+ * leave (a deadline with no attempt), since the call's last answer is still that `503`;
+ * else `error`. The `503` was already heard as re-driven, so the caller lists it once.
+ * Pure.
+ */
+export declare function endedAfterRedrive(pausedAfter: unknown, error: unknown): {
+    error: unknown;
+    heard: boolean;
+};
+/**
+ * The attempt a submission's `error` ended on, as `tried` lists it: the last of a call
+ * that moved between URLs, else the one at `endpoint`; `undefined` when nothing was sent
+ * or no endpoint is known. Pure.
+ */
+export declare function finalAttempt(error: unknown, endpoint: string | undefined): EndpointAttempt | undefined;
+/**
+ * Every attempt a read of the call (the pin, the window) that failed with `error` made:
+ * those of a read that moved between URLs, else none, since no recorder hears a read.
+ * Pure.
+ */
+export declare function attemptsOf(error: unknown): readonly EndpointAttempt[];
+/**
+ * The recorder of one call: hears every attempt its submissions are sent again after,
+ * from the transport (a re-sent status, by its status alone) and from the call (a `503`,
+ * its body read), and keeps them in order, and the first in doubt. Shared by every
+ * submission of the call, so doubt carries across re-pins. The Rust SDK's `Doubt`.
+ */
+export declare class Doubt {
+    #private;
+    /** The first outcome in doubt, by its label (`"503"`, `"timeout"`), or `undefined`. */
+    get earlier(): string | undefined;
+    /** Every attempt heard so far, in order. */
+    get tried(): readonly EndpointAttempt[];
+    /** Hears an attempt the transport sent again: in doubt unless its connection never opened. */
+    resent(attempt: EndpointAttempt): void;
+    /** Hears a submission the call sent again after reading its `error`: in doubt unless it wrote nothing. */
+    redriven(endpoint: string, error: AxorumError): void;
+}
+/**
+ * What bounds one submission: its deadline on the `performance.now()` clock, and who
+ * hears each attempt.
+ */
+export interface SubmissionBound {
+    readonly deadline: number;
+    /** Hears each attempt as the transport sends it again: where it went, how it ended, whether the re-send moved on. */
+    readonly onResend: (attempt: EndpointAttempt) => void;
+    /** Hears each submission the call sends again itself after reading its `503`: where it went, and the error. */
+    readonly onRedrive?: (endpoint: string, error: AxorumError) => void;
+    /** Hears where the submission's last attempt went, when it ended without an answer. */
+    readonly onEnded?: (endpoint: string) => void;
+}
+/** What {@link runAuthorize} needs from the client: the edges, and nothing else. */
+export interface AuthorizeTransport {
+    /** Reads the policy in force. */
+    activePolicy(signal: AbortSignal | undefined): Promise<string | null>;
+    /**
+     * Sends one pinned envelope on `authorize`'s lane, within `bound` or the call's
+     * deadline, whichever comes first.
+     */
+    submit(envelope: ReturnType<typeof pinIntent>, signal: AbortSignal | undefined, bound: SubmissionBound): Promise<AgentOutcome>;
+    /** The pin the client believes is in force, shared by its clones. */
+    readonly pin: {
+        value: string | undefined;
+    };
+    /**
+     * The wall-clock window the client last read, if it read one. A safe floor: the
+     * service never shrinks its window in ticks (`axorum-serve`'s
+     * `idempotency::boot_policy` never lowers it, and the admin route refuses a shorter
+     * one with `409 idempotency_window_shrink`), and the service's own
+     * `409 stale_idempotency_key` catches what the copy misses.
+     */
+    keptWindow(): IdempotencyWindow | undefined;
+    /**
+     * Reads the service's idempotency window, keeping it when it states a wall-clock
+     * length. Throws {@link IdempotencyWindowError} when the headers state none.
+     */
+    readWindow(signal: AbortSignal | undefined): Promise<IdempotencyWindow>;
+}
+/**
+ * Why a keyed payment must not be sent, or `undefined` to go ahead: the pure half of the
+ * key gate. A payment keyed for another agent would name that agent's transaction.
+ */
+export declare function keyGate(agentUri: string, pay: Payment): AuthorizeFailure | undefined;
+/**
+ * Whether a refusal from the client's kept copy of the window is read again before it
+ * stands: only a stale key, and only when the copy was kept rather than just read. The
+ * window never shrinks, so a copy that covers the key needs no second look, and one
+ * that refuses it may be out of date because the window grew.
+ */
+export declare function rereads(kept: boolean, gated: AuthorizeFailure | undefined): boolean;
+/**
+ * Whether a key may be sent at `nowMs` under the service's window, as its headers stated
+ * it (an {@link IdempotencyWindowError} when they stated none): `undefined` to send,
+ * else why not. A key minted in this process (`held` false) was never sent before and
+ * always goes ahead; one from the caller's records goes only while the window covers
+ * it. Pure; `spec/fixtures/key-gate-v1.json` pins it in both SDKs.
+ */
+export declare function vouch(held: boolean, key: IdempotencyKey, window: IdempotencyWindow | IdempotencyWindowError, nowMs: number): AuthorizeFailure | undefined;
+/**
+ * The pin loop: the only part of `authorize` that does I/O. Pins (from the shared cache,
+ * or by reading the active policy), submits, and re-pins at most
+ * {@link MAX_AUTHORIZE_PINS} times. It owns no transport retry; the client's lane holds
+ * every request to the call's deadline.
+ *
+ * @param caller - The caller's own cancellation. When it fires, its reason is thrown
+ *   as-is, never dressed up as a ledger failure.
+ */
+export declare function runAuthorize(transport: AuthorizeTransport, agent: Agent, pay: Payment, caller: AbortSignal | undefined): Promise<Authorization>;
+//# sourceMappingURL=authorize.d.ts.map