@percayso/identity-contracts 0.1.0

package/dist/parse.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The decoding half of this package's invariants.
+ *
+ * Every rule here has a twin in the type system, and neither is sufficient alone. A
+ * type cannot police a value that arrived as JSON from a caller this pillar does not
+ * control — §1.2 is explicit that a locally operated Piper Platform deployment and
+ * everything shipped with it are under the operator's control, so a wire value is an
+ * assertion by a stranger until something checks it. A parser, equally, cannot stop
+ * a programmer inside this repository writing the wrong identifier into the right
+ * field. So the canon's invariants are written twice: once as a shape that cannot be
+ * expressed, and once as a value that is refused.
+ *
+ * TWO PROPERTIES OF THE REFUSALS HERE ARE LOAD-BEARING.
+ *
+ * **A refusal names the field and the rule, never the value.** §14.4's disclosure
+ * criterion forbids a document field, a legal identity value or a raw image reaching
+ * logs or traces, and a parse error is a string that ends up in both. Echoing the
+ * offending input is the most natural thing in the world to write and would put the
+ * exact values this pillar exists to protect into every stack trace. `contract.test.ts`
+ * asserts it: a refusal never contains what it refused.
+ *
+ * **A refusal is not the wire refusal.** `ContractParseError` is thrown at a
+ * boundary inside a consumer's own process. What a caller receives is the closed,
+ * non-enumerating `Refusal` of `refusal.ts`, which carries a code and nothing else.
+ * The two must never be joined up: a parse message is detailed because it is private,
+ * and it stops being safe the moment it is returned.
+ */
+/** Raised when a wire value does not satisfy the contract. Never caught to proceed. */
+export declare class ContractParseError extends Error {
+    readonly name = "ContractParseError";
+    /** The field that failed, in dotted form, so a caller can say where without saying what. */
+    readonly field: string;
+    constructor(field: string, rule: string);
+}
+/** Refuse a value. The message states the rule; it never restates the input. */
+export declare const refuseValue: (field: string, rule: string) => never;
+/**
+ * A plain object, or a refusal.
+ *
+ * Arrays and `null` are refused rather than coerced. `null` is an object to
+ * `typeof` and an array is an object to everything, and a decoder that accepted
+ * either would accept a shape its caller never meant to send.
+ */
+export declare const readObject: (value: unknown, field: string) => Readonly<Record<string, unknown>>;
+/**
+ * A plain object whose keys are all permitted, or a refusal.
+ *
+ * UNKNOWN KEYS ARE REFUSED, and that is a security property rather than a tidiness
+ * one. Several of the canon's "must not hold" rules in §15 are about a field's
+ * ABSENCE — `cayso_provisioning` must not hold a balance, `verification_cases` must
+ * not hold a bare provider score as the decision, `audit_events` must not hold raw
+ * evidence. A decoder that ignored what it did not recognise would let every one of
+ * those arrive, be carried through a consumer untyped, and be written back out. A
+ * closed record is how "must not hold" survives a round trip.
+ */
+export declare const readClosedRecord: (value: unknown, field: string, permitted: readonly string[]) => Readonly<Record<string, unknown>>;
+/** A required string field, or a refusal. */
+export declare const readString: (record: Readonly<Record<string, unknown>>, field: string, key: string) => string;
+/** A required member of a closed union, or a refusal. */
+export declare const readMember: <T extends string>(record: Readonly<Record<string, unknown>>, field: string, key: string, members: readonly T[]) => T;
+/** A required boolean field, or a refusal. */
+export declare const readBoolean: (record: Readonly<Record<string, unknown>>, field: string, key: string) => boolean;
+/**
+ * A required array field, or a refusal. The element decoder runs over every entry, so
+ * a list is as closed as the values in it.
+ */
+export declare const readArray: <T>(record: Readonly<Record<string, unknown>>, field: string, key: string, element: (value: unknown, elementField: string) => T) => readonly T[];

package/dist/parse.js

