@percayso-community/cayso-contracts 0.27.0 → 0.30.0

package/dist/errors.d.ts

@@ -43,8 +43,9 @@
  */
 import type { FounderClaimRefusal } from './citizenship.js';
 import type { BuyBackRefusal, QuotePlacementRefusal, QuoteWithdrawalRefusal } from './citizen-market.js';
-import type { SettlementAssertionRefusal, StandingAuthorisationRefusal } from './cloud-settlement.js';
+import type { SettlementAssertionRefusal, StandingAuthorisationRefusal, StandingAuthorisationRevocationRefusal, NodeBindingQueryRefusal, NodeBindingRefusal } from './cloud-settlement.js';
 import type { CitizenTransferRefusal } from './citizen-transfer.js';
+import type { HandleChangeReceiptReadRefusal, HandleChangeRefusal } from './handle-change.js';
 import type { CommercialPaymentRefusal } from './commercial-payment.js';
 import type { MarketplaceReceiptReadRefusal } from './marketplace-receipt.js';
 import type { MarketplaceOrderRefusal, MarketplaceRefundRefusal } from './marketplace-settlement.js';
@@ -126,6 +127,21 @@ export type CaysoApiErrorCode =
  * transfer's refusal union.
  */
  | 'citizen_transfer_store_not_configured'
+/**
+ * No Handle-change store is wired, so the route is closed (CAY-0091). It describes
+ * the deployment and not the payment, so it is not a member of the refusal union.
+ */
+ | 'handle_change_store_not_configured'
+/**
+ * The Handle-change price is not configured on this deployment, so nothing can be
+ * charged (CAY-0091). An unset price is a closed door, never a free Handle change.
+ */
+ | 'handle_change_price_not_configured'
+/**
+ * The Organisation Wallet a Handle change is charged to is not configured on this
+ * deployment (CAY-0091). There is no default payee, so the route is closed.
+ */
+ | 'handle_change_payee_not_configured'
 /**
  * The citizen market is shut on this deployment: no store is wired, or a figure
  * the book needs is not set in the canon and so not configured here (CAY-0080,
@@ -159,6 +175,59 @@ export type CaysoApiErrorCode =
  * start.
  */
  | 'receipt_signing_not_configured'
