@percayso/identity-contracts 0.1.0

package/dist/assertion.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The assertion vocabulary: who may be the subject, what a request may ask for, and
+ * what an issuance record may keep afterwards.
+ *
+ * CONTEXT.md states the rule this file exists to hold: "The Citizen ID is the only
+ * identifier that may appear as an assertion subject." §8.7 lists the structural
+ * tests phase one relies on instead of the phase-two binding table, and two of them
+ * are about this type — "no Piper subject or deployment identifier appears in the
+ * Citizen-creation input" and "no assertion derives `sub` from a Piper identifier".
+ *
+ * ENFORCED TWICE.
+ *
+ * `AssertionRequest.subject` is a `CitizenId`. A `PiperPlatformSubject` is a
+ * different brand and is not assignable to it — in either direction, with no
+ * conversion function anywhere in this package — so an issuer that tried to pass one
+ * through does not compile. `parseAssertionRequest` is the runtime twin: the subject
+ * arrives as a string like everything else on a wire, and only `readCitizenId`
+ * accepts it.
+ *
+ * `DeploymentId` is present and carries nothing. §14.4: "Possession of any
+ * deployment credential is insufficient without independently verifiable Citizen
+ * proof", and Appendix B rejects "Piper deployment class as an authorisation basis"
+ * outright. It is recorded because §15's `deployments` row wants registration,
+ * admission and revocation as separate concepts — not because it authorises
+ * anything. Nothing in this package reads it, and no function here takes one where a
+ * subject is expected.
+ *
+ * SHORT-LIVED, SINGLE-USE, OPERATION-SCOPED — AND WHICH OF THE THREE THIS PACKAGE
+ * CAN HOLD.
+ *
+ * Operation-scoped it holds completely: `scope` is a non-empty tuple type, so an
+ * empty scope is not expressible, and the decoder refuses an empty array. An empty
+ * scope authorises nothing, and a caller who sends one has almost certainly built
+ * the list dynamically and lost it.
+ *
+ * Short-lived it holds partially and says so. `expiresAt` must be after `issuedAt`,
+ * which is checkable here; the CEILING on that interval is
+ * `MAX_ASSERTION_LIFETIME_SECONDS`, a runtime export of `@cayso/contracts` that this
+ * package may not value-import — it holds no runtime dependency, and the coupling
+ * scan's rule C enforces that mechanically. Restating the figure here would be
+ * exactly what the canon forbids: a number copied out of its one home, going stale
+ * in a published package that every consumer compiles against. The issuer takes
+ * that value dependency and enforces the ceiling. This package refuses the nonsense
+ * and leaves the figure where it lives.
+ *
+ * Single-use it does not hold at all. Replay refusal needs recorded state — §15's
+ * `assertion_issuance` row, with its unique `jti` or one-way representation — and
+ * this package has no store and no clock. The vocabulary is here; the enforcement is
+ * the issuer's and the verifier's.
+ */
+import type { AssertionClaims, ContractOperation, Millis } from "@cayso/contracts";
+import { type CitizenId, type DeploymentId } from "./ids.js";
+/**
+ * The operations an assertion may be scoped to.
+ *
+ * Cayso's `ContractOperation`, imported and not restated: the scope of an assertion
+ * this pillar mints is read by Cayso's gate, so a second vocabulary would be two
+ * lists that disagree the first time one of them grows. `assertion.test.ts` asserts
+ * this package's runtime list is exactly Cayso's `CONTRACT_OPERATIONS`.
+ */
+export type AssertionOperation = ContractOperation;
+/**
+ * The operations, as a value this package can check a wire scope against.
+ *
+ * `CONTRACT_OPERATIONS` is a runtime export of `@cayso/contracts` and this package
+ * may not value-import it (coupling scan rule C). The list is therefore written once
+ * here and pinned to Cayso's by a test, in both directions, so an operation added or
+ * removed upstream fails this package's test run rather than passing through it.
+ */
+export declare const ASSERTION_OPERATIONS: readonly AssertionOperation[];
+/** A non-empty scope. The type cannot express the empty list; the decoder refuses it. */
+export type AssertionScope = readonly [
+    AssertionOperation,
+    ...AssertionOperation[]
+];
+/**
+ * What an issuer is asked for.
+ *
+ * `subject` is a `CitizenId` and nothing else. `audience` is the literal `"cayso"`,
+ * matching `AssertionClaims.aud` in `@cayso/contracts` — a request that could name
+ * its own audience is a request that could have an assertion minted for a relying
+ * party nobody registered, and §14.4 requires that a modified downloaded Instance
+ * "cannot … change its audience, redirect URI, operation or onboarding target".
+ */
+export interface AssertionRequest {
+    readonly subject: CitizenId;
+    readonly audience: AssertionClaims["aud"];
+    readonly scope: AssertionScope;
+    /**
+     * The installation presenting the request, or `null`. Recorded, never trusted:
+     * it grants nothing, narrows nothing and substitutes for no part of Citizen proof.
+     */
+    readonly deploymentId: DeploymentId | null;
+}
+/** An `AssertionRequest` from a wire value, or a refusal. */
+export declare const parseAssertionRequest: (value: unknown, field?: string) => AssertionRequest;
+/** Whether issuance happened. A closed pair; there is no third answer and no "partial". */
+export type IssuanceOutcome = "issued" | "refused";
+/**
+ * What §15's `assertion_issuance` row keeps, and nothing from its "must not hold"
+ * column.
+ *
+ * There is no field for the encoded assertion, its signature, a legal identity value
+ * or a deployment secret — §15 forbids all four, and §14.4's disclosure criterion
+ * repeats it for logs, traces and analytics. `jtiDigest` is §15's "Unique `jti` or a
+ * one-way representation": a digest is enough to refuse a replay and is not enough
+ * to reconstruct anything.
+ *
+ * `safeReasonCode` is a `RefusalCode`-shaped idea deliberately typed as the closed
+ * refusal union's member set rather than free text — see `refusal.ts` for why a
+ * reason that can hold prose eventually holds a provider's payload.
+ */
+export interface AssertionIssuanceRecord {
+    readonly jtiDigest: string;
+    readonly subject: CitizenId;
+    readonly scope: AssertionScope;
+    readonly audience: AssertionClaims["aud"];
+    /** The `kid` of the key that signed it. An identifier, never the key. */
+    readonly signingKeyId: string;
+    readonly issuedAt: Millis;
+    readonly expiresAt: Millis;
+    readonly outcome: IssuanceOutcome;
+}
+/** An `AssertionIssuanceRecord` from a wire value, or a refusal. */
+export declare const parseAssertionIssuanceRecord: (value: unknown, field?: string) => AssertionIssuanceRecord;