@@ -0,0 +1,109 @@
+/**
+ * The decoding half of this package's invariants.
+ *
+ * Every rule here has a twin in the type system, and neither is sufficient alone. A
+ * type cannot police a value that arrived as JSON from a caller this pillar does not
+ * control — §1.2 is explicit that a locally operated Piper Platform deployment and
+ * everything shipped with it are under the operator's control, so a wire value is an
+ * assertion by a stranger until something checks it. A parser, equally, cannot stop
+ * a programmer inside this repository writing the wrong identifier into the right
+ * field. So the canon's invariants are written twice: once as a shape that cannot be
+ * expressed, and once as a value that is refused.
+ *
+ * TWO PROPERTIES OF THE REFUSALS HERE ARE LOAD-BEARING.
+ *
+ * **A refusal names the field and the rule, never the value.** §14.4's disclosure
+ * criterion forbids a document field, a legal identity value or a raw image reaching
+ * logs or traces, and a parse error is a string that ends up in both. Echoing the
+ * offending input is the most natural thing in the world to write and would put the
+ * exact values this pillar exists to protect into every stack trace. `contract.test.ts`
+ * asserts it: a refusal never contains what it refused.
+ *
+ * **A refusal is not the wire refusal.** `ContractParseError` is thrown at a
+ * boundary inside a consumer's own process. What a caller receives is the closed,
+ * non-enumerating `Refusal` of `refusal.ts`, which carries a code and nothing else.
+ * The two must never be joined up: a parse message is detailed because it is private,
+ * and it stops being safe the moment it is returned.
+ */
+/** Raised when a wire value does not satisfy the contract. Never caught to proceed. */
+export class ContractParseError extends Error {
+    name = "ContractParseError";
+    /** The field that failed, in dotted form, so a caller can say where without saying what. */
+    field;
+    constructor(field, rule) {
+        super(`${field}: ${rule}`);
+        this.field = field;
+    }
+}
+/** Refuse a value. The message states the rule; it never restates the input. */
+export const refuseValue = (field, rule) => {
+    throw new ContractParseError(field, rule);
+};
+/**
+ * A plain object, or a refusal.
+ *
+ * Arrays and `null` are refused rather than coerced. `null` is an object to
+ * `typeof` and an array is an object to everything, and a decoder that accepted
+ * either would accept a shape its caller never meant to send.
+ */
+export const readObject = (value, field) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        refuseValue(field, "must be an object");
+    }
+    return value;
+};
+/**
+ * A plain object whose keys are all permitted, or a refusal.
+ *
+ * UNKNOWN KEYS ARE REFUSED, and that is a security property rather than a tidiness
+ * one. Several of the canon's "must not hold" rules in §15 are about a field's
+ * ABSENCE — `cayso_provisioning` must not hold a balance, `verification_cases` must
+ * not hold a bare provider score as the decision, `audit_events` must not hold raw
+ * evidence. A decoder that ignored what it did not recognise would let every one of
+ * those arrive, be carried through a consumer untyped, and be written back out. A
+ * closed record is how "must not hold" survives a round trip.
+ */
+export const readClosedRecord = (value, field, permitted) => {
+    const record = readObject(value, field);
+    for (const key of Object.keys(record)) {
+        if (!permitted.includes(key)) {
+            refuseValue(`${field}.${key}`, "is not a field of this contract type. The contract is closed: an unrecognised field is refused rather than carried");
+        }
+    }
+    return record;
+};
+/** A required string field, or a refusal. */
+export const readString = (record, field, key) => {
+    const value = record[key];
+    if (typeof value !== "string") {
+        refuseValue(`${field}.${key}`, "must be a string");
+    }
+    return value;
+};
+/** A required member of a closed union, or a refusal. */
+export const readMember = (record, field, key, members) => {
+    const value = readString(record, field, key);
+    if (!members.includes(value)) {
+        refuseValue(`${field}.${key}`, `must be one of the ${members.length} members of this closed union`);
+    }
+    return value;
+};
+/** A required boolean field, or a refusal. */
+export const readBoolean = (record, field, key) => {
+    const value = record[key];
+    if (typeof value !== "boolean") {
+        refuseValue(`${field}.${key}`, "must be a boolean");
+    }
+    return value;
+};
+/**
+ * A required array field, or a refusal. The element decoder runs over every entry, so
+ * a list is as closed as the values in it.
+ */
+export const readArray = (record, field, key, element) => {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+        refuseValue(`${field}.${key}`, "must be an array");
+    }
+    return value.map((entry, index) => element(entry, `${field}.${key}[${index}]`));
+};

