@percayso-community/cayso-contracts 0.24.0 → 0.27.0

package/dist/errors.d.ts

@@ -39,10 +39,12 @@
  * to the unions that own them, so neither can grow a member this union does not
  * carry. The founder claim's refusals are included the same way, and so are the
  * commercial payment's, the citizen market's, the marketplace status read's and the
- * two marketplace settlements'.
+ * two marketplace settlements', and the Percayso Cloud's two seams'.
  */
 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 { CommercialPaymentRefusal } from './commercial-payment.js';
 import type { MarketplaceReceiptReadRefusal } from './marketplace-receipt.js';
 import type { MarketplaceOrderRefusal, MarketplaceRefundRefusal } from './marketplace-settlement.js';
@@ -118,6 +120,12 @@ export type CaysoApiErrorCode =
  * (CAY-0079 §3).
  */
  | 'commercial_payment_store_not_configured'
+/**
+ * No Citizen transfer store is wired, so the route is closed (CAY-0088 §3). It
+ * describes the deployment and not the transfer, so it is not a member of the
+ * transfer's refusal union.
+ */
+ | 'citizen_transfer_store_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,
@@ -175,7 +183,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 | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal;
+ | 'internal_error' | PurchaseFailureReason | PurchaseCancelRefusalReason | FounderClaimRefusal | CommercialPaymentRefusal | CitizenTransferRefusal | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal | StandingAuthorisationRefusal | SettlementAssertionRefusal;
 /**
  * The body of every refusal on this surface: one code, and nothing beside it.
  *

package/dist/index.d.ts

@@ -57,8 +57,13 @@
  * same cents. It is compile-time data with no side effects, and it enforces
  * nothing.
  *
- * This is the *Piper-facing surface only*. Peer types, admin types, holdings and
- * carves are deliberately not exported here; they are not a consumer's business.
+ * This is the surface of every consumer outside this tree (CAY-0026, Amendment 3):
+ * Piper first, and the Percayso Cloud second, whose two seams with Cayso arrive from
+ * `cloud-settlement`. Peer types, admin types, holdings and carves are deliberately
+ * not exported here; they are not a consumer's business. The three operator reads an
+ * operator app's server calls are published, but on their own entry point,
+ * `@percayso-community/cayso-contracts/operator` (CAY-0026, Amendment 4), and nothing
+ * here re-exports them: none of this barrel's consumers is an operator.
  * And it carries **no numbers** — amounts, rates, tiers, schedules and thresholds
  * live in the canon PRD and are read from one place, never restated here.
  */
@@ -71,6 +76,37 @@
  * 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.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
+ * method `makeCitizenTransfer`; and `CaysoApiErrorCode` gains
+ * {@link CitizenTransferRefusal} by reference and the seam code
+ * `citizen_transfer_store_not_configured`. It is BREAKING in the package's sense
+ * because three closed tables grew. It is additive on the wire: no route a `0.26.0`
+ * consumer calls changed or answers anything new (CAY-0086).
+ *
+ * `0.25.0` → `0.26.0` publishes the operator read surface on its own entry point,
+ * `@percayso-community/cayso-contracts/operator` (CAY-0026 Amendment 4), and describes
+ * it in the schema under `operator`: the movement list, the purchase list and the
+ * quickening ladder, with their scopes, query inputs, rows, pages and closed refusal
+ * bodies. Nothing new is served — the three routes answered these shapes already —
+ * and nothing in this barrel changed, so no closed table grew: `ROUTES`,
+ * `ContractOperation` and `CaysoApiErrorCode` are as `0.25.0` published them. It is
+ * additive in the package's sense and on the wire (CAY-0086).
+ *
+ * `0.24.0` → `0.25.0` publishes the Percayso Cloud's two seams with Cayso (CMTY-0018
+ * §3) and serves neither. `ROUTES` gains `standingAuthorisation`, where an Instance
+ * presents its owner's standing authorisation under the owner's assertion, with the
+ * client method `presentStandingAuthorisation`; the Contribution Store's settlement
+ * path is published as {@link CLOUD_SETTLEMENT_ROUTE}, outside `ROUTES`, and in the
+ * schema under `issuerRoutes`. The claim types of both documents and of Cayso's
+ * acknowledgement arrive from `cloud-settlement`, carrying no Instance ID (CAY-0059
+ * §6) and no figure. It is BREAKING in the package's sense because three closed
+ * tables grew: `ROUTES`, `ContractOperation` (with `'present-standing-authorisation'`,
+ * money-grade in `ASSURANCE_POLICY`) and `CaysoApiErrorCode`, which gains the two
+ * seams' refusal unions by reference. It is additive on the wire: no route a
+ * `0.24.0` consumer calls changed or answers anything new (CAY-0086).
+ *
  * `0.23.0` → `0.24.0` SERVES `settle-marketplace-order` for a house-publisher sale
  * at `ROUTES.marketplaceOrder` (CAY-0082 §2, CAY-0083 §3), with the client method
  * `settleMarketplaceOrder` and three seam codes: `marketplace_order_keys_not_configured`,
