@percayso-community/cayso-contracts 0.27.0 → 0.29.0

package/dist/assertion.d.ts

@@ -326,6 +326,21 @@
  * credential minted to place a quote must not thereby move cents to somebody without
  * a match, nor the reverse. It is served at `ROUTES.citizenTransfer`.
  *
+ * `'change-handle'` is a Citizen's Handle change, charged by Cayso (CAY-0091). It is
+ * not a second use of `'make-citizen-transfer'`, which pays another Citizen, nor of
+ * `'settle-marketplace-order'`, which presents Store Platform's signed order: a Handle
+ * change charges the Citizen for a Community service on the authority of a change
+ * reference Percayso ID minted. A credential minted for any other operation must not
+ * authorise a Handle change, and the reverse. It is served at `ROUTES.handleChange`,
+ * and it charges for the change reference named by
+ * {@link AssertionClaims.handleChangeReference} and no other.
+ *
+ * `'read-handle-change-receipt'` asks whether a change reference was charged
+ * (CAY-0091), as `'read-marketplace-receipt'` asks of a checkout key. It is its own
+ * operation because it is a read beside the money-grade charge it reports on: a
+ * credential minted to ask what happened must not thereby be able to make something
+ * happen. It is served at `ROUTES.handleChangeReceipt`.
+ *
  * `'place-quote'`, `'withdraw-quote'` and `'request-buy-back'` are the citizen
  * market's three acts (CAY-0080, Open decision Q). They are three operations
  * because they are three acts: a credential minted to withdraw a quote must not
@@ -370,7 +385,7 @@
  * Contribution Store's assertion, which no person presents and which therefore has
  * no operation here. It is classified before it is served.
  */
-export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'make-citizen-transfer' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation';
+export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'make-citizen-transfer' | 'change-handle' | 'read-handle-change-receipt' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation';
 /**
  * An operation key belonging to a deployment's OWN surfaces rather than to this
  * contract — operator work, above all. Deliberately not enumerated: this package
@@ -839,6 +854,42 @@ export interface AssertionClaims {
      * of work.
      */
     readonly founderClaimReference?: string;