package/dist/provisioning.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Provisioning coordination: what this pillar believes about a Citizen's Cayso
+ * provisioning, and the several things it refuses to claim.
+ *
+ * §11.3 gives the five coordination states and then constrains what they mean, in a
+ * sentence that decides most of this file: "**This state is operational belief,
+ * never the economic fact.** It may decide what the next session attempts. It may
+ * never be cited as proof that a grant exists."
+ *
+ * HOW THAT IS ENFORCED TWICE.
+ *
+ * There is no balance field, and there is no predicate that answers "does this
+ * Citizen have a grant". The union below can express "we have not confirmed", "we do
+ * not know" and "Cayso told us it was done, and here is what it said" — and it
+ * cannot express a figure this pillar arrived at on its own, because there is
+ * nowhere to put one. That is the type half. The decoder half is
+ * `readClosedRecord`, which refuses an unrecognised field rather than dropping it:
+ * a caller who sends a balance is told the contract has no such field, instead of
+ * having it silently discarded and adding it to the type next week to stop the
+ * discarding. §15's `cayso_provisioning` row forbids "A current balance; any use as
+ * proof a grant exists", and both halves are needed — a type cannot refuse JSON and
+ * a decoder cannot stop a programmer.
+ *
+ * `confirmed` carries a `CaysoConfirmation`, whose `source` is the literal
+ * `"cayso-response"`. Nothing else is assignable to it, so a confirmed coordination
+ * record cannot be assembled from a Reviewer's belief or from an operator's screen.
+ * §11.3: "No operator 'mark grant received' action may bypass a response or
+ * side-effect-free read from Cayso, and reconciliation may observe Cayso state but
+ * never create or adjust a balance." The witness type is that rule; nothing in this
+ * package mints one from anything but a parsed Cayso response.
+ *
+ * THE FIELDS THAT ARE ABSENT BECAUSE A DECISION IS OPEN. A deferred provisioning
+ * outbox — `next_attempt` and lease fields — is permitted only once Cayso authorises
+ * one, and it has not. So those fields are not here, and
+ * `parseProvisioningCoordination` refuses them by name rather than by the general
+ * unknown-field rule: a caller sending `nextAttemptAt` is building a scheduled retry
+ * path that does not exist yet, and deserves to be told so rather than have the field
+ * quietly ignored. **No worker, no lease, no scheduled retry path** until Cayso
+ * authorises one."
+ *
+ * The extension seam §11.3 asks for is therefore a schema and issue-level seam, not
+ * a set of dormant fields in a published contract. A field a consumer can already
+ * send is not a seam; it is the feature, shipped early, without the amendment.
+ */
+import type { Cents, Millis } from "@cayso/contracts";
+import { type CitizenId } from "./ids.js";
+/**
+ * The coordination states of §11.3's table, one member each.
+ *
+ * `confirmation_unknown` is the one worth reading twice: it is not a failure and not
+ * a success, and a consumer that renders it as either is the reason it exists. §11.3
+ * describes exactly what happens next — the next authenticated session "first
+ * performs the side-effect-free citizenship read, then repeats the idempotent
+ * operation if necessary".
+ */
+export type ProvisioningState = "awaiting_citizen_action" | "attempting" | "confirmation_unknown" | "confirmed" | "permanent_failure";
+/** Every coordination state, in §11.3's order. */
+export declare const PROVISIONING_STATES: readonly ProvisioningState[];
+/**
+ * The edges §11.3 describes, and no others.
+ *
+ * `confirmation_unknown --> attempting` is the recovery §11.3 specifies and the only
+ * loop here; it is entered by a Citizen's next authenticated session, never by a
+ * timer, because there is no worker to hold one. `permanent_failure` has no outgoing
+ * edge: §11.3 defines it as a refusal "requiring intervention or a policy change",
+ * and what such an intervention is permitted to do is not decided, so this package
+ * draws no edge rather than inventing the one that looks safe.
+ */
+export declare const PROVISIONING_TRANSITIONS: Readonly<Record<ProvisioningState, readonly ProvisioningState[]>>;
+/** Whether §11.3 draws this edge. */
+export declare const isProvisioningTransitionPermitted: (from: ProvisioningState, to: ProvisioningState) => boolean;
+/**
+ * What Cayso said, recorded as coordination evidence and nothing more.
+ *
+ * §15's `cayso_provisioning` row permits the confirmed references — `wallet_id`,
+ * `grant_movement_id`, amount and confirmation time — and forbids "any use as proof
+ * a grant exists". Both halves are true at once, and the distinction is the reason
+ * `source` exists: these figures are a record of a message from the pillar that owns
+ * the ledger, not a statement this pillar is entitled to make. A consumer that needs
+ * to know what a Citizen holds asks Cayso, whose side-effect-free citizenship read
+ * exists for the purpose.
+ *
+ * `source` is the literal `"cayso-response"`, so there is no second way to build
+ * one. It is the same device `ApprovedApplication` uses on the Citizen side: a
+ * witness type that widening cannot produce.
+ */
+export interface CaysoConfirmation {
+    readonly source: "cayso-response";
+    /** Cayso's wallet reference, as returned. Opaque here; this pillar never interprets it. */
+    readonly walletId: string;
+    /** Cayso's movement reference for the sign-up grant, as returned. */
+    readonly grantMovementId: string;
+    /** The amount Cayso reported granting. Cayso's figure, in Cayso's units, never recomputed here. */
+    readonly grantedCents: Cents;
+    readonly confirmedAt: Millis;
+}
+/**
+ * One Citizen's coordination row, as a discriminated union over the state.
+ *
+ * The union is what stops a half-filled record: only the `confirmed` branch has a
+ * `CaysoConfirmation`, so an unconfirmed row cannot carry one, and a confirmed row
+ * cannot lack one. A single flat record with optional fields would have permitted
+ * both — "confirmed with nothing to show for it" is precisely the shape an operator
+ * marking a row by hand would produce.
+ *
+ * `attemptCount`, `lastAttemptAt` and `lastSafeError` come from §15 and are on every
+ * branch because they describe this pillar's own behaviour rather than Cayso's.
+ * `lastSafeError` is SAFE: a short, non-enumerating reason fit to be stored and
+ * shown, never a provider payload — §14.4 requires a Citizen to see "actionable,
+ * accessible status and refusal text without exposure of internal risk signals".
+ */
+export type ProvisioningCoordination = {
+    readonly citizenId: CitizenId;
+    readonly attemptCount: number;
+    readonly lastAttemptAt: Millis | null;
+    readonly lastSafeError: string | null;
+} & ({
+    readonly state: Exclude<ProvisioningState, "confirmed">;
+    readonly confirmation?: undefined;
+} | {
+    readonly state: "confirmed";
+    readonly confirmation: CaysoConfirmation;
+});
+/**
+ * A `CaysoConfirmation` from a wire value, or a refusal.
+ *
+ * `source` must be the exact string `"cayso-response"`. A caller with a different
+ * provenance for these figures has an operator's belief, which §11.3 refuses.
+ */
+export declare const parseCaysoConfirmation: (value: unknown, field?: string) => CaysoConfirmation;
+/**
+ * A `ProvisioningCoordination` from a wire value, or a refusal.
+ *
+ * Three refusals here are deliberate and named: the fields of a deferred provisioning
+ * outbox, which is not part of this contract; the economic fields, which belong to
+ * Cayso's ledger and never to a coordination row; and a `confirmed` state carrying no
+ * confirmation, which is the wire form of an operator marking a row done.
+ */
+export declare const parseProvisioningCoordination: (value: unknown, field?: string) => ProvisioningCoordination;