@@ -486,7 +522,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.24.0";
+export declare const CONTRACT_VERSION: "0.27.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**
@@ -503,6 +539,13 @@ export { WALLET_CAPABILITY } from './wallet.js';
  */
 export { PURCHASE_CAPABILITY } from './purchase.js';
 export { ROUTES } from './routes.js';
+/**
+ * Where the Percayso Cloud's Contribution Store presents a settlement assertion
+ * (CMTY-0018 §2). A value beside `ROUTES` and never in it: the path is
+ * authenticated by a registered Store issuer (CAY-0030), not by a person, so it has
+ * no operation, no assurance bar and no client method.
+ */
+export { CLOUD_SETTLEMENT_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
@@ -619,9 +662,11 @@ export type { HolderType, Millis, Cents, WalletRecord, Balance, Allowance, Walle
 export type { SignUpGrantTerms, SignUpGrant, CitizenshipNotProvisioned, CitizenshipProvisioned, CitizenshipFounderClaimed, Citizenship, CitizenshipView, FounderClaimRefusal, } from './citizenship.js';
 export type { OrganisationView } from './organisation.js';
 export type { CommercialPaymentAuthority, CommercialPaymentRequest, CommercialPayment, CommercialPaymentMade, CommercialPaymentRefused, CommercialPaymentResponse, CommercialPaymentRefusal, } from './commercial-payment.js';
+export type { CitizenTransferRequest, CitizenTransfer, CitizenTransferMade, CitizenTransferRefused, CitizenTransferResponse, CitizenTransferRefusal, } from './citizen-transfer.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 { 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';

package/dist/index.js

@@ -72,8 +72,13 @@
  * same cents. It is compile-time data with no side effects, and it enforces
  * nothing.
  *
- * This is the *Piper-facing surface only*. Peer types, admin types, holdings and
- * carves are deliberately not exported here; they are not a consumer's business.
+ * This is the surface of every consumer outside this tree (CAY-0026, Amendment 3):
+ * Piper first, and the Percayso Cloud second, whose two seams with Cayso arrive from
+ * `cloud-settlement`. Peer types, admin types, holdings and carves are deliberately
+ * not exported here; they are not a consumer's business. The three operator reads an
+ * operator app's server calls are published, but on their own entry point,
+ * `@percayso-community/cayso-contracts/operator` (CAY-0026, Amendment 4), and nothing
+ * here re-exports them: none of this barrel's consumers is an operator.
  * And it carries **no numbers** — amounts, rates, tiers, schedules and thresholds
  * live in the canon PRD and are read from one place, never restated here.
  */
@@ -87,6 +92,37 @@
  * 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.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
+ * method `makeCitizenTransfer`; and `CaysoApiErrorCode` gains
+ * {@link CitizenTransferRefusal} by reference and the seam code
+ * `citizen_transfer_store_not_configured`. It is BREAKING in the package's sense
+ * because three closed tables grew. It is additive on the wire: no route a `0.26.0`
+ * consumer calls changed or answers anything new (CAY-0086).
+ *
+ * `0.25.0` → `0.26.0` publishes the operator read surface on its own entry point,
+ * `@percayso-community/cayso-contracts/operator` (CAY-0026 Amendment 4), and describes
+ * it in the schema under `operator`: the movement list, the purchase list and the
+ * quickening ladder, with their scopes, query inputs, rows, pages and closed refusal
+ * bodies. Nothing new is served — the three routes answered these shapes already —
+ * and nothing in this barrel changed, so no closed table grew: `ROUTES`,
+ * `ContractOperation` and `CaysoApiErrorCode` are as `0.25.0` published them. It is
+ * additive in the package's sense and on the wire (CAY-0086).
+ *
+ * `0.24.0` → `0.25.0` publishes the Percayso Cloud's two seams with Cayso (CMTY-0018
+ * §3) and serves neither. `ROUTES` gains `standingAuthorisation`, where an Instance
+ * presents its owner's standing authorisation under the owner's assertion, with the
+ * client method `presentStandingAuthorisation`; the Contribution Store's settlement
+ * path is published as {@link CLOUD_SETTLEMENT_ROUTE}, outside `ROUTES`, and in the
+ * schema under `issuerRoutes`. The claim types of both documents and of Cayso's
+ * acknowledgement arrive from `cloud-settlement`, carrying no Instance ID (CAY-0059
+ * §6) and no figure. It is BREAKING in the package's sense because three closed
+ * tables grew: `ROUTES`, `ContractOperation` (with `'present-standing-authorisation'`,
+ * money-grade in `ASSURANCE_POLICY`) and `CaysoApiErrorCode`, which gains the two
+ * seams' refusal unions by reference. It is additive on the wire: no route a
+ * `0.24.0` consumer calls changed or answers anything new (CAY-0086).
+ *
  * `0.23.0` → `0.24.0` SERVES `settle-marketplace-order` for a house-publisher sale
  * at `ROUTES.marketplaceOrder` (CAY-0082 §2, CAY-0083 §3), with the client method
  * `settleMarketplaceOrder` and three seam codes: `marketplace_order_keys_not_configured`,
@@ -502,7 +538,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.24.0';
+export const CONTRACT_VERSION = '0.27.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**
@@ -519,6 +555,13 @@ export { WALLET_CAPABILITY } from './wallet.js';
  */
 export { PURCHASE_CAPABILITY } from './purchase.js';
 export { ROUTES } from './routes.js';
+/**
+ * Where the Percayso Cloud's Contribution Store presents a settlement assertion
+ * (CMTY-0018 §2). A value beside `ROUTES` and never in it: the path is
+ * authenticated by a registered Store issuer (CAY-0030), not by a person, so it has
+ * no operation, no assurance bar and no client method.
+ */
+export { CLOUD_SETTLEMENT_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

package/dist/operator.d.ts

@@ -0,0 +1,298 @@
+/**
+ * `@percayso-community/cayso-contracts/operator` — the operator READ surface, on its
+ * own entry point: three reads and nothing else (CAY-0026, Amendment 4).
+ *
+ *   - `GET /api/operator/movements`  — the movement list, under `list-movements-as-operator`.
+ *   - `GET /api/operator/purchases`  — the purchase list, under `list-purchases-as-operator`.
+ *   - `GET /api/operator/quickenings` — the quickening ladder, under
+ *     `read-quickening-ladder-as-operator`.
+ *
+ * ## Who calls this, and from where
+ *
+ * An operator app's SERVER. Cayso answers no browser: it serves no CORS headers and
+ * that does not change here, so a page that wants these reads asks its own server,
+ * and that server calls Cayso with an operator's minted assertion. Publishing the
+ * shapes lets that server type what it sends and what it is answered, instead of
+ * keeping a hand-copied mirror that drifts from the routes.
+ *
+ * ## Why its own entry point, and not the barrel
+ *
+ * `@percayso-community/cayso-contracts` is the surface Piper and the Percayso Cloud
+ * read. None of them is an operator, and none of them should be handed an operator
+ * vocabulary to grow a dependency on. So nothing here is re-exported from the barrel,
+ * and the schema describes it under its own key (`operator`), apart from the routes
+ * a person calls. A consumer that never imports this subpath never sees it.
+ *
+ * ## What it carries, and what it deliberately does not
+ *
+ *   - **The three reads only.** The operator surface is larger than this — the wallet
+ *     lookup, the resolver, the market alarms, the founder lapse — and all of it stays
+ *     unpublished. Widening this entry point is a further amendment to CAY-0026, not
+ *     an edit to this file.
+ *   - **No peer, holdings or carve type.** A row here is a movement or a purchase as
+ *     an operator LIST shows it, never a holding and never the carve that produced it.
+ *   - **The wallet id is the handle.** No row carries a Percayso identity, an
+ *     attribution or the acting party: an operator list must not be casually a
+ *     directory of identities (CAY-0006).
+ *   - **Money is {@link Cents}.** An integer count, never formatted; the ladder's
+ *     `publishedValuePence` is a field read from the deployment, never a value fixed
+ *     here.
+ *   - **No numbers.** The page-size cap, the page-number cap and the wallet-id filter's
+ *     length bound are the service's, and a consumer that copied them would hold a
+ *     second home for each.
+ *
+ * ## The API is the source of truth
+ *
+ * Every shape here is the one `apps/api` serves, and a test in `apps/api` drives the
+ * three routes and fails on any field the service sends that this file does not
+ * describe. Where an earlier hand-written client disagreed with the service, the
+ * service won.
+ */
+import type { PurchaseFailureReason, PurchaseStatus } from './purchase.js';
+import type { Cents } from './wallet.js';
+/**
+ * The scope an operator's assertion must name for each read. A closed union: a route
+ * here refuses a credential that does not name what it is about to do, exactly as a
+ * contract-surface route does (`403 assertion_scope_refused`).
+ */
+export type OperatorReadScope = 'list-movements-as-operator' | 'list-purchases-as-operator' | 'read-quickening-ladder-as-operator';
+/** One published operator read: its method, its path and the scope it requires. */
+export interface OperatorReadRoute {
+    readonly method: 'GET';
+    readonly path: string;
+    readonly scope: OperatorReadScope;
+}
+/** The three reads, by name. The paths and scopes are the service's own. */
+export declare const OPERATOR_READ_ROUTES: {
+    readonly movements: {
+        readonly method: "GET";
+        readonly path: "/api/operator/movements";
+        readonly scope: "list-movements-as-operator";
+    };
+    readonly purchases: {
+        readonly method: "GET";
+        readonly path: "/api/operator/purchases";
+        readonly scope: "list-purchases-as-operator";
+    };
+    readonly quickenings: {
+        readonly method: "GET";
+        readonly path: "/api/operator/quickenings";
+        readonly scope: "read-quickening-ladder-as-operator";
+    };
+};
+/**
+ * What a movement is, declared by the act before the draw (CAY-0075). Closed: the
+ * 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';
+/** Every {@link MovementKind}, in the service's order — for a filter a person picks from. */
+export declare const MOVEMENT_KINDS: readonly MovementKind[];
+/**
+ * One movement as the operator list shows it. A movement is final and append-only
+ * (CAY-0023), so there is no status and no failure reason: a movement that did not
+ * happen is not a movement.
+ *
+ * `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.
+ */
+export interface OperatorMovementRow {
+    /** The row's own opaque handle: a stable list key, not an identity. */
+    readonly movementId: string;
+    /** When the movement happened, as an ISO-8601 UTC instant. */
+    readonly occurredAt: string;
+    readonly kind: MovementKind;
+    readonly fromWalletId: string | null;
+    readonly toWalletId: string | null;
+    readonly cents: Cents;
+    /**
+     * The contract's `Restriction`, written out: `restriction.ts` is not on the schema's
+     * surface (its capability policy is a mapped type the generator refuses), so a
+     * reference would dangle. `operator.test.ts` pins the two equal.
+     */
+    readonly restriction: 'restricted' | 'unrestricted';
+}
+/**
+ * One page of movements, newest first, and the walk's frozen snapshot.
+ *
+ * `nextCursor` resumes after this page and is null at the end. `anchor` is the
+ * snapshot's upper bound: computed on a request that carries none, and sent back
+ * thereafter, so `total` and `pageCount` hold still while movements arrive. `page` is
+ * the page actually served. An empty walk is `anchor: null`, `total: 0`,
+ * `pageCount: 0`, `page: 1`. Both cursors are opaque strings; a consumer passes them
+ * back and never reads them. The counts are counts of rows — nothing here but the
+ * rows' `cents` is money.
+ */
+export interface OperatorMovementsPage {
+    readonly movements: readonly OperatorMovementRow[];
+    readonly nextCursor: string | null;
+    readonly anchor: string | null;
+    readonly total: number;
+    readonly pageCount: number;
+    readonly page: number;
+}
+/**
+ * One purchase as the operator list shows it: the buyer's wallet id, the cents, when
+ * it began, its status, and — exactly when it failed — the closed-union reason. No
+ * identity, no gateway handle, no idempotency key.
+ */
+export interface OperatorPurchaseRow {
+    /** The row's own opaque handle: a stable list key, not an identity. */
+    readonly purchaseId: string;
+    /** When the purchase began, as an ISO-8601 UTC instant. */
+    readonly createdAt: string;
+    readonly walletId: string;
+    readonly cents: Cents;
+    readonly status: PurchaseStatus;
+    readonly failureReason: PurchaseFailureReason | null;
+}
+/** One page of purchases. The envelope is the movement list's, for the same reasons. */
+export interface OperatorPurchasesPage {
+    readonly purchases: readonly OperatorPurchaseRow[];
+    readonly nextCursor: string | null;
+    readonly anchor: string | null;
+    readonly total: number;
+    readonly pageCount: number;
+    readonly page: number;
+}
+/**
+ * The query a list accepts, as query-string parameters. Every one is optional, and a
+ * filter is refused rather than coerced: a value the service does not accept is a
+ * `400` naming the parameter, never a quietly broader list.
+ *
+ *   - `after` — the `nextCursor` of the page before, to resume after it.
+ *   - `anchor` — the `anchor` the first page answered, to stay inside its snapshot.
+ *   - `limit` — rows per page. Out of range it is clamped, not refused: above the
+ *     service's cap is the cap, below one is one, and a value that is not a number
+ *     is the cap.
+ *   - `page` — which page of the snapshot to serve, clamped the same way; absent or
+ *     not a number is the first.
+ *   - `walletId` — one wallet id. Bounded printable ASCII with no spaces; longer or
+ *     otherwise malformed is `400 invalid_wallet_id`. A wallet that does not exist is
+ *     an empty page, not a refusal.
+ *   - `from`, `to` — the half-open range `[from, to)`: `from` is included, `to` is
+ *     not. Each is a UTC calendar date (`YYYY-MM-DD`, meaning its midnight) or a
+ *     `Z`-terminated instant (`YYYY-MM-DDTHH:MM:SS` with optional milliseconds). A
+ *     zone offset or an impossible date is `400 invalid_from` / `invalid_to`.
+ *
+ * A parameter given twice is `400 repeated_<name>`.
+ */
+export interface OperatorMovementsQuery {
+    readonly after?: string;
+    readonly anchor?: string;
+    readonly limit?: number;
+    readonly page?: number;
+    readonly walletId?: string;
+    readonly from?: string;
+    readonly to?: string;
+    /** One kind. A movement has no status, and `status` here is `400 status_not_filterable_on_movements`. */
+    readonly kind?: MovementKind;
+}
+/** The purchase list's query: the movement list's, with a status and a failure reason for `kind`. */
+export interface OperatorPurchasesQuery {
+    readonly after?: string;
+    readonly anchor?: string;
+    readonly limit?: number;
+    readonly page?: number;
+    readonly walletId?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly status?: PurchaseStatus;
+    readonly failureReason?: PurchaseFailureReason;
+}
+/** One band of the ladder. Three integers; no formatted string. */
+export interface QuickeningLadderBand {
+    readonly band: number;
+    /** The active-citizen count this band begins at. */
+    readonly fromActiveCitizens: number;
+    /** What ₡1 is worth in this band, in whole pence. */
+    readonly publishedValuePence: number;
+}
+/** Where the deployment sits on the ladder, from its newest policy row. */
+export interface LiveQuickeningBand {
+    readonly band: number;
+    readonly publishedValuePence: number;
+}
+/**
+ * The ladder, the live band, and the active-citizen count.
+ *
+ * `live` is null when no policy row exists. A live band the ladder does not contain is
+ * REPORTED as it stands, never repaired (CAY-0028). `activeCitizens` is displayed
+ * only: the live band is read from the policy row, never derived from the count.
+ */
+export interface QuickeningLadder {
+    readonly bands: readonly QuickeningLadderBand[];
+    readonly live: LiveQuickeningBand | null;
+    readonly activeCitizens: number;
+}
+/**
+ * `401` — no credential, or one the verifier refused. Every member is also a
+ * {@link import('./errors.js').CaysoApiErrorCode}: the gate is the one every route
+ * shares.
+ */
+export type OperatorAuthenticationRefusal = 'unauthenticated' | 'assertion_invalid' | 'assertion_expired' | 'assertion_issuer_refused' | 'assertion_key_refused' | 'assertion_algorithm_refused' | 'assertion_subject_refused' | 'assertion_replayed';
+/**
+ * `403` — a verified credential that may not make this read, with a bare `{ error }`.
+ *
+ *   - `assertion_scope_refused` — the credential does not name the route's
+ *     {@link OperatorReadScope}.
+ *   - `subject_not_a_natural_person` — the credential does not say it belongs to one
+ *     human being (CAY-0069).
+ *   - `not_an_operator` — money-grade and a person, but not on this deployment's
+ *     operator allowlist, which is empty until it is told otherwise.
+ */
+export type OperatorAccessRefusal = 'assertion_scope_refused' | 'subject_not_a_natural_person' | 'not_an_operator';
+/**
+ * `403` — the credential's verification method is not money-grade (the development
+ * bypass, or unverified). The same envelope a money route answers, so a listed
+ * operator learns its METHOD is the problem, not its listing.
+ */
+export interface OperatorVerificationRefused {
+    readonly outcome: 'refused';
+    readonly error: 'verification_refused';
+}
+/** `429` — too many credentials presented too fast. */
+export type OperatorRateLimited = 'request_rate_limited';
+/**
+ * `503` — the deployment cannot answer any operator read: no verifier, no issuer
+ * registry, or the read audit cannot be written. A read that cannot be recorded does
+ * not happen (CAY-0027).
+ */
+export type OperatorReadUnavailable = 'verifier_not_configured' | 'issuer_registry_not_configured' | 'operator_read_audit_unavailable';
+/** `500` — the service failed, and the reason is not the caller's. */
+export type OperatorReadFailed = 'internal_error';
+/** `400` — the movement list's query was refused. Named per parameter. */
+export type OperatorMovementsQueryRefusal = 'invalid_cursor' | 'invalid_anchor' | 'invalid_wallet_id' | 'invalid_from' | 'invalid_to' | 'invalid_kind' | 'status_not_filterable_on_movements' | 'repeated_walletId' | 'repeated_from' | 'repeated_to' | 'repeated_kind';
+/** `400` — the purchase list's query was refused. Named per parameter. */
+export type OperatorPurchasesQueryRefusal = 'invalid_cursor' | 'invalid_anchor' | 'invalid_wallet_id' | 'invalid_from' | 'invalid_to' | 'invalid_status' | 'invalid_failure_reason' | 'repeated_walletId' | 'repeated_from' | 'repeated_to' | 'repeated_status' | 'repeated_failureReason';
+/** `503` — this deployment has no movement reader wired. */
+export type OperatorMovementsUnavailable = 'operator_movements_reader_not_configured';
+/** `503` — this deployment has no purchase reader wired. */
+export type OperatorPurchasesUnavailable = 'operator_purchases_reader_not_configured';
+/**
+ * `503` — the ladder cannot be read: no reader wired, or a reader and no ladder
+ * seeded. Kept apart so an operator can tell a wiring fault from an empty table.
+ */
+export type QuickeningLadderUnavailable = 'quickening_ladder_reader_not_configured' | 'quickening_ladder_not_configured';
+/** Every `{ error }` code the movement list answers. */
+export type OperatorMovementsErrorCode = OperatorMovementsQueryRefusal | OperatorAuthenticationRefusal | OperatorAccessRefusal | OperatorRateLimited | OperatorReadUnavailable | OperatorMovementsUnavailable | OperatorReadFailed;
+/** Every `{ error }` code the purchase list answers. */
+export type OperatorPurchasesErrorCode = OperatorPurchasesQueryRefusal | OperatorAuthenticationRefusal | OperatorAccessRefusal | OperatorRateLimited | OperatorReadUnavailable | OperatorPurchasesUnavailable | OperatorReadFailed;
+/** Every `{ error }` code the ladder answers. It takes no query, so nothing is a `400`. */
+export type QuickeningLadderErrorCode = OperatorAuthenticationRefusal | OperatorAccessRefusal | OperatorRateLimited | OperatorReadUnavailable | QuickeningLadderUnavailable | OperatorReadFailed;
+export interface OperatorMovementsError {
+    readonly error: OperatorMovementsErrorCode;
+}
+export interface OperatorPurchasesError {
+    readonly error: OperatorPurchasesErrorCode;
+}
+export interface QuickeningLadderError {
+    readonly error: QuickeningLadderErrorCode;
+}
+/** Everything `GET /api/operator/movements` answers: `200`, or one refusal body. */
+export type OperatorMovementsResponse = OperatorMovementsPage | OperatorVerificationRefused | OperatorMovementsError;
+/** Everything `GET /api/operator/purchases` answers: `200`, or one refusal body. */
+export type OperatorPurchasesResponse = OperatorPurchasesPage | OperatorVerificationRefused | OperatorPurchasesError;
+/** Everything `GET /api/operator/quickenings` answers: `200`, or one refusal body. */
+export type QuickeningLadderResponse = QuickeningLadder | OperatorVerificationRefused | QuickeningLadderError;

package/dist/operator.js

@@ -0,0 +1,48 @@
+/*
+ * 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 three reads, by name. The paths and scopes are the service's own. */
+export const OPERATOR_READ_ROUTES = {
+    movements: {
+        method: 'GET',
+        path: '/api/operator/movements',
+        scope: 'list-movements-as-operator',
+    },
+    purchases: {
+        method: 'GET',
+        path: '/api/operator/purchases',
+        scope: 'list-purchases-as-operator',
+    },
+    quickenings: {
+        method: 'GET',
+        path: '/api/operator/quickenings',
+        scope: 'read-quickening-ladder-as-operator',
+    },
+};
+/** Every {@link MovementKind}, in the service's order — for a filter a person picks from. */
+export const MOVEMENT_KINDS = [
+    'issuance',
+    'purchase',
+    'grant',
+    'charge',
+    'payout',
+    'transfer',
+    'burn',
+    'forfeit',
+    'commercial_payment',
+    'quoted_sale',
+    'buy_back',
+    'quoted_sale_compensation',
+];

package/dist/routes.d.ts

@@ -76,6 +76,14 @@
  * (CAY-0079 §2). A path that took a payee's identity would make this route a
  * directory of identities for anyone holding a mandate.
  *
+ * ## Why `citizenTransfer` names only the payee, and never the sender
+ *
+ * `POST /api/citizen-transfers` is a Citizen transferring Cayso to another Citizen
+ * (CAY-0088). The body carries the payee's wallet id, the cents and the key. The
+ * sending wallet is NOT in the request: it is the verified subject's own Citizen
+ * 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 the citizen market is FOUR PATHS, and none of them names a wallet
  *
  * `citizenMarket` reads the book, `placeQuote` places a quote, and `withdrawQuote`
@@ -94,6 +102,20 @@
  * `requestBuyBack` asks the Treasury to buy back (CAY-0080 §2.2). It is a fourth path
  * for the same reason: selling to the Treasury is not a quote (Open decision G), and a
  * credential scoped to place one must not thereby cash out. It names no wallet either.
+ *
+ * ## Why `standingAuthorisation` is here, and the Cloud's settlement is not
+ *
+ * `standingAuthorisation` is an Instance presenting its owner's standing
+ * authorisation under the owner's assertion (`present-standing-authorisation`,
+ * CMTY-0018 §1). A person is behind it, so it is classified by a person's
+ * assurance like every other entry. It names no wallet: the wallet is the verified
+ * holder's own. It is published before it is served.
+ *
+ * The Contribution Store's settlement assertion is presented by no person. Its path
+ * is {@link CLOUD_SETTLEMENT_ROUTE}, outside this table, because every entry here is
+ * mapped in `OPERATION_FOR_ROUTE` to the assurance a person needs, and `null` there
+ * means "carries no identity", which is false of an assertion a registered issuer
+ * signed.
  */
 export declare const ROUTES: {
     readonly wallet: {
@@ -132,6 +154,10 @@ export declare const ROUTES: {
         readonly method: "POST";
         readonly path: "/api/commercial-payments";
     };
+    readonly citizenTransfer: {
+        readonly method: "POST";
+        readonly path: "/api/citizen-transfers";
+    };
     readonly citizenMarket: {
         readonly method: "GET";
         readonly path: "/api/citizen-market";
@@ -152,8 +178,30 @@ export declare const ROUTES: {
         readonly method: "POST";
         readonly path: "/api/marketplace/orders";
     };
+    readonly standingAuthorisation: {
+        readonly method: "POST";
+        readonly path: "/api/cloud/standing-authorisations";
+    };
     readonly version: {
         readonly method: "GET";
         readonly path: "/api/version";
     };
 };
+/**
+ * Where the Percayso Cloud's Contribution Store presents one period's settlement
+ * assertion (CMTY-0018 §2, `cloud-settlement`).
+ *
+ * **Authenticated by a registered Store issuer (CAY-0030), not by a person.** The
+ * assertion is its own credential: signed by a key whose public half is a
+ * registered Cayso issuer under its own `kid`, in CAY-0072's format, and verified
+ * against a registry that is empty by default, so a Cayso never told about a Store
+ * settles nothing (CAY-0021). No person's assertion travels with it, and it is not
+ * in {@link ROUTES}, whose every entry is classified by a person's assurance. The
+ * client has no method for it, because no person's software calls it.
+ *
+ * Published before it is served.
+ */
+export declare const CLOUD_SETTLEMENT_ROUTE: {
+    readonly method: "POST";
+    readonly path: "/api/cloud/settlement-assertions";
+};