@percayso-community/cayso-contracts 0.29.0 → 0.30.0

package/dist/index.d.ts

@@ -76,6 +76,64 @@
  * this money surface gains that Piper's own contracts lack, since theirs share
  * one global version bumped across all twenty-two together (CAY-0026).
  *
+ * `0.29.0` → `0.30.0` publishes and SERVES Cayso's authorisation acknowledgement keys
+ * (CAY-0093): {@link ACKNOWLEDGEMENT_KEYS_ROUTE}, `GET /api/acknowledgement-keys`, an
+ * unauthenticated read outside `ROUTES`, described in the schema under `keyRoutes`;
+ * the key set it answers, {@link AcknowledgementKeySet} of
+ * {@link AcknowledgementPublicKey}, Ed25519 public JSON Web Keys and nothing private;
+ * and `CaysoApiErrorCode` gains `acknowledgement_signing_not_configured`, the route's
+ * closed door.
+ *
+ * The same version SERVES the standing authorisation (CAY-0094), published at `0.25.0`
+ * and answered until now by the router's `404`: `ROUTES.standingAuthorisation` answers
+ * {@link StandingAuthorisationResponse} with an acknowledgement signed under that key.
+ * It adds the owner's way to withdraw one: `ROUTES.revokeStandingAuthorisation`,
+ * `POST /api/cloud/standing-authorisation-revocations`, mapped to the new operation
+ * `'revoke-standing-authorisation'`, money-grade in `ASSURANCE_POLICY`; the client
+ * method `revokeStandingAuthorisation`; {@link StandingAuthorisationRevocationRequest},
+ * {@link StandingAuthorisationRevocationResponse} and the closed
+ * {@link StandingAuthorisationRevocationRefusal}, which `CaysoApiErrorCode` gains by
+ * reference; and the seam codes `standing_authorisation_store_not_configured`,
+ * `standing_authorisation_cap_ceiling_not_configured` and
+ * `standing_authorisation_life_ceiling_not_configured`.
+ *
+ * The same version publishes and SERVES binding a Node to a wallet (CMTY-0018 §4,
+ * CAY-0095): `ROUTES.bindNode`, `POST /api/cloud/node-bindings`, mapped to the new
+ * operation `'bind-node'`, money-grade in `ASSURANCE_POLICY`; the client method
+ * `bindNode`; {@link NodePresentationClaims}, {@link NodeBindingRequest},
+ * {@link NodeBindingResponse} and the closed {@link NodeBindingRefusal}. Beside it, the
+ * Contribution Store's read of whether a Node is bound: {@link NODE_BINDING_QUERY_ROUTE},
+ * `POST /api/cloud/node-binding-queries`, outside `ROUTES` and in the schema under
+ * `issuerRoutes`, authenticated by the registered Store issuer; {@link
+ * NodeBindingQueryClaims}, {@link NodeBindingQueryRequest}, the answer
+ * {@link NodeBindingStatus} — `nodeId` and `bound` and nothing else — and the closed
+ * {@link NodeBindingQueryRefusal}. `CaysoApiErrorCode` gains both unions by reference
+ * and the seam codes `node_binding_store_not_configured`, `core_node_ids_not_configured`
+ * and `contribution_store_issuer_not_configured`.
+ *
+ * The same version SERVES the Contribution Store's settlement assertion (CMTY-0018 §2,
+ * CAY-0096) at {@link CLOUD_SETTLEMENT_ROUTE}, published at `0.25.0` and answered until
+ * now by the router's `404`. A settled period writes one `contribution_settlement`
+ * movement per paid contribution row and one `consumption_settlement` per consumption
+ * row, so `MovementKind` and `MOVEMENT_KINDS` gain both. The closed refusal unions gain
+ * the members the write needs: {@link SettlementAssertionLevelRefusal} gains
+ * `settlement_period_not_recognised`, `settlement_period_not_ended` and
+ * `settlement_carve_contended`; {@link ContributionRowRefusal} gains
+ * `contribution_node_is_a_core_node` and `contribution_treasury_short`;
+ * {@link ConsumptionRowRefusal} gains `consumption_authorisation_not_in_force` and
+ * `consumption_wallet_short`. `CaysoApiErrorCode` gains them by reference and the seam
+ * code `cloud_settlement_store_not_configured`.
+ *
+ * BREAKING in the package's sense because closed tables grew: `ROUTES`,
+ * `ContractOperation`, `CaysoApiErrorCode`, `MovementKind` and the settlement's refusal
+ * unions. Additive on the wire (CAY-0086): no route a `0.29.0` consumer could reach
+ * changed, because the only ones that answer differently are the standing
+ * authorisation and the settlement assertion, which no deployment served before, and
+ * they answer the shapes `0.25.0` published, a member those shapes' unions gained, or a
+ * new seam code no served route emits. The operator movement list can now carry the two
+ * new kinds, and it is read only by the admin app in this tree, released with it. The
+ * two Node routes are ones a `0.29.0` consumer cannot name.
+ *
  * `0.28.0` → `0.29.0` publishes and SERVES the Handle change (CAY-0091):
  * `ROUTES.handleChange`, `POST /api/handle-changes`, mapped to the new operation
  * `'change-handle'`, money-grade in `ASSURANCE_POLICY`; `ROUTES.handleChangeReceipt`,
