@percayso-community/cayso-contracts 0.23.0

package/dist/index.d.ts

@@ -0,0 +1,621 @@
+/**
+ * `@percayso-community/cayso-contracts` — the versioned capability contract surface through which
+ * anything outside this repository reads a wallet (`cayso.wallet`).
+ *
+ * This barrel is the *only* public surface of the package: the record and
+ * response types, the closed failure-reason union, the assertion claims and the
+ * route constants land here across slices 5–7 (the assertion claims arrived in
+ * slice 7), and the thin client ships from the separate `./client` entry point
+ * in slice 8. Importing this package must do
+ * nothing but hand back its exports — no server, no connection, no environment
+ * read (CLAUDE.md: packages have no side effects on import).
+ *
+ * The assurance profile (CAY-0029) joins them, and is the first contract here to
+ * carry runtime values as well as types — the evidence statements and the
+ * acceptance policy are data a consumer and an issuer both have to read, and a
+ * type is erased before either can. The trust envelope (CAY-0030) adds the second
+ * set: the assertion header and envelope types, and the three clock constants an
+ * issuer sizes its credentials against.
+ *
+ * What the envelope adds here is the PIPER-FACING half of CAY-0030 and no more.
+ * The claims, the header, the scope vocabulary and the rotation obligation are a
+ * consumer's business and are published. The issuer registry — who we trust, under
+ * which key ids, serving which environment — is Cayso's own configuration and is
+ * deliberately NOT here: publishing our trust configuration would be publishing a
+ * map of what to attack, and it lives in the private `@cayso/identity` instead.
+ *
+ * The issued-but-uncaptured purchase (CAY-0033) is the newest: the status a
+ * purchase takes when its cents landed and its capture did not, which is neither a
+ * success nor a failure and may still become either; the bound on how many times
+ * capture is attempted before only an operator can move it; and the closed reason a
+ * compensated purchase finally carries. Its one runtime value is that bound.
+ *
+ * Purchase replay and continuation (CAY-0032) is the record before it: what a repeat `POST`
+ * with the same idempotency key does — it REPLAYS the original authorisation, at
+ * the original price — which statuses are terminal, the cancel path available to a
+ * holder, and what expiry releases. It carries three runtime values: the terminal
+ * status list and its predicate, and the reservation window a consumer sizes its
+ * confirmation page against.
+ *
+ * Citizenship provisioning (CAY-0031) is the contract before it: an explicit,
+ * idempotent call that provisions a wallet and its sign-up grant as one unit, and
+ * a separate read by which a consumer can ask whether a citizen has been
+ * provisioned WITHOUT provisioning them. It carries one runtime value — the
+ * `not_provisioned` wire code — and no figures: the grant's amount and its
+ * restriction period are FIELDS a consumer reads at runtime, sourced from the
+ * canon PRD through configuration, never literals here.
+ *
+ * The restricted-Cayso capability policy (CAY-0035) is the newest, and it is the
+ * only contract here that is a POLICY rather than a shape: four capabilities
+ * against four kinds of holding, every one of the sixteen cells written out as
+ * permitted, refused or explicitly open. It settles what a restriction actually
+ * restricts — cash-out, not spending — and it publishes the one cell the canon has
+ * not decided AS undecided rather than guessing it. It is published because a
+ * consumer rendering the restricted/unrestricted split on a balance cannot say what
+ * that split MEANS for a holder without it, and each consumer inventing its own
+ * answer is how two surfaces end up telling a citizen different things about the
+ * same cents. It is compile-time data with no side effects, and it enforces
+ * nothing.
+ *
+ * This is the *Piper-facing surface only*. Peer types, admin types, holdings and
+ * carves are deliberately not exported here; they are not a consumer's business.
+ * And it carries **no numbers** — amounts, rates, tiers, schedules and thresholds
+ * live in the canon PRD and are read from one place, never restated here.
+ */
+/**
+ * The independent semantic version of this contract surface.
+ *
+ * It is declared here and must agree with the package's own `version` field —
+ * a test asserts the two never drift. This is deliberately *not* a repo-wide
+ * constant shared with anything else: independent versioning is precisely what
+ * this money surface gains that Piper's own contracts lack, since theirs share
+ * one global version bumped across all twenty-two together (CAY-0026).
+ *
+ * `0.22.0` → `0.23.0` publishes the two money-grade marketplace operations and
+ * CAY-0082 §7's closed refusal unions (CAY-0083 §3, #303), and it is BREAKING because
+ * three closed tables grew:
+ *
+ *   - **`ContractOperation` gains `'settle-marketplace-order'` and
+ *     `'settle-marketplace-refund'`**, so every total map over the vocabulary needs
+ *     their entries.
+ *   - **`ASSURANCE_POLICY` gains their two rows, both money-grade allowlists** at the
+ *     purchase path's bar. `'dev-bypass'` is `'refused'` at both, and a future method
+ *     is admissible at neither without a policy decision (CAY-0029).
+ *   - **`CaysoApiErrorCode` gains {@link MarketplaceOrderRefusal} and
+ *     {@link MarketplaceRefundRefusal} by reference**, and with them the codes they
+ *     add.
+ *
+ * The shapes are additive. {@link MarketplaceOrderRequest} and
+ * {@link MarketplaceRefundRequest} each carry one {@link StoreSignedStatement}: the
+ * exact bytes Store Platform signed and the signature over them, with nothing beside
+ * them, so the idempotency key, the price and who is paid are never the caller's
+ * word. {@link MarketplaceOrderResponse} is a receipt narrowed to a sale's, or one
+ * refusal; {@link MarketplaceRefundResponse} is a receipt narrowed to a refund's, or
+ * one refusal. No route serves either operation yet.
+ *
+ * `0.21.0` → `0.22.0` publishes the marketplace status read (CAY-0083 §2, #302), and
+ * it is BREAKING because two closed tables grew:
+ *
+ *   - **`ContractOperation` gains `'read-marketplace-receipt'`**, so every total map
+ *     over the vocabulary — `ASSURANCE_POLICY` among them — needs its entry.
+ *   - **`ASSURANCE_POLICY` gains its row, read-scope (`'not-required'`)**: the read
+ *     moves nothing and writes no row of its own, and the bar was applied when the
+ *     sale or refund it reports on was presented.
+ *
+ * The shapes are additive. {@link MarketplaceReceiptReadRequest} carries the
+ * idempotency key and nothing else, because the paying wallet is the verified
+ * subject's own. {@link MarketplaceReceiptReadResponse} is a receipt, "no movement
+ * for this key", or a refusal from {@link MarketplaceReceiptReadRefusal} — and
+ * never "pending", because a movement is written or it is not (CAY-0023). The
+ * refusal joins `CaysoApiErrorCode` by reference and adds no code. No route serves
+ * the read yet, and the two money-grade marketplace operations are not published
+ * here (#303).
+ *
+ * `0.20.0` → `0.21.0` publishes the marketplace receipt (CAY-0083 §1, #301), and it
+ * is BREAKING because one closed union grew:
+ *
+ *   - **`CaysoApiErrorCode` gains `receipt_signing_not_configured`**: the deployment
+ *     holds no key it may sign a receipt with, so it writes no marketplace sale or
+ *     refund. Published before the checkout that answers it (#303).
+ *
+ * The rest is additive. {@link MarketplaceReceipt} is a statement and Cayso's
+ * signature over its encoding, and the statement is one of four shapes — a
+ * third-party sale, a house-publisher charge, and the refund of each — so a
+ * house-publisher statement has no publisher leg to fill. It names wallet ids and
+ * never a Percayso identity. Two values arrive with it:
+ * {@link MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM}, and
+ * {@link encodeMarketplaceReceiptStatement}, the one encoding the signer and Store
+ * Platform both compute the signature over. No key, key set or verifier is here;
+ * no route serves a receipt yet (#302, #303).
+ *
+ * `0.19.0` → `0.20.0` serves the Treasury's buy-back (CAY-0080 slice 10, #291), and it
+ * is BREAKING because three closed tables grew:
+ *
+ *   - **`ROUTES` gains `requestBuyBack`**, `POST /api/buy-backs`.
+ *     `OPERATION_FOR_ROUTE` maps it to `'request-buy-back'`, the operation `0.17.0`
+ *     classified, and the client gains `requestBuyBack`.
+ *   - **{@link BuyBackRefusal} gains `eligible_sterling_insufficient`**: the Treasury's
+ *     eligible sterling cannot meet the request, which is refused whole and never
+ *     rationed (§2.3), pending Simon James's answer to Open decision I. There is still
+ *     no per-holder limit reason: figure 11 is his, and until he answers the buy-back
+ *     is shut by configuration.
+ *   - **`CaysoApiErrorCode` gains `buy_back_not_configured` and
+ *     `sterling_not_observed`**. The first is the buy-back's closed door, on a
+ *     deployment with no buy-back store or with one of its figures unset. The second
+ *     is a deployment that has never observed sterling; the purchase path already
+ *     answered it (#246), and the union now says so.
+ *
+ * The buy-back's request and answer shapes are the ones `0.17.0` published, unchanged.
+ * The payout stays behind the fake gateway (§3.4) and adds nothing here.
+ *
+ * `0.18.0` → `0.19.0` settles a match (CAY-0080 slice 9, #290), and it is BREAKING
+ * because two closed unions grew:
+ *
+ *   - **{@link QuoteWithdrawalReason} gains `authorisation_refused`**: a bid that met
+ *     an ask and whose holder's sterling could not be authorised for the match leaves
+ *     the book with this reason, and no cents move (CAY-0080 §3.2, step 2). A
+ *     consumer's exhaustive rendering of a withdrawn quote must place it.
+ *   - **{@link QuotePlacementRefusal} gains `sterling_leg_unavailable`**: the quote met
+ *     the book and the sterling leg could not be reached, so nothing was written and
+ *     the placement may be retried under the same key.
+ *
+ * The match's settlement — its capture, its bounded retries and an operator's
+ * re-attempt or compensation — is an operator surface and adds nothing here.
+ *
+ * `0.17.0` → `0.18.0` serves the citizen market's book (CAY-0080 slice 8, #289), and
+ * it is BREAKING because three closed tables grew.
+ *
+ *   - **`ROUTES` gains `citizenMarket`, `placeQuote` and `withdrawQuote`**:
+ *     `GET /api/citizen-market`, `POST /api/quotes` and `POST /api/quote-withdrawals`.
+ *     `OPERATION_FOR_ROUTE` maps the two writes to `'place-quote'` and
+ *     `'withdraw-quote'`, and the client gains `getCitizenMarket`, `placeQuote` and
+ *     `withdrawQuote`, one method for each route. The buy-back is not served yet.
+ *   - **`ContractOperation` gains `'read-citizen-market'`**, the read beside the two
+ *     writes, with no assurance bar, as `'read-own-wallet'` has none.
+ *   - **`CaysoApiErrorCode` gains `citizen_market_not_configured`**, the market's
+ *     closed door on a deployment with no store or an unset figure. It is none of the
+ *     market's refusal unions' members.
+ *
+ * The book's read shapes are new and additive: {@link CitizenMarketResponse} and
+ * {@link CitizenMarketView} — the published value and its band, both bounds per
+ * quote unit, the best bid and ask as {@link BookLevel}s, and the caller's own
+ * quotes as {@link OwnQuote}s, a withdrawn one carrying its closed
+ * {@link QuoteWithdrawalReason}. No match price, no feed and no history (Open
+ * decision F). The refusal unions of `0.17.0` do not change.
+ *
+ * `0.16.0` → `0.17.0` is the citizen market's contract and acceptance policy
+ * (CAY-0080 slices 3 and 4, #286), and it is BREAKING because two closed unions
+ * grew. No route is added and no migration is behind it: the operations are
+ * classified before they are served, as the commercial payment's was.
+ *
+ *   - **`ContractOperation` gains `'place-quote'`, `'withdraw-quote'` and
+ *     `'request-buy-back'`**, each money-grade in `ASSURANCE_POLICY` — `'document'`
+ *     and `'document-and-biometric'`, never `'dev-bypass'` (Open decision Q). A
+ *     consumer's exhaustive handling of the operation vocabulary must place them.
+ *   - **`CaysoApiErrorCode` gains the market's refusals by reference**:
+ *     {@link QuotePlacementRefusal}, which is CAY-0080 §1.6's fixed set
+ *     ({@link QuoteEntryRefusal}) beside the key-reuse refusal,
+ *     {@link QuoteWithdrawalRefusal} and {@link BuyBackRefusal}. The buy-back names
+ *     no eligible-sterling shortfall and no per-holder limit, because both are
+ *     Simon James's (Open decision I, figure 11).
+ *   - **The request and answer shapes are new and additive**: {@link QuoteRequest}
+ *     and {@link QuoteResponse}, {@link QuoteWithdrawalRequest} and
+ *     {@link QuoteWithdrawalResponse}, {@link BuyBackRequest} and
+ *     {@link BuyBackResponse}, each discriminated by `outcome`. No request names a
+ *     wallet: the holder is the verified subject.
+ *
+ * Under semver below `1.0.0` the minor is where a breaking change goes, so the minor
+ * moves and the patch does not.
+ *
+ * `0.15.0` → `0.16.0` serves the commercial payment's Authorised-User route (CAY-0079,
+ * #284), and it is BREAKING because a closed union SHRANK.
+ *
+ *   - **`CaysoApiErrorCode` loses `payment_allowance_route_not_served`.** It answered
+ *     `authority: 'payment-allowance'` until the Authorised-User route shipped, and
+ *     that route is now served: a caller declaring it is held to the pair's payment
+ *     allowance and the Signatory / Authorised-User threshold, and is answered in
+ *     `CommercialPaymentResponse`. A consumer that rendered the retired code must
+ *     drop the case; nothing produces it.
+ *
+ * `CommercialPaymentRefusal` does not change: the Authorised-User route's members were
+ * on it from `0.14.0`, and the route now produces them.
+ *
+ * `0.14.0` → `0.15.0` serves the commercial payment, on the mandate route (CAY-0079
+ * slice 6, #283), and it is BREAKING because two closed tables grew.
+ *
+ *   - **`ROUTES` gains `commercialPayment`**, `POST /api/commercial-payments`, and
+ *     `OPERATION_FOR_ROUTE` maps it to `'make-commercial-payment'`. The client
+ *     gains `makeCommercialPayment`, one method for the one route.
+ *   - **`CaysoApiErrorCode` gains two seam codes.**
+ *     `commercial_payment_store_not_configured` is the route's closed door on a
+ *     deployment not told enough to make a payment. `payment_allowance_route_not_served`
+ *     is the answer to `authority: 'payment-allowance'` until the Authorised-User
+ *     route ships second (Open decision H); nothing is checked against an allowance
+ *     and the mandate route is never tried instead. Neither is a
+ *     `CommercialPaymentRefusal`, because each describes the deployment and not the
+ *     payment.
+ *
+ * `CommercialPaymentRefusal` itself does not change. The route answers its members,
+ * including `assurance_not_money_grade` from the money gate, in the
+ * `CommercialPaymentRefused` envelope.
+ *
+ * `0.13.0` → `0.14.0` is the commercial payment's contract (CAY-0079, #281), and it
+ * is BREAKING because two closed unions grew. No route is added: the operation is
+ * classified before it is served, as `'provision-citizenship'` was, and the route is
+ * CAY-0079's slice 6.
+ *
+ *   - **`ContractOperation` gains `'make-commercial-payment'`**, an Organisation
+ *     paying a Citizen. Its acceptance policy is money-grade — `'document'` and
+ *     `'document-and-biometric'`, never `'dev-bypass'` — the purchase path's bar. A
+ *     consumer's exhaustive handling of the operation vocabulary must place it.
+ *   - **`CaysoApiErrorCode` gains {@link CommercialPaymentRefusal} by reference**:
+ *     CAY-0079 §3's set, including the Authorised-User route's reasons, which
+ *     nothing can produce until that route ships second (Open decision H). They are
+ *     here from the first version so that they are never a later change to a closed
+ *     union.
+ *   - **The request and answer shapes are new and additive**:
+ *     {@link CommercialPaymentRequest}, and {@link CommercialPaymentResponse}
+ *     discriminated by `outcome` as `'paid'` or `'refused'`. There is no status,
+ *     because a commercial payment is one movement or nothing.
+ *
+ * Under semver below `1.0.0` the minor is where a breaking change goes, so the minor
+ * moves and the patch does not.
+ *
+ * `0.12.0` → `0.13.0` is erasure resolving a holder's in-flight purchases (CAY-0085,
+ * H8-R2), and it is BREAKING because a closed union grew:
+ *
+ *   - **`PurchaseFailureReason` gains `'holder_erased'`.** The union is closed and
+ *     consumers switch on it exhaustively, so a new member is breaking by construction
+ *     (CAY-0023) — which is the property that makes it safe to add. Erasing a holder's
+ *     binding now first ends every purchase of theirs that was authorised and had
+ *     issued nothing, with this reason, and a settlement delivery for a wallet with no
+ *     binding is refused with it rather than issuing into a wallet bound to nobody. A
+ *     consumer polling such a purchase sees it end `failed` with a member it can
+ *     render.
+ *
+ * Under semver below `1.0.0` the minor is where a breaking change goes, so the minor
+ * moves and the patch does not.
+ *
+ * `0.11.0` → `0.12.0` is the founder claim's contract (CAY-0081, #252), and it is
+ * BREAKING because two closed unions grew. The operation was classified first and is
+ * served in the same version, so no release carries the operation without its route.
+ *
+ *   - **`ROUTES` gains `citizenshipFounderClaim`**, `POST /api/citizenship/founder-claim`,
+ *     and the client gains `claimFounderWallet()` beside it. Neither takes a
+ *     parameter: the founder wallet is named by the reference inside the signed
+ *     assertion, and the Citizen by its subject. It answers
+ *     {@link CitizenshipFounderClaimed} alone, with no `terms`, because a founder is
+ *     never offered a sign-up grant.
+ *   - **`ContractOperation` gains `'claim-founder-wallet'`.** Its acceptance policy
+ *     accepts `'document-and-biometric'` alone, stricter than any other operation,
+ *     because a founder completes full identity proofing before claiming. An issuer
+ *     minting it must also mint the new claim beside it.
+ *   - **`AssertionClaims` gains `founderClaimReference`**, optional on the wire and
+ *     bound to that operation in both directions. A credential scoped to
+ *     `'claim-founder-wallet'` without it is refused, and so is a credential that
+ *     carries it without that scope. No credential this surface accepted before is
+ *     refused now, because until today neither the key nor the scope entry could
+ *     appear on a credential that verified.
+ *   - **`Citizenship` gains `'founder-claimed'`** ({@link CitizenshipFounderClaimed}),
+ *     carrying the wallet and no sign-up grant. A consumer's exhaustive switch on
+ *     `state` must handle it. The founder claim answers it, and so do both
+ *     citizenship routes for a claimed founder. A consumer that treated it as
+ *     `not-provisioned` would offer a claimed founder the provisioning call that
+ *     must not reach them.
+ *   - **`CaysoApiErrorCode` gains {@link FounderClaimRefusal} by reference**,
+ *     including `founder_wallet_lapsed`, which nothing can produce until the lapse
+ *     is built. It is here from the first version so that it is never a later
+ *     change to a closed union. It also gains `founder_claim_store_not_configured`,
+ *     the route's 503 for a wiring with no store, beside its siblings.
+ *
+ * Under semver below `1.0.0` the minor is where a breaking change goes, so the
+ * minor moves and the patch does not.
+ *
+ * `0.10.0` → `0.11.0` is the build, not the contract (#270). `0.10.0` shipped relative
+ * imports without an extension, which Node's ESM loader refuses, so a consumer running
+ * the package with no bundler in front of it failed at start-up (piper.platform#182).
+ * The package now builds under NodeNext and every emitted specifier names its `.js`
+ * file. No type, export, route or file changed, and nothing on the wire moved. By the
+ * convention below that is a patch; #270 set the minor, so the minor moves.
+ *
+ * `0.9.0` → `0.10.0` is the transfer of a restricted lot, decided (CAY-0074). No type
+ * changed and nothing on the wire moved. What changed is two cells of
+ * `CAPABILITY_POLICY`: `transfer-to-another-holder` for a promotional reward and for
+ * a founder allocation went from `open` to `refused`, because a carve does not move
+ * restriction and a transfer would shed it. `OPEN_CAPABILITIES` is now empty. The
+ * `'open'` standing stays in the union for the next undecided cell.
+ *
+ * A consumer that does nothing keeps compiling, which would make this a patch. The
+ * minor moves instead because the answer a consumer renders changed behind an
+ * unchanged shape. A page that showed a citizen "not decided" must now show "not
+ * permitted", and that is the case this file exists to make visible.
+ *
+ * `0.8.0` → `0.9.0` is the published refusal contract (CAY-0058 §5), and it is
+ * PURELY ADDITIVE. No existing type changed, no closed union gained a member, no
+ * route was added or altered, and no refusal this surface already answered is
+ * spelled differently today than it was yesterday. What arrives is the envelope
+ * those refusals always travelled in ({@link CaysoErrorResponse}) and the closed
+ * set of codes it may carry ({@link CaysoApiErrorCode}), written down at last, plus
+ * the one code the request-rate limits answer with.
+ *
+ *   - **`REQUEST_RATE_LIMITED` is new, and so is the refusal behind it.** A request
+ *     may now be refused because too many arrived too quickly — from one source
+ *     address, or under one verified credential. A consumer that renders an
+ *     unrecognised code as an outage would mislead somebody who simply needs to
+ *     wait, so the code is published and a consumer should render it as a refusal
+ *     to retry shortly. The refusal carries no header and no body field saying how
+ *     long shortly is; that is the contract, not an omission.
+ *   - **`CaysoApiErrorCode` includes `PurchaseFailureReason` and
+ *     `PurchaseCancelRefusalReason` by reference.** They are not restated, so
+ *     neither can grow a member the published code set does not carry.
+ *
+ * A consumer that does nothing keeps working, which under the convention stated
+ * below would make this a patch. The minor moves instead because the surface grew a
+ * contract a consumer may now depend on exhausting — and because a refusal code that
+ * did not exist can now arrive, which is a behaviour change behind unchanged shapes,
+ * the case this file exists to make visible.
+ *
+ * `0.7.0` → `0.8.0` is the sterling that cannot be priced into cents (pen-test
+ * C3-3, #148), and it is BREAKING for the same reason the bump below is — a closed
+ * union grew:
+ *
+ *   - **`PurchaseFailureReason` gains `'amount_not_priceable'`.** The union is
+ *     closed and consumers switch on it exhaustively, so a new member is breaking
+ *     by construction (CAY-0023) — which is the property that makes it safe to
+ *     add. `POST /api/purchases` accepted any positive whole number of pence and
+ *     decided whether it could be priced into cents deeper in, where the answer
+ *     had no way of reaching a consumer; sterling beyond what integer cents can
+ *     hold at the published value in force is now refused with this member, before
+ *     anything is authorised, reserved or charged. A consumer asking for ordinary
+ *     amounts sees no difference; one that could previously be answered with a
+ *     failure outside the union now gets a member it can render.
+ *
+ * The bound the refusal marks is arithmetic and not a figure: it is the largest
+ * sterling that still prices inside integer cents at the published value, so it
+ * rises as the published value ratchets (CAY-0002, CAY-0013) and no number about
+ * it appears anywhere on this surface.
+ *
+ * `0.6.1` → `0.7.0` is the amount-mismatched replay (#134), and it is BREAKING
+ * because a closed union grew:
+ *
+ *   - **`PurchaseFailureReason` gains `'amount_mismatch'`.** The union is closed
+ *     and consumers switch on it exhaustively, so a new member is breaking by
+ *     construction (CAY-0023) — which is the property that makes it safe to add. A
+ *     repeat `POST /api/purchases` under a key the same holder has already used at
+ *     a DIFFERENT `sterlingPence` is now refused with it, where it used to be
+ *     answered as a Replay at whichever amount the first request carried. Replay
+ *     means "the same idempotency key again" and a different amount is not the
+ *     same request; a consumer that resumes an interrupted purchase by repeating
+ *     it unchanged sees no difference, and one that changed the amount now learns
+ *     that it must use a new key instead of being quietly charged the old one.
+ *
+ * `ScopeKey = ContractOperation | InternalOperation` arrived on this same
+ * unreleased line and is additive: `ContractOperation` stays closed, so a contract
+ * consumer's mistyped operation is still a compile error.
+ *
+ * `0.6.0` → `0.6.1` is the restricted-Cayso capability policy (CAY-0035), and it
+ * is PURELY ADDITIVE. No existing type changed, no closed union gained a member, no
+ * route was added or altered, and nothing on the wire moved: `Balance` still reports
+ * the same restricted and unrestricted figures it always did. What arrives is a new
+ * compile-time table saying what those figures MEAN, which a consumer may read or
+ * ignore. A consumer that does nothing keeps working, so the patch moves and the
+ * minor does not — the same convention the breaking bumps below state from the other
+ * side.
+ *
+ * It is a version bump at all, rather than none, because the surface genuinely grew:
+ * a consumer can now depend on `CAPABILITY_POLICY` existing, and a published package
+ * whose exports change without its version changing cannot be depended on at all.
+ *
+ * `0.5.0` → `0.6.0` is the issued-but-uncaptured purchase (CAY-0033), and it is
+ * BREAKING in three places, bumped as one — the same reasoning as the bump below.
+ *
+ *   - **`PurchaseStatus` gains `'issued_uncaptured'`.** The union is closed and
+ *     consumers switch on it exhaustively, so a new member is breaking by
+ *     construction (CAY-0023) — which is the property that makes it safe to add. It
+ *     is NOT terminal: a consumer that treated an unknown status as an ending would
+ *     stop polling one step before the answer, which is exactly why the new member
+ *     has to be visible in the version rather than arrive quietly.
+ *   - **`PurchaseAuthorisationResponse` gains an `'unresolved'` branch.** A repeat
+ *     `POST` of a key whose purchase has issued but not captured is answered with
+ *     it. A consumer's exhaustive switch on `outcome` must handle it; there is no
+ *     live hold to confirm and nothing has ended, so neither existing branch could
+ *     have carried the truth.
+ *   - **`PurchaseFailureReason` gains `'capture_failed'`, and
+ *     `PurchaseCancelRefusalReason` gains `'already_issued'`.** Both unions are
+ *     closed and exhaustively switched on, so both are breaking additions.
+ *
+ * `MAX_CAPTURE_ATTEMPTS`, the `PurchaseUnresolved` type and the `LivePurchaseStatus`
+ * union are additive and would not have needed a breaking bump on their own. Under
+ * semver below `1.0.0` the minor is where a breaking change goes, so the minor moves
+ * and the patch does not.
+ *
+ * `0.4.0` → `0.5.0` is purchase replay and continuation (CAY-0032), and it is
+ * BREAKING in three places, bumped as one. It is stated as breaking rather than
+ * softened, for the reason the bump below was: a consumer reading this must change
+ * what it does.
+ *
+ *   - **`PurchaseAuthorised` gains a required `outcome` discriminant.** The
+ *     response to `POST /api/purchases` is now ONE declared union
+ *     ({@link PurchaseAuthorisationResponse}) that a consumer switches on, rather
+ *     than three shapes it told apart by which fields were present. A consumer
+ *     that sniffed for `paymentClientSecret` still works by accident today and
+ *     will not the next time a branch is added, so the discriminant is required
+ *     and the version says so.
+ *   - **`PurchaseStatus` gains `'cancelled'`.** The union is closed and consumers
+ *     switch on it exhaustively, so a new member is breaking by construction
+ *     (CAY-0023) — which is the property that makes it safe to add. A cancelled
+ *     purchase is deliberately not a failed one: a failure happened TO somebody, a
+ *     cancellation was CHOSEN, and rendering them alike tells a holder their
+ *     payment failed when they changed their mind.
+ *   - **`ContractOperation` gains `'cancel-purchase'`.** An issuer minting
+ *     assertions must put it in `scope` for a holder to be able to cancel, and an
+ *     empty or unchanged scope authorises nothing (CAY-0030). A consumer that does
+ *     not mint it simply cannot cancel — which is a refusal, not a failure, but it
+ *     is a change to what an issuer must do.
+ *
+ * The cancel route, the terminal-status statement, the reservation window and the
+ * cancel response types are additive and would not have needed a breaking bump on
+ * their own. Under semver below `1.0.0` the minor is where a breaking change goes,
+ * so the minor moves and the patch does not.
+ *
+ * `0.3.0` → `0.4.0` was citizenship provisioning (CAY-0031), and it was a BREAKING
+ * change in two places, bumped as one. Both are stated as breaking rather than
+ * softened: a consumer reading this must change what it does, and a version that
+ * implied otherwise would be the lie that costs it an outage.
+ *
+ *   - **`GET /api/wallet` no longer provisions.** It used to create a wallet on
+ *     the first authenticated read (CAY-0022); it now creates nothing and refuses
+ *     an unprovisioned citizen with {@link NOT_PROVISIONED}. A consumer that
+ *     relied on reading a wallet to bring one into being must call
+ *     `ROUTES.citizenshipProvision` first. Nothing in a type changed, which is
+ *     exactly why the version has to say so: a silent behaviour change behind an
+ *     unchanged shape is the worst kind, and the only place a consumer can be
+ *     warned is here.
+ *   - **`PurchaseFailureReason` gains `'not_provisioned'`.** The union is closed
+ *     and consumers switch on it exhaustively, so a new member is breaking by
+ *     construction (CAY-0023) — which is the property that makes it safe to add.
+ *
+ * The new `citizenship` types and the two new routes are additive and would not
+ * have needed a breaking bump on their own. Under semver below `1.0.0` the minor
+ * is where a breaking change goes, so the minor moves and the patch does not.
+ */
+export declare const CONTRACT_VERSION: "0.23.0";
+/** The package's own name, so a consumer can name what it depends on. */
+export declare const packageName = "@percayso-community/cayso-contracts";
+/**
+ * The `cayso.wallet` capability name (slice 5). A value, not a type: a consumer
+ * names the capability it is reading, and `CaysoWallet.capability` is typed as
+ * `typeof WALLET_CAPABILITY` so the two can never drift apart.
+ */
+export { WALLET_CAPABILITY } from './wallet.js';
+/**
+ * The `cayso.purchase` capability name and the route table (slice 6). Both are
+ * values: a consumer names the capability it is exercising, and reads a method
+ * and path from `ROUTES` rather than hand-writing a URL. The closed
+ * failure-reason union that pairs with them is a type, exported below.
+ */
+export { PURCHASE_CAPABILITY } from './purchase.js';
+export { ROUTES } from './routes.js';
+/**
+ * The purchase lifecycle's runtime half (CAY-0032): which statuses a purchase
+ * never leaves, the predicate over them, and the window an authorisation holds its
+ * reserved headroom for.
+ *
+ * Values rather than types, and for the same reason the credential's clock
+ * parameters are: a consumer has to be able to READ them. A poller deciding
+ * whether to stop needs the terminal set at runtime, and a confirmation page
+ * deciding how long to stay live needs the window — neither can be read from a
+ * type, and a consumer that maintains its own copy of either maintains the copy
+ * that goes stale. The window is a MECHANISM parameter of this contract, the
+ * documented exception to keeping numbers in the canon PRD; no economic figure is
+ * here.
+ */
+export { TERMINAL_PURCHASE_STATUSES, isTerminalPurchaseStatus, PURCHASE_RESERVATION_WINDOW_SECONDS, } from './purchase.js';
+/**
+ * How many capture attempts a purchase gets before only an operator can move it
+ * (CAY-0033). A value for the same reason the window beside it is one: a consumer
+ * watching a purchase sit in `'issued_uncaptured'` is entitled to know that the
+ * retrying is bounded and where the bound is, and cannot read either from a type.
+ * A MECHANISM parameter of this contract, not an economic figure.
+ */
+export { MAX_CAPTURE_ATTEMPTS } from './purchase.js';
+/**
+ * The `not_provisioned` wire code (CAY-0031). A value, not a type: a consumer
+ * comparing a refusal against the contract's own string is comparing against one
+ * source, where a consumer retyping our spelling has made a second.
+ */
+export { NOT_PROVISIONED } from './citizenship.js';
+/**
+ * The credential's clock and retention parameters (CAY-0030): the ceiling an
+ * `exp` is measured against, the skew two honest clocks are allowed, and the
+ * floor on how long a recorded use must be kept so replay is actually refused.
+ *
+ * Values rather than types because a consumer has to be able to READ them — an
+ * issuer sizing its lifetimes against our ceiling cannot do it from a type — and
+ * because the retention floor is DERIVED from the other two and must stay derived.
+ * They are security parameters of this credential, which is the documented
+ * exception to keeping numbers in the canon PRD; no economic figure is here.
+ */
+export { MAX_ASSERTION_LIFETIME_SECONDS, CLOCK_SKEW_TOLERANCE_SECONDS, MINIMUM_ASSERTION_USE_RETENTION_SECONDS, } from './assertion.js';
+/**
+ * The assurance profile (CAY-0029): what each `VerificationMethod` asserts, which
+ * methods each operation accepts, and the version a claim is minted under.
+ *
+ * Unlike the other contracts here, this one has a RUNTIME half and must: a
+ * statement of evidence that only existed as a type would be erased before any
+ * issuer could check its own claim against it, and an acceptance policy only a
+ * compiler can read is not a policy a consumer can read. The values are frozen
+ * data and pure functions — nothing runs on import.
+ */
+export { ASSURANCE_PROFILE_VERSION, RECOGNISED_ASSURANCE_PROFILE_VERSIONS, EVIDENCE_STATEMENTS, VERIFICATION_METHODS, ASSURANCE_POLICY, CONTRACT_OPERATIONS, OPERATION_FOR_ROUTE, acceptedMethods, assessAssurance, evidenceSupports, methodForEvidence, } from './assurance.js';
+/**
+ * The restricted-Cayso capability policy (CAY-0035): what each kind of holding may
+ * do, which kinds land restricted and what an expiry does for each, and where a
+ * lot of any kind stands once its restriction has lapsed.
+ *
+ * Values rather than types for the same reason the assurance policy is one — a
+ * table only a compiler can read is not a table a consumer can render. A wallet
+ * page showing a holder why part of their balance cannot be cashed out yet reads
+ * these; a page that hard-coded the answer would be a second copy of a policy that
+ * has one home. Frozen data and nothing else: there is deliberately no function
+ * here, because a predicate over a standing would have to fold an open cell into
+ * a yes or a no.
+ *
+ * `OPEN_CAPABILITIES` is exported so that "which cells has nobody decided" has a
+ * runtime answer. It is empty since CAY-0074 settled the two transfer cells; a
+ * consumer still renders any cell it lists as open, never as refused, which is the
+ * comfortable mistake.
+ */
+export { CAPABILITY_POLICY, RESTRICTION_ON_ARRIVAL, ONCE_UNRESTRICTED, HOLDING_KINDS, HOLDING_CAPABILITIES, OPEN_CAPABILITIES, } from './restriction.js';
+/**
+ * The money path's own cents type (CAY-0045): the constructor that is the only way
+ * to obtain a {@link PositiveCents}, the amount a caller may ask the economy to
+ * move.
+ *
+ * A value rather than a type, and it has to be: a brand is erased, so a type alone
+ * publishes a shape nobody can construct. It is the second layer CLAUDE.md requires
+ * beside the schema's `CHECK (cents > 0)`, and it is HERE rather than beside the
+ * carve because `packages/ledger` may not depend on an app — the module that moves
+ * cents could not otherwise reach the module that types them (pen-test C3-1).
+ *
+ * It changes no wire shape. `Cents` stays the permissive alias every request and
+ * response speaks in, the served contract schema is unchanged, and nothing on this
+ * surface newly refuses a figure a consumer could already send. `money.ts` says why
+ * the two types are separate on purpose.
+ */
+export { positiveCents } from './money.js';
+/**
+ * The refusal envelope's one published code (CAY-0058 §5): what a request refused
+ * by a request-rate limit answers with.
+ *
+ * A value rather than a type for the reason `NOT_PROVISIONED` is one — a consumer
+ * comparing a refusal against a string it retyped itself is a consumer whose
+ * rendering goes wrong silently. The envelope and the closed code union beside it
+ * are erased and appear in the type block below; this constant is the whole of the
+ * runtime surface the refusal contract adds.
+ */
+export { REQUEST_RATE_LIMITED } from './errors.js';
+/**
+ * The marketplace receipt's runtime half (CAY-0083 §1): the algorithm it is signed
+ * with, and the exact bytes the signature is over.
+ *
+ * Values rather than types because both sides must compute the same bytes: a
+ * verifier that wrote its own JSON for the statement would one day disagree with the
+ * signer by a space and refuse every receipt. The encoder is pure — JSON and a UTF-8
+ * encoder, no cryptographic dependency — and refuses a statement that is not exactly
+ * one of the four.
+ */
+export { MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM, encodeMarketplaceReceiptStatement, } from './marketplace-receipt.js';
+export type { PositiveCents } from './money.js';
+export type { CaysoApiErrorCode, CaysoErrorResponse } from './errors.js';
+export type { HolderType, Millis, Cents, WalletRecord, Balance, Allowance, WalletView, CaysoWallet, } from './wallet.js';
+export type { SignUpGrantTerms, SignUpGrant, CitizenshipNotProvisioned, CitizenshipProvisioned, CitizenshipFounderClaimed, Citizenship, CitizenshipView, FounderClaimRefusal, } from './citizenship.js';
+export type { OrganisationView } from './organisation.js';
+export type { CommercialPaymentAuthority, CommercialPaymentRequest, CommercialPayment, CommercialPaymentMade, CommercialPaymentRefused, CommercialPaymentResponse, CommercialPaymentRefusal, } from './commercial-payment.js';
+export type { QuoteSide, QuoteRequest, Quote, QuotePlaced, QuoteRefused, QuoteResponse, QuoteEntryRefusal, QuotePlacementRefusal, QuoteWithdrawalRequest, QuoteWithdrawal, QuoteWithdrawn, QuoteWithdrawalRefused, QuoteWithdrawalResponse, QuoteWithdrawalRefusal, BuyBackRequest, BuyBack, BuyBackMade, BuyBackRefused, BuyBackResponse, BuyBackRefusal, BookLevel, QuoteStatus, QuoteWithdrawalReason, OwnQuote, OwnQuoteNotWithdrawn, OwnQuoteWithdrawn, CitizenMarketView, CitizenMarketViewed, CitizenMarketViewRefusal, CitizenMarketViewRefused, CitizenMarketResponse, } from './citizen-market.js';
+export type { MarketplaceReceiptSignatureAlgorithm, MarketplaceReceiptKeyId, MarketplaceSaleKind, MarketplaceReceiptLeg, MarketplaceSettlementReceiptStatement, HousePublisherChargeReceiptStatement, ThirdPartyRefundReceiptStatement, HousePublisherRefundReceiptStatement, MarketplaceReceiptStatement, MarketplaceReceipt, MarketplaceReceiptReadRequest, MarketplaceReceiptFound, MarketplaceNoMovement, MarketplaceReceiptReadRefusal, MarketplaceReceiptReadRefused, MarketplaceReceiptReadResponse, } from './marketplace-receipt.js';
+export type { StoreSignedStatement, MarketplaceOrderRequest, MarketplaceRefundRequest, MarketplaceOrderReceipt, MarketplaceRefundReceipt, MarketplaceOrderSettled, MarketplaceOrderRefused, MarketplaceOrderResponse, MarketplaceOrderRefusal, MarketplaceRefundSettled, MarketplaceRefundRefused, MarketplaceRefundResponse, MarketplaceRefundRefusal, } from './marketplace-settlement.js';
+export type { PurchaseRequest, PurchaseAuthorised, PurchaseTerminal, PurchaseUnresolved, PurchaseRefused, PurchaseAuthorisationResponse, PurchaseFailureReason, PurchaseStatus, LivePurchaseStatus, TerminalPurchaseStatus, PurchaseCancelRefusalReason, PurchaseCancelled, PurchaseCancelRefused, PurchaseCancelResponse, PurchaseResult, } from './purchase.js';
+export type { VerificationMethod, VerificationStatus, SubjectPersonhood, AssertionClaims, AssertionHeader, AssertionEnvelope, ContractOperation, InternalOperation, ScopeKey, } from './assertion.js';
+export type { VerificationEvidence, EvidenceStatement, MethodDecision, MethodDecisions, AssuranceRequired, AssuranceNotRequired, OperationAssurance, AssuranceRefusalReason, AssuranceAssessment, } from './assurance.js';
+export type { Restriction, HoldingKind, HoldingCapability, PermittedStanding, RefusedStanding, OpenStanding, CapabilityStanding, CapabilityCell, CapabilityCoordinate, CapabilityPolicy, ArrivalAndExpiry, } from './restriction.js';