+/**
+ * This deployment holds no key it may sign an authorisation acknowledgement with,
+ * so it publishes no acknowledgement key and signs no acknowledgement (CAY-0093).
+ * A closed door, never an empty key set: a verifier reading an empty set would
+ * learn nothing true.
+ */
+ | 'acknowledgement_signing_not_configured'
+/**
+ * No standing-authorisation store is wired, so no Instance key can be bound and no
+ * authorisation presented or revoked (CAY-0094).
+ */
+ | 'standing_authorisation_store_not_configured'
+/**
+ * The ceiling on what a holder may delegate to an Instance per period is not
+ * configured on this deployment, so no standing authorisation is acknowledged
+ * (CAY-0094, CAY-0024). The figure is the canon's; unset is a closed door and never
+ * "no limit", and it is not `cap_not_delegable`, which says the cap is too high.
+ */
+ | 'standing_authorisation_cap_ceiling_not_configured'
+/**
+ * The ceiling on how long a standing authorisation may live is not configured on
+ * this deployment, so none is acknowledged (CAY-0094). The figure is the canon's;
+ * unset is a closed door and never "no limit", and it is not
+ * `authorisation_outlives_its_ceiling`, which says the authorisation is too long.
+ */
+ | 'standing_authorisation_life_ceiling_not_configured'
+/**
+ * No Node-binding store is wired, so no Node can be bound and the Contribution
+ * Store's read of a Node's binding is not answered (CAY-0095). Never "unbound": a
+ * read that cannot look must not tell the Store a bound Node's rows are withheld.
+ */
+ | 'node_binding_store_not_configured'
+/**
+ * This deployment has not been told which Node IDs are Core Nodes, so no Node is
+ * bound and the Store's read is not answered (CAY-0095): binding one, or answering for
+ * one, without knowing would let a Core Node, whose owner is the Operator, earn for a
+ * Citizen Wallet. Told "none" is a configuration; untold is a closed door.
+ */
+ | 'core_node_ids_not_configured'
+/**
+ * No Contribution Store issuer is registered on this deployment, so no statement
+ * from the Store is verified and the Store's read of a Node's binding is not
+ * answered (CAY-0095). Not Store Platform's order keys, which
+ * are `marketplace_order_keys_not_configured`'s.
+ */
+ | 'contribution_store_issuer_not_configured'
+/**
+ * No settlement store is wired — this deployment has no Treasury configured, so a
+ * contribution has nowhere to be paid from and a consumption nowhere to be paid to
+ * — and no settlement assertion is settled (CAY-0096). Never a refusal: the Store's
+ * period is not wrong, Cayso is not ready to read it.
+ */
+ | 'cloud_settlement_store_not_configured'
 /**
  * This deployment holds no registry of Store Platform order keys, so no signed
  * order can be verified and no marketplace operation is served (CAY-0083 §4).
@@ -171,11 +240,13 @@ export type CaysoApiErrorCode =
  */
  | 'marketplace_order_store_not_configured'
 /**
- * The signed order pays a Citizen publisher, and this version serves the
- * house-publisher sale only (CAY-0082 §2). Nothing was checked against the payee and
- * nothing moved. A seam code rather than a {@link MarketplaceOrderRefusal}, because it
- * describes this deployment and not the order; the third-party sale retires it when
- * it ships.
+ * The signed order pays a Citizen publisher and carries no Community share
+ * (`communityShareBasisPoints`): Store Platform signed it before CAY-0090 put the
+ * share in the order, so Cayso has no figure to divide the price by. Nothing was
+ * checked against the payee and nothing moved. Before the share was a fact every
+ * Citizen publisher's order was answered this way; now only one without it is.
+ * A seam code rather than a {@link MarketplaceOrderRefusal}, because it describes
+ * what the deployments in the path speak and not the order.
  */
  | 'third_party_marketplace_sale_not_served'
 /** The request body or parameters did not satisfy the declared schema. */
@@ -183,7 +254,7 @@ export type CaysoApiErrorCode =
 /** There is no such purchase under this caller's wallet. */
  | 'not_found'
 /** Something failed on the way and the refusal discloses nothing further. */
