@percayso/identity-contracts 0.1.0

package/dist/citizen.js

@@ -0,0 +1,144 @@
+/**
+ * The Citizen: the three statuses of §5.2, what a Citizen record may carry, and the
+ * witness required before one can exist at all.
+ *
+ * THERE IS NO `pending` CITIZEN, and this file is where that sentence stops being
+ * prose. §5.2: "Citizen states are `active`, `suspended` and `closed`. **There is no
+ * `pending` Citizen** — pending belongs to an Application." §15's `citizens` row
+ * says the same from the other side, forbidding a generic pending state on
+ * `applications` too. So the union omits it — a `switch` over `CitizenStatus` that
+ * adds a `pending` arm does not compile — and `parseCitizenStatus` refuses the
+ * string by name, with a message that says where pending actually belongs. The
+ * type cannot express it and the decoder will not accept it; either alone would
+ * leave the other half open.
+ *
+ * THE SECOND INVARIANT IS THAT A CITIZEN CANNOT BE CREATED WITHOUT AN APPROVAL.
+ * §14.4: "No route, script, production fixture or flag creates a Citizen outside an
+ * Application." `CitizenCreation` requires an `ApprovedApplication`, whose `state`
+ * is the literal `"approved"` — so there is no Citizen-shaped value a caller can
+ * assemble from an Application in any other state, and no optional field that could
+ * be left out. `parseCitizenCreation` refuses the same thing at runtime.
+ *
+ * AND THE THIRD IS THAT A CITIZEN RECORD HOLDS NO MONEY. §15's `citizens` row must
+ * not hold "any balance, wallet balance or workspace role", and §11.3 is blunter:
+ * coordination state "is operational belief, never the economic fact". There is no
+ * balance field here, no wallet field and no role field, and `readClosedRecord`
+ * refuses a caller who sends one rather than dropping it silently — a dropped field
+ * is a field somebody adds to the type next week to stop it being dropped.
+ *
+ * WHAT IS ABSENT BY DESIGN. A Citizen record does not say whether a Citizen Space
+ * exists. §5.2: "An approved Citizen whose Citizen Space has not yet been created is
+ * an ordinary `active` Citizen with outstanding onboarding coordination. They are
+ * not a lesser kind of Citizen." A flag here would create the lesser kind, so the
+ * coordination state lives in `provisioning.ts` where it cannot be mistaken for a
+ * property of the person.
+ */
+import { parseApprovedApplication, } from "./application.js";
+import { parseCommunityEmailAddress, parseDisplayHandle, readCitizenId, readVerificationCaseId, } from "./ids.js";
+import { readClosedRecord, readString, refuseValue } from "./parse.js";
+/** Every Citizen status, in §5.2's order. */
+export const CITIZEN_STATUSES = Object.freeze([
+    "active",
+    "suspended",
+    "closed",
+]);
+/**
+ * A Citizen status from a wire value, or a refusal.
+ *
+ * `pending` gets its own refusal rather than falling through the general one. The
+ * general message would say a value was outside a closed union, which is true and
+ * unhelpful; this one says where pending belongs, because a caller sending it has
+ * almost certainly read an Application state and written it into a Citizen field.
+ */
+export const parseCitizenStatus = (value, field = "status") => {
+    if (value === "pending") {
+        refuseValue(field, "must not be pending. There is no pending Citizen — pending belongs to an Application (§5.2)");
+    }
+    if (typeof value !== "string" ||
+        !CITIZEN_STATUSES.includes(value)) {
+        refuseValue(field, `must be one of the ${CITIZEN_STATUSES.length} Citizen statuses of §5.2`);
+    }
+    return value;
+};
+const CITIZEN_RECORD_FIELDS = Object.freeze([
+    "citizenId",
+    "status",
+    "approvedVerificationCaseId",
+    "assuranceProfileVersion",
+    "verificationMethod",
+    "createdAt",
+]);
+/**
+ * Cayso's verification methods, as a value this package can check against.
+ *
+ * `VERIFICATION_METHODS` is a runtime export of `@cayso/contracts`, and this package
+ * may not take a value import on it: the coupling scan's rule C forbids a bare
+ * specifier in a value position here, which is how a contract package stays free of
+ * runtime dependencies. So the members are listed once, in one place, and
+ * `citizen.test.ts` asserts the list is exactly Cayso's by checking assignability in
+ * both directions — a member added or removed upstream fails this package's
+ * typecheck rather than passing through it. That test is the seam; this array is not
+ * a second vocabulary.
+ */
+const VERIFICATION_METHOD_MEMBERS = Object.freeze(["dev-bypass", "document", "document-and-biometric"]);
+const readVerificationMethod = (record, field, key) => {
+    const value = readString(record, field, key);
+    if (!VERIFICATION_METHOD_MEMBERS.includes(value)) {
+        refuseValue(`${field}.${key}`, "must be a verification method of the Cayso assurance profile");
+    }
+    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;
+};
+/** A `CitizenRecord` from a wire value, or a refusal. */
+export const parseCitizenRecord = (value, field = "citizen") => {
+    const record = readClosedRecord(value, field, CITIZEN_RECORD_FIELDS);
+    return {
+        citizenId: readCitizenId(record, field, "citizenId"),
+        status: parseCitizenStatus(record["status"], `${field}.status`),
+        approvedVerificationCaseId: readVerificationCaseId(record, field, "approvedVerificationCaseId"),
+        assuranceProfileVersion: readString(record, field, "assuranceProfileVersion"),
+        verificationMethod: readVerificationMethod(record, field, "verificationMethod"),
+        createdAt: readMillis(record, field, "createdAt"),
+    };
+};
+const CITIZEN_NAMES_FIELDS = Object.freeze([
+    "citizenId",
+    "handle",
+    "communityEmailAddress",
+]);
+/** A `CitizenNames` from a wire value, or a refusal. */
+export const parseCitizenNames = (value, field = "citizenNames") => {
+    const record = readClosedRecord(value, field, CITIZEN_NAMES_FIELDS);
+    return {
+        citizenId: readCitizenId(record, field, "citizenId"),
+        handle: parseDisplayHandle(readString(record, field, "handle"), `${field}.handle`),
+        communityEmailAddress: parseCommunityEmailAddress(readString(record, field, "communityEmailAddress"), `${field}.communityEmailAddress`),
+    };
+};
+const CITIZEN_CREATION_FIELDS = Object.freeze([
+    "approvedApplication",
+    "citizenId",
+    "assuranceProfileVersion",
+    "verificationMethod",
+]);
+/**
+ * A `CitizenCreation` from a wire value, or a refusal.
+ *
+ * The refusal a caller is most likely to meet here is the `ContractParseError`
+ * `parseApprovedApplication` raises: `approvedApplication.state: must be approved`.
+ */
+export const parseCitizenCreation = (value, field = "citizenCreation") => {
+    const record = readClosedRecord(value, field, CITIZEN_CREATION_FIELDS);
+    return {
+        approvedApplication: parseApprovedApplication(record["approvedApplication"], `${field}.approvedApplication`),
+        citizenId: readCitizenId(record, field, "citizenId"),
+        assuranceProfileVersion: readString(record, field, "assuranceProfileVersion"),
+        verificationMethod: readVerificationMethod(record, field, "verificationMethod"),
+    };
+};