+    /**
+     * The change reference: the single-use, opaque value Percayso ID issued when it
+     * reserved the Citizen's proposed Handle (CAY-0091). OPTIONAL on the wire, and read by
+     * `'change-handle'` and `'read-handle-change-receipt'` and by no other operation.
+     *
+     * ## It travels with its operations, in both directions
+     *
+     * As {@link founderClaimReference} does. A credential whose `scope` carries
+     * `'change-handle'` or `'read-handle-change-receipt'` must carry this claim, and a
+     * credential that carries this claim must be scoped to one of them. A verifier refuses
+     * either half missing as a malformed credential, before any gate reads it: a Handle
+     * change with no reference charges for nothing, and a reference carried to any other
+     * operation is half of a Handle change put in front of a route with no business
+     * reading it.
+     *
+     * ## It is carried here and never in a request
+     *
+     * The reference fixes the new Handle BEFORE the charge, so a receipt cannot be spent
+     * on a different name. A reference named in a body would be the caller's claim about
+     * which Handle change is theirs (CAY-0021); inside the signed assertion it is Percayso
+     * ID's statement. Cayso charges at most once per reference, keys the charge by it, and
+     * names it in the signed receipt.
+     *
+     * ## What it is not
+     *
+     * It is NOT the Handle. Cayso never learns the Handle: the reference is opaque, and
+     * Cayso compares it and never parses it. It is not derived from a Percayso identity,
+     * and it carries no `sub`, no name and no email. This contract asks for a non-empty
+     * string and nothing more.
+     *
+     * ## It is as trustworthy as the verifier, and no more
+     *
+     * As with every claim: declaring it makes the promise structural, and a real
+     * signature check is what makes it trustworthy.
+     */
+    readonly handleChangeReference?: string;
     /**
      * The Organisation **Wallet IDs** this identity holds the mandate for
      * (CAY-0024, CAY-0059 §7). Each entry is a wallet id — the opaque identifier

package/dist/assurance.js

@@ -343,6 +343,33 @@ export const ASSURANCE_POLICY = {
             'anything but the development bypass. An unverified holder must never be able to send, ' +
             'because sending is how value reaches somebody else.',
     },
+    // A Citizen paying Cayso to change their Handle (CAY-0091). Money-grade, at the
+    // Citizen transfer's bar: value leaves the holder, and the payment is what lets
+    // Percayso ID change a public name, so an unverified holder must not be able to
+    // make it. An allowlist, so a future method is admissible only when somebody
+    // decides it here.
+    'change-handle': {
+        operation: 'change-handle',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "A Handle change charges the Citizen's own Citizen Wallet, so it is money-grade: anything " +
+            'but the development bypass. The receipt it answers with lets Percayso ID change a ' +
+            'Handle, which an unverified holder must never be able to buy.',
+    },
+    // Asking whether a change reference was charged (CAY-0091). A read: nothing moves and
+    // nothing is reserved, so it applies no bar, as the marketplace receipt read applies
+    // none. A credential scoped to it cannot charge anything.
+    'read-handle-change-receipt': {
+        operation: 'read-handle-change-receipt',
+        assurance: 'not-required',
+        rationale: 'Asking whether a change reference was charged moves nothing and reserves nothing. It ' +
+            'answers a receipt Cayso already signed, or that there was no charge, and nothing more.',
+    },
     // The citizen market's three acts (CAY-0080 §7, Open decision Q). All three are
     // money-grade and all three are allowlists, at the purchase path's bar: the acting
     // party is a Citizen, and a bar no issuer can yet clear would shut the market on
@@ -524,6 +551,8 @@ export const OPERATION_FOR_ROUTE = {
     purchaseCancel: 'cancel-purchase',
     commercialPayment: 'make-commercial-payment',
     citizenTransfer: 'make-citizen-transfer',
+    handleChange: 'change-handle',
+    handleChangeReceipt: 'read-handle-change-receipt',
     citizenMarket: 'read-citizen-market',
     placeQuote: 'place-quote',
     withdrawQuote: 'withdraw-quote',

package/dist/client.d.ts

@@ -72,6 +72,7 @@ import type { CitizenshipFounderClaimed, CitizenshipView } from './citizenship.j
 import type { StandingAuthorisationAcknowledged, StandingAuthorisationRequest } from './cloud-settlement.js';
 import type { CitizenTransferMade, CitizenTransferRequest } from './citizen-transfer.js';
 import type { CommercialPaymentMade, CommercialPaymentRequest } from './commercial-payment.js';
+import type { HandleChangeCharged, HandleChangeReceiptReadResponse } from './handle-change.js';
 import type { MarketplaceOrderRequest, MarketplaceOrderSettled } from './marketplace-settlement.js';
 import type { OrganisationView } from './organisation.js';
 import type { PurchaseAuthorised, PurchaseCancelled, PurchaseRequest, PurchaseResult, PurchaseTerminal } from './purchase.js';
@@ -225,6 +226,24 @@ export interface CaysoClient {
      * refusal means nothing moved.
      */
     makeCitizenTransfer(req: CitizenTransferRequest): Promise<CitizenTransferMade>;