- | 'internal_error' | PurchaseFailureReason | PurchaseCancelRefusalReason | FounderClaimRefusal | CommercialPaymentRefusal | CitizenTransferRefusal | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal | StandingAuthorisationRefusal | SettlementAssertionRefusal;
+ | 'internal_error' | PurchaseFailureReason | PurchaseCancelRefusalReason | FounderClaimRefusal | CommercialPaymentRefusal | CitizenTransferRefusal | HandleChangeRefusal | HandleChangeReceiptReadRefusal | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal | StandingAuthorisationRefusal | StandingAuthorisationRevocationRefusal | NodeBindingRefusal | NodeBindingQueryRefusal | SettlementAssertionRefusal;
 /**
  * The body of every refusal on this surface: one code, and nothing beside it.
  *

package/dist/handle-change.d.ts

@@ -0,0 +1,189 @@
+/**
+ * `handle-change` — a Citizen's Handle change, charged by Cayso, and the signed receipt
+ * Percayso ID relies on before it changes the Handle record (CAY-0091).
+ *
+ * Every Handle change after approval is charged in Cayso (Percayso ID's onboarding PRD
+ * §7.2). Cayso holds the price and makes the charge; Percayso ID changes the Handle only
+ * once Cayso has answered with a receipt. Served at `ROUTES.handleChange`, under the
+ * operation `'change-handle'`, and read back at `ROUTES.handleChangeReceipt`, under
+ * `'read-handle-change-receipt'`.
+ *
+ * ## Who calls it
+ *
+ * Percayso ID, over its back channel, as it presents a founder claim. The Citizen
+ * confirms on Percayso ID's own pages; Percayso ID mints a `change-handle` assertion for
+ * that interactive session — never from the background source (CAY-0070) — and presents
+ * it here. The assertion's `sub` is the Citizen ID.
+ *
+ * ## One `charge` for a Community service, or nothing
+ *
+ * The charge is one `charge` movement from the Citizen's own Citizen Wallet to the
+ * Organisation Wallet of the organisation that operates Percayso ID, named in Cayso's
+ * configuration — never a Citizen Wallet (CAY-0084). A Handle change is a Community
+ * service (CAY-0076, as extended by CAY-0091), and a `charge` may draw restricted lots
+ * like any charge, so restricted and unrestricted cents are drawn together. There is no
+ * sterling leg and so no lifecycle: the answer is a {@link HandleChangeCharged} carrying
+ * the signed receipt, or a {@link HandleChangeRefused} meaning nothing moved.
+ *
+ * ## Nothing in the request names anything
+ *
+ * There is no request body. The paying wallet is the verified subject's own Citizen
+ * Wallet, resolved inside the service (CAY-0021). The price is Cayso's configuration.
+ * The change reference — the single-use reference Percayso ID issued when it reserved
+ * the proposed Handle — is carried INSIDE the signed assertion, as
+ * `handleChangeReference`, because a reference named in a body would be the caller's
+ * claim about which Handle change is theirs. Cayso never learns the Handle.
+ *
+ * ## At most one charge per change reference
+ *
+ * The change reference is the charge's key. The first presentation charges; a later
+ * presentation of the same reference for the same Citizen, under a fresh assertion,
+ * charges nothing and answers the receipt of the charge already made — so Percayso ID,
+ * having had no response, retries with the same reference and is answered idempotently.
+ * A reference already charged to another wallet is refused. The same assertion
+ * presented twice never reaches this far: its `jti` is single-use, and the replay is
+ * refused at the gate.
+ *
+ * ## The receipt is a statement Cayso signs
+ *
+ * {@link HandleChangeReceipt} is a {@link HandleChangeReceiptStatement} and an `ES256`
+ * signature over {@link encodeHandleChangeReceiptStatement} of it, made with Cayso's
+ * receipt key (CAY-0083 §1, as amended by CAY-0091) and published in the same key set
+ * as a marketplace receipt's. It is BOUND to the charge: it names the change reference
+ * and the issuer and `jti` of the assertion the charge was made under, which Percayso ID
+ * minted and alone can tie to a Citizen. It names a wallet id and never a Percayso
+ * identity (CAY-0006, CAY-0054): there is no `sub` and no Handle.
+ *
+ * ## Was this reference charged? A receipt or "no charge", never "pending"
+ *
+ * {@link HandleChangeReceiptReadResponse} answers the read Percayso ID makes before it
+ * releases a held Handle: the receipt of the charge the reference landed, or
+ * `no-charge` — nothing was charged under this reference for this Citizen. There is no
+ * `pending`: a movement is written or it is not (CAY-0023). A read writes no row and
+ * moves nothing.
+ *
+ * ## The bytes that are signed, and why they cannot be a marketplace receipt
+ *
+ * {@link encodeHandleChangeReceiptStatement} is the one encoding, called by the signer
+ * and by every verifier: the statement's fields in the order the interface declares
+ * them, as UTF-8 JSON with no whitespace, refusing any field it does not name. Its first
+ * field is `"reason":"handle-change"`, and no marketplace receipt has a `reason` field —
+ * that encoder refuses one — so the one key signing both cannot make either read as the
+ * other.
+ *
+ * ## What is not here
+ *
+ * No figure: the price is a canon figure, configured, and the receipt carries the cents
+ * that moved. No key material and no verifier: which keys Percayso ID trusts is Percayso
+ * ID's configuration, empty by default.
+ */
+import type { MarketplaceReceiptKeyId, MarketplaceReceiptLeg } from './marketplace-receipt.js';
+import type { Millis } from './wallet.js';
+/**
+ * What Cayso signs about one Handle-change charge. Every field is signed, including
+ * `keyId`, so which key signed is part of what is signed.
+ */
+export interface HandleChangeReceiptStatement {
+    /** The reason for the charge. Always the literal, and always first in the encoding. */
+    readonly reason: 'handle-change';
+    /** The act: one `charge`, from the payer to the payee. */
+    readonly movementKind: 'charge';
+    /** The movement that carried the cents. */
+    readonly movementId: string;
+    /** The change reference charged for, exactly as Percayso ID minted it into the assertion. */
+    readonly handleChangeReference: string;
+    /** The issuer of the assertion the charge was made under. */
+    readonly assertionIssuer: string;
+    /** The `jti` of the assertion the charge was made under. */
+    readonly assertionId: string;
+    /** The paying wallet: the Citizen's own Citizen Wallet. */
+    readonly payerWalletId: string;
+    /** The whole price, to the configured Organisation Wallet, as the cents that moved. */
+    readonly payeeLeg: MarketplaceReceiptLeg;
+    /** When the movement was written. */
+    readonly writtenAt: Millis;
+    /** The receipt key the signature was made with. */
+    readonly keyId: MarketplaceReceiptKeyId;
+}
+/** A receipt: the statement, and Cayso's signature over its encoding. */
+export interface HandleChangeReceipt {
+    readonly statement: HandleChangeReceiptStatement;
+    /**
+     * `ES256` over {@link encodeHandleChangeReceiptStatement}`(statement)`: `r || s`, 64
+     * bytes, as unpadded base64url.
+     */
+    readonly signature: string;
+}
+/** The Handle change was charged, by this request or by an earlier one for the same reference. */
+export interface HandleChangeCharged {
+    readonly outcome: 'charged';
+    readonly receipt: HandleChangeReceipt;
+}
+/** The charge was refused, with one member of the closed union. Nothing was written. */
+export interface HandleChangeRefused {
+    readonly outcome: 'refused';
+    readonly error: HandleChangeRefusal;
+}
+/** The ONE declared answer to a Handle change, discriminated by `outcome`. */
+export type HandleChangeResponse = HandleChangeCharged | HandleChangeRefused;
+/**
+ * Why a Handle change was refused: CAY-0091's set, closed. Every member means the same
+ * thing about money: nothing moved.
+ */
+export type HandleChangeRefusal = 
+/**
+ * The verification method is outside the money-grade assurance profile
+ * (`ASSURANCE_POLICY['change-handle']`). `dev-bypass` is never inside it.
+ */
+'assurance_not_money_grade'
+/** The verified subject resolves to no Citizen Wallet. A Handle change never provisions one. */
+ | 'payer_has_no_citizen_wallet'
+/** The payer's cents, restricted and unrestricted together, are short of the price. */
+ | 'cents_insufficient'
+/** A holding the charge would draw is frozen. */
+ | 'cents_frozen'
+/** The change reference has already been charged, to another wallet. */
+ | 'handle_change_reference_charged_to_another_wallet'
+/** Too many concurrent draws on the paying wallet. Nothing moved; retry with the same reference. */
+ | 'carve_contended';
+/** The reference was charged for this Citizen: the receipt of that charge. */
+export interface HandleChangeReceiptFound {
+    readonly outcome: 'receipt';
+    readonly receipt: HandleChangeReceipt;
+}
+/**
+ * Nothing was charged under this reference for this Citizen. Never "pending": there is
+ * no pending charge.
+ */
+export interface HandleChangeNoCharge {
+    readonly outcome: 'no-charge';
+}
+/**
+ * Why the read could not be answered. Closed, and a refusal is never a statement about
+ * the reference: a caller must not read one as "no charge".
+ */
+export type HandleChangeReceiptReadRefusal = 
+/**
+ * No wallet is bound to the verified subject now, so there is no paying wallet to ask
+ * about, and whether the reference was charged is not known.
+ */
+'payer_has_no_citizen_wallet'
+/** The reference was charged, to another wallet. */
+ | 'handle_change_reference_charged_to_another_wallet';
+/** The read was refused, with one reason. Nothing was written. */
+export interface HandleChangeReceiptReadRefused {
+    readonly outcome: 'refused';
+    readonly error: HandleChangeReceiptReadRefusal;
+}
+/** The ONE declared answer to the read: a receipt, "no charge", or a refusal. Never "pending". */
+export type HandleChangeReceiptReadResponse = HandleChangeReceiptFound | HandleChangeNoCharge | HandleChangeReceiptReadRefused;
+/**
+ * The exact bytes a Handle-change receipt's signature is computed over.
+ *
+ * Builds a fresh object from the statement's named fields, in a fixed order, so the
+ * encoding depends on nothing but their values. THROWS a `TypeError` for anything that
+ * is not exactly a {@link HandleChangeReceiptStatement}: a wrong literal, a missing or
+ * extra field, a string field that is not a string, or cents or a time that is not a
+ * safe whole number no less than zero.
+ */
+export declare function encodeHandleChangeReceiptStatement(statement: HandleChangeReceiptStatement): Uint8Array<ArrayBuffer>;