package/dist/provisioning.js

@@ -0,0 +1,223 @@
+/**
+ * Provisioning coordination: what this pillar believes about a Citizen's Cayso
+ * provisioning, and the several things it refuses to claim.
+ *
+ * §11.3 gives the five coordination states and then constrains what they mean, in a
+ * sentence that decides most of this file: "**This state is operational belief,
+ * never the economic fact.** It may decide what the next session attempts. It may
+ * never be cited as proof that a grant exists."
+ *
+ * HOW THAT IS ENFORCED TWICE.
+ *
+ * There is no balance field, and there is no predicate that answers "does this
+ * Citizen have a grant". The union below can express "we have not confirmed", "we do
+ * not know" and "Cayso told us it was done, and here is what it said" — and it
+ * cannot express a figure this pillar arrived at on its own, because there is
+ * nowhere to put one. That is the type half. The decoder half is
+ * `readClosedRecord`, which refuses an unrecognised field rather than dropping it:
+ * a caller who sends a balance is told the contract has no such field, instead of
+ * having it silently discarded and adding it to the type next week to stop the
+ * discarding. §15's `cayso_provisioning` row forbids "A current balance; any use as
+ * proof a grant exists", and both halves are needed — a type cannot refuse JSON and
+ * a decoder cannot stop a programmer.
+ *
+ * `confirmed` carries a `CaysoConfirmation`, whose `source` is the literal
+ * `"cayso-response"`. Nothing else is assignable to it, so a confirmed coordination
+ * record cannot be assembled from a Reviewer's belief or from an operator's screen.
+ * §11.3: "No operator 'mark grant received' action may bypass a response or
+ * side-effect-free read from Cayso, and reconciliation may observe Cayso state but
+ * never create or adjust a balance." The witness type is that rule; nothing in this
+ * package mints one from anything but a parsed Cayso response.
+ *
+ * THE FIELDS THAT ARE ABSENT BECAUSE A DECISION IS OPEN. A deferred provisioning
+ * outbox — `next_attempt` and lease fields — is permitted only once Cayso authorises
+ * one, and it has not. So those fields are not here, and
+ * `parseProvisioningCoordination` refuses them by name rather than by the general
+ * unknown-field rule: a caller sending `nextAttemptAt` is building a scheduled retry
+ * path that does not exist yet, and deserves to be told so rather than have the field
+ * quietly ignored. **No worker, no lease, no scheduled retry path** until Cayso
+ * authorises one."
+ *
+ * The extension seam §11.3 asks for is therefore a schema and issue-level seam, not
+ * a set of dormant fields in a published contract. A field a consumer can already
+ * send is not a seam; it is the feature, shipped early, without the amendment.
+ */
+import { readCitizenId } from "./ids.js";
+import { readClosedRecord, readString, refuseValue } from "./parse.js";
+/** Every coordination state, in §11.3's order. */
+export const PROVISIONING_STATES = Object.freeze([
+    "awaiting_citizen_action",
+    "attempting",
+    "confirmation_unknown",
+    "confirmed",
+    "permanent_failure",
+]);
+/**
+ * The edges §11.3 describes, and no others.
+ *
+ * `confirmation_unknown --> attempting` is the recovery §11.3 specifies and the only
+ * loop here; it is entered by a Citizen's next authenticated session, never by a
+ * timer, because there is no worker to hold one. `permanent_failure` has no outgoing
+ * edge: §11.3 defines it as a refusal "requiring intervention or a policy change",
+ * and what such an intervention is permitted to do is not decided, so this package
+ * draws no edge rather than inventing the one that looks safe.
+ */
+export const PROVISIONING_TRANSITIONS = Object.freeze({
+    awaiting_citizen_action: Object.freeze(["attempting"]),
+    attempting: Object.freeze([
+        "confirmed",
+        "confirmation_unknown",
+        "permanent_failure",
+    ]),
+    confirmation_unknown: Object.freeze([
+        "attempting",
+        "confirmed",
+        "permanent_failure",
+    ]),
+    confirmed: Object.freeze([]),
+    permanent_failure: Object.freeze([]),
+});
+/** Whether §11.3 draws this edge. */
+export const isProvisioningTransitionPermitted = (from, to) => PROVISIONING_TRANSITIONS[from].includes(to);
+const COORDINATION_FIELDS = Object.freeze([
+    "citizenId",
+    "state",
+    "attemptCount",
+    "lastAttemptAt",
+    "lastSafeError",
+    "confirmation",
+]);
+/**
+ * Fields that name the deferred outbox, refused with what would have to be agreed
+ * before any of them could mean anything.
+ */
+const DEFERRED_OUTBOX_FIELDS = Object.freeze([
+    "nextAttempt",
+    "nextAttemptAt",
+    "lease",
+    "leaseExpiresAt",
+    "leasedBy",
+    "lockedUntil",
+]);
+/** Fields that would make coordination state into an economic claim. §15 forbids them outright. */
+const ECONOMIC_FIELDS = Object.freeze([
+    "balanceCents",
+    "currentBalance",
+    "walletBalance",
+    "restrictedCents",
+    "unrestrictedCents",
+]);
+const readCount = (record, field, key) => {
+    const value = record[key];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        refuseValue(`${field}.${key}`, "must be a non-negative integer");
+    }
+    return value;
+};
+const readMillis = (record, field, key) => {
+    const value = record[key];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        refuseValue(`${field}.${key}`, "must be a non-negative integer count of milliseconds");
+    }
+    return value;
+};
+const readNullableMillis = (record, field, key) => {
+    const value = record[key];
+    if (value === null) {
+        return null;
+    }
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        refuseValue(`${field}.${key}`, "must be null or a non-negative integer count of milliseconds");
+    }
+    return value;
+};
+const CONFIRMATION_FIELDS = Object.freeze([
+    "source",
+    "walletId",
+    "grantMovementId",
+    "grantedCents",
+    "confirmedAt",
+]);
+/**
+ * A `CaysoConfirmation` from a wire value, or a refusal.
+ *
+ * `source` must be the exact string `"cayso-response"`. A caller with a different
+ * provenance for these figures has an operator's belief, which §11.3 refuses.
+ */
+export const parseCaysoConfirmation = (value, field = "confirmation") => {
+    const record = readClosedRecord(value, field, CONFIRMATION_FIELDS);
+    const source = readString(record, field, "source");
+    if (source !== "cayso-response") {
+        refuseValue(`${field}.source`, "must be cayso-response. Confirmation comes from a Cayso response or a side-effect-free read, never from an operator action (§11.3)");
+    }
+    const grantedCents = record["grantedCents"];
+    if (typeof grantedCents !== "number" ||
+        !Number.isSafeInteger(grantedCents) ||
+        grantedCents < 0) {
+        refuseValue(`${field}.grantedCents`, "must be a non-negative integer, exactly as Cayso reported it");
+    }
+    return {
+        source: "cayso-response",
+        walletId: readString(record, field, "walletId"),
+        grantMovementId: readString(record, field, "grantMovementId"),
+        grantedCents: grantedCents,
+        confirmedAt: readMillis(record, field, "confirmedAt"),
+    };
+};
+/**
+ * The closed-record read for a coordination row, with the two refusals that have to
+ * name their reason before the general unknown-field rule reaches them.
+ */
+const readCoordinationRecord = (value, field) => {
+    const record = readClosedRecord(value, field, [
+        ...COORDINATION_FIELDS,
+        ...DEFERRED_OUTBOX_FIELDS,
+        ...ECONOMIC_FIELDS,
+    ]);
+    for (const key of Object.keys(record)) {
+        if (DEFERRED_OUTBOX_FIELDS.includes(key)) {
+            refuseValue(`${field}.${key}`, "belongs to a deferred provisioning outbox. There is no worker, no lease and no scheduled retry path, and there will be none until Cayso authorises one (§11.3, §15)");
+        }
+        if (ECONOMIC_FIELDS.includes(key)) {
+            refuseValue(`${field}.${key}`, "is an economic fact and not coordination state. This row may never be cited as proof that a grant exists (§11.3, §15)");
+        }
+    }
+    return record;
+};
+/**
+ * A `ProvisioningCoordination` from a wire value, or a refusal.
+ *
+ * Three refusals here are deliberate and named: the fields of a deferred provisioning
+ * outbox, which is not part of this contract; the economic fields, which belong to
+ * Cayso's ledger and never to a coordination row; and a `confirmed` state carrying no
+ * confirmation, which is the wire form of an operator marking a row done.
+ */
+export const parseProvisioningCoordination = (value, field = "coordination") => {
+    const record = readCoordinationRecord(value, field);
+    const state = readString(record, field, "state");
+    if (!PROVISIONING_STATES.includes(state)) {
+        refuseValue(`${field}.state`, `must be one of the ${PROVISIONING_STATES.length} coordination states of §11.3`);
+    }
+    const common = {
+        citizenId: readCitizenId(record, field, "citizenId"),
+        attemptCount: readCount(record, field, "attemptCount"),
+        lastAttemptAt: readNullableMillis(record, field, "lastAttemptAt"),
+        lastSafeError: record["lastSafeError"] === null
+            ? null
+            : readString(record, field, "lastSafeError"),
+    };
+    if (state === "confirmed") {
+        return {
+            ...common,
+            state: "confirmed",
+            confirmation: parseCaysoConfirmation(record["confirmation"], `${field}.confirmation`),
+        };
+    }
+    if (record["confirmation"] !== undefined) {
+        refuseValue(`${field}.confirmation`, "is permitted only in the confirmed state. Cayso's references are recorded when Cayso returns them and not before (§11.3)");
+    }
+    return {
+        ...common,
+        state: state,
+    };
+};