package/dist/assertion.js

@@ -0,0 +1,221 @@
+/**
+ * The assertion vocabulary: who may be the subject, what a request may ask for, and
+ * what an issuance record may keep afterwards.
+ *
+ * CONTEXT.md states the rule this file exists to hold: "The Citizen ID is the only
+ * identifier that may appear as an assertion subject." §8.7 lists the structural
+ * tests phase one relies on instead of the phase-two binding table, and two of them
+ * are about this type — "no Piper subject or deployment identifier appears in the
+ * Citizen-creation input" and "no assertion derives `sub` from a Piper identifier".
+ *
+ * ENFORCED TWICE.
+ *
+ * `AssertionRequest.subject` is a `CitizenId`. A `PiperPlatformSubject` is a
+ * different brand and is not assignable to it — in either direction, with no
+ * conversion function anywhere in this package — so an issuer that tried to pass one
+ * through does not compile. `parseAssertionRequest` is the runtime twin: the subject
+ * arrives as a string like everything else on a wire, and only `readCitizenId`
+ * accepts it.
+ *
+ * `DeploymentId` is present and carries nothing. §14.4: "Possession of any
+ * deployment credential is insufficient without independently verifiable Citizen
+ * proof", and Appendix B rejects "Piper deployment class as an authorisation basis"
+ * outright. It is recorded because §15's `deployments` row wants registration,
+ * admission and revocation as separate concepts — not because it authorises
+ * anything. Nothing in this package reads it, and no function here takes one where a
+ * subject is expected.
+ *
+ * SHORT-LIVED, SINGLE-USE, OPERATION-SCOPED — AND WHICH OF THE THREE THIS PACKAGE
+ * CAN HOLD.
+ *
+ * Operation-scoped it holds completely: `scope` is a non-empty tuple type, so an
+ * empty scope is not expressible, and the decoder refuses an empty array. An empty
+ * scope authorises nothing, and a caller who sends one has almost certainly built
+ * the list dynamically and lost it.
+ *
+ * Short-lived it holds partially and says so. `expiresAt` must be after `issuedAt`,
+ * which is checkable here; the CEILING on that interval is
+ * `MAX_ASSERTION_LIFETIME_SECONDS`, a runtime export of `@cayso/contracts` that this
+ * package may not value-import — it holds no runtime dependency, and the coupling
+ * scan's rule C enforces that mechanically. Restating the figure here would be
+ * exactly what the canon forbids: a number copied out of its one home, going stale
+ * in a published package that every consumer compiles against. The issuer takes
+ * that value dependency and enforces the ceiling. This package refuses the nonsense
+ * and leaves the figure where it lives.
+ *
+ * Single-use it does not hold at all. Replay refusal needs recorded state — §15's
+ * `assertion_issuance` row, with its unique `jti` or one-way representation — and
+ * this package has no store and no clock. The vocabulary is here; the enforcement is
+ * the issuer's and the verifier's.
+ */
+import { parseDeploymentId, readCitizenId, } from "./ids.js";
+import { readArray, readClosedRecord, readString, refuseValue, } from "./parse.js";
+/**
+ * The operations, as a value this package can check a wire scope against.
+ *
+ * `CONTRACT_OPERATIONS` is a runtime export of `@cayso/contracts` and this package
+ * may not value-import it (coupling scan rule C). The list is therefore written once
+ * here and pinned to Cayso's by a test, in both directions, so an operation added or
+ * removed upstream fails this package's test run rather than passing through it.
+ */
+export const ASSERTION_OPERATIONS = Object.freeze([
+    "read-own-wallet",
+    "read-purchase-result",
+    "authorise-purchase",
+    "cancel-purchase",
+    "provision-citizenship",
+    "read-own-citizenship",
+]);
+/**
+ * A scope that is known to be non-empty, or a refusal.
+ *
+ * The check and the type agree by construction: the first element is read out and
+ * refused when it is absent, so the tuple is built from a value the compiler has
+ * seen rather than asserted into existence by a cast.
+ */
+const asScope = (operations, field) => {
+    const [first, ...rest] = operations;
+    if (first === undefined) {
+        refuseValue(field, "must name at least one operation. An empty scope authorises nothing");
+    }
+    return [first, ...rest];
+};
+const REQUEST_FIELDS = Object.freeze([
+    "subject",
+    "audience",
+    "scope",
+    "deploymentId",
+]);
+/**
+ * Field names by which a caller might try to supply the subject from somewhere
+ * other than an established Percayso ID session.
+ *
+ * §14.4: "No browser, Piper API or installation registration can substitute a
+ * Citizen through path, query, body, header or cookie." A request carrying one of
+ * these is refused by name, because the caller needs to know the substitution was
+ * seen and rejected rather than ignored. The `PiperPlatformSubject` type in `ids.ts`
+ * exists precisely so that such a value has somewhere to live that is NOT here.
+ */
+const SUBJECT_SUBSTITUTION_FIELDS = Object.freeze([
+    "piperSubject",
+    "piperPlatformSubject",
+    "localSubject",
+    "sub",
+    "onBehalfOf",
+    "actAs",
+    "impersonate",
+]);
+/** An `AssertionRequest` from a wire value, or a refusal. */
+export const parseAssertionRequest = (value, field = "assertionRequest") => {
+    const record = readClosedRecord(value, field, [
+        ...REQUEST_FIELDS,
+        ...SUBJECT_SUBSTITUTION_FIELDS,
+    ]);
+    for (const key of Object.keys(record)) {
+        if (SUBJECT_SUBSTITUTION_FIELDS.includes(key)) {
+            refuseValue(`${field}.${key}`, "cannot supply the subject. The Citizen ID is the only identifier that may appear as an assertion subject, and it comes from this pillar's own session (§8.7, §14.4)");
+        }
+    }
+    const audience = readString(record, field, "audience");
+    if (audience !== "cayso") {
+        refuseValue(`${field}.audience`, "must be cayso. A caller does not choose the audience an assertion is minted for (§14.4)");
+    }
+    const scope = readArray(record, field, "scope", (entry, elementField) => {
+        if (typeof entry !== "string" ||
+            !ASSERTION_OPERATIONS.includes(entry)) {
+            refuseValue(elementField, "must be an operation of the Cayso contract");
+        }
+        return entry;
+    });
+    const deploymentId = record["deploymentId"];
+    return {
+        subject: readCitizenId(record, field, "subject"),
+        audience: "cayso",
+        scope: asScope(scope, `${field}.scope`),
+        deploymentId: deploymentId === null
+            ? null
+            : parseDeploymentId(readString(record, field, "deploymentId"), `${field}.deploymentId`),
+    };
+};
+const ISSUANCE_FIELDS = Object.freeze([
+    "jtiDigest",
+    "subject",
+    "scope",
+    "audience",
+    "signingKeyId",
+    "issuedAt",
+    "expiresAt",
+    "outcome",
+]);
+/**
+ * Field names carrying signing material or the encoded assertion itself.
+ *
+ * These spellings appear here as names this contract REFUSES. They are not this
+ * pillar's vocabulary for an Assertion — CONTEXT.md's banned-word table settles that
+ * — and a record that could carry one would put it in every audit export.
+ *
+ * THE LIST DELIBERATELY STOPS SHORT OF NAMING A PER-DEPLOYMENT SECRET. §14.4 is not
+ * that such a field must be refused; it is that no such thing exists — a Piper
+ * Platform deployment is a public client and holds no secret. Writing the name here
+ * to refuse it would put the term into the repository, where the credential scan
+ * finds it and is right to. A wire value carrying one is refused anyway, by
+ * `readClosedRecord`, as a field this contract type does not have.
+ */
+const FORBIDDEN_MATERIAL_FIELDS = Object.freeze([
+    "assertion",
+    "encoded",
+    "signature",
+    "privateKey",
+    "signingKey",
+    "legalName",
+    "dateOfBirth",
+]);
+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;
+};
+/** An `AssertionIssuanceRecord` from a wire value, or a refusal. */
+export const parseAssertionIssuanceRecord = (value, field = "issuance") => {
+    const record = readClosedRecord(value, field, [
+        ...ISSUANCE_FIELDS,
+        ...FORBIDDEN_MATERIAL_FIELDS,
+    ]);
+    for (const key of Object.keys(record)) {
+        if (FORBIDDEN_MATERIAL_FIELDS.includes(key)) {
+            refuseValue(`${field}.${key}`, "is signing material, an encoded credential or a legal identity value. An issuance record holds none of them (§14.4, §15)");
+        }
+    }
+    const audience = readString(record, field, "audience");
+    if (audience !== "cayso") {
+        refuseValue(`${field}.audience`, "must be cayso");
+    }
+    const scope = readArray(record, field, "scope", (entry, elementField) => {
+        if (typeof entry !== "string" ||
+            !ASSERTION_OPERATIONS.includes(entry)) {
+            refuseValue(elementField, "must be an operation of the Cayso contract");
+        }
+        return entry;
+    });
+    const issuedAt = readMillis(record, field, "issuedAt");
+    const expiresAt = readMillis(record, field, "expiresAt");
+    if (expiresAt <= issuedAt) {
+        refuseValue(`${field}.expiresAt`, "must be after issuedAt. How much after is bounded by the Cayso contract's published maximum lifetime, which the issuer enforces and this package does not restate");
+    }
+    const outcome = readString(record, field, "outcome");
+    if (outcome !== "issued" && outcome !== "refused") {
+        refuseValue(`${field}.outcome`, "must be issued or refused");
+    }
+    return {
+        jtiDigest: readString(record, field, "jtiDigest"),
+        subject: readCitizenId(record, field, "subject"),
+        scope: asScope(scope, `${field}.scope`),
+        audience: "cayso",
+        signingKeyId: readString(record, field, "signingKeyId"),
+        issuedAt,
+        expiresAt,
+        outcome: outcome,
+    };
+};