package/dist/handle-change.js

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2026 Percayso Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// --- The encoding ------------------------------------------------------------
+/** The statement's own fields, in the order they are encoded. */
+const FIELDS = [
+    'reason',
+    'movementKind',
+    'movementId',
+    'handleChangeReference',
+    'assertionIssuer',
+    'assertionId',
+    'payerWalletId',
+    'payeeLeg',
+    'writtenAt',
+    'keyId',
+];
+/** Every string field, each of which must be a string when it arrives. */
+const STRING_FIELDS = [
+    'movementId',
+    'handleChangeReference',
+    'assertionIssuer',
+    'assertionId',
+    'payerWalletId',
+    'keyId',
+];
+/** The fields of a leg, in the order they are encoded. */
+const LEG_FIELDS = ['walletId', 'cents'];
+/**
+ * The exact bytes a Handle-change receipt's signature is computed over.
+ *
+ * Builds a fresh object from the statement's named fields, in a fixed order, so the
+ * encoding depends on nothing but their values. THROWS a `TypeError` for anything that
+ * is not exactly a {@link HandleChangeReceiptStatement}: a wrong literal, a missing or
+ * extra field, a string field that is not a string, or cents or a time that is not a
+ * safe whole number no less than zero.
+ */
+export function encodeHandleChangeReceiptStatement(statement) {
+    const value = statement;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('a Handle-change receipt statement is an object');
+    }
+    requireExactly(value, FIELDS, 'a Handle-change receipt carries exactly its own fields');
+    if (value['reason'] !== 'handle-change' || value['movementKind'] !== 'charge') {
+        throw new TypeError('a Handle-change receipt is for a Handle change made by a charge');
+    }
+    for (const field of STRING_FIELDS) {
+        if (typeof value[field] !== 'string') {
+            throw new TypeError('every identifier of a Handle-change receipt is a string');
+        }
+    }
+    requireWholeNumber(value['writtenAt'], 'a Handle-change receipt is written at whole milliseconds');
+    const canonical = {};
+    for (const field of FIELDS) {
+        canonical[field] = field === 'payeeLeg' ? canonicalLeg(value[field]) : value[field];
+    }
+    return new TextEncoder().encode(JSON.stringify(canonical));
+}
+/** A leg rebuilt in its fixed order, or a refusal. */
+function canonicalLeg(leg) {
+    if (typeof leg !== 'object' || leg === null || Array.isArray(leg)) {
+        throw new TypeError('a Handle-change receipt leg is an object');
+    }
+    const value = leg;
+    requireExactly(value, LEG_FIELDS, 'a Handle-change receipt leg carries a wallet id and cents only');
+    if (typeof value['walletId'] !== 'string') {
+        throw new TypeError('a Handle-change receipt leg names its wallet by id');
+    }
+    requireWholeNumber(value['cents'], 'a Handle-change receipt leg carries whole cents');
+    return { walletId: value['walletId'], cents: value['cents'] };
+}
+/** Refuse an object whose own keys are not exactly `fields`. */
+function requireExactly(value, fields, category) {
+    const keys = Object.keys(value);
+    if (keys.length !== fields.length || !fields.every((field) => Object.hasOwn(value, field))) {
+        throw new TypeError(category);
+    }
+}
+/** Refuse anything that is not a safe whole number no less than zero. */
+function requireWholeNumber(value, category) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(category);
+    }
+}

