@percayso-community/cayso-contracts 0.29.0 → 1.0.0

package/dist/operator.d.ts

@@ -1,11 +1,14 @@
 /**
  * `@percayso-community/cayso-contracts/operator` — the operator READ surface, on its
- * own entry point: three reads and nothing else (CAY-0026, Amendment 4).
+ * own entry point: four reads and nothing else (CAY-0026, Amendments 4 and 5).
  *
  *   - `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`.
+ *   - `GET /api/operator/summary` — the economy summary, under
+ *     `read-economy-summary-as-operator` (Amendment 5): whole-number counts and cent
+ *     totals, and never a row.
  *
  * ## Who calls this, and from where
  *
@@ -25,7 +28,7 @@
  *
  * ## What it carries, and what it deliberately does not
  *
- *   - **The three reads only.** The operator surface is larger than this — the wallet
+ *   - **The four 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.
@@ -44,7 +47,7 @@
  * ## 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
+ * four 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.
  */
@@ -55,14 +58,14 @@ import type { Cents } from './wallet.js';
  * 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';
+export type OperatorReadScope = 'list-movements-as-operator' | 'list-purchases-as-operator' | 'read-quickening-ladder-as-operator' | 'read-economy-summary-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. */
+/** The four reads, by name. The paths and scopes are the service's own. */
 export declare const OPERATOR_READ_ROUTES: {
     readonly movements: {
         readonly method: "GET";
@@ -79,13 +82,18 @@ export declare const OPERATOR_READ_ROUTES: {
         readonly path: "/api/operator/quickenings";
         readonly scope: "read-quickening-ladder-as-operator";
     };
+    readonly summary: {
+        readonly method: "GET";
+        readonly path: "/api/operator/summary";
+        readonly scope: "read-economy-summary-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' | '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 +109,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. */
@@ -231,6 +244,120 @@ export interface QuickeningLadder {
     readonly live: LiveQuickeningBand | null;
     readonly activeCitizens: number;
 }
+/**
+ * How many wallets exist, by holder kind, and how many were created recently.
+ *
+ * `citizenWallets + organisationWallets` is `total`: the two holder kinds are the only
+ * two (CONTEXT.md, *Wallet*). `founderWallets` counts the Founder wallets among the
+ * Citizen Wallets, claimed or not, so it is a part of `citizenWallets` and not a third
+ * kind. The two windows end at `asOf` and include it: `createdInLast7Days` counts
+ * wallets created in `(asOf − 7 days, asOf]`.
+ */
+export interface OperatorWalletCounts {
+    readonly total: number;
+    readonly citizenWallets: number;
+    readonly organisationWallets: number;
+    readonly founderWallets: number;
+    readonly createdInLast7Days: number;
+    readonly createdInLast30Days: number;
+}
+/**
+ * The cents this economy has minted, cancelled and holds, and where the held cents sit.
+ *
+ * Conservation is the identity `heldCents = totalMintedCents − cancelledCents`
+ * (migration `0005`); both sides are reported as read, and a disagreement is reported,
+ * never repaired (CAY-0028). `heldCents` is the system-wide sum of holdings — the cents
+ * in circulation — and is never a stored total: a balance is derived (CAY-0019).
+ *
+ *   - `restrictedCents + unrestrictedCents` is `heldCents`.
+ *   - `inCitizenWalletsCents + inOrganisationWalletsCents` is `heldCents`.
+ *   - `inFounderWalletsCents` is a part of `inCitizenWalletsCents`, and
+ *     `inTreasuryCents` a part of `inOrganisationWalletsCents`: the Treasury is an
+ *     Organisation Wallet. `inTreasuryCents` is null when this deployment has no
+ *     Treasury configured, which is not the same as a Treasury holding nothing.
+ *
+ * Every figure is an integer number of cents (₡1 = 100 cents) and never sterling: the
+ * sterling value of a cent is the published value's, and it is not carried here.
+ */
+export interface OperatorSupplySummary {
+    readonly totalMintedCents: Cents;
+    readonly cancelledCents: Cents;
+    readonly heldCents: Cents;
+    readonly restrictedCents: Cents;
+    readonly unrestrictedCents: Cents;
+    readonly inCitizenWalletsCents: Cents;
+    readonly inOrganisationWalletsCents: Cents;
+    readonly inFounderWalletsCents: Cents;
+    readonly inTreasuryCents: Cents | null;
+}
+/**
+ * How many movements there are of each {@link MovementKind}. Every kind is present, at
+ * zero when none has happened: a missing key would read as "not counted", which is a
+ * different statement from "none". `operator.test.ts` pins the keys to the union.
+ */
+export interface OperatorMovementCountsByKind {
+    readonly issuance: number;
+    readonly purchase: number;
+    readonly grant: number;
+    readonly charge: number;
+    readonly payout: number;
+    readonly transfer: number;
+    readonly burn: number;
+    readonly forfeit: number;
+    readonly commercial_payment: number;
+    readonly quoted_sale: number;
+    readonly buy_back: number;
+    readonly quoted_sale_compensation: number;
+    readonly marketplace_settlement: number;
+    readonly contribution_settlement: number;
+    readonly consumption_settlement: number;
+}
+/**
+ * How many movements there are, how many happened recently, and of which kind. A
+ * movement is final and append-only (CAY-0023), so there is no status to count by.
+ * The windows are the wallet counts' windows, on `occurredAt`.
+ */
+export interface OperatorMovementCounts {
+    readonly total: number;
+    readonly inLast7Days: number;
+    readonly inLast30Days: number;
+    readonly byKind: OperatorMovementCountsByKind;
+}
+/**
+ * How many purchases are in each {@link PurchaseStatus}, every status present, at zero
+ * when none is in it. `operator.test.ts` pins the keys to the union.
+ */
+export interface OperatorPurchaseCountsByStatus {
+    readonly pending: number;
+    readonly issued_uncaptured: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly cancelled: number;
+}
+/** How many purchases there are, and in which status. */
+export interface OperatorPurchaseCounts {
+    readonly total: number;
+    readonly byStatus: OperatorPurchaseCountsByStatus;
+}
+/**
+ * The economy summary: aggregate counts and cent totals over the whole deployment,
+ * read in one snapshot at `asOf` (CAY-0026, Amendment 5).
+ *
+ * **Aggregates only.** No wallet id, no Percayso identity, no Handle, no name and no
+ * row of any kind appears here, and nothing in it can be narrowed to one wallet: the
+ * read takes no query. A per-wallet question is the wallet detail's, audited against
+ * that wallet (CAY-0027).
+ *
+ * `asOf` is the instant the read was made, as an ISO-8601 UTC instant, and the instant
+ * every "last N days" window ends at.
+ */
+export interface OperatorEconomySummary {
+    readonly asOf: string;
+    readonly wallets: OperatorWalletCounts;
+    readonly supply: OperatorSupplySummary;
+    readonly movements: OperatorMovementCounts;
+    readonly purchases: OperatorPurchaseCounts;
+}
 /**
  * `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
@@ -280,12 +407,16 @@ export type OperatorPurchasesUnavailable = 'operator_purchases_reader_not_config
  * 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';
+/** `503` — this deployment has no economy summary reader wired. */
+export type OperatorEconomySummaryUnavailable = 'operator_summary_reader_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;
+/** Every `{ error }` code the economy summary answers. It takes no query, so nothing is a `400`. */
+export type OperatorEconomySummaryErrorCode = OperatorAuthenticationRefusal | OperatorAccessRefusal | OperatorRateLimited | OperatorReadUnavailable | OperatorEconomySummaryUnavailable | OperatorReadFailed;
 export interface OperatorMovementsError {
     readonly error: OperatorMovementsErrorCode;
 }
@@ -295,9 +426,14 @@ export interface OperatorPurchasesError {
 export interface QuickeningLadderError {
     readonly error: QuickeningLadderErrorCode;
 }
+export interface OperatorEconomySummaryError {
+    readonly error: OperatorEconomySummaryErrorCode;
+}
 /** 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;
+/** Everything `GET /api/operator/summary` answers: `200`, or one refusal body. */
+export type OperatorEconomySummaryResponse = OperatorEconomySummary | OperatorVerificationRefused | OperatorEconomySummaryError;

package/dist/operator.js

@@ -13,7 +13,7 @@
  * 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. */
+/** The four reads, by name. The paths and scopes are the service's own. */
 export const OPERATOR_READ_ROUTES = {
     movements: {
         method: 'GET',
@@ -30,6 +30,11 @@ export const OPERATOR_READ_ROUTES = {
         path: '/api/operator/quickenings',
         scope: 'read-quickening-ladder-as-operator',
     },
+    summary: {
+        method: 'GET',
+        path: '/api/operator/summary',
+        scope: 'read-economy-summary-as-operator',
+    },
 };
 /** Every {@link MovementKind}, in the service's order — for a filter a person picks from. */
 export const MOVEMENT_KINDS = [
@@ -46,4 +51,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,11 +23,12 @@
  * 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
- * `./operator` entry point (CAY-0026, Amendment 4) — is described under its own
+ * The one part of the operator surface that IS published — the four reads on the
+ * `./operator` entry point (CAY-0026, Amendments 4 and 5) — is described under its own
  * key, {@link ContractSchema.operator}, with its routes and its types apart from
  * `routes` and `types`. A consumer reading the person-facing surface therefore
  * never meets an operator route or an operator type by accident, and the rest of
@@ -105,7 +106,7 @@ export interface SchemaOperatorRoute {
     readonly scope: string;
 }
 /**
- * The published operator read surface (CAY-0026, Amendment 4): the three reads on
+ * The published operator read surface (CAY-0026, Amendments 4 and 5): the four reads on
  * `@percayso-community/cayso-contracts/operator` and the types declared there. A type
  * here may refer to one in {@link ContractSchema.types} — a row's `cents` is `Cents`
  * — but never the other way round: nothing on the person-facing surface depends on
@@ -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": "1.0.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": {