+    /**
+     * Charge the caller's own Citizen Wallet for a Handle change, and receive the signed
+     * receipt Percayso ID relies on (CAY-0091) — or, for a change reference already
+     * charged, the receipt of that charge, with nothing charged again.
+     *
+     * There is nothing to send: the change reference is inside the assertion, the wallet
+     * is the verified holder's own, and the price is Cayso's. A refusal arrives as a thrown
+     * {@link CaysoApiError} whose `code` is a `HandleChangeRefusal` member, one of the
+     * gate's codes, or a seam code. A refusal means nothing moved.
+     */
+    changeHandle(): Promise<HandleChangeCharged>;
+    /**
+     * Ask whether the change reference inside the assertion was charged for the caller
+     * (CAY-0091): its receipt, or `no-charge`. Never "pending". A refusal arrives as a
+     * thrown {@link CaysoApiError} whose `code` is a `HandleChangeReceiptReadRefusal`
+     * member, one of the gate's codes, or a seam code — and is never "no charge".
+     */
+    readHandleChangeReceipt(): Promise<HandleChangeReceiptReadResponse>;
     /**
      * Read the citizen market as the caller sees it (CAY-0080 §1.4): the published
      * value and its band, both bounds per quote unit, the best bid and the best ask with

package/dist/client.js

@@ -231,6 +231,25 @@ function buildClient(options, internals) {
                 idempotencyKey: req.idempotencyKey,
             });
         },
+        async changeHandle() {
+            return requestJson({
+                method: ROUTES.handleChange.method,
+                path: ROUTES.handleChange.path,
+                // Safe to retry with no key: the charge is keyed by the change reference
+                // inside the assertion, so a repeat answers the charge already made, and each
+                // attempt mints a fresh assertion, so the single-use `jti` is never presented
+                // twice.
+                idempotent: true,
+            });
+        },
+        async readHandleChangeReceipt() {
+            return requestJson({
+                method: ROUTES.handleChangeReceipt.method,
+                path: ROUTES.handleChangeReceipt.path,
+                // A read: it moves nothing, so a retry is always safe.
+                idempotent: true,
+            });
+        },
         async getCitizenMarket() {
             return requestJson({
                 method: ROUTES.citizenMarket.method,

package/dist/contract-schema.generated.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 export const CONTRACT_SCHEMA = {
-    "contractVersion": "0.27.0",
+    "contractVersion": "0.29.0",
     "packageName": "@percayso-community/cayso-contracts",
     "capabilities": {
         "wallet": "cayso.wallet",
@@ -61,6 +61,14 @@ export const CONTRACT_SCHEMA = {
             "method": "POST",
             "path": "/api/citizen-transfers"
         },
+        "handleChange": {
+            "method": "POST",
+            "path": "/api/handle-changes"
+        },
+        "handleChangeReceipt": {
+            "method": "GET",
+            "path": "/api/handle-changes/receipt"
+        },
         "citizenMarket": {
             "method": "GET",
             "path": "/api/citizen-market"
@@ -234,6 +242,13 @@ export const CONTRACT_SCHEMA = {
                     "readonly": true,
                     "optional": true
                 },
+                "handleChangeReference": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": true
+                },
                 "mandateFor": {
                     "type": {
                         "array": {
@@ -661,6 +676,15 @@ export const CONTRACT_SCHEMA = {
                     {
                         "literal": "citizen_transfer_store_not_configured"
                     },
+                    {
+                        "literal": "handle_change_store_not_configured"
+                    },
+                    {
+                        "literal": "handle_change_price_not_configured"
+                    },
+                    {
+                        "literal": "handle_change_payee_not_configured"
+                    },
                     {
                         "literal": "citizen_market_not_configured"
                     },
@@ -706,6 +730,12 @@ export const CONTRACT_SCHEMA = {
                     {
                         "ref": "CitizenTransferRefusal"
                     },
+                    {
+                        "ref": "HandleChangeRefusal"
+                    },
+                    {
+                        "ref": "HandleChangeReceiptReadRefusal"
+                    },
                     {
                         "ref": "QuotePlacementRefusal"
                     },
@@ -1499,6 +1529,12 @@ export const CONTRACT_SCHEMA = {
                     {
                         "literal": "make-citizen-transfer"
                     },
+                    {
+                        "literal": "change-handle"
+                    },
+                    {
+                        "literal": "read-handle-change-receipt"
+                    },
                     {
                         "literal": "place-quote"
                     },
@@ -1744,6 +1780,255 @@ export const CONTRACT_SCHEMA = {
                 ]
             }
         },
+        "HandleChangeCharged": {
+            "kind": "object",
+            "properties": {
+                "outcome": {
+                    "type": {
+                        "literal": "charged"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "receipt": {
+                    "type": {
+                        "ref": "HandleChangeReceipt"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "HandleChangeNoCharge": {
+            "kind": "object",
+            "properties": {
+                "outcome": {
+                    "type": {
+                        "literal": "no-charge"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "HandleChangeReceipt": {
+            "kind": "object",
+            "properties": {
+                "statement": {
+                    "type": {
+                        "ref": "HandleChangeReceiptStatement"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "signature": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "HandleChangeReceiptFound": {
+            "kind": "object",
+            "properties": {
+                "outcome": {
+                    "type": {
+                        "literal": "receipt"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "receipt": {
+                    "type": {
+                        "ref": "HandleChangeReceipt"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "HandleChangeReceiptReadRefusal": {
+            "kind": "alias",
+            "of": {
+                "union": [
+                    {
+                        "literal": "payer_has_no_citizen_wallet"
+                    },
+                    {
+                        "literal": "handle_change_reference_charged_to_another_wallet"
+                    }
+                ]
+            }
+        },
+        "HandleChangeReceiptReadRefused": {
+            "kind": "object",
+            "properties": {
+                "outcome": {
+                    "type": {
+                        "literal": "refused"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "error": {
+                    "type": {
+                        "ref": "HandleChangeReceiptReadRefusal"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "HandleChangeReceiptReadResponse": {
+            "kind": "alias",
+            "of": {
+                "union": [
+                    {
+                        "ref": "HandleChangeReceiptFound"
+                    },
+                    {
+                        "ref": "HandleChangeNoCharge"
+                    },
+                    {
+                        "ref": "HandleChangeReceiptReadRefused"
+                    }
+                ]
+            }
+        },
+        "HandleChangeReceiptStatement": {
+            "kind": "object",
+            "properties": {
+                "reason": {
+                    "type": {
+                        "literal": "handle-change"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "movementKind": {
+                    "type": {
+                        "literal": "charge"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "movementId": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "handleChangeReference": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "assertionIssuer": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "assertionId": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "payerWalletId": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "payeeLeg": {
+                    "type": {
+                        "ref": "MarketplaceReceiptLeg"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "writtenAt": {
+                    "type": {
+                        "ref": "Millis"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "keyId": {
+                    "type": {
+                        "ref": "MarketplaceReceiptKeyId"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "HandleChangeRefusal": {
+            "kind": "alias",
+            "of": {
+                "union": [
+                    {
+                        "literal": "assurance_not_money_grade"
+                    },
+                    {
+                        "literal": "payer_has_no_citizen_wallet"
+                    },
+                    {
+                        "literal": "cents_insufficient"
+                    },
+                    {
+                        "literal": "cents_frozen"
+                    },
+                    {
+                        "literal": "handle_change_reference_charged_to_another_wallet"
+                    },
+                    {
+                        "literal": "carve_contended"
+                    }
+                ]
+            }
+        },
+        "HandleChangeRefused": {
+            "kind": "object",
+            "properties": {
+                "outcome": {
+                    "type": {
+                        "literal": "refused"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "error": {
+                    "type": {
+                        "ref": "HandleChangeRefusal"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "HandleChangeResponse": {
+            "kind": "alias",
+            "of": {
+                "union": [
+                    {
+                        "ref": "HandleChangeCharged"
+                    },
+                    {
+                        "ref": "HandleChangeRefused"
+                    }
+                ]
+            }
+        },
         "HolderType": {
             "kind": "alias",
             "of": {
@@ -1998,6 +2283,9 @@ export const CONTRACT_SCHEMA = {
                     {
                         "literal": "allocation_policy_version_not_configured"
                     },
+                    {
+                        "literal": "allocation_share_out_of_range"
+                    },
                     {
                         "literal": "payee_wallet_not_found"
                     },
@@ -2007,6 +2295,9 @@ export const CONTRACT_SCHEMA = {
                     {
                         "literal": "payee_wallet_has_no_live_binding"
                     },
+                    {
+                        "literal": "payee_wallet_is_the_buyers"
+                    },
                     {
                         "literal": "unrestricted_cents_insufficient"
                     },
@@ -4217,6 +4508,9 @@ export const CONTRACT_SCHEMA = {
                         },
                         {
                             "literal": "quoted_sale_compensation"
+                        },
+                        {
+                            "literal": "marketplace_settlement"
                         }
                     ]
                 }

package/dist/errors.d.ts

@@ -45,6 +45,7 @@ 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 { 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,
@@ -171,11 +187,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 +201,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 | 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,36 @@
  * 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.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 +552,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.29.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**
@@ -656,6 +686,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,6 +698,7 @@ 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';

package/dist/index.js

@@ -92,6 +92,36 @@
  * 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.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
@@ -538,7 +568,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 const CONTRACT_VERSION = '0.27.0';
+export const CONTRACT_VERSION = '0.29.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**
@@ -672,3 +702,8 @@ 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';

package/dist/marketplace-settlement.d.ts

@@ -12,8 +12,10 @@
  *
  * **This is the contract surface only.** Nothing here settles anything. Since
  * `0.24.0` a route serves `settle-marketplace-order` for a house-publisher sale
- * (`ROUTES.marketplaceOrder`); the third-party sale and the refund are not served. The sale table, the registry of Store Platform order
- * keys and the ledger stay in this proprietary tree (CAY-0083 §3).
+ * (`ROUTES.marketplaceOrder`), and since `0.28.0` for a Citizen publisher's sale too,
+ * as one `marketplace_settlement` with a publisher leg and a Community leg (CAY-0090).
+ * The refund is not served, for either kind of sale. The sale table, the registry of
+ * Store Platform order keys and the ledger stay in this proprietary tree (CAY-0083 §3).
  *
  * ## Two operations, because two authorities are checked
  *
@@ -41,7 +43,9 @@
  * disagree eventually. What Cayso reads from them, once verified, is CAY-0082's
  * list — the order digest, the checkout's idempotency key, the price, the paying
  * wallet, the payee wallet or the house-publisher fact, and the allocation-policy
- * version.
+ * version — and, since `0.28.0`, the Community's share in basis points, which Store
+ * Platform snapshots into the checkout from its allocation policy and signs beside the
+ * version (CAY-0090, amending CAY-0082 §3).
  *
  * **Nothing about the sale is taken from the caller's word.** The house-publisher
  * fact, the payee wallet, the price and the idempotency key are all inside the
@@ -198,17 +202,33 @@ export type MarketplaceOrderRefusal =
  */
  | 'idempotency_key_reused_for_a_different_order'
 /**
- * The allocation-policy version the order names has no figure configured here, so
- * a third-party sale's split cannot be computed. A closed door, never a default
- * split. A house-publisher sale has no split and never meets it.
+ * RETIRED in `0.28.0`, and never answered since. It was published for a Cayso that
+ * would hold each allocation-policy version's figure itself; CAY-0090 put the figure
+ * in Store Platform's signed order instead, so no version can be "not configured"
+ * here. Kept in the union so a consumer's exhaustive map keeps compiling; a consumer
+ * may stop rendering it.
  */
  | 'allocation_policy_version_not_configured'