@@ -552,7 +610,7 @@
  * have needed a breaking bump on their own. Under semver below `1.0.0` the minor
  * is where a breaking change goes, so the minor moves and the patch does not.
  */
-export declare const CONTRACT_VERSION: "0.29.0";
+export declare const CONTRACT_VERSION: "0.30.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**
@@ -576,6 +634,18 @@ export { ROUTES } from './routes.js';
  * no operation, no assurance bar and no client method.
  */
 export { CLOUD_SETTLEMENT_ROUTE } from './routes.js';
+/**
+ * Where the Contribution Store asks whether a Node is bound (CAY-0095). A value beside
+ * `ROUTES` and never in it, for the settlement path's reason: it is authenticated by
+ * the registered Store issuer, not by a person.
+ */
+export { NODE_BINDING_QUERY_ROUTE } from './routes.js';
+/**
+ * Where Cayso publishes its authorisation acknowledgement keys (CAY-0093). A value
+ * beside `ROUTES` and never in it: an unauthenticated read of a public key carries no
+ * identity, so it has no operation, no assurance bar and no client method.
+ */
+export { ACKNOWLEDGEMENT_KEYS_ROUTE } from './routes.js';
 /**
  * The purchase lifecycle's runtime half (CAY-0032): which statuses a purchase
  * never leaves, the predicate over them, and the window an authorisation holds its
@@ -702,7 +772,7 @@ export type { HandleChangeReceiptStatement, HandleChangeReceipt, HandleChangeCha
 export type { QuoteSide, QuoteRequest, Quote, QuotePlaced, QuoteRefused, QuoteResponse, QuoteEntryRefusal, QuotePlacementRefusal, QuoteWithdrawalRequest, QuoteWithdrawal, QuoteWithdrawn, QuoteWithdrawalRefused, QuoteWithdrawalResponse, QuoteWithdrawalRefusal, BuyBackRequest, BuyBack, BuyBackMade, BuyBackRefused, BuyBackResponse, BuyBackRefusal, BookLevel, QuoteStatus, QuoteWithdrawalReason, OwnQuote, OwnQuoteNotWithdrawn, OwnQuoteWithdrawn, CitizenMarketView, CitizenMarketViewed, CitizenMarketViewRefusal, CitizenMarketViewRefused, CitizenMarketResponse, } from './citizen-market.js';
 export type { MarketplaceReceiptSignatureAlgorithm, MarketplaceReceiptKeyId, MarketplaceSaleKind, MarketplaceReceiptLeg, MarketplaceSettlementReceiptStatement, HousePublisherChargeReceiptStatement, ThirdPartyRefundReceiptStatement, HousePublisherRefundReceiptStatement, MarketplaceReceiptStatement, MarketplaceReceipt, MarketplaceReceiptReadRequest, MarketplaceReceiptFound, MarketplaceNoMovement, MarketplaceReceiptReadRefusal, MarketplaceReceiptReadRefused, MarketplaceReceiptReadResponse, } from './marketplace-receipt.js';
 export type { StoreSignedStatement, MarketplaceOrderRequest, MarketplaceRefundRequest, MarketplaceOrderReceipt, MarketplaceRefundReceipt, MarketplaceOrderSettled, MarketplaceOrderRefused, MarketplaceOrderResponse, MarketplaceOrderRefusal, MarketplaceRefundSettled, MarketplaceRefundRefused, MarketplaceRefundResponse, MarketplaceRefundRefusal, } from './marketplace-settlement.js';
-export type { InstanceKeyId, SettlementPeriodRule, SettlementPeriodId, NodeId, ContributionStoreIssuer, PercaysoCloudAudience, StandingAuthorisationClaims, StandingAuthorisationRequest, AuthorisationAcknowledgementClaims, StandingAuthorisationAcknowledged, StandingAuthorisationRefused, StandingAuthorisationResponse, StandingAuthorisationRefusal, ContributionType, SettlementPeriod, ContributionWithheldReason, ContributionQualified, ContributionWithheld, ContributionQualification, ContributionRow, ConsumptionRow, SettlementTotals, SettlementAssertionClaims, SettlementAssertionRequest, SettlementAssertionSettled, SettlementAssertionRefused, ContributionRowRefused, ConsumptionRowRefused, SettlementAssertionResponse, SettlementAssertionLevelRefusal, ContributionRowRefusal, ConsumptionRowRefusal, SettlementAssertionRefusal, } from './cloud-settlement.js';
+export type { InstanceKeyId, SettlementPeriodRule, SettlementPeriodId, NodeId, ContributionStoreIssuer, PercaysoCloudAudience, StandingAuthorisationClaims, StandingAuthorisationRequest, AuthorisationAcknowledgementClaims, AcknowledgementKeyId, AcknowledgementPublicKey, AcknowledgementKeySet, StandingAuthorisationAcknowledged, StandingAuthorisationRefused, StandingAuthorisationResponse, StandingAuthorisationRefusal, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, StandingAuthorisationRevocationRefused, StandingAuthorisationRevocationResponse, StandingAuthorisationRevocationRefusal, NodePresentationClaims, NodeBindingRequest, NodeBound, NodeBindingRefused, NodeBindingResponse, NodeBindingRefusal, NodeBindingQueryClaims, NodeBindingQueryRequest, NodeBindingStatus, NodeBindingQueryRefused, NodeBindingQueryRefusal, ContributionType, SettlementPeriod, ContributionWithheldReason, ContributionQualified, ContributionWithheld, ContributionQualification, ContributionRow, ConsumptionRow, SettlementTotals, SettlementAssertionClaims, SettlementAssertionRequest, SettlementAssertionSettled, SettlementAssertionRefused, ContributionRowRefused, ConsumptionRowRefused, SettlementAssertionResponse, SettlementAssertionLevelRefusal, ContributionRowRefusal, ConsumptionRowRefusal, SettlementAssertionRefusal, } from './cloud-settlement.js';
 export type { PurchaseRequest, PurchaseAuthorised, PurchaseTerminal, PurchaseUnresolved, PurchaseRefused, PurchaseAuthorisationResponse, PurchaseFailureReason, PurchaseStatus, LivePurchaseStatus, TerminalPurchaseStatus, PurchaseCancelRefusalReason, PurchaseCancelled, PurchaseCancelRefused, PurchaseCancelResponse, PurchaseResult, } from './purchase.js';
 export type { VerificationMethod, VerificationStatus, SubjectPersonhood, AssertionClaims, AssertionHeader, AssertionEnvelope, ContractOperation, InternalOperation, ScopeKey, } from './assertion.js';
 export type { VerificationEvidence, EvidenceStatement, MethodDecision, MethodDecisions, AssuranceRequired, AssuranceNotRequired, OperationAssurance, AssuranceRefusalReason, AssuranceAssessment, } from './assurance.js';

package/dist/index.js

@@ -92,6 +92,64 @@
  * this money surface gains that Piper's own contracts lack, since theirs share
  * one global version bumped across all twenty-two together (CAY-0026).
  *
+ * `0.29.0` → `0.30.0` publishes and SERVES Cayso's authorisation acknowledgement keys
+ * (CAY-0093): {@link ACKNOWLEDGEMENT_KEYS_ROUTE}, `GET /api/acknowledgement-keys`, an
+ * unauthenticated read outside `ROUTES`, described in the schema under `keyRoutes`;
+ * the key set it answers, {@link AcknowledgementKeySet} of
+ * {@link AcknowledgementPublicKey}, Ed25519 public JSON Web Keys and nothing private;
+ * and `CaysoApiErrorCode` gains `acknowledgement_signing_not_configured`, the route's
+ * closed door.
+ *
+ * The same version SERVES the standing authorisation (CAY-0094), published at `0.25.0`
+ * and answered until now by the router's `404`: `ROUTES.standingAuthorisation` answers
+ * {@link StandingAuthorisationResponse} with an acknowledgement signed under that key.
+ * It adds the owner's way to withdraw one: `ROUTES.revokeStandingAuthorisation`,
+ * `POST /api/cloud/standing-authorisation-revocations`, mapped to the new operation
+ * `'revoke-standing-authorisation'`, money-grade in `ASSURANCE_POLICY`; the client
+ * method `revokeStandingAuthorisation`; {@link StandingAuthorisationRevocationRequest},
+ * {@link StandingAuthorisationRevocationResponse} and the closed
+ * {@link StandingAuthorisationRevocationRefusal}, which `CaysoApiErrorCode` gains by
+ * reference; and the seam codes `standing_authorisation_store_not_configured`,
+ * `standing_authorisation_cap_ceiling_not_configured` and
+ * `standing_authorisation_life_ceiling_not_configured`.
+ *
+ * The same version publishes and SERVES binding a Node to a wallet (CMTY-0018 §4,
+ * CAY-0095): `ROUTES.bindNode`, `POST /api/cloud/node-bindings`, mapped to the new
+ * operation `'bind-node'`, money-grade in `ASSURANCE_POLICY`; the client method
+ * `bindNode`; {@link NodePresentationClaims}, {@link NodeBindingRequest},
+ * {@link NodeBindingResponse} and the closed {@link NodeBindingRefusal}. Beside it, the
+ * Contribution Store's read of whether a Node is bound: {@link NODE_BINDING_QUERY_ROUTE},
+ * `POST /api/cloud/node-binding-queries`, outside `ROUTES` and in the schema under
+ * `issuerRoutes`, authenticated by the registered Store issuer; {@link
+ * NodeBindingQueryClaims}, {@link NodeBindingQueryRequest}, the answer
+ * {@link NodeBindingStatus} — `nodeId` and `bound` and nothing else — and the closed
+ * {@link NodeBindingQueryRefusal}. `CaysoApiErrorCode` gains both unions by reference
+ * and the seam codes `node_binding_store_not_configured`, `core_node_ids_not_configured`
+ * and `contribution_store_issuer_not_configured`.
+ *
+ * The same version SERVES the Contribution Store's settlement assertion (CMTY-0018 §2,
+ * CAY-0096) at {@link CLOUD_SETTLEMENT_ROUTE}, published at `0.25.0` and answered until
+ * now by the router's `404`. A settled period writes one `contribution_settlement`
+ * movement per paid contribution row and one `consumption_settlement` per consumption
+ * row, so `MovementKind` and `MOVEMENT_KINDS` gain both. The closed refusal unions gain
+ * the members the write needs: {@link SettlementAssertionLevelRefusal} gains
+ * `settlement_period_not_recognised`, `settlement_period_not_ended` and
+ * `settlement_carve_contended`; {@link ContributionRowRefusal} gains
+ * `contribution_node_is_a_core_node` and `contribution_treasury_short`;
+ * {@link ConsumptionRowRefusal} gains `consumption_authorisation_not_in_force` and
+ * `consumption_wallet_short`. `CaysoApiErrorCode` gains them by reference and the seam
+ * code `cloud_settlement_store_not_configured`.
+ *
+ * BREAKING in the package's sense because closed tables grew: `ROUTES`,
+ * `ContractOperation`, `CaysoApiErrorCode`, `MovementKind` and the settlement's refusal
+ * unions. Additive on the wire (CAY-0086): no route a `0.29.0` consumer could reach
+ * changed, because the only ones that answer differently are the standing
+ * authorisation and the settlement assertion, which no deployment served before, and
+ * they answer the shapes `0.25.0` published, a member those shapes' unions gained, or a
+ * new seam code no served route emits. The operator movement list can now carry the two
+ * new kinds, and it is read only by the admin app in this tree, released with it. The
+ * two Node routes are ones a `0.29.0` consumer cannot name.
+ *
  * `0.28.0` → `0.29.0` publishes and SERVES the Handle change (CAY-0091):
  * `ROUTES.handleChange`, `POST /api/handle-changes`, mapped to the new operation
  * `'change-handle'`, money-grade in `ASSURANCE_POLICY`; `ROUTES.handleChangeReceipt`,
@@ -568,7 +626,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.29.0';
+export const CONTRACT_VERSION = '0.30.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**
@@ -592,6 +650,18 @@ export { ROUTES } from './routes.js';
  * no operation, no assurance bar and no client method.
  */
 export { CLOUD_SETTLEMENT_ROUTE } from './routes.js';