package/dist/client.d.ts

@@ -0,0 +1,140 @@
+/**
+ * A thin client: the routes this contract describes, a decoder on every response,
+ * and nothing else.
+ *
+ * THIN IS A CONSTRAINT, NOT A DESCRIPTION. This package publishes wire types, the
+ * closed unions and a client. It contains no server, no policy engine and no
+ * verifier, and this file is where that boundary is most easily lost: a client that
+ * retried, cached, refreshed a session or decided what a refusal meant would be
+ * making decisions the pillar has not taken yet, inside a package every consumer
+ * compiles against.
+ *
+ * SO IT READS AND NEVER WRITES. There is no method here that creates an Application,
+ * submits evidence, approves anything or asks for an assertion. The Application API
+ * and the approval transaction do not exist yet, and a client method posting to a
+ * route nobody has implemented is worse than no method at all: it looks like a
+ * commitment, and the first consumer to call it discovers the shape by trial.
+ *
+ * WHY THE ROUTE TABLE IS HERE AT ALL. A path is part of a wire contract, and the
+ * sibling precedent publishes one for the same reason: a consumer hand-writing a URL
+ * is a consumer with a private copy of the contract. Publishing it makes a
+ * disagreement between this package and the slice that serves these routes a
+ * VERSION BUMP somebody has to make, rather than a 404 somebody debugs.
+ *
+ * NO SIDE EFFECTS ON IMPORT. Importing this module defines functions and freezes one
+ * table. It opens no connection, reads no environment variable and touches no clock.
+ *
+ * THIS SLICE EXPOSES NO ENDPOINT. §12.5's obligation — declared dimensions, figures
+ * backed by load and abuse evidence — falls on the slice that makes an endpoint
+ * externally reachable. This package is the caller's side of a conversation with a
+ * server that does not exist yet, so it declares no limit policy, and the slice
+ * that serves these routes declares one before it exposes them.
+ */
+import { type ApplicationSummary } from "./application.js";
+import { type CitizenNames, type CitizenRecord } from "./citizen.js";
+import { type VerificationCaseSummary } from "./evidence.js";
+import type { ApplicationId, VerificationCaseId } from "./ids.js";
+import { type ProvisioningCoordination } from "./provisioning.js";
+import { type ContractResult } from "./refusal.js";
+/**
+ * The transport, described structurally so that this package depends on no runtime
+ * and no ambient library.
+ *
+ * `globalThis.fetch` satisfies it, and so does a test double of about ten lines.
+ * The shape is deliberately the smallest subset the client uses: naming the platform
+ * `Request`, `Response` or `AbortSignal` types would put `@types/node` or the DOM
+ * library into this package's published declarations, and a contract package that
+ * makes a consumer's typecheck depend on ITS ambient types is not dependency-free in
+ * any sense a consumer would recognise.
+ */
+export interface HttpRequestInit {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** The part of a response this client reads. */
+export interface HttpResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+/** Anything that can perform a request. `globalThis.fetch` is assignable to it. */
+export type FetchLike = (url: string, init: HttpRequestInit) => Promise<HttpResponse>;
+/**
+ * How the caller carries its established session.
+ *
+ * Deliberately a hook rather than a scheme. Whether a consumer presents a Percayso
+ * ID session cookie, an authorisation-code result or something else is the sign-in
+ * protocol's business, and a header format invented here would become the de facto
+ * answer before that is settled. It returns headers, so a consumer can carry
+ * whatever it has without this package naming it.
+ */
+export type Authorise = () => Promise<Readonly<Record<string, string>>>;
+export interface IdentityClientOptions {
+    /** Where the Identity Platform is. No default: a contract package does not know where you deployed. */
+    readonly baseUrl: string;
+    readonly authorise?: Authorise;
+    readonly fetchImpl?: FetchLike;
+}
+/**
+ * The routes this contract describes.
+ *
+ * Read-only, every one of them. `GET` is stated explicitly rather than assumed,
+ * because §11.3 turns on the existence of a "side-effect-free" read and a table that
+ * left the method implicit would be one refactor away from losing the distinction.
+ */
+export declare const ROUTES: Readonly<{
+    application: Readonly<{
+        method: "GET";
+        path: "/api/applications/:id";
+    }>;
+    ownCitizen: Readonly<{
+        method: "GET";
+        path: "/api/citizens/me";
+    }>;
+    ownCitizenNames: Readonly<{
+        method: "GET";
+        path: "/api/citizens/me/names";
+    }>;
+    verificationCase: Readonly<{
+        method: "GET";
+        path: "/api/verification-cases/:id";
+    }>;
+    ownProvisioningCoordination: Readonly<{
+        method: "GET";
+        path: "/api/citizens/me/provisioning-coordination";
+    }>;
+}>;
+/**
+ * Raised when a response is not something this contract can read at all.
+ *
+ * Distinct from a `Refusal`, which is this pillar saying no in a way the contract
+ * describes, and distinct from a `ContractParseError`, which is a well-formed
+ * response whose contents are wrong. This one means the conversation failed: a
+ * gateway answered, or the body was not JSON. A caller cannot map it to a refusal
+ * code without inventing one.
+ */
+export declare class ContractTransportError extends Error {
+    readonly name = "ContractTransportError";
+    readonly status: number;
+    constructor(status: number, rule: string);
+}
+/** What this client can do. Five reads, no writes — see this file's docblock. */
+export interface IdentityClient {
+    getApplication(applicationId: ApplicationId): Promise<ContractResult<ApplicationSummary>>;
+    getOwnCitizen(): Promise<ContractResult<CitizenRecord>>;
+    getOwnCitizenNames(): Promise<ContractResult<CitizenNames>>;
+    getVerificationCase(verificationCaseId: VerificationCaseId): Promise<ContractResult<VerificationCaseSummary>>;
+    getOwnProvisioningCoordination(): Promise<ContractResult<ProvisioningCoordination>>;
+}
+/**
+ * Create a client.
+ *
+ * Every method returns a `ContractResult`: an `ok` branch carrying a decoded value,
+ * or a `refused` branch carrying the closed `Refusal`. A refusal is not thrown,
+ * because a refusal is an ordinary answer and an exception is how an ordinary answer
+ * gets swallowed by a `catch` written for something else.
+ *
+ * Nothing is retried. A retry policy is a decision about idempotency and about the
+ * limits of §12.5, and neither is settled for routes nobody serves yet.
+ */
+export declare const createIdentityClient: (options: IdentityClientOptions) => IdentityClient;

package/dist/client.js

@@ -0,0 +1,154 @@
+/**
+ * A thin client: the routes this contract describes, a decoder on every response,
+ * and nothing else.
+ *
+ * THIN IS A CONSTRAINT, NOT A DESCRIPTION. This package publishes wire types, the
+ * closed unions and a client. It contains no server, no policy engine and no
+ * verifier, and this file is where that boundary is most easily lost: a client that
+ * retried, cached, refreshed a session or decided what a refusal meant would be
+ * making decisions the pillar has not taken yet, inside a package every consumer
+ * compiles against.
+ *
+ * SO IT READS AND NEVER WRITES. There is no method here that creates an Application,
+ * submits evidence, approves anything or asks for an assertion. The Application API
+ * and the approval transaction do not exist yet, and a client method posting to a
+ * route nobody has implemented is worse than no method at all: it looks like a
+ * commitment, and the first consumer to call it discovers the shape by trial.
+ *
+ * WHY THE ROUTE TABLE IS HERE AT ALL. A path is part of a wire contract, and the
+ * sibling precedent publishes one for the same reason: a consumer hand-writing a URL
+ * is a consumer with a private copy of the contract. Publishing it makes a
+ * disagreement between this package and the slice that serves these routes a
+ * VERSION BUMP somebody has to make, rather than a 404 somebody debugs.
+ *
+ * NO SIDE EFFECTS ON IMPORT. Importing this module defines functions and freezes one
+ * table. It opens no connection, reads no environment variable and touches no clock.
+ *
+ * THIS SLICE EXPOSES NO ENDPOINT. §12.5's obligation — declared dimensions, figures
+ * backed by load and abuse evidence — falls on the slice that makes an endpoint
+ * externally reachable. This package is the caller's side of a conversation with a
+ * server that does not exist yet, so it declares no limit policy, and the slice
+ * that serves these routes declares one before it exposes them.
+ */
+import { parseApplicationSummary, } from "./application.js";
+import { parseCitizenNames, parseCitizenRecord, } from "./citizen.js";
+import { parseVerificationCaseSummary, } from "./evidence.js";
+import { ContractParseError } from "./parse.js";
+import { parseProvisioningCoordination, } from "./provisioning.js";
+import { parseRefusal } from "./refusal.js";
+/**
+ * The routes this contract describes.
+ *
+ * Read-only, every one of them. `GET` is stated explicitly rather than assumed,
+ * because §11.3 turns on the existence of a "side-effect-free" read and a table that
+ * left the method implicit would be one refactor away from losing the distinction.
+ */
+export const ROUTES = Object.freeze({
+    application: Object.freeze({ method: "GET", path: "/api/applications/:id" }),
+    ownCitizen: Object.freeze({ method: "GET", path: "/api/citizens/me" }),
+    ownCitizenNames: Object.freeze({
+        method: "GET",
+        path: "/api/citizens/me/names",
+    }),
+    verificationCase: Object.freeze({
+        method: "GET",
+        path: "/api/verification-cases/:id",
+    }),
+    ownProvisioningCoordination: Object.freeze({
+        method: "GET",
+        path: "/api/citizens/me/provisioning-coordination",
+    }),
+});
+/**
+ * Raised when a response is not something this contract can read at all.
+ *
+ * Distinct from a `Refusal`, which is this pillar saying no in a way the contract
+ * describes, and distinct from a `ContractParseError`, which is a well-formed
+ * response whose contents are wrong. This one means the conversation failed: a
+ * gateway answered, or the body was not JSON. A caller cannot map it to a refusal
+ * code without inventing one.
+ */
+export class ContractTransportError extends Error {
+    name = "ContractTransportError";
+    status;
+    constructor(status, rule) {
+        super(`transport: ${rule}`);
+        this.status = status;
+    }
+}
+const trimTrailingSlash = (value) => value.endsWith("/") ? value.slice(0, -1) : value;
+/**
+ * Build a URL from a route and at most one identifier.
+ *
+ * No escaping is performed and none is needed, which is a property of the
+ * identifiers rather than of this function: every branded identifier in `ids.ts` is
+ * parsed against an alphabet that excludes `/`, `?`, `#`, `:` and whitespace, so a
+ * value that reached here cannot introduce a path segment, a query or a fragment.
+ * The type system is what guarantees it arrived through a parser — this function
+ * accepts a branded identifier, and a bare `string` is not assignable to one.
+ */
+const urlFor = (baseUrl, route, identifier) => {
+    const path = identifier === undefined
+        ? route.path
+        : route.path.replace(":id", identifier);
+    return `${trimTrailingSlash(baseUrl)}${path}`;
+};
+const resolveFetch = (options) => {
+    const provided = options.fetchImpl;
+    if (provided !== undefined) {
+        return provided;
+    }
+    const ambient = globalThis.fetch;
+    if (ambient === undefined) {
+        throw new ContractTransportError(0, "no fetch implementation. Pass fetchImpl when the runtime has no global fetch");
+    }
+    return ambient;
+};
+/**
+ * Create a client.
+ *
+ * Every method returns a `ContractResult`: an `ok` branch carrying a decoded value,
+ * or a `refused` branch carrying the closed `Refusal`. A refusal is not thrown,
+ * because a refusal is an ordinary answer and an exception is how an ordinary answer
+ * gets swallowed by a `catch` written for something else.
+ *
+ * Nothing is retried. A retry policy is a decision about idempotency and about the
+ * limits of §12.5, and neither is settled for routes nobody serves yet.
+ */
+export const createIdentityClient = (options) => {
+    const performFetch = resolveFetch(options);
+    const { baseUrl, authorise } = options;
+    const read = async (route, decode, field, identifier) => {
+        const headers = authorise === undefined ? {} : await authorise();
+        const response = await performFetch(urlFor(baseUrl, route, identifier), {
+            method: route.method,
+            headers: { accept: "application/json", ...headers },
+        });
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            throw new ContractTransportError(response.status, "response body was not JSON");
+        }
+        if (response.ok) {
+            return { outcome: "ok", value: decode(body, field) };
+        }
+        try {
+            return { outcome: "refused", refusal: parseRefusal(body, "refusal") };
+        }
+        catch (error) {
+            if (error instanceof ContractParseError) {
+                throw new ContractTransportError(response.status, "response was neither a result nor a refusal this contract describes");
+            }
+            throw error;
+        }
+    };
+    return {
+        getApplication: (applicationId) => read(ROUTES.application, parseApplicationSummary, "application", applicationId),
+        getOwnCitizen: () => read(ROUTES.ownCitizen, parseCitizenRecord, "citizen"),
+        getOwnCitizenNames: () => read(ROUTES.ownCitizenNames, parseCitizenNames, "citizenNames"),
+        getVerificationCase: (verificationCaseId) => read(ROUTES.verificationCase, parseVerificationCaseSummary, "verificationCase", verificationCaseId),
+        getOwnProvisioningCoordination: () => read(ROUTES.ownProvisioningCoordination, parseProvisioningCoordination, "coordination"),
+    };
+};