+/**
+ * The Community's share the signed order carries (`communityShareBasisPoints`) is not
+ * a whole number from 0 to 10000, or, for a Citizen publisher's sale, leaves the
+ * publisher leg or the Community leg at zero cents at this price. A leg is a lot that
+ * arrives, and a lot of no cents is not one (CAY-0078, CAY-0090), so a share of 0 or
+ * 10000, or a price too small to split, is refused rather than settled with one leg.
+ */
+ | 'allocation_share_out_of_range'
 /** No wallet has the payee's id. */
  | 'payee_wallet_not_found'
 /** The payee's wallet is an Organisation Wallet or the Treasury. A paid sale's publisher is a Citizen (CAY-0082 §8). */
  | 'payee_wallet_not_a_citizens'
 /** No Citizen is bound to the payee's wallet now, for example because the binding was erased. */
  | 'payee_wallet_has_no_live_binding'
+/**
+ * The payee's wallet is the buyer's own: a publisher buying their own listing. A
+ * movement never runs from a wallet to itself, so nothing is paid and nothing is
+ * written (CAY-0090).
+ */
+ | 'payee_wallet_is_the_buyers'
 /**
  * A third-party sale: the buyer's unrestricted cents are short. Restricted cents
  * are never counted and never drawn for one (CAY-0076), so a wallet holding enough

package/dist/operator.d.ts

@@ -85,7 +85,7 @@ export declare const OPERATOR_READ_ROUTES: {
  * movement list's `kind` filter refuses anything outside it (`400 invalid_kind`), and
  * every row's `kind` is one of these.
  */