package/dist/brand.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The brand, which is how this package says that two strings are not each other.
+ *
+ * Several of the canon's hardest invariants are statements about WHICH identifier
+ * may appear WHERE, and every one of those identifiers is a string on the wire. A
+ * Citizen ID, a Piper Platform subject and a canonical Handle are all opaque text;
+ * nothing structural distinguishes them, so nothing structural can stop one being
+ * passed where another belongs. CONTEXT.md's rule — "the Citizen ID is the only
+ * identifier that may appear as an assertion subject" — would then be a sentence in
+ * a document rather than something a compiler can hold.
+ *
+ * A brand fixes that half. `CitizenId` and `PiperPlatformSubject` are both `string`
+ * at runtime and are mutually unassignable at compile time, so a function that asks
+ * for one cannot be handed the other, and there is no widening that quietly works.
+ *
+ * It is only half, deliberately. A brand is erased, so it says nothing about a value
+ * that arrived over a wire — which is why every branded type in `ids.ts` also has a
+ * parser, and why the parser is the layer a reviewer should read second.
+ */
+declare const brand: unique symbol;
+/**
+ * An opaque string that is only itself.
+ *
+ * `Name` never appears at runtime and is never read; it exists so that two brands
+ * declared with different names are different types.
+ */
+export type Branded<Name extends string> = string & {
+    readonly [brand]: Name;
+};
+export {};