package/dist/index.d.ts

@@ -76,6 +76,94 @@
  * 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.29.0` → `0.30.0` publishes and SERVES Cayso's authorisation acknowledgement keys
+ * (CAY-0093): {@link ACKNOWLEDGEMENT_KEYS_ROUTE}, `GET /api/acknowledgement-keys`, an
+ * unauthenticated read outside `ROUTES`, described in the schema under `keyRoutes`;
+ * the key set it answers, {@link AcknowledgementKeySet} of
+ * {@link AcknowledgementPublicKey}, Ed25519 public JSON Web Keys and nothing private;
+ * and `CaysoApiErrorCode` gains `acknowledgement_signing_not_configured`, the route's
+ * closed door.
+ *
+ * The same version SERVES the standing authorisation (CAY-0094), published at `0.25.0`
+ * and answered until now by the router's `404`: `ROUTES.standingAuthorisation` answers
+ * {@link StandingAuthorisationResponse} with an acknowledgement signed under that key.
+ * It adds the owner's way to withdraw one: `ROUTES.revokeStandingAuthorisation`,
+ * `POST /api/cloud/standing-authorisation-revocations`, mapped to the new operation
+ * `'revoke-standing-authorisation'`, money-grade in `ASSURANCE_POLICY`; the client
+ * method `revokeStandingAuthorisation`; {@link StandingAuthorisationRevocationRequest},
+ * {@link StandingAuthorisationRevocationResponse} and the closed
+ * {@link StandingAuthorisationRevocationRefusal}, which `CaysoApiErrorCode` gains by
+ * reference; and the seam codes `standing_authorisation_store_not_configured`,
+ * `standing_authorisation_cap_ceiling_not_configured` and
+ * `standing_authorisation_life_ceiling_not_configured`.
+ *
+ * The same version publishes and SERVES binding a Node to a wallet (CMTY-0018 §4,
+ * CAY-0095): `ROUTES.bindNode`, `POST /api/cloud/node-bindings`, mapped to the new
+ * operation `'bind-node'`, money-grade in `ASSURANCE_POLICY`; the client method
+ * `bindNode`; {@link NodePresentationClaims}, {@link NodeBindingRequest},
+ * {@link NodeBindingResponse} and the closed {@link NodeBindingRefusal}. Beside it, the
+ * Contribution Store's read of whether a Node is bound: {@link NODE_BINDING_QUERY_ROUTE},
+ * `POST /api/cloud/node-binding-queries`, outside `ROUTES` and in the schema under
+ * `issuerRoutes`, authenticated by the registered Store issuer; {@link
+ * NodeBindingQueryClaims}, {@link NodeBindingQueryRequest}, the answer
+ * {@link NodeBindingStatus} — `nodeId` and `bound` and nothing else — and the closed
+ * {@link NodeBindingQueryRefusal}. `CaysoApiErrorCode` gains both unions by reference
+ * and the seam codes `node_binding_store_not_configured`, `core_node_ids_not_configured`
+ * and `contribution_store_issuer_not_configured`.
+ *
+ * The same version SERVES the Contribution Store's settlement assertion (CMTY-0018 §2,
+ * CAY-0096) at {@link CLOUD_SETTLEMENT_ROUTE}, published at `0.25.0` and answered until
+ * now by the router's `404`. A settled period writes one `contribution_settlement`
+ * movement per paid contribution row and one `consumption_settlement` per consumption
+ * row, so `MovementKind` and `MOVEMENT_KINDS` gain both. The closed refusal unions gain
+ * the members the write needs: {@link SettlementAssertionLevelRefusal} gains
+ * `settlement_period_not_recognised`, `settlement_period_not_ended` and
+ * `settlement_carve_contended`; {@link ContributionRowRefusal} gains
+ * `contribution_node_is_a_core_node` and `contribution_treasury_short`;
+ * {@link ConsumptionRowRefusal} gains `consumption_authorisation_not_in_force` and
+ * `consumption_wallet_short`. `CaysoApiErrorCode` gains them by reference and the seam
+ * code `cloud_settlement_store_not_configured`.
+ *
+ * BREAKING in the package's sense because closed tables grew: `ROUTES`,
+ * `ContractOperation`, `CaysoApiErrorCode`, `MovementKind` and the settlement's refusal
+ * unions. Additive on the wire (CAY-0086): no route a `0.29.0` consumer could reach
+ * changed, because the only ones that answer differently are the standing
+ * authorisation and the settlement assertion, which no deployment served before, and
+ * they answer the shapes `0.25.0` published, a member those shapes' unions gained, or a
+ * new seam code no served route emits. The operator movement list can now carry the two
+ * new kinds, and it is read only by the admin app in this tree, released with it. The
+ * two Node routes are ones a `0.29.0` consumer cannot name.
+ *
+ * `0.28.0` → `0.29.0` publishes and SERVES the Handle change (CAY-0091):
+ * `ROUTES.handleChange`, `POST /api/handle-changes`, mapped to the new operation
+ * `'change-handle'`, money-grade in `ASSURANCE_POLICY`; `ROUTES.handleChangeReceipt`,
+ * `GET /api/handle-changes/receipt`, mapped to the new read-scope operation
+ * `'read-handle-change-receipt'`; the assertion claim `handleChangeReference`, which
+ * travels with those two operations in both directions; the client methods
+ * `changeHandle` and `readHandleChangeReceipt`; the signed {@link HandleChangeReceipt}
+ * and its one encoding, {@link encodeHandleChangeReceiptStatement}; and
+ * `CaysoApiErrorCode` gains {@link HandleChangeRefusal} and
+ * {@link HandleChangeReceiptReadRefusal} by reference and the seam codes
+ * `handle_change_store_not_configured`, `handle_change_price_not_configured` and
+ * `handle_change_payee_not_configured`. BREAKING in the package's sense because closed
+ * tables grew. Additive on the wire: no route a `0.28.0` consumer calls changed or
+ * answers anything new, and a credential a `0.28.0` issuer mints carries neither the new
+ * scope keys nor the new claim (CAY-0086).
+ *
+ * `0.27.0` → `0.28.0` SERVES a Citizen publisher's marketplace sale (CAY-0090):
+ * `POST /api/marketplace/orders` settles a signed order whose payee is a
+ * `citizen_publisher` as one `marketplace_settlement`, answering the
+ * `MarketplaceSettlementReceiptStatement` `0.24.0` already published. The share is
+ * read from a new signed-order fact, `communityShareBasisPoints`, which Store Platform
+ * signs beside `allocationPolicyVersion`. {@link MarketplaceOrderRefusal} gains
+ * `allocation_share_out_of_range` and `payee_wallet_is_the_buyers`, and
+ * `allocation_policy_version_not_configured` is retired (kept, never answered). The
+ * operator `MovementKind` gains `marketplace_settlement`. BREAKING in the package's
+ * sense because closed tables grew. On the wire, every order a `0.27.0` consumer could
+ * present — one Store Platform signed without the new fact — is answered exactly as
+ * before, a Citizen publisher's with `third_party_marketplace_sale_not_served`; only an
+ * order carrying the new fact can reach a new code (CAY-0086).
+ *
  * `0.26.0` → `0.27.0` publishes and SERVES the Citizen transfer (CAY-0088):
  * `ROUTES.citizenTransfer`, `POST /api/citizen-transfers`, mapped to the new
  * operation `'make-citizen-transfer'`, money-grade in `ASSURANCE_POLICY`; the client
@@ -522,7 +610,7 @@
  * 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.27.0";
+export declare const CONTRACT_VERSION: "0.30.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**
@@ -546,6 +634,18 @@ export { ROUTES } from './routes.js';
  * no operation, no assurance bar and no client method.
  */
 export { CLOUD_SETTLEMENT_ROUTE } from './routes.js';
+/**
+ * Where the Contribution Store asks whether a Node is bound (CAY-0095). A value beside
+ * `ROUTES` and never in it, for the settlement path's reason: it is authenticated by
+ * the registered Store issuer, not by a person.
+ */
+export { NODE_BINDING_QUERY_ROUTE } from './routes.js';
+/**
+ * Where Cayso publishes its authorisation acknowledgement keys (CAY-0093). A value
+ * beside `ROUTES` and never in it: an unauthenticated read of a public key carries no
+ * identity, so it has no operation, no assurance bar and no client method.
+ */
+export { ACKNOWLEDGEMENT_KEYS_ROUTE } 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
@@ -656,6 +756,11 @@ export { REQUEST_RATE_LIMITED } from './errors.js';
  * one of the four.
  */
 export { MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM, encodeMarketplaceReceiptStatement, } from './marketplace-receipt.js';
+/**
+ * The one encoding of a Handle-change receipt statement, called by the signer and by
+ * Percayso ID's verifier (CAY-0091).
+ */
+export { encodeHandleChangeReceiptStatement } from './handle-change.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';
@@ -663,10 +768,11 @@ export type { SignUpGrantTerms, SignUpGrant, CitizenshipNotProvisioned, Citizens
 export type { OrganisationView } from './organisation.js';
 export type { CommercialPaymentAuthority, CommercialPaymentRequest, CommercialPayment, CommercialPaymentMade, CommercialPaymentRefused, CommercialPaymentResponse, CommercialPaymentRefusal, } from './commercial-payment.js';
 export type { CitizenTransferRequest, CitizenTransfer, CitizenTransferMade, CitizenTransferRefused, CitizenTransferResponse, CitizenTransferRefusal, } from './citizen-transfer.js';
+export type { HandleChangeReceiptStatement, HandleChangeReceipt, HandleChangeCharged, HandleChangeRefused, HandleChangeResponse, HandleChangeRefusal, HandleChangeReceiptFound, HandleChangeNoCharge, HandleChangeReceiptReadRefusal, HandleChangeReceiptReadRefused, HandleChangeReceiptReadResponse, } from './handle-change.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 { InstanceKeyId, SettlementPeriodRule, SettlementPeriodId, NodeId, ContributionStoreIssuer, PercaysoCloudAudience, StandingAuthorisationClaims, StandingAuthorisationRequest, AuthorisationAcknowledgementClaims, StandingAuthorisationAcknowledged, StandingAuthorisationRefused, StandingAuthorisationResponse, StandingAuthorisationRefusal, ContributionType, SettlementPeriod, ContributionWithheldReason, ContributionQualified, ContributionWithheld, ContributionQualification, ContributionRow, ConsumptionRow, SettlementTotals, SettlementAssertionClaims, SettlementAssertionRequest, SettlementAssertionSettled, SettlementAssertionRefused, ContributionRowRefused, ConsumptionRowRefused, SettlementAssertionResponse, SettlementAssertionLevelRefusal, ContributionRowRefusal, ConsumptionRowRefusal, SettlementAssertionRefusal, } from './cloud-settlement.js';
+export type { InstanceKeyId, SettlementPeriodRule, SettlementPeriodId, NodeId, ContributionStoreIssuer, PercaysoCloudAudience, StandingAuthorisationClaims, StandingAuthorisationRequest, AuthorisationAcknowledgementClaims, AcknowledgementKeyId, AcknowledgementPublicKey, AcknowledgementKeySet, StandingAuthorisationAcknowledged, StandingAuthorisationRefused, StandingAuthorisationResponse, StandingAuthorisationRefusal, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, StandingAuthorisationRevocationRefused, StandingAuthorisationRevocationResponse, StandingAuthorisationRevocationRefusal, NodePresentationClaims, NodeBindingRequest, NodeBound, NodeBindingRefused, NodeBindingResponse, NodeBindingRefusal, NodeBindingQueryClaims, NodeBindingQueryRequest, NodeBindingStatus, NodeBindingQueryRefused, NodeBindingQueryRefusal, ContributionType, SettlementPeriod, ContributionWithheldReason, ContributionQualified, ContributionWithheld, ContributionQualification, ContributionRow, ConsumptionRow, SettlementTotals, SettlementAssertionClaims, SettlementAssertionRequest, SettlementAssertionSettled, SettlementAssertionRefused, ContributionRowRefused, ConsumptionRowRefused, SettlementAssertionResponse, SettlementAssertionLevelRefusal, ContributionRowRefusal, ConsumptionRowRefusal, SettlementAssertionRefusal, } from './cloud-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';