@oimlsmart/platform-server 0.1.0

package/src/store.ts

@@ -0,0 +1,1826 @@
+// ═══════════════════════════════════════════════════════════════════
+// The server-store seam (TODO.cs-e2e/14 — the Cloudflare deployment).
+//
+// The routes never talk to a database driver directly: they go through
+// the ServerStore, an ASYNC contract with two implementations:
+//
+//   - SQLite (node, self-hosted): sqlite-server-store.ts wraps the
+//     pre-existing sync modules (store.ts / entities.ts) — better-sqlite3
+//     stays behind this interface, so the Worker bundle never imports
+//     it;
+//   - D1 (Cloudflare Workers): d1-store.ts implements the same surface
+//     against the D1 binding.
+//
+// The store is chosen by BINDING PRESENCE at the composition root: the
+// Worker entry installs the D1 store when env.DB is bound (the same
+// profile pattern ENTITY_BACKEND uses for the client); the node entry
+// (server/index.ts) and the node scripts/tests install the SQLite one.
+//
+// This module is WORKER-SAFE: no node built-ins, no driver imports —
+// every platform carries it.
+// ═══════════════════════════════════════════════════════════════════
+
+/** The INITIAL role/org for an OAuth-provisioned account
+ *  (findOrCreateOAuthUser): applied ONLY when the account is created —
+ *  an existing account keeps its locally assigned role/org (the
+ *  admin's users-section decisions stand, TODO.federation/12). Absent:
+ *  the historical defaults (role 'user', org null). */
+export interface OAuthInitialAssignment {
+  role?: string
+  orgId?: string | null
+}
+
+export interface AuthUserPayload {
+  id: string
+  email: string
+  name: string
+  role: string
+  /** The FULL assigned role set (TODO.federation/12 RBAC) — `role` stays
+   *  the section-gating primary; permissions resolve over this set
+   *  (absent = the primary role only). */
+  roles?: string[]
+  orgId: string | null
+  avatarUrl?: string
+  /** TODO.identity/04: the account's sign-in provider family ('demo',
+   *  'github', 'oidc', the OP's account provider) — projected from the
+   *  row by the row-backed reads (undefined where a constructor does not
+   *  know it). The SSO cutover's moved-account guard reads it. */
+  provider?: string
+  /** TODO.identity/06: the primary address's verification state
+   *  (users.email_verified_at; undefined on stores that do not project
+   *  it, null = never verified). The account console shows it honestly. */
+  emailVerifiedAt?: string | null
+  /** TODO.identity-sso/02+03: the SESSION's authentication provenance
+   *  (sessions.amr — the RFC 8176 values: 'pwd', 'otp', 'webauthn', 'hwk',
+   *  plus the OP-private 'recovery'). Projected by the session-backed
+   *  read (getSessionUser) only; ABSENT = no OP-side credential event
+   *  recorded (an upstream-provider sign-in, a legacy row). */
+  amr?: string[]
+}
+
+// ── identity federation (TODO.federation/10) ─────────────────────────
+
+/** The admin approval queue's row: an SSO-authenticated user no claim
+ *  mapping rule matched (and no defaultRole is declared) — no account,
+ *  no session, until an administrator approves with a role (+ org) or
+ *  rejects. UNIQUE per (issuer, sub): a repeat sign-in refreshes
+ *  last_seen, never duplicates. */
+export interface IdentityApproval {
+  id: string
+  email: string
+  name: string
+  /** The issuing IdP (the configured issuer URL). */
+  issuer: string
+  /** The IdP's subject id. */
+  sub: string
+  /** The claims snapshot shown to the deciding admin (JSON). */
+  claimsJson: string | null
+  status: 'pending' | 'approved' | 'rejected'
+  decidedRole: string | null
+  decidedOrg: string | null
+  decidedBy: string | null
+  createdAt: string
+  lastSeen: string
+  decidedAt: string | null
+}
+
+/** The RP's one-time OIDC sign-in state (TODO.identity/04): the nonce +
+ *  the PKCE verifier for one /signin/oidc → /callback/oidc round trip,
+ *  store-backed (the sso_states table) so the Worker's isolates share
+ *  it. Consumed atomically — a replay answers null. */
+export interface SsoSignInState {
+  state: string
+  nonce: string
+  verifier: string
+  expiresAt: string
+}
+
+/** The admin view of a user (TODO.federation/12 — the instance settings
+ *  users section + the users API). */
+export interface UserAdminRow {
+  id: string
+  email: string
+  name: string
+  /** The section-gating primary role. */
+  role: string
+  /** The full assigned role set (drives permissions). */
+  roles: string[]
+  orgId: string | null
+  active: boolean
+  provider: string
+  lastLogin: string | null
+  /** TODO.identity/06: the primary address's verification state
+   *  (users.email_verified_at; null = never verified). */
+  emailVerifiedAt?: string | null
+}
+
+export interface EntityRow {
+  store: string
+  id: string
+  org_id: string | null
+  data: string
+  updated_at: string
+}
+
+// ── federation peers (TODO.federation/04) ────────────────────────────
+
+/** A pinned federation peer: the counterparty instance's descriptor,
+ *  fetched + validated + pinned (or pasted out-of-band). The registry
+ *  is the intake's trust base beyond locally-registered org keys — a
+ *  REVOKED peer's keys never verify. Revocation flips status (the row
+ *  stays: the audit + the revocations list carry the history). */
+export interface FederationPeer {
+  /** The peer's descriptor instance.id (globally stable). */
+  id: string
+  name: string
+  /** JSON array of 'hub' | 'ia' | 'tl'. */
+  roles: string
+  /** Where the descriptor was pinned from (null for a pure manual paste). */
+  descriptorUrl: string | null
+  /** The pinned descriptor, whole (JSON). */
+  descriptorJson: string
+  pinnedVia: 'url' | 'manual' | 'directory'
+  /** 'verified' = the pin path probed a live endpoint; 'unverified' = the
+   *  out-of-band paste (documented honestly in the UI). */
+  connectivity: 'verified' | 'unverified'
+  status: 'active' | 'revoked'
+  addedAt: string
+  addedBy: string | null
+  refreshedAt: string | null
+  revokedAt: string | null
+  revokedBy: string | null
+}
+
+export interface EntityChange {
+  seq: number
+  store: string
+  type: 'persist' | 'remove'
+  id: string
+  at: string
+}
+
+// ── the platform event store (TODO.notify/01) ────────────────────────
+
+/** A notifiable platform event (TODO.notify/00's event model): one row
+ *  per DECLARED act (the catalog is deliberate — not every write is an
+ *  event). The hierarchical key `<domain>/<entity-id>/<action>`
+ *  (`certificate/crt-acme-lc/issued`) is SPLIT into columns so the
+ *  subscription grammar's prefixes resolve in SQL
+ *  (`WHERE domain = ? AND entity_id = ?`), never a string scan; the
+ *  composed key is derived at read, never stored. `payload` is the JSON
+ *  envelope the catalog row declares (the summary line, the deep link,
+ *  the actors, the entity's store for the read-time visibility gate).
+ *  `seq` is the feed cursor (the entity_changes journal's pattern). */
+export interface PlatformEvent {
+  seq: number
+  id: string
+  domain: string
+  entityId: string
+  action: string
+  payload: string
+  at: string
+}
+
+/** The key pattern's SQL legs: a subscription pattern (`application/**`,
+ *  `certificate` + `issued` across the domain, one entity's
+ *  `test-run/asg-…-001/**`) compiles to the columns it pins; absent legs
+ *  stay free. */
+export interface EventKeyFilter {
+  domain?: string
+  entityId?: string
+  action?: string
+}
+
+// ── the notification subscriptions store (TODO.notify/02) ────────────
+
+/** The rule row's mode: 'subscribe' adds the user to the candidates of
+ *  every event the pattern covers; 'mute' removes them (the pattern-level
+ *  "unwatch" — the per-entity mute rows carry the thread-level one). */
+export type NotifyRuleMode = 'subscribe' | 'mute'
+
+/** A per-user subscription rule (TODO.notify/00's GitHub shape): the
+ *  authored `pattern` in the catalog's grammar (`application/**`,
+ *  `certificate` + `issued` across the domain, one entity's
+ *  `test-run/asg-…-001/**`, or an exact key)
+ *  with its pinned legs SPLIT into columns (domain always pinned;
+ *  entity_id/action NULL = the wild leg) so the recipient resolution's
+ *  reverse match — EVERY user's rules covering one event — resolves in
+ *  SQL (`WHERE domain = ? AND (entity_id IS NULL OR entity_id = ?) …`),
+ *  never a string scan. channel_overrides is the subscribe row's
+ *  per-rule email override (JSON `{ "email": "immediate"|"digest"|"off"
+ *  }`; NULL = the category preference rules on); a mute row never
+ *  carries one. UNIQUE (user_id, pattern). */
+export interface NotifyRule {
+  id: string
+  userId: string
+  pattern: string
+  domain: string
+  entityId: string | null
+  action: string | null
+  mode: NotifyRuleMode
+  channelOverrides: string | null
+  createdAt: string
+}
+
+/** The thread-level mute (TODO.notify/00: the "unwatch this thread" of
+ *  the model — the entity-page bell's Muted state and the email
+ *  footer's one-click unsubscribe both set it). Wins over every
+ *  candidate class, subscriptions included; the access is unchanged. */
+export interface NotifyEntityMute {
+  id: string
+  userId: string
+  domain: string
+  entityId: string
+  createdAt: string
+}
+
+/** The per-category email posture (TODO.notify/00's channel split): the
+ *  inbox always carries the event; 'immediate' emails at once, 'digest'
+ *  holds for the daily digest, 'off' stays in-app. */
+export type NotifyChannelPreference = 'immediate' | 'digest' | 'off'
+
+/** The user's preferences row: `channels` is the JSON map
+ *  { "<domain>": "immediate"|"digest"|"off" } over the catalog's
+ *  domains; a domain ABSENT falls back to the catalog row's own email
+ *  default. One row per user, written at first preference write. */
+export interface NotifyPreferences {
+  userId: string
+  channels: string
+  updatedAt: string
+}
+
+// ── the inbox state (TODO.notify/03) ─────────────────────────────────
+
+/** The per-user per-event inbox marker (TODO.notify/00's "the inbox
+ *  state (D1): per-user per-event state (read / done / saved) written
+ *  lazily at read"): one row per (user, event), created at the first act
+ *  on the inbox row. `readAt` stamps the mark-read (NULL = unread);
+ *  `doneAt` stamps the archive (NULL = in the inbox — a done row leaves
+ *  the feed, the marker keeps the state). 'saved' joins with wave 05.
+ *  The feed is COMPUTED at read (events × the user's rules × the
+ *  visibility gate); this table is the state that computation joins. A
+ *  marker on a wiped event never joins (the user's state is their own,
+ *  never the workflow's — the subscriptions store's posture). */
+export interface NotifyInboxState {
+  userId: string
+  eventId: string
+  readAt: string | null
+  doneAt: string | null
+  createdAt: string
+}
+
+// ── the OIDC Provider (TODO.identity/01) ─────────────────────────────
+
+/** A registered relying party (an instance allowed to request tokens).
+ *  secretHash NULL = a public client (PKCE carries the proof);
+ *  claimsPolicy is the parsed claims-policy JSON — `claims` names which
+ *  claims the ID token carries for this client, and the OPTIONAL
+ *  `roles` allowlist (TODO.identity/03) bounds WHICH roles those claims
+ *  may carry: the OP never emits a role the client is not configured
+ *  to receive (absent = the policy does not bound the role set). */
+export interface OidcClient {
+  clientId: string
+  name: string
+  secretHash: string | null
+  /** The exact redirect URIs (string equality — no pattern matching). */
+  redirectUris: string[]
+  /** Parsed claims policy (null = profile+email claims only — no role
+   *  claims leave the OP). */
+  claimsPolicy: OidcClientClaimsPolicy | null
+  /** The SSO-home launch metadata (null = the client never appears on
+   *  the launcher). Managed through setOidcClientLaunch — the registry
+   *  upsert never touches it, so a re-seed keeps the admin's edits. */
+  launch: OidcClientLaunch | null
+  status: 'active' | 'disabled'
+  createdAt: string
+  createdBy: string | null
+}
+
+/** The client registry's claims policy (TODO.identity/01 + /03). */
+export interface OidcClientClaimsPolicy {
+  /** The claims the ID token carries for this client (roles, groups,
+   *  org — profile+email ride the scopes). */
+  claims: string[]
+  /** OPTIONAL (TODO.identity/03): the closed allowlist of roles the
+   *  role claims may carry for this client. ABSENT = no policy bound
+   *  (the assignment set carries as-is). */
+  roles?: string[]
+}
+
+/** The client registry's launch metadata (the SSO home, the post-login
+ *  launcher on the identity service): how a signed-in account meets the
+ *  service. A client with NO launch row (launch_url NULL) never appears
+ *  on the launcher — the machine-only clients stay off it. */
+export interface OidcClientLaunch {
+  /** The service's sign-in start (an absolute http(s) URL): the card
+   *  launches it, the live OP session lets the user straight in. */
+  url: string
+  /** The card's glyph: a name from the identity service's small icon
+   *  set (null = the default launch glyph). */
+  icon: string | null
+  /** The card's one-line description (null = the name alone carries it). */
+  description: string | null
+  /** The visibility rule for an account the computed role set does NOT
+   *  admit: 'roles' hides the card (the default), 'request' shows it
+   *  with a plain request-access state, 'open' never gates (every
+   *  signed-in account may launch — the service admits them all). */
+  visibility: 'roles' | 'request' | 'open'
+}
+
+/** A pending authorization between /op/authorize's validation and the
+ *  consent decision. */
+export interface OidcAuthorization {
+  id: string
+  clientId: string
+  redirectUri: string
+  scope: string
+  state: string
+  nonce: string | null
+  codeChallenge: string
+  userId: string | null
+  decision: 'allow' | 'deny' | null
+  createdAt: string
+  expiresAt: string
+}
+
+/** The one-time authorization code (consumed atomically at the token
+ *  endpoint). */
+export interface OidcCode {
+  code: string
+  clientId: string
+  redirectUri: string
+  scope: string
+  nonce: string | null
+  codeChallenge: string
+  userId: string
+  /** TODO.identity/11 — the ACTIVE-ORG CONTEXT the consent decision was
+   *  made under (the session's stamped context at decide time; NULL =
+   *  the account's primary context). The token endpoint re-judges it
+   *  against the LIVE membership (a membership disabled mid-flow falls
+   *  back to the primary context, never emits a dead org's claims). */
+  contextOrg: string | null
+  /** TODO.identity-sso/02+03: the consenting session's amr provenance
+   *  (parsed from the row's JSON; null = none recorded). */
+  amr: string[] | null
+  expiresAt: string
+}
+
+/** An issued access token (the userinfo endpoint resolves it). */
+export interface OidcAccessToken {
+  token: string
+  userId: string
+  clientId: string
+  scope: string
+  /** The context the granting code carried (userinfo answers the SAME
+   *  claims the ID token did). */
+  contextOrg: string | null
+  /** TODO.identity-sso/02+03: the authorizing authentication's amr
+   *  provenance — userinfo answers the same truth the ID token carried. */
+  amr: string[] | null
+  expiresAt: string
+}
+
+/** The OP key rotation history — the PUBLIC half only. */
+export interface OidcKeyRow {
+  kid: string
+  publicJwk: string
+  status: 'active' | 'retired'
+  createdAt: string
+  retiredAt: string | null
+}
+
+// ── the upstream providers (TODO.identity/08) ────────────────────────
+
+/** An upstream identity provider the OP links + accepts (a registry
+ *  row — adding a provider is never a code fork). kind 'github' runs
+ *  the OAuth web flow; kind 'oidc' runs discovery + code + PKCE against
+ *  the issuer (Google/Entra/Apple/generic — Apple's documented quirks
+ *  key on the issuer host, auth/upstream/registry.ts). The client
+ *  SECRET is never stored: clientSecretRef names an env variable
+ *  ('env:<NAME>'). */
+export interface IdentityProvider {
+  id: string
+  kind: 'github' | 'oidc'
+  displayName: string
+  /** The brand-mark key the login/account pages map to an icon
+   *  (github | google | apple | microsoft | oidc; null = generic). */
+  brandMark: string | null
+  /** The OIDC issuer URL (kind 'oidc'; NULL for github — its endpoints
+   *  ride the GITHUB_*_BASE_URL env seam, auth/github.ts). */
+  issuer: string | null
+  clientId: string
+  /** 'env:<NAME>' — resolved per request, never stored resolved. */
+  clientSecretRef: string | null
+  /** The scope override (NULL = the kind's default: github 'read:user
+   *  user:email'; oidc 'openid profile email'; Apple 'openid name
+   *  email'). */
+  scopes: string | null
+  enabled: boolean
+  createdAt: string
+  createdBy: string | null
+  updatedAt: string | null
+}
+
+/** A linked upstream identity (TODO.identity/02's table shape, landed
+ *  additively with 08's flows): THE match rule for an upstream sign-in
+ *  — resolve by (provider, providerAccountId), NEVER by email alone. */
+export interface IdentityLink {
+  id: string
+  userId: string
+  /** The identity_providers row id. */
+  provider: string
+  providerAccountId: string
+  linkedAt: string
+  /** Who performed the link (the account holder's email, or the admin's). */
+  linkedBy: string | null
+}
+
+// ── the OP's account model (TODO.identity/02) ────────────────────────
+
+/** The invite-only enrollment link's row. One-time (consumed_at flips
+ *  atomically at completion), 24 h TTL. */
+export interface EnrollmentToken {
+  token: string
+  userId: string
+  createdBy: string | null
+  createdAt: string
+  expiresAt: string
+  consumedAt: string | null
+}
+
+/** The account page's session row — NEVER the token itself. `current`
+ *  marks the row the presenting cookie resolves to (computed in SQL, so
+ *  the token never leaves the store). TODO.identity/06 adds the sign-in
+ *  context (user agent / IP at creation, last-active on resolution);
+ *  NULLs render as "not recorded" on older rows. */
+export interface SessionView {
+  id: string
+  createdAt: string
+  expiresAt: string
+  lastSeenAt: string | null
+  userAgent: string | null
+  ip: string | null
+  current: boolean
+}
+
+/** The aggregate live-session row (TODO.identity-sso/01 — the admin
+ *  dashboard's "who is signed in NOW"): a SessionView plus the account
+ *  it belongs to. The SessionView rule stands: NEVER the token itself;
+ *  `current` marks the presenting administrator's own row (computed in
+ *  SQL, so the token never leaves the store). */
+export interface OpLiveSession extends SessionView {
+  userId: string
+}
+
+/** The enrollment completion's honest outcomes. */
+export type CompleteEnrollmentResult =
+  | { kind: 'ok'; userId: string }
+  /** Never existed or already consumed (one-time means one-time — the
+   *  two classes are deliberately indistinguishable). */
+  | { kind: 'unknown' }
+  /** Past the TTL: burned on presentation, never redeemable later. */
+  | { kind: 'expired' }
+
+// ── the central user registry (TODO.identity/03) ─────────────────────
+
+/** A PER-CLIENT role assignment (the op_client_roles row): the roles
+ *  the account holds on ONE relying party. An empty `roles` is the
+ *  explicit "no roles on this client" — distinct from NO ROW, which
+ *  leaves the account's OP-side role set as that client's default. */
+export interface OpClientRoleAssignment {
+  userId: string
+  clientId: string
+  roles: string[]
+  assignedBy: string | null
+  createdAt: string
+  updatedAt: string | null
+}
+
+/** The erasure act's removal counts (the audit event's metadata):
+ *  revokeOpUserCredentials' four plus the links, the per-client
+ *  assignments, the org memberships (TODO.identity/11), and the
+ *  credential/token rows (passwords, enrollment tokens, email-change
+ *  tokens). TODO.identity-sso/02+03 adds `factors`: the factor-registry
+ *  rows removed (passkeys, TOTP secrets, recovery codes, and the
+ *  account's pending ceremony state). */
+export interface OpAccountErasure {
+  sessions: number
+  accessTokens: number
+  codes: number
+  authorizations: number
+  links: number
+  clientRoles: number
+  memberships: number
+  tokens: number
+  factors: number
+}
+
+// ── the account console (TODO.identity/06) ───────────────────────────
+
+/** The verify-new-email ceremony's row (the enrollment link's doctrine:
+ *  a 256-bit random token backed by the D1 row; one-time, 24 h).
+ *  deliveredBy records the channel the link traveled: 'mailer' (sent to
+ *  the NEW address; completing verifies it) or 'shown' (no mailer
+ *  configured, the link was displayed to the signed-in holder; the change
+ *  applies but the address stays unverified, honestly). */
+export interface EmailChangeToken {
+  token: string
+  userId: string
+  newEmail: string
+  deliveredBy: 'mailer' | 'shown'
+  createdAt: string
+  expiresAt: string
+  consumedAt: string | null
+}
+
+/** The email change completion's honest outcomes. */
+export type CompleteEmailChangeResult =
+  | { kind: 'ok'; userId: string; newEmail: string; verified: boolean }
+  /** Never existed or already consumed (indistinguishable, the
+   *  enrollment rule). */
+  | { kind: 'unknown' }
+  /** Past the TTL: burned on presentation, never redeemable later. */
+  | { kind: 'expired' }
+  /** Another account took the address between request and completion
+   *  (the token is burned; the change must start over). */
+  | { kind: 'conflict' }
+
+// ── strong authentication: the factor registry (TODO.identity-sso/02 + /03)
+
+/** A registered passkey (the webauthn_credentials row). publicKeyCose is
+ *  the COSE key bytes (base64url) exactly as the attestation carried
+ *  them; aaguid + transports record what the browser DECLARED at
+ *  registration (attestation is 'none' — the console's display hints,
+ *  never proof). signCount is the authenticator's signature counter. */
+export interface WebauthnCredential {
+  credentialId: string
+  userId: string
+  name: string
+  publicKeyCose: string
+  signCount: number
+  aaguid: string | null
+  transports: string[]
+  createdAt: string
+  lastUsedAt: string | null
+  lastIp: string | null
+}
+
+/** The counter advance's honest outcomes (the clone rule): the guarded
+ *  UPDATE either lands ('ok'), refuses a REGRESSED counter ('regressed'
+ *  — the audit event's signal), or names a credential that is not there
+ *  ('unknown'). A (0 → 0) pair is a software authenticator that never
+ *  counts and passes; a zeroed-or-behind count against a started one
+ *  regresses. */
+export type AdvanceCounterResult = 'ok' | 'regressed' | 'unknown'
+
+/** A TOTP authenticator app's row (RFC 6238). verifiedAt NULL = the
+ *  PENDING enrollment (activates on the first valid code only);
+ *  failCount + lastFailureAt carry the enrollment verify's throttle
+ *  (the six-digit window invites brute force). `secret` is the base32
+ *  seed — the store answers it, the ROUTES never return it after the
+ *  enrollment answer. */
+export interface TotpSecret {
+  id: string
+  userId: string
+  name: string
+  secret: string
+  failCount: number
+  lastFailureAt: string | null
+  createdAt: string
+  verifiedAt: string | null
+  lastUsedAt: string | null
+  lastIp: string | null
+}
+
+/** The recovery-code set's console state (never a hash, never a code):
+ *  the generation's size, the unconsumed remainder, and when the current
+ *  batch was minted. */
+export interface RecoveryCodeState {
+  total: number
+  remaining: number
+  createdAt: string | null
+}
+
+/** The one-time WebAuthn ceremony challenge (the database-is-the-proof
+ *  doctrine): userId binds the registration + the second-factor
+ *  assertion; the passwordless assertion's row carries null (the
+ *  asserted credential id resolves the account). */
+export interface WebauthnChallenge {
+  challenge: string
+  userId: string | null
+  kind: 'register' | 'assert'
+  createdAt: string
+  expiresAt: string
+  consumedAt: string | null
+}
+
+/** The pending second-factor sign-in: the password verified, the session
+ *  waits on the factor. amr carries the methods proven so far (parsed
+ *  JSON, e.g. ['pwd']); failCount + lastFailureAt ride the per-account
+ *  throttle ladder. */
+export interface MfaPending {
+  token: string
+  userId: string
+  amr: string[]
+  failCount: number
+  lastFailureAt: string | null
+  createdAt: string
+  expiresAt: string
+  consumedAt: string | null
+}
+
+
+// ── organization administration (TODO.identity/10) ───────────────────
+
+/** A self-service join request (the "Request an account" page). The
+ *  queue routing is on the row: `orgId` set → the named ORG's admin
+ *  decides (the org must be a REGISTERED participant org at submit and
+ *  again at approval); `orgId` NULL + `orgNameText` → the "my
+ *  organization is not listed" path — BIML's new-organizations queue
+ *  (BIML verifies the participation, then the requester becomes the
+ *  org's administrator). The decision is atomic on 'pending'; approval
+ *  records the invited account in `invitedUserId`. */
+export interface OrgJoinRequest {
+  id: string
+  name: string
+  email: string
+  /** The selected registry org (NULL = the not-listed path). */
+  orgId: string | null
+  /** The free-text organization name (the not-listed path only). */
+  orgNameText: string | null
+  /** The role asked for — bounded by the org's kind (the submit route
+   *  and the approval both validate; 'org_admin' on the not-listed path). */
+  requestedRole: string
+  note: string | null
+  status: 'pending' | 'approved' | 'refused'
+  decidedBy: string | null
+  decidedAt: string | null
+  refusalReason: string | null
+  invitedUserId: string | null
+  createdAt: string
+}
+
+// ── the multi-organization membership model (TODO.identity/11) ───────
+
+/** The membership lifecycle: INVITED (the org's admin added the account,
+ *  the holder has not accepted yet — the account does not act for the
+ *  org) → ACTIVE (the account holds the org's context: the per-org role
+ *  set applies) → DISABLED (the org's admin or the scheme operator
+ *  suspended the membership; reversible — re-activation is a deliberate
+ *  act, never an automatic one). */
+export type OrgMembershipState = 'invited' | 'active' | 'disabled'
+
+/** An account's membership in ONE organization (the org_memberships
+ *  row): the per-org role set + the lifecycle state. The PRIMARY
+ *  membership (isPrimary) is the backward-compatible one: the users
+ *  row's org_id/roles columns mirror it, so every consumer that still
+ *  reads the legacy columns sees exactly the primary context (the
+ *  dual-read doctrine — the columns stay until every consumer reads the
+ *  memberships). */
+export interface OrgMembership {
+  id: string
+  userId: string
+  orgId: string
+  /** The PER-ORG role set (JSON on the row): the roles the account holds
+   *  when acting AS this org. */
+  roles: string[]
+  state: OrgMembershipState
+  isPrimary: boolean
+  invitedBy: string | null
+  createdAt: string
+  activatedAt: string | null
+  disabledAt: string | null
+  disabledBy: string | null
+}
+
+/** The effective org context: the org the account acts AS and the role
+ *  set that context carries. The session payloads and the OP's token
+ *  claims both resolve through resolveOrgContext, so the two never
+ *  drift. */
+export interface OrgContextResolution {
+  orgId: string | null
+  roles: string[]
+}
+
+/**
+ * THE CONTEXT RULE (TODO.identity/11 — the GitHub context-switch
+ * pattern, one pure function every reader shares). Given the account's
+ * legacy columns (role/roles/orgId), the session's stamped active org
+ * (NULL = the primary context), and the membership rows it names:
+ *
+ *   - an ACTIVE-ORG context whose membership is ACTIVE resolves to that
+ *     org + its per-org role set. An ORG-FREE account's account-level
+ *     roles (the scheme's own staff: admin, cs_admin, …) ride EVERY
+ *     context honestly; an org-bound account's legacy set is the
+ *     primary membership's mirror and rides ONLY the primary context —
+ *     a relying party never learns the other memberships.
+ *   - a context whose membership is missing or no longer active (the
+ *     org's admin disabled it mid-session) falls through to the primary
+ *     rule — the stale context never emits a dead org's claims.
+ *   - the PRIMARY context: no membership row at all answers the
+ *     pre-memberships read (the dual-read fallback — a store predating
+ *     the backfill behaves exactly as before); an ACTIVE primary carries
+ *     the mirrored set (byte-identical with the legacy columns); an
+ *     invited/disabled primary means the account does NOT act for the
+ *     org — no org, no org roles.
+ */
+export function resolveOrgContext(
+  user: { role: string; roles?: string[] | null; orgId: string | null },
+  context: { activeOrg: string | null; active: OrgMembership | null; primary: OrgMembership | null },
+): OrgContextResolution {
+  const accountRoles = user.roles?.length ? [...user.roles] : [user.role]
+  if (context.activeOrg) {
+    const m = context.active
+    if (m && m.orgId === context.activeOrg && m.state === 'active') {
+      const global = user.orgId ? [] : accountRoles
+      return { orgId: context.activeOrg, roles: [...new Set([...m.roles, ...global])] }
+    }
+  }
+  if (!user.orgId) return { orgId: null, roles: accountRoles }
+  const p = context.primary
+  if (!p) return { orgId: user.orgId, roles: accountRoles }
+  if (p.state !== 'active') return { orgId: null, roles: [] }
+  return { orgId: user.orgId, roles: [...new Set([...accountRoles, ...p.roles])] }
+}
+
+// ── the organization registry (TODO.identity-features/05) ────────────
+
+/** The registry organization's lifecycle: ACTIVE (the membership graph
+ *  admits it — memberships, assignments, and the join selector where it
+ *  carries a participant kind) → DISABLED (the identity administrator's
+ *  honest removal: the org's memberships disable, its members' per-org
+ *  roles stop carrying; the row and the audit trail keep the history).
+ *  The erasure-adjacent hard delete exists only for an org that never
+ *  held a membership (the routes enforce it; the store removes rows). */
+export type OrgRegistryState = 'active' | 'disabled'
+
+/** One contact on the registry organization (the row's contacts JSON
+ *  array; a malformed entry is skipped on read, never trusted). */
+export interface OrgRegistryContact {
+  name: string | null
+  email: string
+}
+
+/** One organization on the identity service's OWN registry (the
+ *  org_registry row) — the identity plane's membership graph as a
+ *  first-class entity with its lifecycle (the identity administrator's
+ *  add/edit/disable/remove).
+ *
+ *  The id is the stable SLUG; for a participant organization the OIML
+ *  code IS the id (TODO.identity-features/05 §4 — the platform resolves
+ *  the org claim's value against its own participant registry directly:
+ *  the same string on both sides, so the mapping is identity, never a
+ *  lookup table). `kind` names the participant kind for a participant
+ *  org (NULL = a non-participant org — the estate operator's own org, a
+ *  scheme consumer); the program side bounds the assignable per-org
+ *  roles by it. `participantRef` is the OPTIONAL annotation documenting
+ *  which participant record the org mirrors (the link's documentation,
+ *  never a key the store resolves). */
+export interface OrgRegistryOrg {
+  id: string
+  /** The display name. */
+  name: string
+  shortName: string | null
+  /** The participant kind ('issuing-authority' | 'test-laboratory' |
+   *  'utilizer' | 'associate' on the OIML-CS program), NULL for a
+   *  non-participant org. Opaque to the store. */
+  kind: string | null
+  country: string | null
+  contacts: OrgRegistryContact[]
+  participantRef: string | null
+  state: OrgRegistryState
+  createdAt: string
+  createdBy: string | null
+  updatedAt: string | null
+  updatedBy: string | null
+  disabledAt: string | null
+  disabledBy: string | null
+}
+
+// ── the register's holder-org attribution (TODO.register/02) ─────────
+
+/** The hub-side attribution of a REGISTERED certificate to its holder
+ *  organization — the OP-minted org id, never an instance-minted one.
+ *  The hub's OWN row (the certificate_holder_orgs table): the registrar's
+ *  act extracts the descriptor the federation registration package carried
+ *  (source 'registration'), or the estate admin's claim confirmation writes
+ *  it for a legacy row (source 'claim'). ONE row per certificate — the
+ *  first attribution wins, a later writer never overwrites silently.
+ *
+ *  The org display name is DENORMALIZED at attribution time: the register
+ *  reads correctly even when the organization later renames (the
+ *  register's permanence rule — the descriptor is the register's record,
+ *  never a join against a live registry). */
+export interface CertificateHolderOrg {
+  certificateId: string
+  orgId: string
+  orgName: string
+  source: 'registration' | 'claim'
+  attributedAt: string
+  /** The registrar / the confirming estate admin (the actor's name). */
+  attributedBy: string | null
+  /** The confirming claim (source 'claim' only). */
+  claimId: string | null
+}
+
+/** The legacy-row claim act's lifecycle: PENDING (the manufacturer org's
+ *  administrator claimed the row by holder-name match — a claim is a
+ *  claim until confirmed) → CONFIRMED (the estate admin's act; the
+ *  attribution row lands) / REFUSED (terminal for THAT claim, with the
+ *  written reason; a fresh claim may follow). */
+export type CertificateHolderClaimState = 'pending' | 'confirmed' | 'refused'
+
+export interface CertificateHolderClaim {
+  id: string
+  certificateId: string
+  claimantOrgId: string
+  /** The claiming org's display name at claim time (denormalized — the
+   *  confirmed attribution's org_name comes from here). */
+  claimantOrgName: string
+  /** The certificate's free-text holder name the claim matched — the
+   *  snapshot, the claim's evidence. */
+  matchedHolderName: string
+  /** The claiming account (the org admin's name). */
+  claimedBy: string
+  state: CertificateHolderClaimState
+  decidedBy: string | null
+  decidedAt: string | null
+  refusalReason: string | null
+  createdAt: string
+}
+
+// ── the instrument register (TODO.register/03) ──────────────────────
+
+/** The registered instrument's lifecycle: REGISTERED (the declaration
+ *  stood) ⇄ OUT_OF_SERVICE (the holder's mark — the instrument is out
+ *  of service, the registration stands; a return to service re-marks
+ *  it registered) → WITHDRAWN (terminal — the holder withdrew the
+ *  instrument from the register; a withdrawn row never reopens). The
+ *  route owns the transition rule; the store keeps the rows. */
+export type InstrumentRegistrationLifecycle = 'registered' | 'out_of_service' | 'withdrawn'
+
+/** The scope verdict recorded AT REGISTRATION (the executing-scope
+ *  doctrine at the instrument level):
+ *  - in_scope — the certificate's structured scope block (its
+ *    classifications) covered the declared designations;
+ *  - scope_unverified — the certificate carries NO structured scope
+ *    block (the records-mode import's honest degradation): the check
+ *    was unavailable, the registration is marked, and the issuing IA's
+ *    oversight surface sees exactly this mark.
+ * The third verdict — refused — never lands a row: the route refuses
+ * the out-of-scope declaration with the reason. */
+export type InstrumentRegistrationScopeStatus = 'in_scope' | 'scope_unverified'
+
+/** One registered instrument (the instrument_registrations row): the
+ *  serial number riding under a type certificate. The certificate's
+ *  holder organization is referenced by id WITHOUT a foreign key (the
+ *  identity plane and this platform-side register never merge — the
+ *  org_memberships posture); a registration row's honesty never depends
+ *  on a join. */
+export interface InstrumentRegistration {
+  id: string
+  /** The certificate the serial rides under (the entity store's
+   *  certificates row id). */
+  certificateId: string
+  /** The holder organization (the manufacturer org id). */
+  holderOrgId: string
+  /** The Recommendation the certificate belongs to. */
+  standardId: string
+  serialNumber: string
+  /** The ISO manufacture date, null when the declaration omitted it. */
+  manufactureDate: string | null
+  /** The per-serial designations the scope check evaluated (the JSON
+   *  object; a malformed cell reads as the empty object, never
+   *  trusted). */
+  designations: Record<string, unknown>
+  scopeStatus: InstrumentRegistrationScopeStatus
+  /** The verdict's record: the matched classification label
+   *  (in_scope) or the unverified note (scope_unverified). */
+  scopeDetail: string | null
+  lifecycle: InstrumentRegistrationLifecycle
+  registeredAt: string
+  registeredBy: string | null
+  updatedAt: string | null
+  updatedBy: string | null
+}
+
+/** Per-store org fields for the READ visibility (the multi-party
+ *  model: a row is visible when ANY named field equals the user's
+ *  org). The field names are the entities' REAL ones (verified against
+ *  the data model, 2026-08-03 — a guessed name hides everything).
+ *
+ *  The instrument CATALOG (families/groups/models/samples) is NOT here
+ *  on purpose: it is shared reference data — the IA evaluates against
+ *  the model, the TL tests the sample (the 2026-08-03 zero-verdicts
+ *  diagnosis: manufacturer-only catalog reads left the IA's verdict
+ *  engine with no subject chain). Catalog WRITES are gated in
+ *  writeAllowed. */
+export const ORG_FIELDS: Record<string, string[]> = {
+  applications: ['manufacturer_id', 'issuing_authority_id'],
+  testRequests: ['requesting_authority_id', 'assigned_laboratory_id'],
+  testReports: ['laboratory_id'],
+  testAssignments: ['laboratory_id'],
+  testRuns: ['laboratory_id'],
+  evaluationReports: ['authority_id'],
+  modelEvaluations: ['laboratory_id'],
+  certificates: ['issuing_authority_id', 'model_family_id'],
+  acceptanceReviews: ['participant_id'],
+  // TODO.federation/02 — the engagement module, generalized by
+  // TODO.adoption/07 into the negotiation primitive: the two parties of
+  // the pair see the negotiation and its quotation/agreement — the
+  // applicant org and the IA on ia_applicant, the IA and the laboratory
+  // on ia_tl, the applicant org and the laboratory on tl_applicant; on
+  // the test-request quote leg the quotation carries the dispatching IA
+  // and the quoting laboratory (the Quotation/ConsultingAgreement
+  // records denormalize the party ids from their parent — the org fields
+  // are the entities' REAL fields, no parent-resolution leg).
+  engagements: ['manufacturer_id', 'issuing_authority_id', 'test_laboratory_id'],
+  quotations: ['manufacturer_id', 'issuing_authority_id', 'test_laboratory_id'],
+  consultingAgreements: ['manufacturer_id', 'issuing_authority_id', 'test_laboratory_id'],
+  // TODO.adoption/09 — the payment records: the two parties of the
+  // invoice pair both see (and upload evidence to) the record; the hub's
+  // platform roles (not org-bound) see the whole store. Never public.
+  paymentRecords: ['payer_id', 'payee_id'],
+}
+
+/** The instrument catalog stores (shared reference data on read;
+ *  org-gated on write). */
+export const CATALOG_STORES = new Set([
+  'measuringInstrumentModelFamilies',
+  'measuringInstrumentModelGroups',
+  'measuringInstrumentModels',
+  'measuringInstrumentSamples',
+])
+
+/** The org a row is indexed under (the first declared org field's
+ *  value; null when the entity declares none — shared reference data). */
+export function orgIdOf(store: string, data: unknown): string | null {
+  const fields = ORG_FIELDS[store] ?? []
+  const rec = data as Record<string, unknown>
+  for (const f of fields) {
+    if (typeof rec[f] === 'string' && rec[f]) return rec[f] as string
+  }
+  return null
+}
+
+// Role model per TODO.new-paradigm/01: applicant | ia_officer | tl_operator |
+// cs_admin, plus the pre-existing admin/viewer accounts. org_id links the user
+// to their organization record in the browser-side entity graph:
+//   applicant  → manufacturer id (sample data: mfr-acme, the ACME fictional manufacturer)
+//   ia_officer → issuing-authority oiml_code (EX1; XX1 = the pre-signature
+//                demo IA of the task-44 participant registry — its Declaration
+//                is unsigned, so the PD-08 cl. 5 issuance gate blocks it)
+//   tl_operator → test-laboratory oiml_id (21 = the example TL)
+//   mc_member / rc_member / executive_secretary → the OIML-CS organ roles of
+//                TODO.roadmap/44 (approval pipeline + participant registry)
+//   cs_admin/admin/viewer → null (no org)
+export const DEMO_ACCOUNTS = [
+  { email: 'admin@oiml.org', name: 'OIML Admin', role: 'admin', orgId: null as string | null },
+  // TODO.register/02 — the ACME applicant also holds its org's org_admin
+  // (the OP-side manufacturer-org role, simulated on the demo cast until
+  // the identity wave lands it): the register's legacy-row claim act is
+  // the org administrator's. `roles` is the optional full role set (the
+  // users.roles column; absent = the primary role only).
+  { email: 'applicant@oiml.org', name: 'ACME Applicant', role: 'applicant', orgId: 'mfr-acme' as string | null, roles: ['applicant', 'org_admin'] },
+  { email: 'ia@oiml.org', name: 'IA Officer', role: 'ia_officer', orgId: 'EX1' as string | null },
+  { email: 'ia2@oiml.org', name: 'IA Officer (XX1)', role: 'ia_officer', orgId: 'XX1' as string | null },
+  { email: 'tl@oiml.org', name: 'TL Operator', role: 'tl_operator', orgId: '21' as string | null },
+  // The test operators hold their OWN accounts (the demonstration cast,
+  // docs/demo-personas.md): every run, evidence sign-off and report
+  // attributes to a person, never to a shared laboratory login.
+  { email: 'petra.horvat@etl.example.org', name: 'Ms. Petra Horvat', role: 'tl_operator', orgId: '21' as string | null },
+  { email: 'martin.berger@etl.example.org', name: 'Mr. Martin Berger', role: 'tl_operator', orgId: '21' as string | null },
+  { email: 'biml@oiml.org', name: 'BIML Officer', role: 'biml_officer', orgId: null as string | null },
+  { email: 'cs@oiml.org', name: 'CS Administrator', role: 'cs_admin', orgId: null as string | null },
+  { email: 'mc@oiml.org', name: 'MC Member', role: 'mc_member', orgId: null as string | null },
+  { email: 'rc@oiml.org', name: 'RC Member', role: 'rc_member', orgId: null as string | null },
+  { email: 'secretariat@oiml.org', name: 'Executive Secretary', role: 'executive_secretary', orgId: null as string | null },
+  // TODO.adoption/11 — the Utilizer's staff member (scheme_participant):
+  // declares Additional National Requirements for their country on the ANR
+  // registry console; the declaration records the participant it acts for
+  // (the CS registry's approval is the moderation gate).
+  // TODO.adoption/10 — the ORG BINDING (ut-nmi-nl, the seeded NL Utilizer)
+  // is the account's link into the participants register: the register's
+  // participant depth resolves from it (the role alone never upgrades a
+  // viewer — the org-registry's bounds keep the link assignable).
+  { email: 'utilizer@oiml.org', name: 'Utilizer Officer (NL)', role: 'scheme_participant', orgId: 'ut-nmi-nl' as string | null },
+  { email: 'viewer@oiml.org', name: 'Viewer', role: 'viewer', orgId: null as string | null },
+  { email: 'developer@ribose.com', name: 'Ribose Developer', role: 'admin', orgId: null as string | null },
+]
+
+export const DEMO_PASSWORD = 'demo2026'
+
+/** The async store contract the routes consume. Every method mirrors a
+ *  sync counterpart in store.ts / entities.ts — same SQL, same
+ *  semantics, awaited. */
+export interface ServerStore {
+  // ── users / sessions (schema.sql's auth half) ──
+  seedDemoAccounts(): Promise<void>
+  authenticateDemo(email: string, password: string): Promise<AuthUserPayload | null>
+  findOrCreateOAuthUser(
+    provider: string,
+    providerAccountId: string,
+    email: string,
+    name: string,
+    avatarUrl?: string,
+    /** The INITIAL role/org (OAuthInitialAssignment) — create-time only. */
+    initial?: OAuthInitialAssignment,
+  ): Promise<AuthUserPayload>
+  /** TODO.identity/06: the sign-in context (the account console's
+   *  sessions section): the user agent + the client IP, stamped at
+   *  creation (server/auth/client-info.ts). TODO.identity-sso/02+03:
+   *  `amr` records the sign-in's provenance (the RFC 8176 list the ID
+   *  token later carries); absent = no OP-side credential event. */
+  createSession(
+    userId: string,
+    opts?: { idTokenHint?: string | null; userAgent?: string | null; ip?: string | null; amr?: string[] | null },
+  ): Promise<string>
+  /** Stamp the account's last sign-in (TODO.identity/07 — the registry's
+   *  last-sign-in column). The OP's own sign-in paths call this on a
+   *  completed sign-in; the demo/OAuth paths bump it inline already. */
+  touchLastLogin(userId: string): Promise<void>
+  getSessionUser(token: string): Promise<AuthUserPayload | null>
+  /** The SSO logout hint (TODO.federation/10): the id_token of the SSO
+   *  sign-in this session came from, for RP-initiated logout — NEVER
+   *  part of AuthUserPayload (the client never sees it). */
+  getSessionIdTokenHint(token: string): Promise<string | null>
+  deleteSession(token: string): Promise<void>
+  cleanExpiredSessions(): Promise<void>
+  listDemoAccounts(): Promise<Array<{ email: string; name: string; role: string }>>
+
+  // ── identity federation (TODO.federation/10) ──
+  findUserByEmail(email: string): Promise<AuthUserPayload | null>
+  /** The account by its id (TODO.identity/01 — the OP's token endpoint
+   *  resolves the code's user_id). */
+  getUserById(id: string): Promise<AuthUserPayload | null>
+  findUserByProvider(provider: string, providerAccountId: string): Promise<AuthUserPayload | null>
+  /** Provision a NEW account from a validated SSO sign-in (the claim
+   *  mapping's mapped/default outcome). */
+  provisionSsoUser(input: {
+    email: string
+    name: string
+    provider: string
+    providerAccountId: string
+    role: string
+    orgId: string | null
+  }): Promise<AuthUserPayload>
+  /** Link an SSO identity to an EXISTING account (verified-email
+   *  linking): the row takes the provider pair; its role/org stay as
+   *  the local assignment. */
+  linkProviderIdentity(userId: string, provider: string, providerAccountId: string): Promise<void>
+  /** The approval decision's write: the account's role (+ org). */
+  updateUserRoleOrg(userId: string, role: string, orgId: string | null): Promise<void>
+  /** Record/refresh the pending-approval row for (issuer, sub). */
+  upsertIdentityApproval(input: {
+    email: string
+    name: string
+    issuer: string
+    sub: string
+    claimsJson: string | null
+  }): Promise<IdentityApproval>
+  getIdentityApproval(issuer: string, sub: string): Promise<IdentityApproval | null>
+  listIdentityApprovals(status?: IdentityApproval['status']): Promise<IdentityApproval[]>
+  decideIdentityApproval(
+    id: string,
+    decision: { status: 'approved' | 'rejected'; role?: string; orgId?: string | null; decidedBy: string },
+  ): Promise<IdentityApproval | null>
+
+  // ── the SSO sign-in state jar (TODO.identity/04) ──
+  /** Store one OIDC sign-in attempt's one-time state (the nonce + the
+   *  PKCE verifier). STORE-BACKED so every Worker isolate sees it — the
+   *  per-process Map it replaces could lose the callback's state check
+   *  to a sibling isolate. */
+  putSsoState(input: { state: string; nonce: string; verifier: string; ttlMs: number }): Promise<void>
+  /** Atomically consume the state: answers the row exactly once (a
+   *  replay loses the consumed_at race), and an EXPIRED row is consumed
+   *  too — never a second chance. */
+  consumeSsoState(state: string): Promise<SsoSignInState | null>
+
+  // ── federation peers (TODO.federation/04) ──
+  listFederationPeers(status?: FederationPeer['status']): Promise<FederationPeer[]>
+  getFederationPeer(id: string): Promise<FederationPeer | null>
+  /** Add + refresh share this write (the pin path re-validates before
+   *  calling); refreshedAt stamps on update. */
+  upsertFederationPeer(input: {
+    id: string
+    name: string
+    roles: string
+    descriptorUrl: string | null
+    descriptorJson: string
+    pinnedVia: FederationPeer['pinnedVia']
+    connectivity: FederationPeer['connectivity']
+    addedBy: string | null
+  }): Promise<FederationPeer>
+  revokeFederationPeer(id: string, revokedBy: string): Promise<FederationPeer | null>
+
+  // ── user administration (TODO.federation/12 — multi-user instances) ──
+  listUsers(): Promise<UserAdminRow[]>
+  createLocalUser(input: {
+    email: string
+    name: string
+    role: string
+    roles?: string[]
+    orgId?: string | null
+  }): Promise<UserAdminRow>
+  setUserRoles(id: string, role: string, roles: string[]): Promise<boolean>
+  setUserActive(id: string, active: boolean): Promise<boolean>
+
+  // ── the OIDC Provider (TODO.identity/01) ──
+  /** The client registry (admin-managed; the bootstrap seed upserts). */
+  getOidcClient(clientId: string): Promise<OidcClient | null>
+  listOidcClients(): Promise<OidcClient[]>
+  upsertOidcClient(input: {
+    clientId: string
+    name: string
+    secretHash: string | null
+    redirectUris: string[]
+    claimsPolicy: OidcClientClaimsPolicy | null
+    createdBy?: string | null
+  }): Promise<OidcClient>
+  setOidcClientStatus(clientId: string, status: OidcClient['status']): Promise<OidcClient | null>
+  /** The SSO-home launch metadata write (the registry API + the
+   *  bootstrap seed): set the card, or null to take the client off the
+   *  launcher. Answers null when the client does not exist. */
+  setOidcClientLaunch(clientId: string, launch: OidcClientLaunch | null): Promise<OidcClient | null>
+  /** The pending authorizations (consent round trip). */
+  createOidcAuthorization(input: {
+    id: string
+    clientId: string
+    redirectUri: string
+    scope: string
+    state: string
+    nonce: string | null
+    codeChallenge: string
+    userId: string | null
+    ttlMs: number
+  }): Promise<OidcAuthorization>
+  getOidcAuthorization(id: string): Promise<OidcAuthorization | null>
+  /** The consent decision: binds the row's OWN account (userId must
+   *  equal the row's stamped user) and flips the decision atomically —
+   *  a pending row that already carries a decision, or belongs to a
+   *  different account, answers null (the double-submit / cross-account
+   *  case fails honestly). */
+  decideOidcAuthorization(
+    id: string,
+    decision: { userId: string; decision: 'allow' | 'deny' },
+  ): Promise<OidcAuthorization | null>
+  /** The one-time codes. */
+  createOidcCode(input: {
+    code: string
+    clientId: string
+    redirectUri: string
+    scope: string
+    nonce: string | null
+    codeChallenge: string
+    userId: string
+    /** TODO.identity/11: the session's stamped active-org context at the
+     *  consent decision (NULL = the primary context). */
+    contextOrg?: string | null
+    /** TODO.identity-sso/02+03: the consenting session's amr provenance
+     *  (stored as JSON; the token endpoint emits it as the ID token's
+     *  amr). Absent = no provenance recorded. */
+    amr?: string[] | null
+    ttlMs: number
+  }): Promise<void>
+  /** Atomically consume the code: answers the row exactly once (a
+   *  replay/concurrent double-exchange loses the consumed_at race and
+   *  gets null → invalid_grant). An EXPIRED code also answers null. */
+  consumeOidcCode(code: string): Promise<OidcCode | null>
+  /** The access tokens (userinfo). */
+  createOidcAccessToken(input: {
+    token: string
+    userId: string
+    clientId: string
+    scope: string
+    /** The granting code's context (userinfo answers the ID token's
+     *  claims). */
+    contextOrg?: string | null
+    /** TODO.identity-sso/02+03: the authorizing authentication's amr —
+     *  userinfo answers the same truth the ID token carried. */
+    amr?: string[] | null
+    ttlMs: number
+  }): Promise<void>
+  getOidcAccessToken(token: string): Promise<OidcAccessToken | null>
+  /** The key rotation history (public halves). */
+  listOidcKeys(): Promise<OidcKeyRow[]>
+  upsertOidcKey(input: { kid: string; publicJwk: string }): Promise<void>
+  retireOidcKey(kid: string): Promise<void>
+
+  // ── the upstream providers (TODO.identity/08) ──
+  /** The upstream registry (admin-managed; OP_UPSTREAM_SEED bootstraps).
+   *  Secrets are NEVER in these rows — clientSecretRef is an env name. */
+  listIdentityProviders(): Promise<IdentityProvider[]>
+  getIdentityProvider(id: string): Promise<IdentityProvider | null>
+  upsertIdentityProvider(input: {
+    id: string
+    kind: IdentityProvider['kind']
+    displayName: string
+    brandMark?: string | null
+    issuer?: string | null
+    clientId: string
+    clientSecretRef?: string | null
+    scopes?: string | null
+    enabled?: boolean
+    createdBy?: string | null
+  }): Promise<IdentityProvider>
+  setIdentityProviderEnabled(id: string, enabled: boolean): Promise<IdentityProvider | null>
+  deleteIdentityProvider(id: string): Promise<boolean>
+
+  // ── the linked identities (TODO.identity/02's shape, 08's flows) ──
+  /** The account's linked upstream identities (the account surface). */
+  listIdentityLinks(userId: string): Promise<IdentityLink[]>
+  /** THE match rule's read: resolve (provider, providerAccountId) → the
+   *  link (and thereby the account). NEVER match by email alone. */
+  findIdentityLink(provider: string, providerAccountId: string): Promise<IdentityLink | null>
+  /** Create the link; answers NULL when (provider, providerAccountId)
+   *  is already linked (to any account — the UNIQUE constraint), the
+   *  honest conflict the route maps to a refusal. */
+  createIdentityLink(input: {
+    userId: string
+    provider: string
+    providerAccountId: string
+    linkedBy?: string | null
+  }): Promise<IdentityLink | null>
+  /** Remove the account's link for a provider (the unlink action). */
+  deleteIdentityLink(userId: string, provider: string): Promise<boolean>
+
+  // ── the OP's account model (TODO.identity/02) ──
+  /** Create an OP password account (provider 'password', email
+   *  normalized lowercase). Answers null when the email is taken (the
+   *  invite route's 409; the UNIQUE constraint is the backstop). */
+  createOpAccount(input: {
+    email: string
+    name: string
+    role: string
+    createdBy?: string | null
+  }): Promise<UserAdminRow | null>
+  /** The password sign-in's lookup: the credential + the account's
+   *  active flag by email (normalized). Null = no such credential — the
+   *  route still runs one full-cost verify (the timing-shape rule,
+   *  auth/passwords.ts). The hash never leaves the server. */
+  getPasswordLogin(email: string): Promise<{ userId: string; hash: string; active: boolean } | null>
+  /** Set/replace the account's password credential (enrollment
+   *  completion, the account page's change). */
+  setPasswordHash(userId: string, hash: string, setBy?: string | null): Promise<void>
+  /** The sign-in methods the account holds (the account page's
+   *  password-set state + the admin list's posture). TODO.identity-sso/02:
+   *  `passkeys` counts the registered passkeys — a passkey is a PRIMARY
+   *  sign-in method (passwordless), so the at-least-one-way-in guard
+   *  reads it alongside the password and the links. */
+  countSignInMethods(userId: string): Promise<{ password: boolean; links: number; passkeys: number }>
+  /** The enrollment links (invite-only). The token arrives from the
+   *  caller (auth/op/accounts.ts's mint); expires_at = now + ttlMs. */
+  createEnrollmentToken(input: {
+    token: string
+    userId: string
+    createdBy?: string | null
+    ttlMs: number
+  }): Promise<EnrollmentToken>
+  getEnrollmentToken(token: string): Promise<EnrollmentToken | null>
+  /** Complete the enrollment: consume the token ATOMICALLY (a presented
+   *  link works exactly once, expired or not), then set the password.
+   *  The tagged result lets the route answer honestly. */
+  completeEnrollment(token: string, passwordHash: string, setBy?: string | null): Promise<CompleteEnrollmentResult>
+  /** The account's live sessions (expired ones excluded), `current`
+   *  computed against the presenting token — never exposed. */
+  listUserSessions(userId: string, currentToken?: string): Promise<SessionView[]>
+  /** Revoke ONE of the account's own sessions (the user_id clause makes
+   *  another account's session id a no-op). */
+  deleteSessionById(userId: string, sessionId: string): Promise<boolean>
+  /** The aggregate "who is signed in NOW" read across accounts
+   *  (TODO.identity-sso/01's live-sessions surface): every live session
+   *  (expired excluded), `current` computed against the presenting
+   *  administrator's token. The account name/email join stays with the
+   *  caller (listUsers) — this read carries the session rows only. */
+  listOpLiveSessions(currentToken?: string): Promise<OpLiveSession[]>
+  /** The administrator's revoke-ALL of an account's sessions (the
+   *  dashboard's light act): EVERY session deleted, no kept exception
+   *  (the self-service's deleteOtherSessions keeps the presenting one;
+   *  this keeps none). Answers the revoked count (the audit event's
+   *  metadata). */
+  deleteAllUserSessions(userId: string): Promise<number>
+
+  // ── the central user registry (TODO.identity/03) ──
+  /** The account's per-client role assignments (the registry console's
+   *  per-client view), one row per client that carries an override. */
+  listOpClientRoles(userId: string): Promise<OpClientRoleAssignment[]>
+  /** EVERY per-client assignment across accounts (TODO.identity-sso/01's
+   *  live access review reads the privileged per-client grants without a
+   *  per-account loop). */
+  listAllOpClientRoles(): Promise<OpClientRoleAssignment[]>
+  /** The assignment for ONE client: the roles the ID token issued to
+   *  that client carries (pre-allowlist). NULL = no row — the account's
+   *  OP-side role set is that client's default (the pre-03 behavior).
+   *  An EMPTY array is the explicit "no roles on this client". */
+  getOpClientRoles(userId: string, clientId: string): Promise<string[] | null>
+  /** Upsert the per-client assignment (roles may be empty — the explicit
+   *  none). The route validates the set against the client's policy. */
+  setOpClientRoles(userId: string, clientId: string, roles: string[], assignedBy: string | null): Promise<void>
+  /** Clear the per-client assignment (the account default is restored). */
+  deleteOpClientRoles(userId: string, clientId: string): Promise<boolean>
+  /** The deactivation's revocation half: delete EVERY live session, every
+   *  issued OIDC access token, every unconsumed authorization code and
+   *  every pending authorization of the account. Answers the counts (the
+   *  audit event's metadata). The user row STAYS (the history). */
+  revokeOpUserCredentials(userId: string): Promise<{ sessions: number; accessTokens: number; codes: number; authorizations: number }>
+  /** The offboarding runbook's DELETE path (the erasure): every credential,
+   *  token, link and per-client assignment removed, the user row anonymized
+   *  in place (provider 'erased' — it drops out of every account surface;
+   *  the tombstone keeps the audit chain's entity_id resolvable). Answers
+   *  the counts, or null when the account does not exist. */
+  eraseOpAccount(userId: string): Promise<OpAccountErasure | null>
+  /** Edit the account row's name/email (the registry's edit act).
+   *  Answers false when the account does not exist; the email UNIQUE
+   *  conflict surfaces as the 'unique' error (the route's 409). */
+  updateOpAccount(id: string, input: { name?: string; email?: string }): Promise<boolean>
+  /** The last OP-side sign-in per account, read FROM THE AUDIT CHAIN:
+   *  the latest auditEvents row whose action is a sign-in
+   *  ('account.sign_in' — the password login; 'upstream_sign_in' — a
+   *  linked-provider sign-in) per entity_id. Answers userId → ISO
+   *  timestamp; accounts that never signed in are absent. */
+  lastAccountSignIns(): Promise<Record<string, string>>
+
+  // ── the account console (TODO.identity/06) ──
+  /** The profile edit's write (the display name). Answers false when the
+   *  account is gone. */
+  updateUserName(userId: string, name: string): Promise<boolean>
+  /** The avatar write (users.avatar_url: the upload's serving URL, the
+   *  linked provider's picture, NULL for the initials). Answers false when
+   *  the account is gone. */
+  setUserAvatar(userId: string, avatarUrl: string | null): Promise<boolean>
+  /** Remove the account's password credential (the sign-in METHODS
+   *  section's remove action; the route holds the at-least-one-method
+   *  guard). Answers false when no credential was set. */
+  deletePasswordHash(userId: string): Promise<boolean>
+  /** Revoke every session of the account EXCEPT the presenting one (the
+   *  "sign out everywhere else" action + the password change's
+   *  best-practice revocation). Answers the revoked count. */
+  deleteOtherSessions(userId: string, keepToken: string): Promise<number>
+  /** Mint the verify-new-email ceremony's token. A fresh request VOIDS
+   *  the account's earlier pending rows (only the newest link works).
+   *  deliveredBy is stamped at request time and decides whether
+   *  completion may verify the address. */
+  createEmailChangeToken(input: {
+    token: string
+    userId: string
+    newEmail: string
+    deliveredBy: 'mailer' | 'shown'
+    ttlMs: number
+  }): Promise<EmailChangeToken>
+  getEmailChangeToken(token: string): Promise<EmailChangeToken | null>
+  /** The account's pending change (the newest unconsumed, unexpired row),
+   *  so the console can show it. */
+  getPendingEmailChange(userId: string): Promise<EmailChangeToken | null>
+  /** Complete the ceremony: consume the token ATOMICALLY (a presented
+   *  link works exactly once, expired or not), judge the expiry, re-check
+   *  the address's uniqueness (a conflict burns the token honestly), then
+   *  move the account's email. verified = the token traveled by mailer
+   *  (mailbox proven); a shown link never verifies. */
+  completeEmailChange(token: string): Promise<CompleteEmailChangeResult>
+
+  // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03) ──
+  /** The one-time WebAuthn ceremony challenge. The challenge value IS the
+   *  key (the clientDataJSON binds it); expires_at = now + ttlMs. */
+  createWebauthnChallenge(input: {
+    challenge: string
+    userId: string | null
+    kind: WebauthnChallenge['kind']
+    ttlMs: number
+  }): Promise<void>
+  /** Atomically consume the challenge: answers the row exactly once (a
+   *  replay loses the consumed_at race); an EXPIRED row is consumed too
+   *  and answers null — never a second chance. */
+  consumeWebauthnChallenge(challenge: string): Promise<WebauthnChallenge | null>
+  /** Register the passkey. Answers NULL when the credential id is already
+   *  registered (to any account — the PRIMARY KEY is the race backstop;
+   *  the route maps it to the honest conflict). */
+  createWebauthnCredential(input: {
+    credentialId: string
+    userId: string
+    name: string
+    publicKeyCose: string
+    signCount: number
+    aaguid: string | null
+    transports: string[]
+    ip?: string | null
+  }): Promise<WebauthnCredential | null>
+  /** The account's passkeys (the console's factors section), oldest first. */
+  listWebauthnCredentials(userId: string): Promise<WebauthnCredential[]>
+  /** The assertion's lookup by the authenticator's credential id. */
+  getWebauthnCredential(credentialId: string): Promise<WebauthnCredential | null>
+  /** Revoke the account's own passkey (the user_id clause makes another
+   *  account's credential id a no-op). */
+  deleteWebauthnCredential(userId: string, credentialId: string): Promise<boolean>
+  /** The signature counter's advance, GUARDED (the clone rule): the
+   *  UPDATE lands only when the presented count legitimately follows the
+   *  stored one (both zero = the authenticator never counts; otherwise
+   *  strictly greater). 'regressed' is the clone signal — the route
+   *  fails the assertion and audits. A landed advance stamps
+   *  last_used_at/last_ip. */
+  advanceWebauthnCounter(credentialId: string, newCount: number, opts?: { ip?: string | null }): Promise<AdvanceCounterResult>
+
+  /** Start the TOTP enrollment (the PENDING row — verified_at NULL; it
+   *  activates at markTotpSecretVerified, never before). */
+  createTotpSecret(input: { id: string; userId: string; name: string; secret: string }): Promise<TotpSecret>
+  /** The account's TOTP rows, pending ones included (the route filters;
+   *  the console lists the verified only). */
+  listTotpSecrets(userId: string): Promise<TotpSecret[]>
+  getTotpSecret(id: string): Promise<TotpSecret | null>
+  /** Activate the enrollment: verified_at (+ the final name) set where
+   *  the row is still pending and belongs to the account. */
+  markTotpSecretVerified(id: string, userId: string, name: string): Promise<boolean>
+  /** The enrollment verify's throttle: fail_count++ + last_failure_at,
+   *  answering the fresh count (the route's backoff + cap read it). */
+  recordTotpEnrollFailure(id: string, userId: string): Promise<number>
+  /** A verified secret's sign-in use: last_used_at/last_ip stamped. */
+  markTotpSecretUsed(id: string, opts?: { ip?: string | null }): Promise<void>
+  /** Revoke the account's own TOTP factor (pending or verified). */
+  deleteTotpSecret(userId: string, id: string): Promise<boolean>
+
+  /** Replace the account's recovery-code set WHOLE (the regenerate: the
+   *  old batch is deleted, the new hashes land, one transaction/batch).
+   *  The hashes are SHA-256 of the normalized codes — the plaintext is
+   *  shown once and never stored. */
+  replaceRecoveryCodes(userId: string, batch: string, codeHashes: string[]): Promise<void>
+  /** The console's honest state (counts + the batch's age — never a hash). */
+  recoveryCodeState(userId: string): Promise<RecoveryCodeState>
+  /** The one-time use: consumed_at flips atomically WHERE the hash matches
+   *  an unconsumed row of the account — true exactly once per code. */
+  consumeRecoveryCode(userId: string, codeHash: string): Promise<boolean>
+
+  /** The pending second-factor sign-in row (the password verified; the
+   *  session waits on the factor). amr is the methods proven so far. */
+  createMfaPending(input: { token: string; userId: string; amr: string[]; ttlMs: number }): Promise<void>
+  /** The verify attempt's read (NOT consuming — failures keep it alive
+   *  under the throttle ladder until the cap or the TTL). */
+  getMfaPending(token: string): Promise<MfaPending | null>
+  /** The completion: consumed ATOMICALLY (a concurrent completion loses
+   *  the race and answers null); an EXPIRED row is consumed too, never
+   *  redeemed later. */
+  consumeMfaPending(token: string): Promise<MfaPending | null>
+  /** The failure ladder: fail_count++ + last_failure_at, answering the
+   *  fresh row (null when the token is gone). */
+  recordMfaPendingFailure(token: string): Promise<MfaPending | null>
+
+  // ── organization administration (TODO.identity/10) ──
+  /** File a join request (the public "Request an account" page). */
+  createOrgJoinRequest(input: {
+    name: string
+    email: string
+    orgId: string | null
+    orgNameText: string | null
+    requestedRole: string
+    note?: string | null
+  }): Promise<OrgJoinRequest>
+  getOrgJoinRequest(id: string): Promise<OrgJoinRequest | null>
+  /** The queue reads. scope 'org' = one org's queue (orgId required);
+   *  'unregistered' = BIML's new-organizations queue (org_id IS NULL);
+   *  'all' = every request (BIML's oversight). Default: 'all'. */
+  listOrgJoinRequests(filter?: {
+    scope?: 'org' | 'unregistered' | 'all'
+    orgId?: string
+    status?: OrgJoinRequest['status']
+  }): Promise<OrgJoinRequest[]>
+  /** The decision — ATOMIC on 'pending': an already-decided row answers
+   *  null (a double approve/refuse loses the race honestly). */
+  decideOrgJoinRequest(
+    id: string,
+    decision: {
+      status: 'approved' | 'refused'
+      decidedBy: string
+      refusalReason?: string | null
+      invitedUserId?: string | null
+    },
+  ): Promise<OrgJoinRequest | null>
+  /** A PENDING request from the same email exists (the duplicate guard —
+   *  decided requests never block a fresh ask). */
+  findPendingOrgJoinRequestByEmail(email: string): Promise<OrgJoinRequest | null>
+
+  // ── the multi-organization membership model (TODO.identity/11) ──
+  // The org_memberships table is the account × org × per-org role set
+  // with the lifecycle state. THE DUAL-READ DOCTRINE: the users row's
+  // org_id/roles columns stay the backward-compatible read (the PRIMARY
+  // membership's mirror) until every consumer reads the memberships —
+  // the store mirrors every legacy write into the primary membership
+  // row, and resolveOrgContext falls back to the columns when no
+  // membership row exists.
+  /** The account's memberships, every state (the console's
+   *  Organizations section, the admin's per-user page). */
+  listOrgMemberships(userId: string): Promise<OrgMembership[]>
+  /** One org's memberships (the per-org view), every state. */
+  listOrgMembers(orgId: string): Promise<OrgMembership[]>
+  getOrgMembership(userId: string, orgId: string): Promise<OrgMembership | null>
+  /** Create the membership — the org's admin inviting an EXISTING
+   *  account (state 'invited': the holder accepts from the account
+   *  console), or the join-request approval's grant (state 'active':
+   *  both consents are on record). NULL on the (user, org) conflict —
+   *  the honest "already a member". */
+  createOrgMembership(input: {
+    userId: string
+    orgId: string
+    roles: string[]
+    state: OrgMembershipState
+    invitedBy?: string | null
+  }): Promise<OrgMembership | null>
+  /** Replace the per-org role set. A PRIMARY membership's write mirrors
+   *  into the users row's roles (and the section-gating primary role
+   *  when it fell out of the set) — the dual-write keeps the legacy
+   *  read identical. Answers false when no membership exists. */
+  setOrgMembershipRoles(userId: string, orgId: string, roles: string[]): Promise<boolean>
+  /** The lifecycle act: invited → active (the holder's accept, or the
+   *  approval), active ⇄ disabled (the org's admin / the scheme
+   *  operator). Stamps activated_at / disabled_at(+by); disabling also
+   *  clears the account's sessions' active-org stamps pointing at the
+   *  org (the context ends honestly). Answers null when no membership
+   *  exists. */
+  setOrgMembershipState(
+    userId: string,
+    orgId: string,
+    state: OrgMembershipState,
+    actor?: string | null,
+  ): Promise<OrgMembership | null>
+  /** Remove the row — the holder declining an invitation, and the
+   *  erasure's cleanup. (The routes refuse the PRIMARY membership: the
+   *  primary binding moves through the account's role/org assignment,
+   *  never through a delete.) */
+  deleteOrgMembership(userId: string, orgId: string): Promise<boolean>
+  /** The session's stamped active-org context (NULL = the primary
+   *  context; also NULL for an unknown/expired token). */
+  getSessionActiveOrg(token: string): Promise<string | null>
+  /** Stamp the session's active-org context (the account console's
+   *  switcher; the route validates the membership first). NULL clears
+   *  to the primary context. */
+  setSessionActiveOrg(token: string, orgId: string | null): Promise<boolean>
+
+  // ── the organization registry (TODO.identity-features/05) ──
+  // The identity service's OWN org registry (the org_registry table):
+  // the first-class organizations the membership graph above references
+  // by id (the slug; the participant orgs' OIML codes). The lifecycle
+  // acts are the routes' — the disable CASCADE (every active membership
+  // of the org disabling honestly) is the route's loop over
+  // setOrgMembershipState; the store keeps the rows.
+  /** Every registry organization, every state, name-ordered. */
+  listOrgRegistryOrgs(): Promise<OrgRegistryOrg[]>
+  getOrgRegistryOrg(id: string): Promise<OrgRegistryOrg | null>
+  /** Add the organization. NULL on the id conflict (the slug is taken —
+   *  the route's honest 409). */
+  createOrgRegistryOrg(input: {
+    id: string
+    name: string
+    shortName?: string | null
+    kind?: string | null
+    country?: string | null
+    contacts?: OrgRegistryContact[]
+    participantRef?: string | null
+    createdBy?: string | null
+  }): Promise<OrgRegistryOrg | null>
+  /** Edit the display data (the id is the stable slug — never editable);
+   *  stamps updated_at/by. NULL when the registry does not carry the
+   *  org. */
+  updateOrgRegistryOrg(
+    id: string,
+    patch: {
+      name?: string
+      shortName?: string | null
+      kind?: string | null
+      country?: string | null
+      contacts?: OrgRegistryContact[]
+      participantRef?: string | null
+    },
+    actor?: string | null,
+  ): Promise<OrgRegistryOrg | null>
+  /** The lifecycle act: disable (the honest removal — stamps
+   *  disabled_at/by) / re-enable (the disable stamps clear; the org's
+   *  memberships stay as they are — re-activation is the per-membership
+   *  deliberate act, never an automatic one). NULL when the registry
+   *  does not carry the org. */
+  setOrgRegistryOrgState(id: string, state: OrgRegistryState, actor?: string | null): Promise<OrgRegistryOrg | null>
+  /** The erasure-adjacent hard delete — the ROUTE refuses it while any
+   *  membership or join request references the org (the honest 409:
+   *  disable it instead); this removes the row only. */
+  deleteOrgRegistryOrg(id: string): Promise<boolean>
+
+  // ── the register's holder-org attribution (TODO.register/02) ──
+  // The certificate_holder_orgs / certificate_holder_claims tables (the
+  // 0015 migration): the hub's record of WHICH OP org a registered
+  // certificate belongs to, and the legacy-row claim act's state machine.
+  /** The attribution write — INSERT-IF-ABSENT (the first attribution
+   *  wins): the new row, or NULL when the certificate already carries
+   *  one (the claim's confirmation reports the conflict honestly). */
+  attributeCertificateHolderOrg(input: {
+    certificateId: string
+    orgId: string
+    orgName: string
+    source: CertificateHolderOrg['source']
+    attributedAt: string
+    attributedBy?: string | null
+    claimId?: string | null
+  }): Promise<CertificateHolderOrg | null>
+  getCertificateHolderOrg(certificateId: string): Promise<CertificateHolderOrg | null>
+  /** The surface's reads: one org's attributions (the manufacturer cone),
+   *  or every row (the estate cone — no filter). */
+  listCertificateHolderOrgs(filter?: { orgId?: string }): Promise<CertificateHolderOrg[]>
+  /** File the legacy-row claim (the manufacturer org admin's act). */
+  createCertificateHolderClaim(input: {
+    certificateId: string
+    claimantOrgId: string
+    claimantOrgName: string
+    matchedHolderName: string
+    claimedBy: string
+  }): Promise<CertificateHolderClaim>
+  getCertificateHolderClaim(id: string): Promise<CertificateHolderClaim | null>
+  /** The queues: the estate admin's pending list (state filter), the
+   *  claiming org's own claims (claimantOrgId filter), one certificate's
+   *  claim history (certificateId filter). */
+  listCertificateHolderClaims(filter?: {
+    state?: CertificateHolderClaimState
+    claimantOrgId?: string
+    certificateId?: string
+  }): Promise<CertificateHolderClaim[]>
+  /** The estate admin's decision — ATOMIC on 'pending': an
+   *  already-decided claim answers null (a double confirm/refuse loses
+   *  the race honestly). */
+  decideCertificateHolderClaim(
+    id: string,
+    decision: {
+      status: 'confirmed' | 'refused'
+      decidedBy: string
+      refusalReason?: string | null
+    },
+  ): Promise<CertificateHolderClaim | null>
+  /** A PENDING claim on this certificate exists (the one-active-claim
+   *  guard — decided claims never block a fresh claim). */
+  findPendingCertificateHolderClaim(certificateId: string): Promise<CertificateHolderClaim | null>
+  // ── the instrument register (TODO.register/03) ──
+  // The platform-side serial register (the instrument_registrations
+  // table): one row per registered instrument under a type certificate.
+  // The scope check + the cones are the ROUTE's (browser/server/routes/
+  // registrations.ts); the store keeps the rows. Every row the store
+  // returns is a registration that STOOD — the refused declaration never
+  // lands (the route answers it with the reason).
+  /** Every registered instrument (the BIML/operator cone); ordered by
+   *  certificate then serial. */
+  listInstrumentRegistrations(): Promise<InstrumentRegistration[]>
+  /** The serials registered under one certificate (the certificate
+   *  detail's serials tab + the issuing IA's oversight cone). */
+  listInstrumentRegistrationsForCertificate(certificateId: string): Promise<InstrumentRegistration[]>
+  /** The serials one holder organization registered (the manufacturer's
+   *  own cone). */
+  listInstrumentRegistrationsForHolder(holderOrgId: string): Promise<InstrumentRegistration[]>
+  getInstrumentRegistration(id: string): Promise<InstrumentRegistration | null>
+  /** Register the instrument. NULL on the (certificate_id,
+   *  serial_number) conflict — the same physical unit never registers
+   *  twice under one certificate (the route's honest 409). */
+  createInstrumentRegistration(input: {
+    id: string
+    certificateId: string
+    holderOrgId: string
+    standardId: string
+    serialNumber: string
+    manufactureDate?: string | null
+    designations?: Record<string, unknown>
+    scopeStatus: InstrumentRegistrationScopeStatus
+    scopeDetail?: string | null
+    registeredBy?: string | null
+  }): Promise<InstrumentRegistration | null>
+  /** The lifecycle act (registered ⇄ out_of_service → withdrawn; the
+   *  transition RULE is the route's — withdrawn is terminal): stamps
+   *  updated_at/by. NULL when the register does not carry the id. */
+  setInstrumentRegistrationLifecycle(
+    id: string,
+    lifecycle: InstrumentRegistrationLifecycle,
+    actor?: string | null,
+  ): Promise<InstrumentRegistration | null>
+
+  // ── the workflow entity store + change journal ──
+  listEntities(store: string): Promise<EntityRow[]>
+  getEntity(store: string, id: string): Promise<EntityRow | undefined>
+  putEntity(store: string, id: string, orgId: string | null, data: string): Promise<void>
+  deleteEntity(store: string, id: string): Promise<boolean>
+  changesAfter(seq: number, limit?: number): Promise<EntityChange[]>
+  latestChangeSeq(): Promise<number>
+
+  // ── the platform event store (TODO.notify/01) ──
+  /** Append one declared event (the emitter's write; one row inside the
+   *  acting request's envelope). Answers the stored row (seq + at read
+   *  back). */
+  appendEvent(input: {
+    id: string
+    domain: string
+    entityId: string
+    action: string
+    payload: string
+  }): Promise<PlatformEvent>
+  /** The feed's raw leg: events past the cursor, seq-ordered. The
+   *  visibility gate is the READER's layer (server/notify-feed.ts) —
+   *  never waived here, never duplicated into the SQL. */
+  eventsAfter(seq: number, limit?: number): Promise<PlatformEvent[]>
+  latestEventSeq(): Promise<number>
+  /** The by-id read (the inbox state write's guard — TODO.notify/03: a
+   *  marker lands only on an event that exists and is the caller's). */
+  getEvent(id: string): Promise<PlatformEvent | null>
+  /** The subscription grammar's SQL resolution: the columns the pattern
+   *  pins, equality-matched (`WHERE domain = ? AND entity_id = ?` — the
+   *  column split's whole point, never a string scan on a composed key). */
+  eventsMatching(filter: EventKeyFilter, limit?: number): Promise<PlatformEvent[]>
+
+  // ── the notification subscriptions store (TODO.notify/02) ──
+  /** The user's own rule rows (both modes) — the settings page's list. */
+  listNotifyRules(userId: string): Promise<NotifyRule[]>
+  /** The upsert on UNIQUE (user_id, pattern): subscribe/unsubscribe and
+   *  pattern-mute ride the same write; the caller (the route) has already
+   *  compiled the pattern into its split legs. Answers the stored row. */
+  putNotifyRule(input: {
+    id: string
+    userId: string
+    pattern: string
+    domain: string
+    entityId: string | null
+    action: string | null
+    mode: NotifyRuleMode
+    channelOverrides: string | null
+  }): Promise<NotifyRule>
+  /** Remove the user's rule on the exact pattern (unsubscribe /
+   *  un-mute). Idempotent: answers false when no row existed. */
+  deleteNotifyRule(userId: string, pattern: string): Promise<boolean>
+  /** THE RESOLUTION'S READ (cross-user): every rule row whose pinned
+   *  legs the event satisfies — `domain = ? AND (entity_id IS NULL OR
+   *  entity_id = ?) AND (action IS NULL OR action = ?)`. The split
+   *  columns make the reverse match an index walk. */
+  notifyRulesForEvent(filter: { domain: string; entityId: string; action: string }): Promise<NotifyRule[]>
+  /** The user's per-entity mutes (the settings page's muted-threads
+   *  list). */
+  listNotifyEntityMutes(userId: string): Promise<NotifyEntityMute[]>
+  /** The entity mute's write (the bell's Muted state, the email
+   *  footer's one-click unsubscribe). Idempotent on UNIQUE
+   *  (user_id, domain, entity_id). */
+  putNotifyEntityMute(input: { id: string; userId: string; domain: string; entityId: string }): Promise<NotifyEntityMute>
+  /** Clear the entity mute. Idempotent: false when nothing was muted. */
+  deleteNotifyEntityMute(userId: string, domain: string, entityId: string): Promise<boolean>
+  /** THE RESOLUTION'S entity-mute read (cross-user): every mute naming
+   *  the event's entity. */
+  notifyEntityMutesForEvent(domain: string, entityId: string): Promise<NotifyEntityMute[]>
+  /** The user's preferences row — NULL until the first preference write
+   *  (every category then follows the catalog defaults). */
+  getNotifyPreferences(userId: string): Promise<NotifyPreferences | null>
+  /** The preferences write (the whole channels map, validated by the
+   *  route). Answers the stored row. */
+  putNotifyPreferences(userId: string, channels: string): Promise<NotifyPreferences>
+
+  // ── the inbox state (TODO.notify/03) ──
+  /** The user's inbox markers (the feed's join: read/done per event).
+   *  Written lazily at the first act — most events carry no row. */
+  listNotifyInboxStates(userId: string): Promise<NotifyInboxState[]>
+  /** The marker write (the upsert on PRIMARY KEY (user_id, event_id)):
+   *  each PRESENT flag sets its stamp (datetime('now')) or clears it
+   *  (NULL); absent flags keep. Answers the stored row. */
+  putNotifyInboxState(input: {
+    userId: string
+    eventId: string
+    read?: boolean
+    done?: boolean
+  }): Promise<NotifyInboxState>
+
+  // ── provisioning / dev support ──
+  /** The mutable workflow stores emptied (the dev-reset + demo reseed
+   *  leg): entities, entity_changes, evidence_records, events, and
+   *  instrument_registrations (TODO.register/03 — the register is
+   *  mutable workflow state; the e2e isolation resets it with the
+   *  rest). Users and sessions persist.
+   *  With `range`, ONE bounded round instead: only rows whose rowid
+   *  falls in (range.after, range.through] go, per table. The demo
+   *  reseed's reset phase walks these rounds under the slice budget —
+   *  an unbounded DELETE on a grown store dies against D1's per-
+   *  statement execution limits (the 2026-08 demo-reset flake), and
+   *  rowid ranges are stable under deletion, so rounds resume and
+   *  replay exactly. Returns the rows deleted (all tables summed). */
+  wipeWorkflowStores(range?: { after: number; through: number }): Promise<number>
+  /** The rowid ceiling across the wiped tables — the reset phase's
+   *  round planning (rounds = ceil(ceiling / chunk)). 0 on empty
+   *  stores. */
+  workflowStoreRowCeiling(): Promise<number>
+  countEntities(): Promise<number>
+}
+
+let current: ServerStore | null = null
+
+/** The composition roots install the store exactly once per process /
+ *  per binding. The stores are stateless facades over a connection or a
+ *  binding, so a per-isolate memoized install is safe across concurrent
+ *  requests. */
+export function installStore(store: ServerStore): void {
+  current = store
+}
+
+/** The installed store. Throws honestly when no composition root ran —
+ *  a route hit without an installed store is a wiring bug, never a
+ *  silent fallback. */
+export function getStore(): ServerStore {
+  if (!current) {
+    throw new Error(
+      'the server store is not installed — the composition root installs it '
+      + '(server/index.ts installs SQLite on node; server/cloudflare.ts installs D1 on the Worker)',
+    )
+  }
+  return current
+}