package/dist/refusal.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The closed refusal union: what a caller is told when this pillar says no, and
+ * everything it is deliberately not told.
+ *
+ * §14.4 sets both halves of the requirement, and they pull against each other. "A
+ * Citizen sees actionable, accessible status and refusal text without exposure of
+ * internal risk signals." Actionable, so a refusal cannot be an opaque failure;
+ * without internal risk signals, so it cannot be the reason. A closed union of codes
+ * satisfies both: the code says what the caller may do next, and the consumer
+ * renders the text — accessibly, in the Citizen's language, at the right reading
+ * level — because a wire string can be none of those things.
+ *
+ * ENFORCED TWICE, AND THE SECOND HALF IS THE INTERESTING ONE.
+ *
+ * `Refusal` has no message field, no detail field and no reason field. There is
+ * nowhere to put prose, so no handler can attach a provider's explanation to a
+ * refusal on its way out; that is the type half, and it is the half that survives a
+ * hurried afternoon. `parseRefusal` is the decoder half and refuses those field
+ * names explicitly rather than by the general unknown-key rule, because a caller
+ * sending `reason` has a provider payload in their hand and needs to be told why it
+ * stops here.
+ *
+ * WHY THE UNION DOES NOT ENUMERATE.
+ *
+ * Several members cover more than one underlying cause on purpose. `not_permitted`
+ * answers both "this is not yours" and "this does not exist", because two codes
+ * would make the refusal an existence oracle for anything addressed by identifier.
+ * `onboarding_result_not_redeemable` covers every one of §14.4's five cases — a
+ * second redemption, another client, expiry, an altered Citizen, a different
+ * transaction verifier — as one member, because telling an attacker WHICH of the
+ * five they tripped is how they work out what to change. The union cannot express
+ * the distinction, which is stronger than a convention that it should not be
+ * exposed.
+ *
+ * A REFUSAL IS NOT A PARSE ERROR. `ContractParseError` in `parse.ts` is detailed
+ * because it is private to a consumer's own process. A `Refusal` crosses a network
+ * boundary and carries a code and a correlation reference, and nothing else. Joining
+ * them up — returning a parse message to a caller — would leak exactly what §14.4's
+ * disclosure criterion protects.
+ */
+import { type CorrelationReference } from "./ids.js";
+/**
+ * Why this pillar refused, in terms a caller can act on.
+ *
+ * Every member answers "what now" rather than "what happened inside". A member is
+ * added by amending this union, which is a breaking change to a published contract
+ * and therefore a decision somebody takes on purpose — not a new string that appears
+ * in a log one morning.
+ */
+export type RefusalCode = 
+/** No Percayso ID session is established. Sign in, then retry. */
+"unauthenticated"
+/** The session is real but not fresh or strong enough for this operation. Re-authenticate. */
+ | "step_up_required"
+/**
+ * The caller may not do this. Deliberately also the answer when the target does
+ * not exist: a distinct "not found" would let anyone enumerate Citizens,
+ * Applications and cases by identifier.
+ */
+ | "not_permitted"
+/** The record is not in a state where this is possible. See §5.2 and §11.3 for the diagrams. */
+ | "state_not_permitted"
+/** The request did not satisfy the contract. Nothing about the caller is implied. */
+ | "input_not_acceptable"
+/** That Handle is taken or reserved. §14.4: a collision returns to selection. */
+ | "handle_unavailable"
+/**
+ * The identity document is already bound to an active Citizen (§8.5). §14.4
+ * requires this refusal to be appealable, which is why it is its own member: a
+ * refusal a person cannot recognise is a refusal they cannot appeal.
+ */
+ | "document_already_bound"
+/** The evidence does not support what was asked for (§8.2). Never a provider's figure. */
+ | "evidence_insufficient"
+/**
+ * The onboarding result cannot be redeemed. One member for all five of §14.4's
+ * cases, on purpose — see this file's docblock.
+ */
+ | "onboarding_result_not_redeemable"
+/** A declared limit was reached (§12.5). The limits themselves are the exposing slice's. */
+ | "rate_limited"
+/**
+ * The operation cannot be performed right now and may succeed later. §11.4:
+ * issuance refuses on signing failure, with no unsigned, stub or stale-key
+ * fallback, and absence of signing configuration fails readiness.
+ */
+ | "temporarily_unavailable";
+/** Every refusal code. A consumer that must render them all reads this. */
+export declare const REFUSAL_CODES: readonly RefusalCode[];
+/** Whether §8.6's appeal route applies to this refusal. */
+export declare const isAppealable: (code: RefusalCode) => boolean;
+/**
+ * What crosses the wire when this pillar refuses.
+ *
+ * Two fields, and the second one is what makes the first one supportable. A Citizen
+ * who cannot be told why can still be helped: they quote the correlation reference,
+ * and a support path with the right authority reads the audited record behind it.
+ * §15's `audit_events` row carries that same reference, which is how the opaque code
+ * a caller sees and the full account a Reviewer sees are the same event.
+ */
+export interface Refusal {
+    readonly refusal: RefusalCode;
+    readonly correlationReference: CorrelationReference;
+}
+/** A `Refusal` from a wire value, or a refusal of its own. */
+export declare const parseRefusal: (value: unknown, field?: string) => Refusal;
+/**
+ * What every operation in this contract returns: a value, or a refusal.
+ *
+ * A discriminated union rather than a thrown error, because a refusal is an ordinary
+ * outcome of asking this pillar a question and an exception is not. A caller must
+ * switch on `outcome`, so there is no path where a refusal is ignored by a `catch`
+ * nobody wrote — and the refused branch has no value field, so there is no
+ * half-populated result to read out of it.
+ */
+export type ContractResult<T> = {
+    readonly outcome: "ok";
+    readonly value: T;
+} | {
+    readonly outcome: "refused";
+    readonly refusal: Refusal;
+};