@axorum/client 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,531 @@
-# Temporary Holding Version
+# `@axorum/client`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official TypeScript SDK for the **Axorum agent plane** — submit intents, read ledger
+state, and recover from a stale policy pin, against an `axorum-serve` instance.
+
+Axorum is a deontic financial-control ledger. An agent submits an *intent envelope*; the
+service permits or refuses it under the policy in force, and **records the outcome either
+way**. This client exists to get one thing right that a generated client cannot:
+
+> **A policy refusal is not an error.** It is a `200`, it resolves, and the refusal record
+> is the product.
+
+Zero runtime dependencies — the platform's `fetch`, `crypto.randomUUID` and `AbortSignal`
+are all it needs. ESM-only, Node ≥ 20.
+
+## Install
+
+```sh
+pnpm add @axorum/client
+```
+
+## Quickstart
+
+```ts
+import { AxorumClient } from "@axorum/client";
+
+const axorum = new AxorumClient({
+  baseUrl: "https://axorum.internal:8443",
+  attestation: paseto,                       // the PASETO v4.public capability attestation
+});
+
+const outcome = await axorum.submitPinned({
+  agent: "agent://example.com/agent/clerk_01h455vb4pex5vsknk084sn02q",
+  attestation: paseto,                       // the same token, carried in the envelope
+  action: { action: "post", bindings: {} },
+  entries: [
+    { account: cash,    side: "Debit",  amount: { minor: 1_000n, currency: "USD" } },
+    { account: revenue, side: "Credit", amount: { minor: 1_000n, currency: "USD" } },
+  ],
+  justification: "invoice 4471, approved by the purchase order",
+});
+```
+
+`submitPinned` reads the policy in force, stamps it onto the envelope, submits, and — if
+the policy moved out from under it — re-pins and submits again. It is the loop every
+correct agent writes, so it ships in the client rather than in your code.
+
+### The permitted outcome
+
+```ts
+if (outcome.posted) {
+  console.log(outcome.verdict);      // "Permitted"
+  console.log(outcome.policy);       // the policy it committed under
+  console.log(outcome.transaction);  // the id it committed as
+}
+```
+
+### The refusal — **which is a value, not a throw**
+
+Point the same code at a policy that forbids the action and nothing about the control flow
+changes. The promise **resolves**:
+
+```ts
+const outcome = await axorum.submitPinned(draft);
+
+if (!outcome.posted) {
+  console.log(outcome.verdict);   // "ForbiddenRejected"
+  console.log(outcome.policy);    // the policy that refused it
+
+  // The refusal is ON THE LEDGER. Read it back like any other record.
+  const record = await axorum.transaction(outcome.transaction);
+}
+```
+
+The intent reached the commit point, was judged, and the refusal was *recorded*. That
+recording is what the ledger exists to produce. **Branch on `posted` / `verdict`, never on
+a status code.** A rejected promise means the ledger never got to answer at all.
+
+### Provenance and evaluation semantics
+
+The outcome's `provenance` is either the recorded audit trail or the string `"Archived"`.
+Recorded provenance has an optional `semantics?: SemanticsVersion` field. The TypeScript
+SDK represents `SemanticsVersion` as a `bigint`, following its contract-wide integer
+convention; it is omitted for pre-versioning records. The stamp names the evaluation law,
+not the outcome. `master_data` is also optional and is omitted when the policy did not
+consult replicated reference data.
+
+### Trusting a private API CA
+
+A deployment's API listener presents a certificate from its own CA, which Node's default
+trust store does not hold. Point Node at that CA's `ca.crt` before the process starts:
+
+```sh
+NODE_EXTRA_CA_CERTS=/path/to/api/ca.crt node agent.js
+```
+
+## The API
+
+```ts
+new AxorumClient({ baseUrl, attestation?, timeoutMs?, retry?, authorizeDeadlineMs?, authorizeRetries?, fetch? })
+
+axorum.authorize(agent, payment, opts?)         // → Promise<Authorization>      one call, see below
+axorum.activePolicy(opts?)                      // → Promise<string | null>      no credential
+axorum.submitIntent(envelope, opts?)            // → Promise<AgentOutcome>       in-envelope
+axorum.submitPinned(draft, opts?)               // → Promise<AgentOutcome>       in-envelope
+axorum.submitPinnedFrom(draft, policyId, opts?) // → Promise<AgentOutcome>       in-envelope
+axorum.transaction(txnId, opts?)                // → Promise<TransactionRecord>  ATTESTATION
+axorum.obligations(actor?, opts?)               // → Promise<ObligationsResponse> ATTESTATION
+axorum.balance(accountId, opts?)                // → Promise<BalanceResponse>    ATTESTATION
+axorum.usage(usageId, opts?)                    // → Promise<UsageBalanceReport> ATTESTATION
+axorum.withAttestation(token)                   // → AxorumClient                rotate the token
+```
+
+Every method takes `opts?: { signal?: AbortSignal; requestId?: string }`. An
+`x-request-id` (UUID v4) is generated per request when you do not supply one.
+
+## Authorize a payment in one call
+
+`authorize(agent, payment)` asks the ledger whether an agent may pay, and answers
+**allowed** or **refused with a reason**. It proposes `purchase(amount, payee)` against the
+**default chart**: it debits the spend account and credits the payable account for the
+payment's currency. It derives both account ids offline, so you never name an account.
+
+```ts
+import { Agent, AuthorizeError, AxorumClient, payment } from "@axorum/client";
+
+const axorum = new AxorumClient({ baseUrl: "https://ledger.acme.com" });
+const buyer = new Agent("agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q", mintToken);
+const order = payment({ amount: { minor: 1_250n, currency: "USD" }, payee: "api.openai.com" });
+
+try {
+  const answer = await axorum.authorize(buyer, order);
+  if (answer.allowed) {
+    await pay();
+  } else {
+    console.log(answer.refusal.code, answer.refusal.rule?.name, answer.refusal.explanation);
+  }
+} catch (error) {
+  if (error instanceof AuthorizeError && error.retryable) {
+    // The ledger never answered. Re-drive the SAME `order`: its transaction id replays.
+  }
+  throw error;
+}
+```
+
+What the deployment needs:
+
+- the operator declared the payment's currency (`[[currencies]]` in `axorum-serve`, or
+  `axorum currency declare`) and opened the default chart in it (`[default_chart]
+  version = 1`, or `axorum chart provision`); otherwise the error is
+  `currency_not_declared` (the service checks the currency first), or
+  `chart_not_provisioned` when only the chart is missing;
+- the policy in force declares `action purchase(amount: amount, payee: text)`;
+- the payee is in the counterparty registry when a rule or aggregate scopes by it. A payee
+  the registry has never heard of is `unknown_payee`, a `422`, not a refusal: nothing is
+  recorded. Import it with `approved: false` to have it refused.
+
+**Pass the agent URI in canonical form**, the one form `agent-uri` renders: a lowercase host,
+a port without leading zeros, an IPv6 address as RFC 5952 writes it, and no query or
+fragment. `new Agent` refuses any other spelling with an `InvalidAgentError` whose
+`canonical` names the form to pass, because a keyed payment derives its id from the URI's
+exact bytes and both SDKs must derive the same one.
+
+**The SDK binds the payee as text.** A payment rail governed by the same policy must be set
+to `payee_binding = "text"`; a rail left on the default `"party"` binds a different type,
+and the same policy cannot serve both.
+
+The agent's attestation can be a string, or a function `() => Promise<string>` that
+`authorize` calls on **every submission** (the first, and each re-pin), so a short-lived
+token is refreshed as it goes. A rejected one is `attestation_rejected` with
+`needsFreshAttestation` set.
+
+`payment()` mints the transaction id (UUIDv7) **once**, before any I/O. Every send
+carries it, so one that committed replays its answer instead of paying twice.
+
+**Time and retries.** `authorize` runs under one time budget for the whole call:
+`AUTHORIZE_DEADLINE_MS` (15 s), or less with the `authorizeDeadlineMs` client option. The
+idempotency window and policy reads, every submission, every re-pin, every attempt and
+every pause share it. Each submission attempt waits the commit wait a clustered service
+advertises (the `axorum-submit-timeout-ms` header on `GET /api/openapi.json`) plus 1 s, so
+the service's own `503 commit_unavailable` is heard rather than cut off, or 6 s
+(`SUBMIT_ATTEMPT_FALLBACK_MS`) when it advertises none; each read waits 6 s. The `debug`
+client option is the client's diagnostic sink, for everything it would say at debug level;
+it hears, once per client, why attempts wait the fallback. Every attempt is
+clamped to what is left of the budget, and one the clamp cuts below the commit wait plus
+1 s may end `indeterminate`: re-drive the same payment. Requests are re-sent under
+`AUTHORIZE_RETRY_POLICY`: full jitter between 100 ms and 1.6 s, so a fleet of agents does
+not re-send in step, with attempts bounded by the deadline alone. The client's `retry`
+and `timeoutMs` govern its other calls, not `authorize`. The policy mirrors the Rust SDK's `acton-service-client` 0.2,
+and `spec/fixtures/retry-v1.json` pins both SDKs to the same rows.
+
+```ts
+import { AxorumClient } from "@axorum/client";
+
+// A checkout that cannot wait 15 s for an answer.
+const axorum = new AxorumClient({ baseUrl, authorizeDeadlineMs: 5_000 });
+```
+
+Re-sending is on by default. A caller that runs its own re-drive loop sets
+`authorizeRetries: false`: each request is then sent once, still under the deadline, and
+the first unanswered one ends the call, `not_submitted` or `indeterminate` as below.
+
+| Re-sent until the deadline | Not re-sent |
+|---|---|
+| connection failures and timeouts | a refusal (it is an answer) |
+| `429`, `502`, `504`, and `423` with `Retry-After`, honouring a `Retry-After` that fits before the deadline | `422`, including `chart_not_provisioned` and `unknown_payee` |
+| `421 not_primary`, on the next of the `failoverUrls`: `primary_api_addr` is a hint, never followed | `409 transaction_reused` |
+| a `503` of any code, to the same URL, by the call itself with its body read | `400` / `401` / `403` / `404` / `500` / `507` |
+| `409` stale pin: re-pinned, at most 3 times | |
+
+Every send carries the same transaction id, so re-sending a submission that committed
+replays its answer. A posted outcome whose verdict is not an allow, or a refusal that
+does not say why, fails closed as `unexpected_verdict`.
+
+A call whose last answer wrote nothing, with no earlier attempt in doubt, is
+`not_submitted`, never a refusal. Its `cause` names that answer: a connection that never
+opened, the service's own `429`, `503 idempotency_unseeded`, `500
+idempotency_seed_refused`, `503 not_normal`, `503 archive_pressure`, `503 quarantined`,
+`500 proposal_refused`, or a budget spent before the first send (`deadline_exceeded`);
+`tried` lists every attempt, the last included. The six codes count only with the body
+read.
+
+Every other attempt leaves doubt: a timeout, a connection that broke after the request
+went out, any other `503`, and every status the transport sent again. The transport
+re-sends on the status alone, without reading the body, so a `421`, or a `429` that was
+sent again, always leaves doubt. When the budget runs out on an answer like these, the
+failure is `indeterminate`, carrying that answer as its cause. After doubt, a typed
+failure, or a last answer that wrote nothing (an unseeded `503`, a `429`), is
+`indeterminate` too, cause `earlier_attempt_in_doubt`, naming the first attempt in
+doubt, unless it settles the transaction id (`transaction_reused`). Re-driving the same payment is safe either way.
+`not_submitted` and `indeterminate` are the two `retryable` failures. If an earlier call
+with this key was ambiguous, the transaction may still commit; retry with the same key
+and the server will replay.
+
+### Every replica, for a cluster
+
+A clustered deployment accepts writes only on its primary. Name every replica's API URL
+and `authorize` moves an attempt that meets a `421`, a connection that never opens, or an
+attempt timeout on to the next one at once, under the same deadline and the same
+transaction id; a `503` is sent again to the same URL. The next call starts at the URL
+that last answered. `submitKeyed` runs on the same transport.
+
+```ts
+import { AxorumClient, RETRIES_COUNTER, ROTATIONS_COUNTER, rotationLabel } from "@axorum/client";
+
+const axorum = new AxorumClient({
+  baseUrl: "https://axorum-0.axorum.svc:8443",
+  failoverUrls: ["https://axorum-1.axorum.svc:8443", "https://axorum-2.axorum.svc:8443"],
+  // The Rust SDK counts on these names; count the same way.
+  onRotation: (_left, reason) => metrics.increment(ROTATIONS_COUNTER, { reason: rotationLabel(reason) }),
+  onRetry: (_endpoint, reason) => metrics.increment(RETRIES_COUNTER, { reason: rotationLabel(reason) }),
+});
+```
+
+Each failover URL is a bare origin of `baseUrl`'s scheme; `baseUrl`'s path is used on
+every one. No redirect is followed, and `primary_api_addr` is never dialled: it is a
+hint that may be stale. Reads fail over too under a `retry` policy;
+`submitIntent` sends the caller's own envelope once, to one URL. A client built with one
+URL assumes a load balancer that routes to the primary, and the first one built in the
+process warns: "one endpoint configured: an LB routing to the primary is assumed".
+
+## Reads are credentialed
+
+An intent authenticates **in the envelope** — the draft names the `agent://` URI and the
+PASETO attestation, and the service verifies both 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 four party-scoped reads present
+the 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.
+
+```ts
+const axorum = new AxorumClient({ baseUrl, attestation: paseto });
+
+const owed = await axorum.obligations();       // your party's duties — the token decides
+const record = await axorum.transaction(id);   // your party's record, or a 404
+```
+
+A client built **without** an attestation still submits and still reads `activePolicy` —
+both carry their own credential or need none — but a party-scoped read throws
+`MissingAttestationError` **locally**, before a byte leaves the process. The client never
+sent a credential, so relaying the service's `401` would blame the service for rejecting
+one it was never given.
+
+### Metered spend is one intent
+
+An agent that consumes a metered resource carries the usage moves on the **same** draft as
+the journal legs. They are judged in the same commit, under the usage-balance conservation
+law `0 ≤ billed ≤ metered ≤ consumed`:
+
+```ts
+const outcome = await axorum.submitPinned({
+  ...draft,
+  consume_usage: { usage, amount: { minor: 1_000n, currency: "USD" } },  // you used it
+  meter_usage:   { usage, amount: { minor: 1_000n, currency: "USD" } },  // it was measured
+  bill_usage:    { usage, amount: { minor: 1_000n, currency: "USD" } },  // it was billed
+});
+```
+
+All three at once is the *lawful* case, not an edge case: the moves of one intent are
+validated **together** against the combined post-state. Any subset is fine too — metering
+something an earlier intent consumed is one move, not three — and an absent move's key is
+omitted from the wire entirely, never `null`.
+
+Metering more than was consumed is **phantom usage**; billing more than was metered is
+billing with no meter basis. The ledger refuses both with a `422`, and **nothing posts** —
+not the usage moves, and not the journal legs that rode with them. Under-recognition
+(`billed < metered < consumed`) is a lawful transient, not a fault.
+
+Read a balance back with `usage(usageId)`. Its counters are `bigint`s, and here that
+matters most: `consumed` takes no ceiling, so a busy meter's total can lawfully outgrow
+`u64`. Its `text` is the balance narrated in compliance English with exact figures — prefer
+it when you have a human to show.
+
+Usage reads are **owner-scoped and fail-closed**: a balance owned by another party, one
+opened with no owner, and one that never existed all answer the same `404 unknown_usage`.
+The cases are deliberately indistinguishable, so that a usage id is never an existence
+oracle across a tenant boundary. Surface the refusal as it stands; there is nothing further
+in it to infer.
+
+A usage balance is *opened* on the admin plane, which this SDK does not speak — an agent
+receives a usage id, it does not mint one.
+
+### `obligations(actor?)` — an assertion, not a selector
+
+`?actor=` used to *choose* whose duties came back, which is how they were enumerable.
+It is now an assertion the service **checks**:
+
+- **Omit it** — you are answered for the party your token names.
+- **Supply it** (a party id `party_…` or a DSL party name) — the service confirms it
+  resolves to that same party, and answers `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.
+
+### Fulfill a specific duty
+
+An intent fulfills existing obligations only when its `fulfills` collection names
+those duty IDs. Read the obligations your authenticated party owes or is authorized
+to perform, select the intended contract, and submit its concrete `action` together
+with the required accounting entries and `fulfills: [duty.id]`.
+
+To correlate a duty with an acceptance, match **both** `origin_transaction` and
+`origin_tick` against the acceptance outcome's `transaction` and `commit_tick`.
+Transaction IDs can be reused after the retention window. `actor` names the party
+that owes the duty; `performer` names the party authorized to fulfill it. They need
+not be the same party.
+
+A selection contains at most 64 distinct IDs. All selected duties must validate
+atomically: the performer, concrete action, deadline, and current policy must
+permit performance. Invalid selections return `422 invalid_fulfillment` without
+mutation or disclosure of another party's duties. Policy re-pinning preserves the
+selected IDs. An empty selection never discharges an existing duty.
+
+### Rotating an expiring token
+
+Attestations expire. `withAttestation` returns a new client over the **same `fetch`**, so
+re-credentialing costs a string, not a reconnect — and it is also the honest way for one
+process to act for several agents, since no view can see another's data.
+
+```ts
+const rotated = axorum.withAttestation(freshPaseto);
+```
+
+> **`balance` is authenticated, not party-scoped.** The ledger records no account→party
+> edge to scope it by, so any authenticated agent may read any account's balance. That is a
+> known residual gap in the service, not a property of this client — do not treat a balance
+> read as private to your party.
+
+An intent draft is a plain object — `entries`, `evidence`, `justification` and
+`transaction` are optional. Use `pinIntent(draft, policy)` if you drive the pin yourself.
+
+### Transaction ids and idempotency
+
+The **client** mints the transaction id, and it is the substrate's **idempotency key**:
+re-submitting a committed id with the same content replays its stored outcome rather than
+double-posting, marked `replayed: true` with `content_verified: true`. Leave
+`transaction` off your draft and the client mints one — **once**, before its first attempt,
+so every re-pinned retry inside `submitPinned` carries the same id. That is the entire
+reason the retry loop is safe. Mint one yourself with `newTransactionId()`.
+
+An id means one intent, for one window:
+
+- **Different content under a committed id throws `TransactionReusedError`**
+  (`409 transaction_reused`), and nothing is written. Mint a new id for a new intent.
+- **The window is advertised.** The service states how long it answers for an id, and
+  the client refuses to send a key older than that with `StaleIdempotencyKeyError`,
+  before anything is sent. Past the window a resubmission may commit a second time, so
+  read the original back with `transaction(id)` and mint a new id if it did not land.
+
+The id names **one** transaction. Re-submitting it with different content (another agent,
+amount, payee, leg, rail or usage move) is refused with `409 transaction_reused`, naming
+the stored and submitted content hashes, never replayed, and `authorize` never retries it:
+mint a new id for a new payment. The justification, evidence, attestation and policy pin
+are not content. A re-drive that changes only those replays the first answer
+(`replayed: true`), whose `justification_hash` is the **first** justification's;
+`justificationMatches(answer, text)` checks which one the ledger kept.
+
+To derive the id from your own records instead of storing it, build the payment with
+`keyedPayment(agent, paymentKey(key, issuedAtMs), init)`: the same agent and key always
+name the same transaction. The key is 1 to 255 bytes of visible ASCII; `issuedAtMs` is when
+your records first issued it, the same value on every rebuild, and becomes the payment's
+mint time. `authorize` sends a keyed payment only for the agent it was keyed for
+(`keyed_for_another_agent` otherwise, and nothing is sent).
+
+Every payment carries `idempotencyKey`: its transaction id and when it was minted, sent as
+`minted_at_ms`. To re-drive after a restart, persist both and rebuild with
+`resumePayment(new IdempotencyKey(transaction, mintedAtMs), init)`. `payment({ transaction })`
+takes a UUID v7 id's own time and throws `InvalidPaymentError` for any other id. A key from
+your records (`origin` other than `minted`) is sent only while the service's idempotency
+window covers it: otherwise `authorize` fails with `stale_key` (expired, or a service with no
+heartbeat) or `key_window_unstated`, and nothing is sent. Read the transaction back before
+authorizing a new payment.
+
+### Money is `bigint`
+
+The ledger denominates money in **128-bit integer minor units**, on the wire as bare JSON
+numbers. `JSON.parse` decodes those as doubles and silently loses the low bits — the worst
+failure a financial client can have, a wrong balance that looks right. So this client does
+not use `JSON.parse`. It ships its own parser, and the rule is one line:
+
+> **Every JSON integer is a `bigint`.** Every number with a fraction or exponent is a
+> `number`.
+
+So `amount.minor`, `balance`, `anchor`, `deadline` and the `Int`/`Tick` literals are all
+`bigint`, and the generated wire types say so. Write `{ minor: 50_000n, currency: "USD" }`.
+
+## The error taxonomy
+
+Everything below is a subclass of `AxorumError`. Catch by `instanceof` for the narrowed
+fields, or `switch` on the stable `code` — both are first-class.
+
+| Class | `code` | Status | What to do |
+|---|---|---|---|
+| `StalePolicyError` | `stale_policy` / `policy_pin_mismatch` | 409 | Re-pin against `.active` and resubmit. Nothing was written. `submitPinned` does this for you. |
+| `NoActivePolicyError` | `no_active_policy` | 409 | Nothing to pin to. An operator must activate a policy. |
+| `UnknownAgentError` | `unknown_agent` | 401 | The `agent://` URI is not bound to a party — an **authentication** failure. |
+| `AttestationError` | `attestation` | 403 | The PASETO attestation was rejected: bad signature, expired, wrong audience, untrusted issuer. |
+| `NotPrimaryError` | `not_primary` | 421 | You reached a follower. The attempt may or may not have been recorded: a primary stepping down can answer `421` after proposing it. `.primaryApiAddr` is the primary's API origin as the follower last knew it: a hint. **See below.** |
+| `CommitUnavailableError` | `commit_unavailable` | 503 | The commit is *unconfirmed* — it may or may not have landed. Retriable. Expect it while the cluster replaces a lost primary: a failover can outlast the server's commit wait (`submit_timeout_ms`). |
+| `EndpointsExhaustedError` | `endpoints_exhausted` | the last attempt's | Every failover URL failed within the budget. `.attempts` lists each, in order; `.last` is the final error. Retriable. |
+| `ApiError` | the wire code | any | A documented error with no distinct recovery: `unknown_account`, `unknown_usage`, `substrate_rejected`, `capability_mapping`, … The full body is on `.body`. |
+| `MissingAttestationError` | `missing_attestation` | — | A party-scoped read on a client holding no attestation. Raised **locally** — nothing was sent. Build with `attestation`, or `withAttestation`. |
+| `TransportError` | `transport` | — | The service could not be reached, or the request timed out. Retriable. |
+| `DeadlineExceededError` | `deadline_exceeded` | — | A `retry` policy's `deadlineMs` (or `authorize`'s budget) ran out before the request was sent. Retriable. |
+| `ConfigError` | `config` | — | The client could not be built. |
+| `UnexpectedResponseError` | `unexpected_response` | any | A non-2xx that is not an agent-plane body — a proxy, a load balancer. Bytes kept verbatim in `.rawBody`. |
+| `DecodeError` | `decode` | any | A success body that did not decode. Bytes kept verbatim. |
+
+Two accessors say what to do next:
+
+- **`error.isRetriable`** — re-send the *identical* request. True for `TransportError`,
+  `DeadlineExceededError` and `CommitUnavailableError`. Safe even for a submission: the transaction id is the
+  idempotency key, so a replay returns the stored outcome. You cannot double-post by
+  retrying.
+- **`error.requiresRepin`** — the policy moved. True exactly for `StalePolicyError`.
+
+The error body's **extras are load-bearing** and this client never flattens them away:
+without `pinned`/`active` no client could re-pin, and without `primary_api_addr` none
+could tell an operator which replica the follower believed was primary.
+
+```ts
+import { CommitUnavailableError, isAxorumError, StalePolicyError } from "@axorum/client";
+
+try {
+  await axorum.submitPinned(draft);
+} catch (error) {
+  if (error instanceof StalePolicyError) {
+    console.log(`pinned ${error.pinned}, but ${error.active} is in force`);
+  } else if (isAxorumError(error) && error.isRetriable) {
+    // The same envelope, the same transaction id. A replay, not a second posting.
+  }
+}
+```
+
+### A `421` is never followed to `primaryApiAddr`
+
+When a follower turns a mutation away, this client surfaces `primaryApiAddr`, the
+primary's API origin as the follower last knew it (`https://host:port`, or `http://` for a
+plaintext API). The origin is informational: it can name a primary that has just died, so
+the client never routes on it.
+
+`authorize` re-sends the same transaction id over its `failoverUrls` by itself. For any
+other mutation, re-send the same transaction id through the endpoints you configured; the
+transaction id is the idempotency key, so a re-send cannot double-post. A client that
+silently auto-follows would also hide a topology change from the operator who most needs to
+see it.
+
+```ts
+catch (error) {
+  if (error instanceof NotPrimaryError) {
+    console.warn(`a follower answered; it named ${error.primaryApiAddr ?? "no primary"} as the primary's API origin`);
+    // Re-send the same envelope, same transaction id, through your configured endpoints.
+  }
+}
+```
+
+## Development
+
+The wire types in `src/generated/` are generated from the **frozen** OpenAPI contract at
+`spec/openapi/agent-plane.v1.json` and committed. Field names are the wire's own —
+`snake_case` stays `snake_case`, because a second vocabulary is a second thing to keep in
+sync.
+
+This package and `@axorum/mcp` are one pnpm workspace rooted at `clients/`, so install
+once from there; CI regenerates `src/generated/` and fails if the committed output has
+drifted from the contract.
+
+```sh
+cd clients && pnpm install
+
+cd typescript
+pnpm generate    # regenerate src/generated/ from the frozen spec
+pnpm typecheck   # tsc --noEmit, strict
+pnpm build       # → dist/
+pnpm test        # unit + conformance
+```
+
+The **conformance suite** (`test/conformance/`) runs all thirteen scenarios from the Rust
+reference client against a **real, booted `axorum-serve`** — real routes, real policy
+evaluation, real error bodies. It deliberately does not mock: a mock would put whatever
+bytes the test author *believed* the service emits on the wire, which is exactly the belief
+under test. It needs the harness binary at
+`target/debug/examples/conformance_server`, built by the Rust workspace.
+
+```sh
+pnpm test:unit          # no server required
+pnpm test:conformance   # boots a real axorum-serve per scenario
+```

package/dist/agent-uri.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `agent://` URIs a payment may name: exactly the canonical form `agent-uri` 0.5.0
+ * renders, which the Rust SDK and the service parse with.
+ *
+ * A keyed payment derives its transaction id from the agent URI's bytes, so two
+ * spellings of one agent would derive two ids for one payment. Accepting only the
+ * canonical spelling makes both SDKs derive the same id. The rules, all pinned against
+ * the Rust parser by `spec/fixtures/agent-uri-canonical-v1.json`:
+ *
+ * - the grammar: `agent://<trust root>/<capability path>/<agent id>`, within the length
+ *   and segment limits;
+ * - N1: a domain is lowercase;
+ * - N2, N3: a port is decimal with no leading zero and no sign;
+ * - N4: an IPv6 address is written as RFC 5952 writes it, and an IPv4-mapped one in
+ *   dotted form (`::ffff:192.0.2.1`), as Rust's `Ipv6Addr` displays it;
+ * - no query and no fragment.
+ *
+ * @packageDocumentation
+ */
+/** Why a string is not a canonical agent URI, and the canonical form when there is one. */
+export interface AgentUriProblem {
+    readonly reason: string;
+    readonly canonical: string | undefined;
+}
+/**
+ * Why `uri` is not an agent URI in canonical form, or `undefined` when it is. When the
+ * part before any query or fragment parses, `canonical` names the form to pass. Pure.
+ */
+export declare function agentUriProblem(uri: string): AgentUriProblem | undefined;
+//# sourceMappingURL=agent-uri.d.ts.map

package/dist/agent-uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-uri.d.ts","sourceRoot":"","sources":["../src/agent-uri.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAqBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAYxE"}