package/dist/brand.js

@@ -0,0 +1,20 @@
+/**
+ * The brand, which is how this package says that two strings are not each other.
+ *
+ * Several of the canon's hardest invariants are statements about WHICH identifier
+ * may appear WHERE, and every one of those identifiers is a string on the wire. A
+ * Citizen ID, a Piper Platform subject and a canonical Handle are all opaque text;
+ * nothing structural distinguishes them, so nothing structural can stop one being
+ * passed where another belongs. CONTEXT.md's rule — "the Citizen ID is the only
+ * identifier that may appear as an assertion subject" — would then be a sentence in
+ * a document rather than something a compiler can hold.
+ *
+ * A brand fixes that half. `CitizenId` and `PiperPlatformSubject` are both `string`
+ * at runtime and are mutually unassignable at compile time, so a function that asks
+ * for one cannot be handed the other, and there is no widening that quietly works.
+ *
+ * It is only half, deliberately. A brand is erased, so it says nothing about a value
+ * that arrived over a wire — which is why every branded type in `ids.ts` also has a
+ * parser, and why the parser is the layer a reviewer should read second.
+ */
+export {};

package/dist/citizen.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 type { Millis, VerificationMethod } from "@cayso/contracts";
+import { type ApplicationSummary, type ApprovedApplication } from "./application.js";
+import { type CitizenId, type CommunityEmailAddress, type DisplayHandle, type VerificationCaseId } from "./ids.js";
+/**
+ * The Citizen statuses of §5.2 — three, and the third one's meaning is not settled.
+ *
+ * `closed` is carried because the canon carries it, and deliberately without any
+ * statement of what it entails: the meaning and duration of `closed` is a
+ * Community-wide question that has not been settled. Until it is, closure is
+ * reversible by policy — so nothing in this package treats `closed` as terminal, and
+ * no predicate here says it is.
+ */
+export type CitizenStatus = "active" | "suspended" | "closed";
+/** Every Citizen status, in §5.2's order. */
+export declare const CITIZEN_STATUSES: readonly CitizenStatus[];
+/**
+ * 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 declare const parseCitizenStatus: (value: unknown, field?: string) => CitizenStatus;
+/**
+ * The Citizen record of §15, and nothing its "must not hold" column forbids.
+ *
+ * `assuranceProfileVersion` is a `string` because that is what
+ * `AssertionClaims.assuranceProfileVersion` is in `@cayso/contracts` — narrowing it
+ * to a union here would be this package inventing a rule about another pillar's
+ * field, and the one profile version that exists today is Cayso's value to publish,
+ * not ours to copy. `verificationMethod` is Cayso's `VerificationMethod` for the
+ * same reason, imported rather than restated: two closed unions describing one
+ * vocabulary diverge on the first addition, and the one that diverges silently is
+ * the one nobody is looking at.
+ */
+export interface CitizenRecord {
+    readonly citizenId: CitizenId;
+    readonly status: CitizenStatus;
+    /** The verification case that justified approval. §15 requires the Citizen to be able to name it. */
+    readonly approvedVerificationCaseId: VerificationCaseId;
+    /** The assurance profile the approval was assessed under. Cayso's field, Cayso's vocabulary. */
+    readonly assuranceProfileVersion: string;
+    /** How the human was verified. Never widened, never inferred from the Citizen's age or activity. */
+    readonly verificationMethod: VerificationMethod;
+    readonly createdAt: Millis;
+}
+/** A `CitizenRecord` from a wire value, or a refusal. */
+export declare const parseCitizenRecord: (value: unknown, field?: string) => CitizenRecord;
+/**
+ * What a Citizen is called, as distinct from what a Citizen IS.
+ *
+ * §14.4: "A Handle or email address never appears as a Cayso ledger identity and is
+ * never the stable Citizen ID." The three identifiers here are three different
+ * branded types, so the one that may be an assertion subject cannot be substituted
+ * by either of the others, in either direction, at any call site — and the Handle
+ * and the address are mutually unassignable too, which stops the other likely slip.
+ *
+ * They are separate fields rather than one identity blob because §15 keeps them in
+ * separate tables with their own state and change history: a Handle is renameable,
+ * and the address is its **own** identifier with its own lifecycle. A consumer that
+ * cached this record cached a name, not a Citizen.
+ */
+export interface CitizenNames {
+    readonly citizenId: CitizenId;
+    readonly handle: DisplayHandle;
+    readonly communityEmailAddress: CommunityEmailAddress;
+}
+/** A `CitizenNames` from a wire value, or a refusal. */
+export declare const parseCitizenNames: (value: unknown, field?: string) => CitizenNames;
+/**
+ * The only shape from which a Citizen record may be created.
+ *
+ * The `approvedApplication` field is required and its type cannot be satisfied by an
+ * Application in any other state, which is §14.4's "No route, script, production
+ * fixture or flag creates a Citizen outside an Application" made structural. A
+ * fixture that wants a Citizen must produce an approved Application first; there is
+ * no shorter path in this package, and adding one would be visible as a new exported
+ * type rather than as a flag.
+ *
+ * It deliberately carries no status. A newly created Citizen is `active` — §5.2
+ * leaves no other reading, since `suspended` and `closed` are consequences of later
+ * decisions — and letting a caller choose would let a creation path produce a
+ * Citizen who was born suspended.
+ */
+export interface CitizenCreation {
+    readonly approvedApplication: ApprovedApplication;
+    readonly citizenId: CitizenId;
+    readonly assuranceProfileVersion: string;
+    readonly verificationMethod: 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 declare const parseCitizenCreation: (value: unknown, field?: string) => CitizenCreation;
+/**
+ * Where a person stands, as one discriminated union rather than three flags.
+ *
+ * §5.1 draws exactly this: `Visitor ──application created──▶ Applicant ──approval──▶
+ * Citizen`. Modelling it as a union is what makes "an Applicant is not a partial
+ * Citizen" hold at compile time — the `applicant` branch has no Citizen field to
+ * leave null, the `citizen` branch has no Application state to inspect, and no value
+ * can be in two branches at once. Three optional fields on one object would have
+ * permitted all eight combinations, including the partial Citizen §5.1 says does not
+ * exist.
+ *
+ * The `visitor` branch carries nothing at all, deliberately: a Visitor is a person
+ * this pillar knows nothing about, and a Visitor identifier would be the first step
+ * towards knowing something it has no basis to record.
+ */
+export type Personhood = {
+    readonly stage: "visitor";
+} | {
+    readonly stage: "applicant";
+    readonly application: ApplicationSummary;
+} | {
+    readonly stage: "citizen";
+    readonly citizen: CitizenRecord;
+    readonly names: CitizenNames;
+};