-export type MovementKind = 'issuance' | 'purchase' | 'grant' | 'charge' | 'payout' | 'transfer' | 'burn' | 'forfeit' | 'commercial_payment' | 'quoted_sale' | 'buy_back' | 'quoted_sale_compensation';
+export type MovementKind = 'issuance' | 'purchase' | 'grant' | 'charge' | 'payout' | 'transfer' | 'burn' | 'forfeit' | 'commercial_payment' | 'quoted_sale' | 'buy_back' | 'quoted_sale_compensation' | 'marketplace_settlement';
 /** Every {@link MovementKind}, in the service's order — for a filter a person picks from. */
 export declare const MOVEMENT_KINDS: readonly MovementKind[];
 /**
@@ -96,6 +96,11 @@ export declare const MOVEMENT_KINDS: readonly MovementKind[];
  * `fromWalletId` is null when the cents came from unissued (an issuance) and
  * `toWalletId` is null when they went back to it (a burn, a forfeiture). Both are
  * wallet ids — the operator-facing handle — and never an identity.
+ *
+ * A `marketplace_settlement` lands in two wallets (CAY-0082 §1): `toWalletId` is the
+ * publisher's Citizen Wallet and `cents` the whole price the buyer paid. The Community
+ * leg's share of it went to the Treasury inside the same movement, and the row does not
+ * itemise it; the signed receipt names both legs (CAY-0090).
  */
 export interface OperatorMovementRow {
     /** The row's own opaque handle: a stable list key, not an identity. */

package/dist/operator.js

@@ -45,4 +45,5 @@ export const MOVEMENT_KINDS = [
     'quoted_sale',
     'buy_back',
     'quoted_sale_compensation',
+    'marketplace_settlement',
 ];

package/dist/routes.d.ts

@@ -84,6 +84,16 @@
  * Wallet, resolved inside `apps/api`, because a sending wallet the caller named would
  * be the caller's claim about whose cents these are (CAY-0021).
  *
+ * ## Why `handleChange` and `handleChangeReceipt` take nothing but the credential
+ *
+ * `POST /api/handle-changes` is a Citizen's Handle change, charged by Cayso, and
+ * `GET /api/handle-changes/receipt` asks whether a change reference was charged
+ * (CAY-0091). Nothing either request could carry is the caller's to say: the paying
+ * wallet is the verified subject's own, the price is Cayso's configuration, and the
+ * change reference is inside the signed assertion. So there is nothing to send but the
+ * credential, as with the founder claim. They are two paths because they are two
+ * operations, and one path carries one scope requirement at the gate.
+ *
  * ## Why the citizen market is FOUR PATHS, and none of them names a wallet
  *
  * `citizenMarket` reads the book, `placeQuote` places a quote, and `withdrawQuote`
@@ -158,6 +168,14 @@ export declare const ROUTES: {
         readonly method: "POST";
         readonly path: "/api/citizen-transfers";
     };
+    readonly handleChange: {
+        readonly method: "POST";
+        readonly path: "/api/handle-changes";
+    };
+    readonly handleChangeReceipt: {
+        readonly method: "GET";
+        readonly path: "/api/handle-changes/receipt";
+    };
     readonly citizenMarket: {
         readonly method: "GET";
         readonly path: "/api/citizen-market";

package/dist/routes.js

@@ -99,6 +99,16 @@
  * Wallet, resolved inside `apps/api`, because a sending wallet the caller named would
  * be the caller's claim about whose cents these are (CAY-0021).
  *
+ * ## Why `handleChange` and `handleChangeReceipt` take nothing but the credential
+ *
+ * `POST /api/handle-changes` is a Citizen's Handle change, charged by Cayso, and
+ * `GET /api/handle-changes/receipt` asks whether a change reference was charged
+ * (CAY-0091). Nothing either request could carry is the caller's to say: the paying
+ * wallet is the verified subject's own, the price is Cayso's configuration, and the
+ * change reference is inside the signed assertion. So there is nothing to send but the
+ * credential, as with the founder claim. They are two paths because they are two
+ * operations, and one path carries one scope requirement at the gate.
+ *
  * ## Why the citizen market is FOUR PATHS, and none of them names a wallet
  *
  * `citizenMarket` reads the book, `placeQuote` places a quote, and `withdrawQuote`
@@ -143,6 +153,8 @@ export const ROUTES = {
     purchaseCancel: { method: 'POST', path: '/api/purchases/:purchaseId/cancel' },
     commercialPayment: { method: 'POST', path: '/api/commercial-payments' },
     citizenTransfer: { method: 'POST', path: '/api/citizen-transfers' },
+    handleChange: { method: 'POST', path: '/api/handle-changes' },
+    handleChangeReceipt: { method: 'GET', path: '/api/handle-changes/receipt' },
     citizenMarket: { method: 'GET', path: '/api/citizen-market' },
     placeQuote: { method: 'POST', path: '/api/quotes' },
     withdrawQuote: { method: 'POST', path: '/api/quote-withdrawals' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percayso-community/cayso-contracts",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "The versioned capability contract surface through which anything outside this repository reads a wallet. Published; keep it the surface of every consumer outside this tree, Piper and the Percayso Cloud, and nothing internal.",
   "license": "Apache-2.0",
   "repository": {