+/**
+ * Where the Contribution Store asks whether a Node is bound (CAY-0095). A value beside
+ * `ROUTES` and never in it, for the settlement path's reason: it is authenticated by
+ * the registered Store issuer, not by a person.
+ */
+export { NODE_BINDING_QUERY_ROUTE } from './routes.js';
+/**
+ * Where Cayso publishes its authorisation acknowledgement keys (CAY-0093). A value
+ * beside `ROUTES` and never in it: an unauthenticated read of a public key carries no
+ * identity, so it has no operation, no assurance bar and no client method.
+ */
+export { ACKNOWLEDGEMENT_KEYS_ROUTE } from './routes.js';
 /**
  * The purchase lifecycle's runtime half (CAY-0032): which statuses a purchase
  * never leaves, the predicate over them, and the window an authorisation holds its

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' | 'marketplace_settlement';
+export type MovementKind = 'issuance' | 'purchase' | 'grant' | 'charge' | 'payout' | 'transfer' | 'burn' | 'forfeit' | 'commercial_payment' | 'quoted_sale' | 'buy_back' | 'quoted_sale_compensation' | 'marketplace_settlement' | 'contribution_settlement' | 'consumption_settlement';
 /** Every {@link MovementKind}, in the service's order — for a filter a person picks from. */
 export declare const MOVEMENT_KINDS: readonly MovementKind[];
 /**
@@ -101,6 +101,11 @@ export declare const MOVEMENT_KINDS: readonly MovementKind[];
  * 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).
+ *
+ * A `contribution_settlement` runs from the Treasury to a Node's wallet, and a
+ * `consumption_settlement` from an Instance's wallet to the Treasury: one per row of a
+ * settled Cloud period (CAY-0096). Neither row names the Node, the authorisation or
+ * the period; the wallet ids are the handle here as everywhere.
  */
 export interface OperatorMovementRow {
     /** The row's own opaque handle: a stable list key, not an identity. */

package/dist/operator.js

@@ -46,4 +46,6 @@ export const MOVEMENT_KINDS = [
     'buy_back',
     'quoted_sale_compensation',
     'marketplace_settlement',
+    'contribution_settlement',
+    'consumption_settlement',
 ];

package/dist/routes.d.ts

@@ -119,13 +119,34 @@
  * 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.
+ * holder's own. Published at `0.25.0` and served from `0.30.0` (CAY-0094).
+ *
+ * `revokeStandingAuthorisation` withdraws one (`revoke-standing-authorisation`). It
+ * is its own path for citizenship's reason, and a `POST` for cancelling's: nothing is
+ * deleted. The authorisation's row stays, and so does its Instance key's binding to
+ * the wallet; the revocation is a row of its own beside them. The body names the
+ * authorisation's `jti` and no wallet.
+ *
+ * `bindNode` binds a Node to the wallet its presenting Instance key is already bound
+ * to (`bind-node`, CAY-0095), under the owner's assertion. A person is behind it, so
+ * it is classified by a person's assurance. The body carries the Node ID signed by the
+ * Instance key and that key's public half, and no wallet: the wallet is the one the
+ * key is bound to, which must be the verified holder's own. A `POST` to a collection
+ * of bindings, because a Node is bound once and a repeat answers the same.
  *
  * 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.
+ * signed. The Store's read of whether a Node is bound,
+ * {@link NODE_BINDING_QUERY_ROUTE}, is outside it for the same reason.
+ *
+ * ## Why Cayso's acknowledgement keys are outside this table too
+ *
+ * {@link ACKNOWLEDGEMENT_KEYS_ROUTE} publishes the public half of the key Cayso signs
+ * an authorisation acknowledgement with. It carries no identity at all, so it is not
+ * a person's operation either, and it is read by the Percayso Cloud's software rather
+ * than by a person's, so the client has no method for it.
  */
 export declare const ROUTES: {
     readonly wallet: {
@@ -200,6 +221,14 @@ export declare const ROUTES: {
         readonly method: "POST";
         readonly path: "/api/cloud/standing-authorisations";
     };
+    readonly revokeStandingAuthorisation: {
+        readonly method: "POST";
+        readonly path: "/api/cloud/standing-authorisation-revocations";
+    };
+    readonly bindNode: {
+        readonly method: "POST";
+        readonly path: "/api/cloud/node-bindings";
+    };
     readonly version: {
         readonly method: "GET";
         readonly path: "/api/version";
@@ -217,9 +246,45 @@ export declare const ROUTES: {
  * 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.
+ * Published at `0.25.0` and served from `0.30.0` (CAY-0096): a settled period is one
+ * `contribution_settlement` movement per paid contribution row and one
+ * `consumption_settlement` movement per consumption row, written whole or not at all.
  */
 export declare const CLOUD_SETTLEMENT_ROUTE: {
     readonly method: "POST";
     readonly path: "/api/cloud/settlement-assertions";
 };
+/**
+ * Where the Percayso Cloud's Contribution Store asks whether one Node is bound to a
+ * wallet (CMTY-0018 §4, CAY-0095), so it can carry an unbound Node's rows withheld
+ * (`node_not_bound`) rather than pay them to nobody.
+ *
+ * **Authenticated by the registered Store issuer, exactly as
+ * {@link CLOUD_SETTLEMENT_ROUTE} is, and never by a person.** The body is the Store's
+ * own signed query, naming the one Node it asks about, so a captured query answers
+ * for that Node and no other. A person issuer's key is never the Store's, so a query
+ * a person signed is refused. It answers `{ nodeId, bound }` and nothing else: no
+ * wallet, holder, Citizen or date crosses to the Cloud. A `POST` because the question
+ * travels signed in the body; nothing is written. Not in {@link ROUTES}, and no
+ * client method, because no person's software calls it.
+ */
+export declare const NODE_BINDING_QUERY_ROUTE: {
+    readonly method: "POST";
+    readonly path: "/api/cloud/node-binding-queries";
+};
+/**
+ * Where Cayso publishes the public half of every key it signs an authorisation
+ * acknowledgement with (CMTY-0018 §1, CMTY-0022 row 9): a JSON Web Key Set the
+ * Percayso Cloud reads to verify an acknowledgement an Instance hands it.
+ *
+ * **An unauthenticated read**, because a public key is public: it carries no
+ * identity, names no wallet and moves nothing. Not in {@link ROUTES}, whose every
+ * entry is classified by a person's assurance, and no client method, because no
+ * person's software calls it. A deployment holding no acknowledgement key answers
+ * `503 acknowledgement_signing_not_configured`, never an empty set a verifier would
+ * read as "Cayso signs nothing".
+ */
+export declare const ACKNOWLEDGEMENT_KEYS_ROUTE: {
+    readonly method: "GET";
+    readonly path: "/api/acknowledgement-keys";
+};

package/dist/routes.js

@@ -134,13 +134,34 @@
  * 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.
+ * holder's own. Published at `0.25.0` and served from `0.30.0` (CAY-0094).
+ *
+ * `revokeStandingAuthorisation` withdraws one (`revoke-standing-authorisation`). It
+ * is its own path for citizenship's reason, and a `POST` for cancelling's: nothing is
+ * deleted. The authorisation's row stays, and so does its Instance key's binding to
+ * the wallet; the revocation is a row of its own beside them. The body names the
+ * authorisation's `jti` and no wallet.
+ *
+ * `bindNode` binds a Node to the wallet its presenting Instance key is already bound
+ * to (`bind-node`, CAY-0095), under the owner's assertion. A person is behind it, so
+ * it is classified by a person's assurance. The body carries the Node ID signed by the
+ * Instance key and that key's public half, and no wallet: the wallet is the one the
+ * key is bound to, which must be the verified holder's own. A `POST` to a collection
+ * of bindings, because a Node is bound once and a repeat answers the same.
  *
  * 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.
+ * signed. The Store's read of whether a Node is bound,
+ * {@link NODE_BINDING_QUERY_ROUTE}, is outside it for the same reason.
+ *
+ * ## Why Cayso's acknowledgement keys are outside this table too
+ *
+ * {@link ACKNOWLEDGEMENT_KEYS_ROUTE} publishes the public half of the key Cayso signs
+ * an authorisation acknowledgement with. It carries no identity at all, so it is not
+ * a person's operation either, and it is read by the Percayso Cloud's software rather
+ * than by a person's, so the client has no method for it.
  */
 export const ROUTES = {
     wallet: { method: 'GET', path: '/api/wallet' },
@@ -161,6 +182,11 @@ export const ROUTES = {
     requestBuyBack: { method: 'POST', path: '/api/buy-backs' },
     marketplaceOrder: { method: 'POST', path: '/api/marketplace/orders' },
     standingAuthorisation: { method: 'POST', path: '/api/cloud/standing-authorisations' },
+    revokeStandingAuthorisation: {
+        method: 'POST',
+        path: '/api/cloud/standing-authorisation-revocations',
+    },
+    bindNode: { method: 'POST', path: '/api/cloud/node-bindings' },
     version: { method: 'GET', path: '/api/version' },
 };
 /**
@@ -175,9 +201,45 @@ export const ROUTES = {
  * 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.
+ * Published at `0.25.0` and served from `0.30.0` (CAY-0096): a settled period is one
+ * `contribution_settlement` movement per paid contribution row and one
+ * `consumption_settlement` movement per consumption row, written whole or not at all.
  */
 export const CLOUD_SETTLEMENT_ROUTE = {
     method: 'POST',
     path: '/api/cloud/settlement-assertions',
 };
+/**
+ * Where the Percayso Cloud's Contribution Store asks whether one Node is bound to a
+ * wallet (CMTY-0018 §4, CAY-0095), so it can carry an unbound Node's rows withheld
+ * (`node_not_bound`) rather than pay them to nobody.
+ *
+ * **Authenticated by the registered Store issuer, exactly as
+ * {@link CLOUD_SETTLEMENT_ROUTE} is, and never by a person.** The body is the Store's
+ * own signed query, naming the one Node it asks about, so a captured query answers
+ * for that Node and no other. A person issuer's key is never the Store's, so a query
+ * a person signed is refused. It answers `{ nodeId, bound }` and nothing else: no
+ * wallet, holder, Citizen or date crosses to the Cloud. A `POST` because the question
+ * travels signed in the body; nothing is written. Not in {@link ROUTES}, and no
+ * client method, because no person's software calls it.
+ */
+export const NODE_BINDING_QUERY_ROUTE = {
+    method: 'POST',
+    path: '/api/cloud/node-binding-queries',
+};
+/**
+ * Where Cayso publishes the public half of every key it signs an authorisation
+ * acknowledgement with (CMTY-0018 §1, CMTY-0022 row 9): a JSON Web Key Set the
+ * Percayso Cloud reads to verify an acknowledgement an Instance hands it.
+ *
+ * **An unauthenticated read**, because a public key is public: it carries no
+ * identity, names no wallet and moves nothing. Not in {@link ROUTES}, whose every
+ * entry is classified by a person's assurance, and no client method, because no
+ * person's software calls it. A deployment holding no acknowledgement key answers
+ * `503 acknowledgement_signing_not_configured`, never an empty set a verifier would
+ * read as "Cayso signs nothing".
+ */
+export const ACKNOWLEDGEMENT_KEYS_ROUTE = {
+    method: 'GET',
+    path: '/api/acknowledgement-keys',
+};

package/dist/schema-types.d.ts

@@ -23,7 +23,8 @@
  * consumer's business, Piper's or the Percayso Cloud's, and a schema that
  * enumerated the operator surface would have published it (CAY-0026, Amendment 3;
  * CLAUDE.md). The Contribution Store's settlement path is published, but under
- * `issuerRoutes`, apart from the routes a person calls. The generator only ever sees this package, so the
+ * `issuerRoutes`, apart from the routes a person calls, and Cayso's acknowledgement keys
+ * under `keyRoutes`. The generator only ever sees this package, so the
  * internal surface is absent by construction.
  *
  * The one part of the operator surface that IS published — the three reads on the
@@ -129,10 +130,19 @@ export interface ContractSchema {
     /**
      * The routes authenticated by a registered issuer (CAY-0030) rather than by a
      * person, and therefore not in `ROUTES`: today the Contribution Store's
-     * settlement path (`CLOUD_SETTLEMENT_ROUTE`, CMTY-0018 §2). Kept apart from
+     * settlement path (`CLOUD_SETTLEMENT_ROUTE`, CMTY-0018 §2) and its read of whether a
+     * Node is bound (`NODE_BINDING_QUERY_ROUTE`, CAY-0095). Kept apart from
      * {@link routes} so that no consumer reads one as the other.
      */
     readonly issuerRoutes: Readonly<Record<string, SchemaRoute>>;
+    /**
+     * The unauthenticated reads that publish the public half of a key Cayso signs
+     * with, and therefore not in `ROUTES` either: today the authorisation
+     * acknowledgement keys (`ACKNOWLEDGEMENT_KEYS_ROUTE`, CAY-0093). No credential
+     * travels with them, so they are apart from both {@link routes} and
+     * {@link issuerRoutes}.
+     */
+    readonly keyRoutes: Readonly<Record<string, SchemaRoute>>;
     readonly types: Readonly<Record<string, SchemaType>>;
     /**
      * The operator reads an operator app's server calls, and their types — under

package/dist/schema.d.ts

@@ -10,15 +10,27 @@
  * none of this, and importing it does nothing but hand back a frozen data value
  * and its types (CLAUDE.md: packages have no side effects on import).
  *
- * ## This is a diagnostic, NOT a replacement for depending on the package
+ * ## A published, versioned surface — and the one a Go consumer depends on
  *
- * The schema exists so a running deployment can *report* the surface it was built
- * against — for the version endpoint, for the contract test, for an operator
- * eyeballing a mismatch. It is emphatically not a runtime type system: a consumer
- * gets its compile-time guarantees by depending on `@percayso-community/cayso-contracts` and its
- * types, which do not exist at runtime to be fetched. Fetching this schema to
- * drive validation instead of depending on the package would re-implement, badly,
- * the guarantee the package already gives for free (CAY-0026, and the README).
+ * Two consumers read this descriptor, in two ways, and both are depending on the
+ * package (CAY-0026 Amendment 3; CMTY-0018 §3 as amended):
+ *
+ *   - **A TypeScript consumer imports the types** and the compiler holds the
+ *     surface; for it this descriptor is a tool *about* the contract — the version
+ *     endpoint, the CI contract test, an operator eyeballing a mismatch — and never
+ *     a runtime type system standing in for the import.
+ *   - **A consumer in another language generates from this entry point of the
+ *     published tarball at a pinned version**, and fails its own build when its
+ *     generated types drift from the schema. The Percayso Cloud is that consumer: it
+ *     is written in Go, cannot import a TypeScript type, and generates its types for
+ *     the two seams in `cloud-settlement` from the tarball it pins. The pin is its
+ *     lockfile entry and the regeneration is its compile. The schema ships as a JS
+ *     module only, which is why the generator reads the tarball.
+ *
+ * What is refused is reading the schema OFF THE WIRE (`GET /api/version/schema`)
+ * as a substitute for pinning the package: that couples a consumer's build to a
+ * deployment's uptime and replaces a pinned version with whatever is deployed. The
+ * endpoint reports a running deployment; the package is the contract (the README).
  */
 export type { ContractSchema, ScalarKind, SchemaProperty, SchemaOperatorRoute, SchemaOperatorSurface, SchemaRoute, SchemaType, SchemaTypeNode, } from './schema-types.js';
 export { CONTRACT_SCHEMA } from './contract-schema.generated.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percayso-community/cayso-contracts",
-  "version": "0.29.0",
+  "version": "0.30.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": {