package/dist/evidence.d.ts

@@ -0,0 +1,202 @@
+/**
+ * The evidence vocabulary: facts, never scores, and a method that cannot exceed
+ * what its facts support.
+ *
+ * §8.2 is the whole of this file in two sentences. "The verification provider must
+ * return **evidence facts and reason codes**, not an unqualified score or Boolean."
+ * And: "**Evidence is never overstated.** A passport MRZ read plus an unmatched
+ * selfie is not a document-and-biometric decision, and no provider's unqualified
+ * 'pass' may be recorded as one."
+ *
+ * ENFORCED TWICE.
+ *
+ * The compile-time half is `MethodSupportedBy`, a type-level function from evidence
+ * to the strongest method that evidence honestly supports. Code that knows its
+ * evidence as literals — a fixture, a test, a stub profile, the issuer assembling a
+ * claim it is about to mint — writes `MethodSupportedBy<typeof facts>` and gets a
+ * compile error rather than an overclaim. `document-and-biometric` is unreachable
+ * from evidence whose `biometricComparedToDocumentPortrait` is `false`, and there is
+ * no widening that gets there.
+ *
+ * The runtime half is `parseVerificationCaseSummary`, because a type can say nothing
+ * about a provider's JSON. It recomputes the supported method from the facts on the
+ * wire and refuses a `method` stronger than they bear — the exact case §8.2 names.
+ *
+ * WHY THE SUPPORT RULE IS WRITTEN HERE AND NOT IMPORTED.
+ *
+ * `@cayso/contracts` exports `methodForEvidence`, which answers the same question,
+ * and this package deliberately cannot use it: it holds no runtime dependency, and
+ * the coupling scan's rule C makes that mechanical by refusing a bare specifier in a
+ * value position. Two implementations of one rule is normally how they diverge, so
+ * the divergence is closed where it can be closed — `evidence.test.ts` imports
+ * Cayso's function (a test file, outside the coupling scan, using the exact-pinned
+ * development dependency) and asserts the two agree across every combination of the
+ * three facts. An upstream change to the rule fails this package's test run rather
+ * than passing silently into a consumer.
+ *
+ * The authority still belongs upstream. A verifier or issuer taking a real decision
+ * uses Cayso's function, and that is where the value dependency is taken. What lives
+ * here refuses an overstatement at a contract boundary; it does not grant an
+ * assurance.
+ *
+ * NO ROUTE IS HARD-CODED, AND THE STUB'S IDENTIFIER IS NOT IN THIS PACKAGE.
+ *
+ * §8.3 requires a "route-neutral, versioned evidence model" and warns that
+ * "hard-coding the first document reader into policy is how it becomes permanent by
+ * accident". So `EvidenceRoute` and `EvidencePolicyVersion` are opaque versioned
+ * identifiers rather than closed unions: phase one is passport-only, and a published
+ * union with one member would make that the contract every consumer compiled
+ * against. Adding a route is "a **new** evidence-policy version" (§8.3), which is a
+ * value, not a type change.
+ *
+ * The stub's route and policy version are deliberately absent for a stronger reason.
+ * §8.4 requires that "the production bundle contains neither the stub implementation
+ * nor its selection identifier". A member named for the stub in a contract package
+ * every production surface imports would place that selection identifier in every
+ * one of them. The stub names its own route, in its own package, excluded at build
+ * time — which is §8.4's "decisive control is build-time exclusion, not
+ * configuration".
+ */
+import type { VerificationEvidence, VerificationMethod } from "@cayso/contracts";
+import type { Branded } from "./brand.js";
+import { type ApplicationId, type VerificationCaseId } from "./ids.js";
+/**
+ * Which evidence route produced a case — §8.3's `evidence_route`.
+ *
+ * Opaque, so that adding a driving licence, a national identity card, an ePassport
+ * NFC route or a staff-assisted route is a new value rather than a breaking change
+ * to every consumer of this package.
+ */
+export type EvidenceRoute = Branded<"EvidenceRoute">;
+/**
+ * Which version of the evidence policy decided a case — §8.3's
+ * `evidence_policy_version`.
+ *
+ * §8.3: adding a route is "a **new** evidence-policy version — never a migration
+ * that changes the meaning of past approvals". A stored case therefore carries the
+ * version that judged it, for ever, and this pillar never reinterprets an old case
+ * under a new policy.
+ */
+export type EvidencePolicyVersion = Branded<"EvidencePolicyVersion">;
+/** An `EvidenceRoute` from a wire value, or a refusal. */
+export declare const parseEvidenceRoute: (value: string, field?: string) => EvidenceRoute;
+/** An `EvidencePolicyVersion` from a wire value, or a refusal. */
+export declare const parseEvidencePolicyVersion: (value: string, field?: string) => EvidencePolicyVersion;
+/**
+ * What §8.6's table calls an outcome: `pass`, `refer` or `fail`.
+ *
+ * Three members, and the middle one is the reason the union is closed. §8.6: "A
+ * referral is **not** an automated rejection, so it does not inherently require two
+ * reviewers." A Boolean would have had to file `refer` under one of the others, and
+ * whichever it chose would have moved the authority required to overturn it. §8.4
+ * requires the stub to return all three deterministically, which is the same three
+ * and not a development-only set.
+ */
+export type VerificationOutcome = "pass" | "refer" | "fail";
+/** Every outcome, in §8.6's order. */
+export declare const VERIFICATION_OUTCOMES: readonly VerificationOutcome[];
+/** A `VerificationOutcome` from a wire value, or a refusal. */
+export declare const parseVerificationOutcome: (value: unknown, field?: string) => VerificationOutcome;
+/**
+ * The evidence facts of one case: Cayso's three, and the two §8.1 adds.
+ *
+ * It EXTENDS `VerificationEvidence` rather than redeclaring its fields, so a value
+ * of this type is accepted anywhere Cayso's is expected and the two can never
+ * disagree about what `biometricComparedToDocumentPortrait` means. §8.2's
+ * "**Provider vocabulary stops at the adapter**" is the rule that makes this the
+ * right shape: whatever a supplier returns is normalised into these booleans by the
+ * adapter, and no provider's own vocabulary reaches a stored case or a consumer.
+ *
+ * The two additions are facts §8.1 lists as production requirements and Cayso's
+ * profile does not model, because they are this pillar's business to establish
+ * rather than Cayso's to judge. Neither strengthens the method that evidence
+ * supports — `MethodSupportedBy` ignores both, deliberately, because the method
+ * vocabulary is Cayso's and this package does not get to widen what one of its
+ * members asserts. They are recorded so that a case can say what was and was not
+ * done, which is what §8.1's table is for.
+ */
+export interface IdentityEvidenceFacts extends VerificationEvidence {
+    /**
+     * Document authenticity was established by a provider or model check, or by
+     * cryptographic chip validation. §8.1: an MRZ consistency check alone is **not**
+     * document authenticity.
+     */
+    readonly documentAuthenticityEstablished: boolean;
+    /**
+     * A presentation-attack (liveness) check was performed and recorded. §8.6: a
+     * person comparing two photographs is **not** automatically a liveness check.
+     */
+    readonly presentationAttackCheckPerformed: boolean;
+}
+/**
+ * The strongest method this evidence supports, at the type level.
+ *
+ * Written against `Extract<VerificationMethod, …>` rather than against bare string
+ * literals: if either method were renamed or removed upstream, these branches would
+ * collapse to `never` and `evidence.test.ts` would fail, rather than this package
+ * quietly continuing to speak a vocabulary Cayso no longer has.
+ *
+ * `dev-bypass` is never produced. It is not a conclusion evidence supports; it is
+ * the marker of a verification that examined nothing (§8.4: "`dev-bypass` proves
+ * nothing and never migrates as verified evidence").
+ */
+export type MethodSupportedBy<E extends VerificationEvidence> = E extends {
+    readonly identityDocumentChecked: true;
+} ? E extends {
+    readonly biometricCaptured: true;
+    readonly biometricComparedToDocumentPortrait: true;
+} ? Extract<VerificationMethod, "document-and-biometric"> : Extract<VerificationMethod, "document"> : never;
+/**
+ * The strongest method this evidence supports, at runtime, or `null` for evidence
+ * that supports none.
+ *
+ * `null` is not a failure and must not be rendered as one: it is the honest answer
+ * for a case that examined nothing yet. A caller holding `null` has nothing to
+ * assert, which is §8.2's position exactly.
+ */
+export declare const methodSupportedByEvidence: (evidence: VerificationEvidence) => VerificationMethod | null;
+/**
+ * Whether `method` is honest about `evidence` — the refusable form of §8.2.
+ *
+ * Evidence may exceed what a method asserts; it may never fall short of it. A
+ * `dev-bypass` case is honest only when nothing was examined: a bypass that claims
+ * a document was checked is an overstatement in the other direction, and the one a
+ * migration would most like to make.
+ */
+export declare const evidenceSupportsMethod: (method: VerificationMethod, evidence: VerificationEvidence) => boolean;
+/**
+ * What a verification case says, and nothing §15 forbids it to say.
+ *
+ * `verification_cases` must not hold "A bare provider score as the decision", so
+ * there is no score field, no confidence field and no threshold field; the decision
+ * is this pillar's, taken from the facts, under a named policy version. §8.8 makes
+ * the same point about suppliers: "**Disqualifying: 'score only'**". A provider's
+ * own case reference is carried, because a case must be traceable to the supplier
+ * that produced it, and it is opaque here.
+ */
+export interface VerificationCaseSummary {
+    readonly verificationCaseId: VerificationCaseId;
+    readonly applicationId: ApplicationId;
+    readonly outcome: VerificationOutcome;
+    readonly evidenceRoute: EvidenceRoute;
+    readonly evidencePolicyVersion: EvidencePolicyVersion;
+    readonly facts: IdentityEvidenceFacts;
+    /**
+     * The method these facts support and the decision was recorded under. Refused by
+     * `parseVerificationCaseSummary` when the facts do not bear it.
+     */
+    readonly method: VerificationMethod;
+    /** The supplier's own reference for this case, or `null`. Opaque; never interpreted here. */
+    readonly providerCaseReference: string | null;
+}
+/** The evidence facts from a wire value, or a refusal. */
+export declare const parseIdentityEvidenceFacts: (value: unknown, field?: string) => IdentityEvidenceFacts;
+/**
+ * A `VerificationCaseSummary` from a wire value, or a refusal.
+ *
+ * The refusal that matters is the last one: a `method` the facts do not bear is
+ * refused, naming the method the facts actually support. That is §8.2's "A passport
+ * MRZ read plus an unmatched selfie is not a document-and-biometric decision",
+ * enforced where a provider's response enters this pillar.
+ */
+export declare const parseVerificationCaseSummary: (value: unknown, field?: string) => VerificationCaseSummary;