@percayso-community/cayso-contracts 0.23.0

package/dist/routes.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The path and method for each operation on this contract surface, in one place
+ * so that no consumer hand-writes a URL.
+ *
+ * A URL spelled out at each call site drifts: one consumer writes `/wallet`,
+ * another `/api/wallet`, and the two disagree the day the server moves. Naming
+ * every route once, as an `as const` table the consumer reads, is how the method
+ * and path travel with the types they belong to — a change here is a change every
+ * consumer sees at compile time.
+ *
+ * This is a table, not a router. It carries no handler, no schema and no
+ * validator — those live in `apps/api`, which is the only module that serves
+ * these paths and the only one that may open a database connection (CLAUDE.md).
+ * The route for a purchase's result is keyed by `:purchaseId` because a purchase
+ * has a lifecycle a caller polls; a wallet read has none, so it takes no
+ * parameter.
+ *
+ * ## Why citizenship is TWO PATHS rather than one path with two methods
+ *
+ * `citizenship` reads whether the calling citizen has been provisioned;
+ * `citizenshipProvision` provisions them. `GET /api/citizenship` and
+ * `POST /api/citizenship` would have been the tidier pair of URLs and would have
+ * been wrong: the scope a credential must carry is registered PER PATH at
+ * CAY-0030's gate, so two operations sharing one path share one scope
+ * requirement — and the read would inherit the write's, or the write the read's.
+ * Neither is acceptable, and neither would be visible in this table. Distinct
+ * paths keep one path meaning one operation, which is the property the gate is
+ * entitled to assume (CAY-0031).
+ *
+ * ## Why cancelling is its OWN path, and a POST rather than a DELETE
+ *
+ * `purchaseCancel` sits under the purchase it cancels and adds a segment of its
+ * own rather than reusing `purchaseResult`'s path with a second method, for
+ * exactly the reason citizenship is two paths: one path carries one scope
+ * requirement at CAY-0030's gate, and a read that shared a path with a
+ * value-affecting write would share its scope (CAY-0032).
+ *
+ * It is a `POST` and not a `DELETE` because nothing is deleted. Cancelling moves a
+ * purchase to a terminal status and releases its reservation; the purchase row
+ * remains, readable at `purchaseResult` forever after. A `DELETE` would describe
+ * the removal of a resource, and a money record that can be removed is a money
+ * record nobody can audit.
+ *
+ * ## Why `organisationProvision` takes no parameter, and never will
+ *
+ * `POST /api/organisation/provision` carries NOTHING that names the organisation.
+ * No path parameter, no query, no body field. The Organisation ID comes from the
+ * organisation-authority claim on the verified assertion and from nowhere else
+ * (CAY-0059 §4), and a parameter here is precisely the wallet-creation oracle that
+ * decision removes rather than guards: an identifier a caller supplies is a
+ * request, never evidence (CAY-0057). A later edit adding `:organisationId` to
+ * this path would reintroduce the oracle in one line, so the absence is recorded
+ * where the path is written.
+ *
+ * ## Why `citizenshipFounderClaim` takes no parameter, and never will
+ *
+ * `POST /api/citizenship/founder-claim` carries NOTHING that names a Citizen, a
+ * wallet or an amount. The Citizen is the verified assertion's subject. The founder
+ * wallet is named by the founder claim reference, and that reference travels INSIDE
+ * the signed assertion, never in the path, a query or a body (CAY-0081 §2): a
+ * reference a caller supplies beside the credential would be the caller's claim about
+ * which allocation is theirs (CAY-0021). The amount is the allocation already in the
+ * wallet, and nothing about the claim moves it. It is its own path beside
+ * `citizenshipProvision`, for citizenship's reason above: scope is registered per
+ * path, and a credential minted to claim must not provision, nor the reverse.
+ *
+ * ## Why `commercialPayment` names both wallets in the BODY, and nobody in the path
+ *
+ * `POST /api/commercial-payments` is an Organisation paying a Citizen (CAY-0079). The
+ * paying wallet and the payee's wallet travel in the body as wallet ids, beside the
+ * cents, the idempotency key and the authority the caller invokes. Neither is a
+ * path parameter, because neither is a resource the caller owns and polls: a
+ * commercial payment has no lifecycle, so there is nothing under the path to read
+ * back. Nothing in the request names a Percayso identity. The acting party is the
+ * verified assertion's subject, resolved to their own wallet and never echoed
+ * (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 the citizen market is FOUR PATHS, and none of them names a wallet
+ *
+ * `citizenMarket` reads the book, `placeQuote` places a quote, and `withdrawQuote`
+ * withdraws one (CAY-0080). They are three paths for citizenship's reason: one path
+ * carries one scope at CAY-0030's gate, and a read must not share the scope of a
+ * write that reserves cents, nor a withdrawal the scope of a placement.
+ *
+ * None takes a wallet or a holder. The holder is the verified subject, resolved
+ * inside `apps/api` from the holders mapping, and a parameter naming a wallet would
+ * be a claim about who the caller is (CAY-0021). The withdrawal names its quote in
+ * the body, as a purchase's cancellation cannot, because a quote is not a resource
+ * this surface lets a caller poll by id: its progress is on the book's read, among
+ * the caller's own quotes. It is a `POST` because nothing is deleted: a withdrawn
+ * quote leaves the book once, and its row stays.
+ *
+ * `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.
+ */
+export declare const ROUTES: {
+    readonly wallet: {
+        readonly method: "GET";
+        readonly path: "/api/wallet";
+    };
+    readonly citizenship: {
+        readonly method: "GET";
+        readonly path: "/api/citizenship";
+    };
+    readonly citizenshipProvision: {
+        readonly method: "POST";
+        readonly path: "/api/citizenship/provision";
+    };
+    readonly citizenshipFounderClaim: {
+        readonly method: "POST";
+        readonly path: "/api/citizenship/founder-claim";
+    };
+    readonly organisationProvision: {
+        readonly method: "POST";
+        readonly path: "/api/organisation/provision";
+    };
+    readonly purchaseAuthorise: {
+        readonly method: "POST";
+        readonly path: "/api/purchases";
+    };
+    readonly purchaseResult: {
+        readonly method: "GET";
+        readonly path: "/api/purchases/:purchaseId";
+    };
+    readonly purchaseCancel: {
+        readonly method: "POST";
+        readonly path: "/api/purchases/:purchaseId/cancel";
+    };
+    readonly commercialPayment: {
+        readonly method: "POST";
+        readonly path: "/api/commercial-payments";
+    };
+    readonly citizenMarket: {
+        readonly method: "GET";
+        readonly path: "/api/citizen-market";
+    };
+    readonly placeQuote: {
+        readonly method: "POST";
+        readonly path: "/api/quotes";
+    };
+    readonly withdrawQuote: {
+        readonly method: "POST";
+        readonly path: "/api/quote-withdrawals";
+    };
+    readonly requestBuyBack: {
+        readonly method: "POST";
+        readonly path: "/api/buy-backs";
+    };
+    readonly version: {
+        readonly method: "GET";
+        readonly path: "/api/version";
+    };
+};

package/dist/routes.js

@@ -0,0 +1,128 @@
+/*
+ * 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 path and method for each operation on this contract surface, in one place
+ * so that no consumer hand-writes a URL.
+ *
+ * A URL spelled out at each call site drifts: one consumer writes `/wallet`,
+ * another `/api/wallet`, and the two disagree the day the server moves. Naming
+ * every route once, as an `as const` table the consumer reads, is how the method
+ * and path travel with the types they belong to — a change here is a change every
+ * consumer sees at compile time.
+ *
+ * This is a table, not a router. It carries no handler, no schema and no
+ * validator — those live in `apps/api`, which is the only module that serves
+ * these paths and the only one that may open a database connection (CLAUDE.md).
+ * The route for a purchase's result is keyed by `:purchaseId` because a purchase
+ * has a lifecycle a caller polls; a wallet read has none, so it takes no
+ * parameter.
+ *
+ * ## Why citizenship is TWO PATHS rather than one path with two methods
+ *
+ * `citizenship` reads whether the calling citizen has been provisioned;
+ * `citizenshipProvision` provisions them. `GET /api/citizenship` and
+ * `POST /api/citizenship` would have been the tidier pair of URLs and would have
+ * been wrong: the scope a credential must carry is registered PER PATH at
+ * CAY-0030's gate, so two operations sharing one path share one scope
+ * requirement — and the read would inherit the write's, or the write the read's.
+ * Neither is acceptable, and neither would be visible in this table. Distinct
+ * paths keep one path meaning one operation, which is the property the gate is
+ * entitled to assume (CAY-0031).
+ *
+ * ## Why cancelling is its OWN path, and a POST rather than a DELETE
+ *
+ * `purchaseCancel` sits under the purchase it cancels and adds a segment of its
+ * own rather than reusing `purchaseResult`'s path with a second method, for
+ * exactly the reason citizenship is two paths: one path carries one scope
+ * requirement at CAY-0030's gate, and a read that shared a path with a
+ * value-affecting write would share its scope (CAY-0032).
+ *
+ * It is a `POST` and not a `DELETE` because nothing is deleted. Cancelling moves a
+ * purchase to a terminal status and releases its reservation; the purchase row
+ * remains, readable at `purchaseResult` forever after. A `DELETE` would describe
+ * the removal of a resource, and a money record that can be removed is a money
+ * record nobody can audit.
+ *
+ * ## Why `organisationProvision` takes no parameter, and never will
+ *
+ * `POST /api/organisation/provision` carries NOTHING that names the organisation.
+ * No path parameter, no query, no body field. The Organisation ID comes from the
+ * organisation-authority claim on the verified assertion and from nowhere else
+ * (CAY-0059 §4), and a parameter here is precisely the wallet-creation oracle that
+ * decision removes rather than guards: an identifier a caller supplies is a
+ * request, never evidence (CAY-0057). A later edit adding `:organisationId` to
+ * this path would reintroduce the oracle in one line, so the absence is recorded
+ * where the path is written.
+ *
+ * ## Why `citizenshipFounderClaim` takes no parameter, and never will
+ *
+ * `POST /api/citizenship/founder-claim` carries NOTHING that names a Citizen, a
+ * wallet or an amount. The Citizen is the verified assertion's subject. The founder
+ * wallet is named by the founder claim reference, and that reference travels INSIDE
+ * the signed assertion, never in the path, a query or a body (CAY-0081 §2): a
+ * reference a caller supplies beside the credential would be the caller's claim about
+ * which allocation is theirs (CAY-0021). The amount is the allocation already in the
+ * wallet, and nothing about the claim moves it. It is its own path beside
+ * `citizenshipProvision`, for citizenship's reason above: scope is registered per
+ * path, and a credential minted to claim must not provision, nor the reverse.
+ *
+ * ## Why `commercialPayment` names both wallets in the BODY, and nobody in the path
+ *
+ * `POST /api/commercial-payments` is an Organisation paying a Citizen (CAY-0079). The
+ * paying wallet and the payee's wallet travel in the body as wallet ids, beside the
+ * cents, the idempotency key and the authority the caller invokes. Neither is a
+ * path parameter, because neither is a resource the caller owns and polls: a
+ * commercial payment has no lifecycle, so there is nothing under the path to read
+ * back. Nothing in the request names a Percayso identity. The acting party is the
+ * verified assertion's subject, resolved to their own wallet and never echoed
+ * (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 the citizen market is FOUR PATHS, and none of them names a wallet
+ *
+ * `citizenMarket` reads the book, `placeQuote` places a quote, and `withdrawQuote`
+ * withdraws one (CAY-0080). They are three paths for citizenship's reason: one path
+ * carries one scope at CAY-0030's gate, and a read must not share the scope of a
+ * write that reserves cents, nor a withdrawal the scope of a placement.
+ *
+ * None takes a wallet or a holder. The holder is the verified subject, resolved
+ * inside `apps/api` from the holders mapping, and a parameter naming a wallet would
+ * be a claim about who the caller is (CAY-0021). The withdrawal names its quote in
+ * the body, as a purchase's cancellation cannot, because a quote is not a resource
+ * this surface lets a caller poll by id: its progress is on the book's read, among
+ * the caller's own quotes. It is a `POST` because nothing is deleted: a withdrawn
+ * quote leaves the book once, and its row stays.
+ *
+ * `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.
+ */
+export const ROUTES = {
+    wallet: { method: 'GET', path: '/api/wallet' },
+    citizenship: { method: 'GET', path: '/api/citizenship' },
+    citizenshipProvision: { method: 'POST', path: '/api/citizenship/provision' },
+    citizenshipFounderClaim: { method: 'POST', path: '/api/citizenship/founder-claim' },
+    organisationProvision: { method: 'POST', path: '/api/organisation/provision' },
+    purchaseAuthorise: { method: 'POST', path: '/api/purchases' },
+    purchaseResult: { method: 'GET', path: '/api/purchases/:purchaseId' },
+    purchaseCancel: { method: 'POST', path: '/api/purchases/:purchaseId/cancel' },
+    commercialPayment: { method: 'POST', path: '/api/commercial-payments' },
+    citizenMarket: { method: 'GET', path: '/api/citizen-market' },
+    placeQuote: { method: 'POST', path: '/api/quotes' },
+    withdrawQuote: { method: 'POST', path: '/api/quote-withdrawals' },
+    requestBuyBack: { method: 'POST', path: '/api/buy-backs' },
+    version: { method: 'GET', path: '/api/version' },
+};

package/dist/schema-types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The shape of the machine-readable contract schema `GET /api/version/schema`
+ * serves — a structural description of the Piper-facing surface, one that a
+ * consumer (or the CI contract test) can read at runtime.
+ *
+ * ## Why this file is types-only and hand-written, while the schema VALUE is not
+ *
+ * This file declares what a schema descriptor *is*. The descriptor VALUE —
+ * `CONTRACT_SCHEMA` in `contract-schema.generated.ts` — is generated from the
+ * published types by `scripts/generate-contract-schema.ts`, never hand-written: a
+ * hand-maintained schema is a third artefact that silently goes stale (the issue's
+ * first Must-hold), and the whole point of the version endpoint is to catch a type
+ * that changed without the schema following. The generator reads the same source
+ * as `@percayso-community/cayso-contracts`, so the two cannot disagree, and a CI test regenerates and
+ * compares — a type changed without regeneration turns that test red.
+ *
+ * ## Why it describes the Piper-facing surface ONLY
+ *
+ * The descriptor covers the exported wire types, the route table, the capability
+ * names and the contract version — the surface a consumer of `@percayso-community/cayso-contracts`
+ * reads. It does NOT describe the internal routes (`INTERNAL_ROUTES` in
+ * `apps/api`: the operator, webhook and peer endpoints): those are not Piper's
+ * business, and a schema that enumerated the operator surface would have published
+ * it (CAY-0026, CLAUDE.md). The generator only ever sees this package, so the
+ * internal surface is absent by construction.
+ *
+ * ## What it deliberately omits
+ *
+ * `CaysoWallet` — the client capability interface carrying a `getMyWallet()`
+ * METHOD — is not a wire shape: a schema describes the data crossing the boundary,
+ * not a method a client happens to expose. The generator excludes it by name and
+ * refuses (throws) on any other method-bearing or otherwise unrecognised
+ * construct, so a new one cannot slip into the surface undescribed.
+ *
+ * This file carries no numbers: a contract version is a version string, not an
+ * economic amount, and no rate, tier, schedule or threshold appears here.
+ */
+/** A primitive leaf of the type language the descriptor speaks. */
+export type ScalarKind = 'string' | 'number' | 'boolean';
+/**
+ * One node in the structural description of a type. A closed union: a consumer
+ * switches on the present key rather than pattern-matching on prose, the same
+ * discipline the failure-reason union follows.
+ *
+ *   - `{ scalar }`   — a primitive: `string`, `number` or `boolean`.
+ *   - `{ literal }`  — a string-literal type, e.g. the `'cayso'` audience or a
+ *                      failure-reason member.
+ *   - `{ null: true }` — the `null` type, as it appears in `T | null`.
+ *   - `{ ref }`      — a reference to another named type in {@link ContractSchema.types}.
+ *   - `{ array, readonly }` — an array whose element is `array`; `readonly`
+ *                      records whether the source wrote `readonly T[]`.
+ *   - `{ union }`    — a union of the member nodes, in source order.
+ */
+export type SchemaTypeNode = {
+    readonly scalar: ScalarKind;
+} | {
+    readonly literal: string;
+} | {
+    readonly null: true;
+} | {
+    readonly ref: string;
+} | {
+    readonly array: SchemaTypeNode;
+    readonly readonly: boolean;
+} | {
+    readonly union: readonly SchemaTypeNode[];
+};
+/** One property of an object type: its type, and whether it is `readonly`/optional. */
+export interface SchemaProperty {
+    readonly type: SchemaTypeNode;
+    readonly readonly: boolean;
+    readonly optional: boolean;
+}
+/**
+ * A named type on the surface: either a type alias (`type Cents = number`) or an
+ * object type (an interface). `kind` discriminates the two.
+ */
+export type SchemaType = {
+    readonly kind: 'alias';
+    readonly of: SchemaTypeNode;
+} | {
+    readonly kind: 'object';
+    readonly properties: Readonly<Record<string, SchemaProperty>>;
+};
+/** A route on the contract surface, as the descriptor reports it. */
+export interface SchemaRoute {
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * The whole served schema: the contract version it describes, the package name,
+ * the capability names, the route table and every named wire type. Generated from
+ * `@percayso-community/cayso-contracts`' own source; served verbatim at `GET /api/version/schema`.
+ */
+export interface ContractSchema {
+    readonly contractVersion: string;
+    readonly packageName: string;
+    readonly capabilities: Readonly<Record<string, string>>;
+    readonly routes: Readonly<Record<string, SchemaRoute>>;
+    readonly types: Readonly<Record<string, SchemaType>>;
+}

package/dist/schema-types.js

@@ -0,0 +1,16 @@
+/*
+ * 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.
+ */
+export {};

package/dist/schema.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@percayso-community/cayso-contracts/schema` — the machine-readable contract schema, on its own
+ * subpath.
+ *
+ * This is the single value `GET /api/version/schema` serves and the CI contract
+ * test compares against: `CONTRACT_SCHEMA`, generated from the published types
+ * (never hand-written), plus the descriptor types that give it shape. It ships
+ * from a *separate* entry point — the way the client does — so a consumer wanting
+ * only the types (`@percayso-community/cayso-contracts`) or only the client (`./client`) pulls in
+ * 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
+ *
+ * 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).
+ */
+export type { ContractSchema, ScalarKind, SchemaProperty, SchemaRoute, SchemaType, SchemaTypeNode, } from './schema-types.js';
+export { CONTRACT_SCHEMA } from './contract-schema.generated.js';

package/dist/schema.js

@@ -0,0 +1,16 @@
+/*
+ * 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.
+ */
+export { CONTRACT_SCHEMA } from './contract-schema.generated.js';

package/dist/wallet.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `cayso.wallet` — the read side of a wallet: the record, the balance, the
+ * allowances a holder carries, and the response that binds them.
+ *
+ * This is the pillar's first real contract. `wallet` is the noun and `cayso.*`
+ * is the namespace (CAY-0017); a `balance` is the derived sum of a wallet's own
+ * holdings and is never a stored figure (CAY-0019). A consumer of this contract
+ * reads a wallet — it never sees a holding, a carve or a movement, and there is
+ * no mutation here: crediting, debiting or transferring a wallet is not a read,
+ * and nothing on `CaysoWallet` can express one.
+ *
+ * ## Why balance and allowances are two answers, never one sum
+ *
+ * What a citizen *has* and what a citizen *may spend* are different questions,
+ * and this shape keeps them apart on purpose (CAY-0024).
+ *
+ *   - `Balance` is the sum of the wallet's **own** holdings. It is the holder's
+ *     service credit and nothing else.
+ *   - An `Allowance` is a revocable authority to spend from an **organisation's**
+ *     wallet. The cents stay the organisation's until they are spent; an
+ *     allowance is not the holder's money and never becomes it.
+ *
+ * So `balance` and `allowances` are **never summed** — not here, not in any
+ * consumer. The reason is regulatory, not cosmetic: were an employer's allowance
+ * folded into the balance, then in every screen, statement and export it would
+ * read as the citizen's own service credit. That is remuneration in kind — an
+ * employer handing over something cashable — which is precisely the shape
+ * CAY-0024 exists to keep out of the model. Two fields that never add up is how
+ * the contract refuses to tell that lie.
+ *
+ * ## What this file must not decide
+ *
+ *   - **No formatted money.** Every amount is an integer count of cents, paired
+ *     with `publishedValuePence`; the consumer renders "₡500" or "£5.00". A
+ *     server that returned `"₡500.00"` would have fixed the locale, the symbol
+ *     and the rounding for every consumer forever.
+ *   - **No numbers.** Amounts, rates, tiers and thresholds live in the canon PRD
+ *     and are read from one place. `publishedValuePence` is a field, not a value.
+ *   - `restrictedCents` and `unrestrictedCents` are reported figures. What a
+ *     restricted lot may do is the capability policy's (CAY-0035, and CAY-0074's
+ *     rule that a carve does not move restriction), not these fields'.
+ */
+/** The capability this contract surfaces. Matches the glossary exactly. */
+export declare const WALLET_CAPABILITY: "cayso.wallet";
+/** Who a wallet belongs to. */
+export type HolderType = 'citizen' | 'organisation';
+/** Unix epoch milliseconds. */
+export type Millis = number;
+/**
+ * An integer number of cents. **₡1 = 100 cents** — the permanent relationship, and the
+ * whole of the unit. Never fractional.
+ *
+ * The sterling value is NOT part of this type's meaning. ₡1 is £0.01 at tier 1 and the
+ * published value ratchets (CAY-0002), which is why every amount on this surface travels
+ * beside a `publishedValuePence`. **Render sterling from that figure, never from a
+ * constant**: a constant is correct until the first quickening and silently wrong after.
+ */
+export type Cents = number;
+export interface WalletRecord {
+    /** This repository's opaque id, and the only handle an operator surface shows. */
+    readonly walletId: string;
+    readonly holderType: HolderType;
+    readonly createdAt: Millis;
+}
+/** The sum of a wallet's own holdings. Never includes an allowance. */
+export interface Balance {
+    readonly cents: Cents;
+    readonly restrictedCents: Cents;
+    readonly unrestrictedCents: Cents;
+    /** What ₡1 is worth in sterling right now, in pence. */
+    readonly publishedValuePence: number;
+    /** When the figures were true. A lagging read is stale, never wrong. */
+    readonly asOf: Millis;
+}
+/** Authority to spend from an organisation's wallet. Not the holder's money. */
+export interface Allowance {
+    readonly organisationWalletId: string;
+    readonly limitCents: Cents;
+    readonly spentCents: Cents;
+    readonly remainingCents: Cents;
+}
+export interface WalletView {
+    readonly wallet: WalletRecord;
+    readonly balance: Balance;
+    /** Allowances on OTHER wallets. Deliberately not summed into balance. */
+    readonly allowances: readonly Allowance[];
+}
+export interface CaysoWallet {
+    readonly capability: typeof WALLET_CAPABILITY;
+    readonly version: string;
+    getMyWallet(): Promise<WalletView | null>;
+}

package/dist/wallet.js

@@ -0,0 +1,59 @@
+/*
+ * 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.
+ */
+/**
+ * `cayso.wallet` — the read side of a wallet: the record, the balance, the
+ * allowances a holder carries, and the response that binds them.
+ *
+ * This is the pillar's first real contract. `wallet` is the noun and `cayso.*`
+ * is the namespace (CAY-0017); a `balance` is the derived sum of a wallet's own
+ * holdings and is never a stored figure (CAY-0019). A consumer of this contract
+ * reads a wallet — it never sees a holding, a carve or a movement, and there is
+ * no mutation here: crediting, debiting or transferring a wallet is not a read,
+ * and nothing on `CaysoWallet` can express one.
+ *
+ * ## Why balance and allowances are two answers, never one sum
+ *
+ * What a citizen *has* and what a citizen *may spend* are different questions,
+ * and this shape keeps them apart on purpose (CAY-0024).
+ *
+ *   - `Balance` is the sum of the wallet's **own** holdings. It is the holder's
+ *     service credit and nothing else.
+ *   - An `Allowance` is a revocable authority to spend from an **organisation's**
+ *     wallet. The cents stay the organisation's until they are spent; an
+ *     allowance is not the holder's money and never becomes it.
+ *
+ * So `balance` and `allowances` are **never summed** — not here, not in any
+ * consumer. The reason is regulatory, not cosmetic: were an employer's allowance
+ * folded into the balance, then in every screen, statement and export it would
+ * read as the citizen's own service credit. That is remuneration in kind — an
+ * employer handing over something cashable — which is precisely the shape
+ * CAY-0024 exists to keep out of the model. Two fields that never add up is how
+ * the contract refuses to tell that lie.
+ *
+ * ## What this file must not decide
+ *
+ *   - **No formatted money.** Every amount is an integer count of cents, paired
+ *     with `publishedValuePence`; the consumer renders "₡500" or "£5.00". A
+ *     server that returned `"₡500.00"` would have fixed the locale, the symbol
+ *     and the rounding for every consumer forever.
+ *   - **No numbers.** Amounts, rates, tiers and thresholds live in the canon PRD
+ *     and are read from one place. `publishedValuePence` is a field, not a value.
+ *   - `restrictedCents` and `unrestrictedCents` are reported figures. What a
+ *     restricted lot may do is the capability policy's (CAY-0035, and CAY-0074's
+ *     rule that a carve does not move restriction), not these fields'.
+ */
+/** The capability this contract surfaces. Matches the glossary exactly. */
+export const WALLET_CAPABILITY = 'cayso.wallet';

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@percayso-community/cayso-contracts",
+  "version": "0.23.0",
+  "description": "The versioned capability contract surface through which anything outside this repository reads a wallet. Published; keep it the Piper-facing surface only.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Percayso-Community/cayso.platform.git",
+    "directory": "packages/contracts"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "default": "./dist/schema.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "generate-schema": "tsx scripts/generate-contract-schema.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}