@oimlsmart/platform-server 0.1.0

package/src/store/d1.ts

@@ -0,0 +1,2850 @@
+// ═══════════════════════════════════════════════════════════════════
+// The D1 ServerStore (TODO.cs-e2e/14 — the Cloudflare deployment):
+// the SAME surface as the SQLite store (server/db/store.ts +
+// entities.ts) against a Cloudflare D1 binding — D1 IS SQLite, so the
+// schema (schema.sql, and the canonical migration set under
+// migrations/) and every statement port directly; only the driver
+// calls change (prepare/bind/run, async).
+//
+// WORKER-SAFE: the only import is the D1 TYPE (erased at build) — no
+// node built-ins, no better-sqlite3. The binding arrives from the
+// Worker entry (server/cloudflare.ts), which installs this store when
+// env.DB is present — the binding-presence profile switch, the same
+// pattern ENTITY_BACKEND uses client-side.
+//
+// Local proof: the smart monorepo's browser/src/__tests__/
+// d1-store.test.ts runs this class against a better-sqlite3-backed D1
+// facade (the binding contract with real semantics) plus the real
+// workerd binding through scripts/cloudflare-smoke.ts there.
+// ═══════════════════════════════════════════════════════════════════
+
+import type { D1Database, D1PreparedStatement } from '@cloudflare/workers-types'
+import {
+  DEMO_PASSWORD,
+  type AdvanceCounterResult,
+  type AuthUserPayload,
+  type CompleteEmailChangeResult,
+  type CompleteEnrollmentResult,
+  type EmailChangeToken,
+  type EnrollmentToken,
+  type EntityChange,
+  type EntityRow,
+  type EventKeyFilter,
+  type FederationPeer,
+  type IdentityApproval,
+  type IdentityLink,
+  type IdentityProvider,
+  type MfaPending,
+  type NotifyEntityMute,
+  type NotifyInboxState,
+  type NotifyPreferences,
+  type NotifyRule,
+  type OAuthInitialAssignment,
+  type OidcAccessToken,
+  type OidcAuthorization,
+  type OidcClient,
+  type OidcClientLaunch,
+  type OidcCode,
+  type OidcKeyRow,
+  type OpAccountErasure,
+  type OpClientRoleAssignment,
+  type OpLiveSession,
+  type OrgJoinRequest,
+  type OrgMembership,
+  type OrgMembershipState,
+  type CertificateHolderClaim,
+  type CertificateHolderOrg,
+  type OrgRegistryContact,
+  type OrgRegistryOrg,
+  type OrgRegistryState,
+  type InstrumentRegistration,
+  type InstrumentRegistrationLifecycle,
+  type InstrumentRegistrationScopeStatus,
+  type PlatformEvent,
+  resolveOrgContext,
+  type RecoveryCodeState,
+  type ServerStore,
+  type SessionView,
+  type SsoSignInState,
+  type TotpSecret,
+  type UserAdminRow,
+  type WebauthnChallenge,
+  type WebauthnCredential,
+} from '../store'
+// TODO.federation/01 — the account plan follows the deployment profile
+// (the Worker's seed route installs it from the env binding first; the
+// slot defaults to the hub profile, which is exactly DEMO_ACCOUNTS).
+import { getInstanceProfile, seedAccountsForProfile } from '../profile'
+
+interface UserRecord {
+  id: string
+  email: string
+  name: string
+  role: string
+  org_id: string | null
+  avatar_url: string | null
+  roles: string | null
+  active: number
+  provider: string
+  email_verified_at?: string | null
+}
+
+function parseRoles(raw: string | null): string[] | undefined {
+  if (!raw) return undefined
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    return Array.isArray(parsed) && parsed.length ? parsed.filter((v): v is string => typeof v === 'string') : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function toPayload(user: UserRecord, avatarUrl?: string): AuthUserPayload {
+  const roles = parseRoles(user.roles)
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    role: user.role,
+    ...(roles?.length ? { roles } : {}),
+    orgId: user.org_id ?? null,
+    avatarUrl: avatarUrl ?? user.avatar_url ?? undefined,
+    provider: user.provider,
+    // TODO.identity/06: the primary address's verification state.
+    emailVerifiedAt: user.email_verified_at ?? null,
+  }
+}
+
+/** The identity_approvals row → the seam's camelCase shape. */
+function toIdentityApproval(row: Record<string, unknown>): IdentityApproval {
+  return {
+    id: row.id as string,
+    email: row.email as string,
+    name: row.name as string,
+    issuer: row.issuer as string,
+    sub: row.sub as string,
+    claimsJson: (row.claims_json as string | null) ?? null,
+    status: row.status as IdentityApproval['status'],
+    decidedRole: (row.decided_role as string | null) ?? null,
+    decidedOrg: (row.decided_org as string | null) ?? null,
+    decidedBy: (row.decided_by as string | null) ?? null,
+    createdAt: row.created_at as string,
+    lastSeen: (row.last_seen as string | null) ?? (row.created_at as string),
+    decidedAt: (row.decided_at as string | null) ?? null,
+  }
+}
+
+/** The federation_peers row → the seam's camelCase shape
+ *  (TODO.federation/04). */
+function toFederationPeer(row: Record<string, unknown>): FederationPeer {
+  return {
+    id: row.id as string,
+    name: row.name as string,
+    roles: row.roles as string,
+    descriptorUrl: (row.descriptor_url as string | null) ?? null,
+    descriptorJson: row.descriptor_json as string,
+    pinnedVia: row.pinned_via as FederationPeer['pinnedVia'],
+    connectivity: row.connectivity as FederationPeer['connectivity'],
+    status: row.status as FederationPeer['status'],
+    addedAt: row.added_at as string,
+    addedBy: (row.added_by as string | null) ?? null,
+    refreshedAt: (row.refreshed_at as string | null) ?? null,
+    revokedAt: (row.revoked_at as string | null) ?? null,
+    revokedBy: (row.revoked_by as string | null) ?? null,
+  }
+}
+
+function toAdminRow(user: UserRecord & { last_login?: string | null; provider?: string }): UserAdminRow {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    role: user.role,
+    roles: parseRoles(user.roles) ?? [user.role],
+    orgId: user.org_id ?? null,
+    active: user.active !== 0,
+    provider: user.provider ?? 'demo',
+    lastLogin: user.last_login ?? null,
+    emailVerifiedAt: user.email_verified_at ?? null,
+  }
+}
+
+/** The workflow tables the reset wipe covers, in a fixed order. Ranged
+ *  rounds address rows by rowid (stable under deletion, so a resumed
+ *  round never re-scans); every table here is an ordinary rowid table
+ *  (none WITHOUT ROWID — schema.sql). The TODO.notify/01 event store
+ *  wipes with them — its rows reference the workflow entities a reset
+ *  removes (the feed's read-time visibility gate would drop the orphans
+ *  anyway; wiping keeps the demo honest). */
+const WIPE_TABLES = ['entity_changes', 'evidence_records', 'entities', 'events', 'instrument_registrations'] as const
+
+export class D1ServerStore implements ServerStore {
+  constructor(private readonly db: D1Database) {}
+
+  private stmt(sql: string, ...params: unknown[]): D1PreparedStatement {
+    return this.db.prepare(sql).bind(...params)
+  }
+
+  // TODO.federation/12: the roles/active columns arrive with migration
+  // 0002 — a dev D1 migrated from the pre-RBAC 0001 lacks them, so the
+  //  user methods ensure them defensively (PRAGMA probe + ALTER),
+  //  memoized per store.
+  private usersColumnsEnsured: Promise<void> | null = null
+
+  private ensureUserColumns(): Promise<void> {
+    if (!this.usersColumnsEnsured) {
+      this.usersColumnsEnsured = (async () => {
+        const cols = await this.db.prepare('PRAGMA table_info(users)').all<{ name: string }>()
+        const names = new Set(cols.results.map(c => c.name))
+        if (!names.has('roles')) await this.db.prepare('ALTER TABLE users ADD COLUMN roles TEXT').run()
+        if (!names.has('active')) await this.db.prepare('ALTER TABLE users ADD COLUMN active INTEGER NOT NULL DEFAULT 1').run()
+        // TODO.identity/06 (the account console): the address's
+        // verification state.
+        if (!names.has('email_verified_at')) await this.db.prepare('ALTER TABLE users ADD COLUMN email_verified_at TEXT').run()
+      })()
+    }
+    return this.usersColumnsEnsured
+  }
+
+  // TODO.identity/06 (the account console's sessions section): the
+  // sign-in context columns arrive with migration 0009 — a dev D1
+  // migrated from before it lacks them, so the session methods ensure
+  // them defensively (the ensureUserColumns posture, memoized per store).
+  private sessionColumnsEnsured: Promise<void> | null = null
+
+  private ensureSessionColumns(): Promise<void> {
+    if (!this.sessionColumnsEnsured) {
+      this.sessionColumnsEnsured = (async () => {
+        const cols = await this.db.prepare('PRAGMA table_info(sessions)').all<{ name: string }>()
+        const names = new Set(cols.results.map(c => c.name))
+        if (!names.has('user_agent')) await this.db.prepare('ALTER TABLE sessions ADD COLUMN user_agent TEXT').run()
+        if (!names.has('ip')) await this.db.prepare('ALTER TABLE sessions ADD COLUMN ip TEXT').run()
+        if (!names.has('last_seen_at')) await this.db.prepare('ALTER TABLE sessions ADD COLUMN last_seen_at TEXT').run()
+        // TODO.identity-sso/02+03: the sign-in provenance.
+        if (!names.has('amr')) await this.db.prepare('ALTER TABLE sessions ADD COLUMN amr TEXT').run()
+      })()
+    }
+    return this.sessionColumnsEnsured
+  }
+
+  // TODO.identity/11 (the multi-org membership model): the
+  // org_memberships table, the session's active-org stamp and the
+  // token-flow context columns arrive with migration 0011 — a dev D1
+  // migrated from before it lacks them, so the membership/session/token
+  // methods ensure them defensively (the ensureUserColumns posture,
+  // memoized per store). The backfill (the migration's twin) is
+  // IDEMPOTENT and rides the ensure: every org-bound account's primary
+  // membership mirrors the legacy columns.
+  private membershipSupportEnsured: Promise<void> | null = null
+
+  private ensureMembershipSupport(): Promise<void> {
+    if (!this.membershipSupportEnsured) {
+      this.membershipSupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS org_memberships (
+             id TEXT PRIMARY KEY,
+             user_id TEXT NOT NULL REFERENCES users(id),
+             org_id TEXT NOT NULL,
+             roles TEXT NOT NULL DEFAULT '[]',
+             state TEXT NOT NULL DEFAULT 'active',
+             is_primary INTEGER NOT NULL DEFAULT 0,
+             invited_by TEXT,
+             created_at TEXT NOT NULL DEFAULT (datetime('now')),
+             activated_at TEXT,
+             disabled_at TEXT,
+             disabled_by TEXT,
+             UNIQUE (user_id, org_id)
+           )`,
+        ).run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_org_memberships_org ON org_memberships (org_id, state)').run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_org_memberships_user ON org_memberships (user_id, state)').run()
+        const sessionCols = await this.db.prepare('PRAGMA table_info(sessions)').all<{ name: string }>()
+        if (!sessionCols.results.some(c => c.name === 'active_org')) {
+          await this.db.prepare('ALTER TABLE sessions ADD COLUMN active_org TEXT').run()
+        }
+        const codeCols = await this.db.prepare('PRAGMA table_info(oidc_codes)').all<{ name: string }>()
+        if (!codeCols.results.some(c => c.name === 'context_org')) {
+          await this.db.prepare('ALTER TABLE oidc_codes ADD COLUMN context_org TEXT').run()
+        }
+        const accessCols = await this.db.prepare('PRAGMA table_info(oidc_access_tokens)').all<{ name: string }>()
+        if (!accessCols.results.some(c => c.name === 'context_org')) {
+          await this.db.prepare('ALTER TABLE oidc_access_tokens ADD COLUMN context_org TEXT').run()
+        }
+        await this.db.prepare(
+          `INSERT OR IGNORE INTO org_memberships (id, user_id, org_id, roles, state, is_primary, activated_at)
+           SELECT 'mbr-' || id, id, org_id,
+                  CASE WHEN roles IS NOT NULL AND roles != '' THEN roles ELSE json_array(role) END,
+                  'active', 1, COALESCE(last_login, created_at)
+           FROM users WHERE org_id IS NOT NULL`,
+        ).run()
+      })()
+    }
+    return this.membershipSupportEnsured
+  }
+
+  // TODO.identity-features/05 (the organization registry): the
+  // org_registry table arrives with migration 0013 — a dev D1 migrated
+  // from before it lacks the table, so the registry methods ensure it
+  // defensively (the ensureMembershipSupport posture, memoized per
+  // store).
+  private orgRegistrySupportEnsured: Promise<void> | null = null
+
+  private ensureOrgRegistrySupport(): Promise<void> {
+    if (!this.orgRegistrySupportEnsured) {
+      this.orgRegistrySupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS org_registry (
+             id TEXT PRIMARY KEY,
+             name TEXT NOT NULL,
+             short_name TEXT,
+             kind TEXT,
+             country TEXT,
+             contacts TEXT NOT NULL DEFAULT '[]',
+             participant_ref TEXT,
+             state TEXT NOT NULL DEFAULT 'active',
+             created_at TEXT NOT NULL DEFAULT (datetime('now')),
+             created_by TEXT,
+             updated_at TEXT,
+             updated_by TEXT,
+             disabled_at TEXT,
+             disabled_by TEXT
+           )`,
+        ).run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_org_registry_state ON org_registry (state)').run()
+      })()
+    }
+    return this.orgRegistrySupportEnsured
+  }
+
+  // TODO.register/02 (the register's holder-org attribution): the
+  // certificate_holder_orgs / certificate_holder_claims tables arrive with
+  // migration 0015 — a dev D1 migrated from before it lacks them, so the
+  // attribution/claim methods ensure them defensively (the
+  // ensureOrgRegistrySupport posture, memoized per store).
+  private holderAttributionSupportEnsured: Promise<void> | null = null
+
+  private ensureHolderAttributionSupport(): Promise<void> {
+    if (!this.holderAttributionSupportEnsured) {
+      this.holderAttributionSupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS certificate_holder_orgs (
+             certificate_id TEXT PRIMARY KEY,
+             org_id TEXT NOT NULL,
+             org_name TEXT NOT NULL,
+             source TEXT NOT NULL,
+             attributed_at TEXT NOT NULL,
+             attributed_by TEXT,
+             claim_id TEXT
+           )`,
+        ).run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_certificate_holder_orgs_org ON certificate_holder_orgs (org_id)').run()
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS certificate_holder_claims (
+             id TEXT PRIMARY KEY,
+             certificate_id TEXT NOT NULL,
+             claimant_org_id TEXT NOT NULL,
+             claimant_org_name TEXT NOT NULL,
+             matched_holder_name TEXT NOT NULL,
+             claimed_by TEXT NOT NULL,
+             state TEXT NOT NULL DEFAULT 'pending',
+             decided_by TEXT,
+             decided_at TEXT,
+             refusal_reason TEXT,
+             created_at TEXT NOT NULL DEFAULT (datetime('now'))
+           )`,
+        ).run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_certificate_holder_claims_cert ON certificate_holder_claims (certificate_id)').run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_certificate_holder_claims_state ON certificate_holder_claims (state)').run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_certificate_holder_claims_org ON certificate_holder_claims (claimant_org_id)').run()
+      })()
+    }
+    return this.holderAttributionSupportEnsured
+  }
+
+  // TODO.register/03 (the instrument register): the
+  // instrument_registrations table arrives with migration 0016 — a dev
+  // D1 migrated from before it lacks the table, so the register methods
+  // ensure it defensively (the ensureOrgRegistrySupport posture,
+  // memoized per store).
+  private instrumentRegistrationSupportEnsured: Promise<void> | null = null
+
+  private ensureInstrumentRegistrationSupport(): Promise<void> {
+    if (!this.instrumentRegistrationSupportEnsured) {
+      this.instrumentRegistrationSupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS instrument_registrations (
+             id TEXT PRIMARY KEY,
+             certificate_id TEXT NOT NULL,
+             holder_org_id TEXT NOT NULL,
+             standard_id TEXT NOT NULL,
+             serial_number TEXT NOT NULL,
+             manufacture_date TEXT,
+             designations TEXT NOT NULL DEFAULT '{}',
+             scope_status TEXT NOT NULL,
+             scope_detail TEXT,
+             lifecycle TEXT NOT NULL DEFAULT 'registered',
+             registered_at TEXT NOT NULL DEFAULT (datetime('now')),
+             registered_by TEXT,
+             updated_at TEXT,
+             updated_by TEXT,
+             UNIQUE (certificate_id, serial_number)
+           )`,
+        ).run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_instrument_registrations_certificate ON instrument_registrations (certificate_id)').run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_instrument_registrations_holder ON instrument_registrations (holder_org_id)').run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_instrument_registrations_lifecycle ON instrument_registrations (lifecycle)').run()
+      })()
+    }
+    return this.instrumentRegistrationSupportEnsured
+  }
+
+  // TODO.identity-sso/02+03: the amr provenance columns on the OIDC
+  // flow rows arrive with migration 0012 — the OIDC methods ensure them
+  // defensively (the same memoized posture as the session/user columns),
+  // so a dev D1 migrated from before the wave never 500s the core flow.
+  private oidcColumnsEnsured: Promise<void> | null = null
+
+  private ensureOidcColumns(): Promise<void> {
+    if (!this.oidcColumnsEnsured) {
+      this.oidcColumnsEnsured = (async () => {
+        const codeCols = await this.db.prepare('PRAGMA table_info(oidc_codes)').all<{ name: string }>()
+        if (!codeCols.results.some(c => c.name === 'amr')) {
+          await this.db.prepare('ALTER TABLE oidc_codes ADD COLUMN amr TEXT').run()
+        }
+        const tokenCols = await this.db.prepare('PRAGMA table_info(oidc_access_tokens)').all<{ name: string }>()
+        if (!tokenCols.results.some(c => c.name === 'amr')) {
+          await this.db.prepare('ALTER TABLE oidc_access_tokens ADD COLUMN amr TEXT').run()
+        }
+      })()
+    }
+    return this.oidcColumnsEnsured
+  }
+
+  // ── users / sessions ─────────────────────────────────────────────
+
+  async seedDemoAccounts(): Promise<void> {
+    const statements: D1PreparedStatement[] = []
+    for (const account of seedAccountsForProfile(getInstanceProfile())) {
+      // The roles column carries the account's declared FULL set (NULL =
+      // the primary role only); the align clears a stale set honestly
+      // (the SQLite seed's rule).
+      const roles = account.roles?.length ? JSON.stringify(account.roles) : null
+      statements.push(this.stmt(
+        `INSERT OR IGNORE INTO users (id, email, name, provider, provider_account_id, role, org_id, roles)
+         VALUES (?, ?, ?, 'demo', ?, ?, ?, ?)`,
+        crypto.randomUUID(), account.email, account.name, account.email, account.role, account.orgId, roles,
+      ))
+      // Align existing demo rows with the current role/org assignments —
+      // INSERT OR IGNORE alone would leave them stale (same rule as the
+      // SQLite seed).
+      statements.push(this.stmt(
+        `UPDATE users SET name = ?, role = ?, org_id = ?, roles = ? WHERE email = ? AND provider = 'demo'`,
+        account.name, account.role, account.orgId, roles, account.email,
+      ))
+    }
+    // A profile with no demo cast (the production posture) is an honest
+    // no-op, never an error — D1's batch rejects an empty statement
+    // list ("No SQL statements detected").
+    if (statements.length === 0) return
+    await this.db.batch(statements)
+    // TODO.identity/11: the org-bound seed accounts' primary memberships
+    // ride the mirror (idempotent — the seed runs at every boot).
+    for (const account of seedAccountsForProfile(getInstanceProfile())) {
+      if (!account.orgId) continue
+      const row = await this.stmt('SELECT id FROM users WHERE email = ?', account.email).first<{ id: string }>()
+      if (row) await this.syncPrimaryMembership(row.id)
+    }
+  }
+
+  async authenticateDemo(email: string, password: string): Promise<AuthUserPayload | null> {
+    await this.ensureUserColumns()
+    const user = await this.stmt("SELECT * FROM users WHERE email = ? AND provider = 'demo'", email)
+      .first<UserRecord>()
+    if (!user) return null
+    // A deactivated account refuses sign-in (TODO.federation/12).
+    if (user.active === 0) return null
+    if (password !== DEMO_PASSWORD) return null
+    await this.stmt("UPDATE users SET last_login = datetime('now') WHERE id = ?", user.id).run()
+    return toPayload(user)
+  }
+
+  async findOrCreateOAuthUser(
+    provider: string,
+    providerAccountId: string,
+    email: string,
+    name: string,
+    avatarUrl?: string,
+    // The INITIAL role/org — applied only on CREATE (an existing
+    // account keeps its local assignment).
+    initial?: OAuthInitialAssignment,
+  ): Promise<AuthUserPayload> {
+    const existing = await this.stmt(
+      'SELECT * FROM users WHERE provider = ? AND provider_account_id = ?', provider, providerAccountId,
+    ).first<UserRecord>()
+
+    if (existing) {
+      await this.stmt("UPDATE users SET last_login = datetime('now'), avatar_url = ? WHERE id = ?",
+        avatarUrl ?? null, existing.id).run()
+      return toPayload(existing, avatarUrl)
+    }
+
+    const id = crypto.randomUUID()
+    const role = initial?.role ?? 'user'
+    const orgId = initial?.orgId ?? null
+    await this.stmt(
+      "INSERT INTO users (id, email, name, avatar_url, provider, provider_account_id, role, org_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+      id, email, name, avatarUrl ?? null, provider, providerAccountId, role, orgId,
+    ).run()
+    if (orgId) await this.syncPrimaryMembership(id) // TODO.identity/11 — the mirror
+    return { id, email, name, role, orgId, avatarUrl }
+  }
+
+  async createSession(
+    userId: string,
+    opts?: { idTokenHint?: string | null; userAgent?: string | null; ip?: string | null; amr?: string[] | null },
+  ): Promise<string> {
+    await this.ensureSessionColumns()
+    const token = crypto.randomUUID()
+    const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
+    await this.stmt(
+      'INSERT INTO sessions (id, user_id, token, expires_at, id_token_hint, user_agent, ip, last_seen_at, amr) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+      crypto.randomUUID(), userId, token, expiresAt, opts?.idTokenHint ?? null, opts?.userAgent ?? null, opts?.ip ?? null, null,
+      opts?.amr?.length ? JSON.stringify(opts.amr) : null,
+    ).run()
+    return token
+  }
+
+  async touchLastLogin(userId: string): Promise<void> {
+    await this.stmt("UPDATE users SET last_login = datetime('now') WHERE id = ?", userId).run()
+  }
+
+  async getSessionIdTokenHint(token: string): Promise<string | null> {
+    const row = await this.stmt(
+      "SELECT id_token_hint FROM sessions WHERE token = ? AND expires_at > datetime('now')",
+      token,
+    ).first<{ id_token_hint: string | null }>()
+    return row?.id_token_hint ?? null
+  }
+
+  async getSessionUser(token: string): Promise<AuthUserPayload | null> {
+    await this.ensureUserColumns()
+    await this.ensureSessionColumns()
+    await this.ensureMembershipSupport()
+    // The session joins the LIVE user row (TODO.federation/12): a role
+    // reassignment takes effect on the next request; deactivation ends
+    // the session at once.
+    const session = await this.stmt(
+      `SELECT s.user_id, s.active_org, s.amr, u.email, u.name, u.role, u.roles, u.org_id, u.avatar_url, u.provider, u.email_verified_at
+       FROM sessions s JOIN users u ON s.user_id = u.id
+       WHERE s.token = ? AND s.expires_at > datetime('now') AND u.active = 1`,
+      token,
+    ).first<{ user_id: string; active_org: string | null; amr: string | null; email: string; name: string; role: string; roles: string | null; org_id: string | null; avatar_url: string | null; provider: string; email_verified_at: string | null }>()
+    if (!session) return null
+    // TODO.identity/06: the last-active stamp, throttled to one write
+    // per minute per session (the sessions section shows it).
+    await this.stmt(
+      "UPDATE sessions SET last_seen_at = datetime('now') WHERE token = ? AND (last_seen_at IS NULL OR last_seen_at < datetime('now', '-60 seconds'))",
+      token,
+    ).run()
+    const amr = parseRoles(session.amr)
+    const payload: AuthUserPayload = {
+      id: session.user_id,
+      email: session.email,
+      name: session.name,
+      role: session.role,
+      ...(parseRoles(session.roles)?.length ? { roles: parseRoles(session.roles) } : {}),
+      orgId: session.org_id ?? null,
+      avatarUrl: session.avatar_url ?? undefined,
+      provider: session.provider,
+      emailVerifiedAt: session.email_verified_at ?? null,
+      ...(amr?.length ? { amr } : {}),
+    }
+    // TODO.identity/11: the active-org context (the membership model) —
+    // the payload's org/roles follow the session's stamped context.
+    const activeOrg = session.active_org ?? null
+    const active = activeOrg ? await this.getOrgMembership(payload.id, activeOrg) : null
+    const primary = payload.orgId ? await this.getOrgMembership(payload.id, payload.orgId) : null
+    const resolved = resolveOrgContext(payload, { activeOrg, active, primary })
+    if (activeOrg && !(active && active.state === 'active')) {
+      // The stale stamp never lingers (the membership ended mid-session).
+      await this.stmt('UPDATE sessions SET active_org = NULL WHERE user_id = ? AND active_org = ?', payload.id, activeOrg).run()
+    }
+    return { ...payload, orgId: resolved.orgId, roles: resolved.roles }
+  }
+
+  async deleteSession(token: string): Promise<void> {
+    await this.stmt('DELETE FROM sessions WHERE token = ?', token).run()
+  }
+
+  async cleanExpiredSessions(): Promise<void> {
+    await this.stmt("DELETE FROM sessions WHERE expires_at <= datetime('now')").run()
+  }
+
+  async listDemoAccounts(): Promise<Array<{ email: string; name: string; role: string }>> {
+    const res = await this.stmt(
+      "SELECT email, name, role FROM users WHERE provider = 'demo' ORDER BY role, name",
+    ).all<{ email: string; name: string; role: string }>()
+    return res.results
+  }
+
+  // ── identity federation (TODO.federation/10) ───────────────────────
+
+  async findUserByEmail(email: string): Promise<AuthUserPayload | null> {
+    const user = await this.stmt('SELECT * FROM users WHERE email = ?', email).first<UserRecord>()
+    return user ? toPayload(user) : null
+  }
+
+  /** TODO.identity/01 — the OP's token endpoint resolves the code's
+   *  user_id through this. */
+  async getUserById(id: string): Promise<AuthUserPayload | null> {
+    const user = await this.stmt('SELECT * FROM users WHERE id = ?', id).first<UserRecord>()
+    return user ? toPayload(user) : null
+  }
+
+  async findUserByProvider(provider: string, providerAccountId: string): Promise<AuthUserPayload | null> {
+    const user = await this.stmt(
+      'SELECT * FROM users WHERE provider = ? AND provider_account_id = ?', provider, providerAccountId,
+    ).first<UserRecord>()
+    return user ? toPayload(user) : null
+  }
+
+  async provisionSsoUser(input: {
+    email: string
+    name: string
+    provider: string
+    providerAccountId: string
+    role: string
+    orgId: string | null
+  }): Promise<AuthUserPayload> {
+    const id = crypto.randomUUID()
+    await this.stmt(
+      "INSERT INTO users (id, email, name, provider, provider_account_id, role, org_id, last_login) VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))",
+      id, input.email, input.name, input.provider, input.providerAccountId, input.role, input.orgId,
+    ).run()
+    if (input.orgId) await this.syncPrimaryMembership(id) // TODO.identity/11 — the mirror
+    return { id, email: input.email, name: input.name, role: input.role, orgId: input.orgId }
+  }
+
+  async linkProviderIdentity(userId: string, provider: string, providerAccountId: string): Promise<void> {
+    await this.stmt(
+      "UPDATE users SET provider = ?, provider_account_id = ?, last_login = datetime('now') WHERE id = ?",
+      provider, providerAccountId, userId,
+    ).run()
+  }
+
+  async updateUserRoleOrg(userId: string, role: string, orgId: string | null): Promise<void> {
+    await this.stmt('UPDATE users SET role = ?, org_id = ? WHERE id = ?', role, orgId, userId).run()
+    if (orgId) await this.syncPrimaryMembership(userId) // TODO.identity/11 — the mirror
+  }
+
+  // The approval queue rows port directly (D1 is SQLite).
+
+  private async approvalRow(where: string, ...params: unknown[]) {
+    const row = await this.stmt(`SELECT * FROM identity_approvals WHERE ${where}`, ...params)
+      .first<Record<string, unknown>>()
+    return row ? toIdentityApproval(row) : null
+  }
+
+  async upsertIdentityApproval(input: {
+    email: string
+    name: string
+    issuer: string
+    sub: string
+    claimsJson: string | null
+  }): Promise<IdentityApproval> {
+    await this.stmt(
+      `INSERT INTO identity_approvals (id, email, name, issuer, sub, claims_json, last_seen)
+       VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+       ON CONFLICT (issuer, sub) DO UPDATE SET
+         email = excluded.email, name = excluded.name, claims_json = excluded.claims_json,
+         last_seen = datetime('now')`,
+      crypto.randomUUID(), input.email, input.name, input.issuer, input.sub, input.claimsJson,
+    ).run()
+    return (await this.approvalRow('issuer = ? AND sub = ?', input.issuer, input.sub))!
+  }
+
+  async getIdentityApproval(issuer: string, sub: string): Promise<IdentityApproval | null> {
+    return this.approvalRow('issuer = ? AND sub = ?', issuer, sub)
+  }
+
+  async listIdentityApprovals(status?: IdentityApproval['status']): Promise<IdentityApproval[]> {
+    const res = status
+      ? await this.stmt('SELECT * FROM identity_approvals WHERE status = ? ORDER BY created_at', status).all<Record<string, unknown>>()
+      : await this.stmt('SELECT * FROM identity_approvals ORDER BY created_at').all<Record<string, unknown>>()
+    return res.results.map(toIdentityApproval)
+  }
+
+  async decideIdentityApproval(
+    id: string,
+    decision: { status: 'approved' | 'rejected'; role?: string; orgId?: string | null; decidedBy: string },
+  ): Promise<IdentityApproval | null> {
+    await this.stmt(
+      `UPDATE identity_approvals SET status = ?, decided_role = ?, decided_org = ?, decided_by = ?, decided_at = datetime('now')
+       WHERE id = ?`,
+      decision.status, decision.role ?? null, decision.orgId ?? null, decision.decidedBy, id,
+    ).run()
+    return this.approvalRow('id = ?', id)
+  }
+
+  // ── the SSO sign-in state jar (TODO.identity/04) ───────────────────
+  // The rows port directly (D1 is SQLite); the consume's UPDATE flip is
+  // the atomic single-use guarantee across isolates.
+
+  async putSsoState(input: { state: string; nonce: string; verifier: string; ttlMs: number }): Promise<void> {
+    // The expiry sweep rides the write: stale rows are inert (consume
+    // checks the expiry) but never accumulate.
+    await this.stmt('DELETE FROM sso_states WHERE expires_at <= ?', new Date().toISOString()).run()
+    await this.stmt(
+      'INSERT INTO sso_states (state, nonce, verifier, expires_at) VALUES (?, ?, ?, ?)',
+      input.state, input.nonce, input.verifier, new Date(Date.now() + input.ttlMs).toISOString(),
+    ).run()
+  }
+
+  /** Atomically consume the state: the UPDATE flips consumed_at exactly
+   *  once (a replay loses the race and answers null). An EXPIRED row is
+   *  consumed too — never a second chance. */
+  async consumeSsoState(state: string): Promise<SsoSignInState | null> {
+    const res = await this.stmt(
+      "UPDATE sso_states SET consumed_at = datetime('now') WHERE state = ? AND consumed_at IS NULL", state,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    const row = await this.stmt('SELECT state, nonce, verifier, expires_at FROM sso_states WHERE state = ?', state)
+      .first<Record<string, unknown>>()
+    if (!row) return null
+    if (new Date(row.expires_at as string).getTime() <= Date.now()) return null
+    return {
+      state: row.state as string,
+      nonce: row.nonce as string,
+      verifier: row.verifier as string,
+      expiresAt: row.expires_at as string,
+    }
+  }
+
+  // ── federation peers (TODO.federation/04) ───────────────────────────
+  // The peer rows port directly (D1 is SQLite).
+
+  async listFederationPeers(status?: FederationPeer['status']): Promise<FederationPeer[]> {
+    const res = status
+      ? await this.stmt('SELECT * FROM federation_peers WHERE status = ? ORDER BY added_at', status).all<Record<string, unknown>>()
+      : await this.stmt('SELECT * FROM federation_peers ORDER BY added_at').all<Record<string, unknown>>()
+    return res.results.map(toFederationPeer)
+  }
+
+  async getFederationPeer(id: string): Promise<FederationPeer | null> {
+    const row = await this.stmt('SELECT * FROM federation_peers WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? toFederationPeer(row) : null
+  }
+
+  async upsertFederationPeer(input: {
+    id: string
+    name: string
+    roles: string
+    descriptorUrl: string | null
+    descriptorJson: string
+    pinnedVia: FederationPeer['pinnedVia']
+    connectivity: FederationPeer['connectivity']
+    addedBy: string | null
+  }): Promise<FederationPeer> {
+    // The same upsert semantics as the SQLite store: an update stamps
+    // refreshed_at and never resurrects a revoked peer.
+    await this.stmt(
+      `INSERT INTO federation_peers (id, name, roles, descriptor_url, descriptor_json, pinned_via, connectivity, added_by)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (id) DO UPDATE SET
+         name = excluded.name, roles = excluded.roles,
+         descriptor_url = excluded.descriptor_url, descriptor_json = excluded.descriptor_json,
+         pinned_via = excluded.pinned_via, connectivity = excluded.connectivity,
+         refreshed_at = datetime('now')`,
+      input.id, input.name, input.roles, input.descriptorUrl, input.descriptorJson, input.pinnedVia, input.connectivity, input.addedBy,
+    ).run()
+    return (await this.getFederationPeer(input.id))!
+  }
+
+  async revokeFederationPeer(id: string, revokedBy: string): Promise<FederationPeer | null> {
+    await this.stmt(
+      `UPDATE federation_peers SET status = 'revoked', revoked_at = datetime('now'), revoked_by = ? WHERE id = ?`,
+      revokedBy, id,
+    ).run()
+    return this.getFederationPeer(id)
+  }
+
+  // ── user administration (TODO.federation/12) ─────────────────────
+
+  async listUsers(): Promise<UserAdminRow[]> {
+    await this.ensureUserColumns()
+    const res = await this.stmt('SELECT * FROM users ORDER BY name')
+      .all<UserRecord & { last_login?: string | null; provider?: string }>()
+    return res.results.map(toAdminRow)
+  }
+
+  async createLocalUser(input: {
+    email: string
+    name: string
+    role: string
+    roles?: string[]
+    orgId?: string | null
+  }): Promise<UserAdminRow> {
+    await this.ensureUserColumns()
+    const id = crypto.randomUUID()
+    const roles = input.roles?.length ? input.roles : [input.role]
+    await this.stmt(
+      `INSERT INTO users (id, email, name, provider, provider_account_id, role, roles, org_id)
+       VALUES (?, ?, ?, 'demo', ?, ?, ?, ?)`,
+      id, input.email, input.name, input.email, input.role, JSON.stringify(roles), input.orgId ?? null,
+    ).run()
+    if (input.orgId) await this.syncPrimaryMembership(id) // TODO.identity/11 — the mirror
+    const row = await this.stmt('SELECT * FROM users WHERE id = ?', id).first<UserRecord>()
+    return toAdminRow(row!)
+  }
+
+  async setUserRoles(id: string, role: string, roles: string[]): Promise<boolean> {
+    await this.ensureUserColumns()
+    const res = await this.stmt(
+      'UPDATE users SET role = ?, roles = ? WHERE id = ?',
+      role, JSON.stringify(roles.length ? roles : [role]), id,
+    ).run()
+    // TODO.identity/11 — the mirror (a no-op for org-free accounts).
+    if ((res.meta.changes ?? 0) > 0) await this.syncPrimaryMembership(id)
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  async setUserActive(id: string, active: boolean): Promise<boolean> {
+    await this.ensureUserColumns()
+    const res = await this.stmt('UPDATE users SET active = ? WHERE id = ?', active ? 1 : 0, id).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  // ── the OIDC Provider (TODO.identity/01) ───────────────────────────
+  // The OP rows port directly (D1 is SQLite) — the same statements as
+  // op-store.ts's sync half.
+
+  private static toOidcClient(row: Record<string, unknown>): OidcClient {
+    return {
+      clientId: row.client_id as string,
+      name: row.name as string,
+      secretHash: (row.secret_hash as string | null) ?? null,
+      redirectUris: JSON.parse(row.redirect_uris as string) as string[],
+      claimsPolicy: row.claims_policy ? JSON.parse(row.claims_policy as string) as OidcClient['claimsPolicy'] : null,
+      // The SSO-home launch metadata (migration 0011): no launch_url =
+      // the client never appears on the launcher. A pre-0011 database
+      // reads the columns as absent — launch stays null, the honest
+      // default.
+      launch: row.launch_url
+        ? {
+            url: row.launch_url as string,
+            icon: (row.launch_icon as string | null) ?? null,
+            description: (row.launch_description as string | null) ?? null,
+            visibility: ((row.launch_visibility as string | null) ?? 'roles') as OidcClientLaunch['visibility'],
+          }
+        : null,
+      status: row.status as OidcClient['status'],
+      createdAt: row.created_at as string,
+      createdBy: (row.created_by as string | null) ?? null,
+    }
+  }
+
+  private static toOidcAuthorization(row: Record<string, unknown>): OidcAuthorization {
+    return {
+      id: row.id as string,
+      clientId: row.client_id as string,
+      redirectUri: row.redirect_uri as string,
+      scope: row.scope as string,
+      state: row.state as string,
+      nonce: (row.nonce as string | null) ?? null,
+      codeChallenge: row.code_challenge as string,
+      userId: (row.user_id as string | null) ?? null,
+      decision: (row.decision as OidcAuthorization['decision']) ?? null,
+      createdAt: row.created_at as string,
+      expiresAt: row.expires_at as string,
+    }
+  }
+
+  async getOidcClient(clientId: string): Promise<OidcClient | null> {
+    const row = await this.stmt('SELECT * FROM oidc_clients WHERE client_id = ?', clientId).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toOidcClient(row) : null
+  }
+
+  async listOidcClients(): Promise<OidcClient[]> {
+    const res = await this.stmt('SELECT * FROM oidc_clients ORDER BY created_at, client_id').all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toOidcClient)
+  }
+
+  async upsertOidcClient(input: {
+    clientId: string
+    name: string
+    secretHash: string | null
+    redirectUris: string[]
+    claimsPolicy: { claims: string[] } | null
+    createdBy?: string | null
+  }): Promise<OidcClient> {
+    await this.stmt(
+      `INSERT INTO oidc_clients (client_id, name, secret_hash, redirect_uris, claims_policy, created_by)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT (client_id) DO UPDATE SET
+         name = excluded.name,
+         secret_hash = excluded.secret_hash,
+         redirect_uris = excluded.redirect_uris,
+         claims_policy = excluded.claims_policy`,
+      input.clientId, input.name, input.secretHash,
+      JSON.stringify(input.redirectUris),
+      input.claimsPolicy ? JSON.stringify(input.claimsPolicy) : null,
+      input.createdBy ?? null,
+    ).run()
+    return (await this.getOidcClient(input.clientId))!
+  }
+
+  async setOidcClientStatus(clientId: string, status: OidcClient['status']): Promise<OidcClient | null> {
+    const res = await this.stmt('UPDATE oidc_clients SET status = ? WHERE client_id = ?', status, clientId).run()
+    return (res.meta.changes ?? 0) > 0 ? this.getOidcClient(clientId) : null
+  }
+
+  async setOidcClientLaunch(clientId: string, launch: OidcClientLaunch | null): Promise<OidcClient | null> {
+    const res = await this.stmt(
+      `UPDATE oidc_clients SET launch_url = ?, launch_icon = ?, launch_description = ?, launch_visibility = ?
+       WHERE client_id = ?`,
+      launch?.url ?? null,
+      launch?.icon ?? null,
+      launch?.description ?? null,
+      launch?.visibility ?? 'roles',
+      clientId,
+    ).run()
+    return (res.meta.changes ?? 0) > 0 ? this.getOidcClient(clientId) : null
+  }
+
+  async createOidcAuthorization(input: {
+    id: string
+    clientId: string
+    redirectUri: string
+    scope: string
+    state: string
+    nonce: string | null
+    codeChallenge: string
+    userId: string | null
+    ttlMs: number
+  }): Promise<OidcAuthorization> {
+    const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+    await this.stmt(
+      `INSERT INTO oidc_authorizations
+         (id, client_id, redirect_uri, scope, state, nonce, code_challenge, user_id, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      input.id, input.clientId, input.redirectUri, input.scope, input.state,
+      input.nonce, input.codeChallenge, input.userId, expiresAt,
+    ).run()
+    return (await this.getOidcAuthorization(input.id))!
+  }
+
+  async getOidcAuthorization(id: string): Promise<OidcAuthorization | null> {
+    const row = await this.stmt('SELECT * FROM oidc_authorizations WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toOidcAuthorization(row) : null
+  }
+
+  async decideOidcAuthorization(
+    id: string,
+    decision: { userId: string; decision: 'allow' | 'deny' },
+  ): Promise<OidcAuthorization | null> {
+    // The decision binds to the row's OWN account and flips atomically.
+    const res = await this.stmt(
+      'UPDATE oidc_authorizations SET decision = ? WHERE id = ? AND decision IS NULL AND user_id = ?',
+      decision.decision, id, decision.userId,
+    ).run()
+    return (res.meta.changes ?? 0) > 0 ? this.getOidcAuthorization(id) : null
+  }
+
+  async 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> {
+    await this.ensureMembershipSupport()
+    const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+    await this.ensureOidcColumns()
+    await this.stmt(
+      `INSERT INTO oidc_codes (code, client_id, redirect_uri, scope, nonce, code_challenge, user_id, context_org, amr, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      input.code, input.clientId, input.redirectUri, input.scope, input.nonce, input.codeChallenge, input.userId, input.contextOrg ?? null,
+      input.amr?.length ? JSON.stringify(input.amr) : null, expiresAt,
+    ).run()
+  }
+
+  /** Atomically consume the code: the UPDATE flips consumed_at exactly
+   *  once — a replay loses the race and answers null (→ invalid_grant).
+   *  An expired code is consumed too (never a second chance). */
+  async consumeOidcCode(code: string): Promise<OidcCode | null> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt(
+      "UPDATE oidc_codes SET consumed_at = datetime('now') WHERE code = ? AND consumed_at IS NULL", code,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    const row = await this.stmt('SELECT * FROM oidc_codes WHERE code = ?', code).first<Record<string, unknown>>()
+    if (!row) return null
+    if (new Date(row.expires_at as string).getTime() <= Date.now()) return null
+    return {
+      code: row.code as string,
+      clientId: row.client_id as string,
+      redirectUri: row.redirect_uri as string,
+      scope: row.scope as string,
+      nonce: (row.nonce as string | null) ?? null,
+      codeChallenge: row.code_challenge as string,
+      userId: row.user_id as string,
+      contextOrg: (row.context_org as string | null) ?? null,
+      amr: parseRoles((row.amr as string | null) ?? null) ?? null,
+      expiresAt: row.expires_at as string,
+    }
+  }
+
+  async 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> {
+    await this.ensureMembershipSupport()
+    const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+    await this.ensureOidcColumns()
+    await this.stmt(
+      'INSERT INTO oidc_access_tokens (token, user_id, client_id, scope, context_org, amr, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?)',
+      input.token, input.userId, input.clientId, input.scope, input.contextOrg ?? null,
+      input.amr?.length ? JSON.stringify(input.amr) : null, expiresAt,
+    ).run()
+  }
+
+  async getOidcAccessToken(token: string): Promise<OidcAccessToken | null> {
+    await this.ensureMembershipSupport()
+    const row = await this.stmt(
+      "SELECT * FROM oidc_access_tokens WHERE token = ? AND expires_at > datetime('now')", token,
+    ).first<Record<string, unknown>>()
+    if (!row) return null
+    return {
+      token: row.token as string,
+      userId: row.user_id as string,
+      clientId: row.client_id as string,
+      scope: row.scope as string,
+      contextOrg: (row.context_org as string | null) ?? null,
+      amr: parseRoles((row.amr as string | null) ?? null) ?? null,
+      expiresAt: row.expires_at as string,
+    }
+  }
+
+  async listOidcKeys(): Promise<OidcKeyRow[]> {
+    const res = await this.stmt('SELECT * FROM oidc_keys ORDER BY created_at, kid').all<Record<string, unknown>>()
+    return res.results.map(row => ({
+      kid: row.kid as string,
+      publicJwk: row.public_jwk as string,
+      status: row.status as OidcKeyRow['status'],
+      createdAt: row.created_at as string,
+      retiredAt: (row.retired_at as string | null) ?? null,
+    }))
+  }
+
+  async upsertOidcKey(input: { kid: string; publicJwk: string }): Promise<void> {
+    await this.stmt('INSERT OR IGNORE INTO oidc_keys (kid, public_jwk) VALUES (?, ?)', input.kid, input.publicJwk).run()
+  }
+
+  async retireOidcKey(kid: string): Promise<void> {
+    await this.stmt(
+      "UPDATE oidc_keys SET status = 'retired', retired_at = datetime('now') WHERE kid = ? AND status = 'active'", kid,
+    ).run()
+  }
+
+  // ── the upstream providers (TODO.identity/08) ─────────────────────
+  // The provider + link rows port directly (D1 is SQLite).
+
+  private static toIdentityProvider(row: Record<string, unknown>): IdentityProvider {
+    return {
+      id: row.id as string,
+      kind: row.kind as IdentityProvider['kind'],
+      displayName: row.display_name as string,
+      brandMark: (row.brand_mark as string | null) ?? null,
+      issuer: (row.issuer as string | null) ?? null,
+      clientId: row.client_id as string,
+      clientSecretRef: (row.client_secret_ref as string | null) ?? null,
+      scopes: (row.scopes as string | null) ?? null,
+      enabled: row.enabled === 1,
+      createdAt: row.created_at as string,
+      createdBy: (row.created_by as string | null) ?? null,
+      updatedAt: (row.updated_at as string | null) ?? null,
+    }
+  }
+
+  async listIdentityProviders(): Promise<IdentityProvider[]> {
+    const res = await this.stmt('SELECT * FROM identity_providers ORDER BY created_at, id').all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toIdentityProvider)
+  }
+
+  async getIdentityProvider(id: string): Promise<IdentityProvider | null> {
+    const row = await this.stmt('SELECT * FROM identity_providers WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toIdentityProvider(row) : null
+  }
+
+  async 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> {
+    await this.stmt(
+      `INSERT INTO identity_providers
+         (id, kind, display_name, brand_mark, issuer, client_id, client_secret_ref, scopes, enabled, created_by)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (id) DO UPDATE SET
+         kind = excluded.kind,
+         display_name = excluded.display_name,
+         brand_mark = excluded.brand_mark,
+         issuer = excluded.issuer,
+         client_id = excluded.client_id,
+         client_secret_ref = excluded.client_secret_ref,
+         scopes = excluded.scopes,
+         enabled = excluded.enabled,
+         updated_at = datetime('now')`,
+      input.id, input.kind, input.displayName, input.brandMark ?? null, input.issuer ?? null,
+      input.clientId, input.clientSecretRef ?? null, input.scopes ?? null,
+      // Disabled by default (the schema's DEFAULT 0): a deliberate
+      // enable makes the provider visible.
+      input.enabled ? 1 : 0, input.createdBy ?? null,
+    ).run()
+    return (await this.getIdentityProvider(input.id))!
+  }
+
+  async setIdentityProviderEnabled(id: string, enabled: boolean): Promise<IdentityProvider | null> {
+    const res = await this.stmt(
+      "UPDATE identity_providers SET enabled = ?, updated_at = datetime('now') WHERE id = ?",
+      enabled ? 1 : 0, id,
+    ).run()
+    return (res.meta.changes ?? 0) > 0 ? this.getIdentityProvider(id) : null
+  }
+
+  async deleteIdentityProvider(id: string): Promise<boolean> {
+    const res = await this.stmt('DELETE FROM identity_providers WHERE id = ?', id).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  // ── the linked identities (TODO.identity/02's shape, 08's flows) ────
+  // ── the OP's account model (TODO.identity/02) ──────────────────────
+  // The account rows port directly (D1 is SQLite) — the same statements
+  // as op-accounts-store.ts's sync half.
+
+  private static toIdentityLink(row: Record<string, unknown>): IdentityLink {
+    return {
+      id: row.id as string,
+      userId: row.user_id as string,
+      provider: row.provider as string,
+      providerAccountId: row.provider_account_id as string,
+      linkedAt: row.linked_at as string,
+      linkedBy: (row.linked_by as string | null) ?? null,
+    }
+  }
+
+  async listIdentityLinks(userId: string): Promise<IdentityLink[]> {
+    const res = await this.stmt('SELECT * FROM identity_links WHERE user_id = ? ORDER BY linked_at, provider', userId)
+      .all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toIdentityLink)
+  }
+
+  async findIdentityLink(provider: string, providerAccountId: string): Promise<IdentityLink | null> {
+    const row = await this.stmt('SELECT * FROM identity_links WHERE provider = ? AND provider_account_id = ?', provider, providerAccountId)
+      .first<Record<string, unknown>>()
+    return row ? D1ServerStore.toIdentityLink(row) : null
+  }
+
+  /** Create the link; NULL on the UNIQUE(provider, provider_account_id)
+   *  conflict — the pair is already linked (to any account). */
+  async createIdentityLink(input: {
+    userId: string
+    provider: string
+    providerAccountId: string
+    linkedBy?: string | null
+  }): Promise<IdentityLink | null> {
+    const res = await this.stmt(
+      'INSERT OR IGNORE INTO identity_links (id, user_id, provider, provider_account_id, linked_by) VALUES (?, ?, ?, ?, ?)',
+      crypto.randomUUID(), input.userId, input.provider, input.providerAccountId, input.linkedBy ?? null,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.findIdentityLink(input.provider, input.providerAccountId)
+  }
+
+  async deleteIdentityLink(userId: string, provider: string): Promise<boolean> {
+    const res = await this.stmt('DELETE FROM identity_links WHERE user_id = ? AND provider = ?', userId, provider).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  private static toEnrollmentToken(row: Record<string, unknown>): EnrollmentToken {
+    return {
+      token: row.token as string,
+      userId: row.user_id as string,
+      createdBy: (row.created_by as string | null) ?? null,
+      createdAt: row.created_at as string,
+      expiresAt: row.expires_at as string,
+      consumedAt: (row.consumed_at as string | null) ?? null,
+    }
+  }
+
+  async createOpAccount(input: {
+    email: string
+    name: string
+    role: string
+    createdBy?: string | null
+  }): Promise<UserAdminRow | null> {
+    const id = crypto.randomUUID()
+    try {
+      await this.stmt(
+        "INSERT INTO users (id, email, name, provider, role) VALUES (?, ?, ?, 'password', ?)",
+        id, input.email.trim().toLowerCase(), input.name.trim(), input.role,
+      ).run()
+    } catch (e) {
+      if (String((e as Error).message).includes('UNIQUE')) return null
+      throw e
+    }
+    const row = await this.stmt('SELECT * FROM users WHERE id = ?', id).first<UserRecord & { last_login?: string | null; provider?: string }>()
+    return toAdminRow(row!)
+  }
+
+  /** The password sign-in's lookup: the credential + the active flag, by
+   *  (normalized) email. The credential's EXISTENCE is the qualifier. */
+  async getPasswordLogin(email: string): Promise<{ userId: string; hash: string; active: boolean } | null> {
+    const row = await this.stmt(
+      `SELECT u.id AS user_id, u.active AS active, p.hash AS hash
+       FROM users u JOIN passwords p ON p.user_id = u.id
+       WHERE u.email = ?`,
+      email.trim().toLowerCase(),
+    ).first<{ user_id: string; active: number; hash: string }>()
+    if (!row) return null
+    return { userId: row.user_id, hash: row.hash, active: row.active !== 0 }
+  }
+
+  async setPasswordHash(userId: string, hash: string, setBy?: string | null): Promise<void> {
+    await this.stmt(
+      `INSERT INTO passwords (user_id, hash, set_by) VALUES (?, ?, ?)
+       ON CONFLICT (user_id) DO UPDATE SET hash = excluded.hash, set_at = datetime('now'), set_by = excluded.set_by`,
+      userId, hash, setBy ?? null,
+    ).run()
+  }
+
+  /** The sign-in methods the account holds (the account page's
+   *  password-set state + the admin list's posture). TODO.identity-sso/02:
+   *  the passkeys count — a passkey is a PRIMARY sign-in method. */
+  async countSignInMethods(userId: string): Promise<{ password: boolean; links: number; passkeys: number }> {
+    const pw = await this.stmt('SELECT COUNT(*) AS n FROM passwords WHERE user_id = ?', userId).first<{ n: number }>()
+    const links = await this.stmt('SELECT COUNT(*) AS n FROM identity_links WHERE user_id = ?', userId).first<{ n: number }>()
+    const passkeys = await this.stmt('SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?', userId).first<{ n: number }>()
+    return { password: (pw?.n ?? 0) > 0, links: links?.n ?? 0, passkeys: passkeys?.n ?? 0 }
+  }
+
+  async createEnrollmentToken(input: {
+    token: string
+    userId: string
+    createdBy?: string | null
+    ttlMs: number
+  }): Promise<EnrollmentToken> {
+    const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+    await this.stmt(
+      'INSERT INTO enrollment_tokens (token, user_id, created_by, expires_at) VALUES (?, ?, ?, ?)',
+      input.token, input.userId, input.createdBy ?? null, expiresAt,
+    ).run()
+    return (await this.getEnrollmentToken(input.token))!
+  }
+
+  async getEnrollmentToken(token: string): Promise<EnrollmentToken | null> {
+    const row = await this.stmt('SELECT * FROM enrollment_tokens WHERE token = ?', token).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toEnrollmentToken(row) : null
+  }
+
+  /** Complete the enrollment: consume the token ATOMICALLY (a concurrent
+   *  double-submit loses the consumed_at race), judge the expiry (an
+   *  expired link is burned, never redeemed), then set the password. */
+  async completeEnrollment(token: string, passwordHash: string, setBy?: string | null): Promise<CompleteEnrollmentResult> {
+    const res = await this.stmt(
+      "UPDATE enrollment_tokens SET consumed_at = datetime('now') WHERE token = ? AND consumed_at IS NULL", token,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return { kind: 'unknown' }
+    const row = (await this.getEnrollmentToken(token))!
+    if (new Date(row.expiresAt).getTime() <= Date.now()) return { kind: 'expired' }
+    await this.setPasswordHash(row.userId, passwordHash, setBy)
+    // TODO.identity/06: the invite ceremony doubles as the address's
+    // verification (the administrator-delivered one-time link).
+    await this.stmt("UPDATE users SET email_verified_at = datetime('now') WHERE id = ?", row.userId).run()
+    return { kind: 'ok', userId: row.userId }
+  }
+
+  /** The account's live sessions, `current` computed in SQL against the
+   *  presenting token — the token value itself never leaves the store. */
+  async listUserSessions(userId: string, currentToken?: string): Promise<SessionView[]> {
+    await this.ensureSessionColumns()
+    const res = await this.stmt(
+      `SELECT id, created_at, expires_at, last_seen_at, user_agent, ip, (token = ?) AS is_current
+       FROM sessions
+       WHERE user_id = ? AND expires_at > datetime('now')
+       ORDER BY created_at DESC`,
+      currentToken ?? '', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(row => ({
+      id: row.id as string,
+      createdAt: row.created_at as string,
+      expiresAt: row.expires_at as string,
+      lastSeenAt: (row.last_seen_at as string | null) ?? null,
+      userAgent: (row.user_agent as string | null) ?? null,
+      ip: (row.ip as string | null) ?? null,
+      current: Number(row.is_current) === 1,
+    }))
+  }
+
+  /** Revoke ONE of the account's own sessions (the user_id clause makes
+   *  another account's session id a no-op). */
+  async deleteSessionById(userId: string, sessionId: string): Promise<boolean> {
+    const res = await this.stmt('DELETE FROM sessions WHERE id = ? AND user_id = ?', sessionId, userId).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** Every live session across accounts (expired excluded), `current`
+   *  computed in SQL against the presenting token — the aggregate admin
+   *  read (TODO.identity-sso/01); the token never leaves the store. */
+  async listOpLiveSessions(currentToken?: string): Promise<OpLiveSession[]> {
+    await this.ensureSessionColumns()
+    const res = await this.stmt(
+      `SELECT id, user_id, created_at, expires_at, last_seen_at, user_agent, ip, (token = ?) AS is_current
+       FROM sessions
+       WHERE expires_at > datetime('now')
+       ORDER BY created_at DESC`,
+      currentToken ?? '',
+    ).all<Record<string, unknown>>()
+    return res.results.map(row => ({
+      id: row.id as string,
+      userId: row.user_id as string,
+      createdAt: row.created_at as string,
+      expiresAt: row.expires_at as string,
+      lastSeenAt: (row.last_seen_at as string | null) ?? null,
+      userAgent: (row.user_agent as string | null) ?? null,
+      ip: (row.ip as string | null) ?? null,
+      current: Number(row.is_current) === 1,
+    }))
+  }
+
+  /** The administrator's revoke-all (TODO.identity-sso/01's light act):
+   *  every session of the account, none kept; answers the count. */
+  async deleteAllUserSessions(userId: string): Promise<number> {
+    const res = await this.stmt('DELETE FROM sessions WHERE user_id = ?', userId).run()
+    return res.meta.changes ?? 0
+  }
+
+  // ── the central user registry (TODO.identity/03) ──────────────────
+
+  private static toClientRoleAssignment(row: Record<string, unknown>): OpClientRoleAssignment {
+    return {
+      userId: row.user_id as string,
+      clientId: row.client_id as string,
+      roles: JSON.parse(row.roles as string) as string[],
+      assignedBy: (row.assigned_by as string | null) ?? null,
+      createdAt: row.created_at as string,
+      updatedAt: (row.updated_at as string | null) ?? null,
+    }
+  }
+
+  async listOpClientRoles(userId: string): Promise<OpClientRoleAssignment[]> {
+    const res = await this.stmt(
+      'SELECT * FROM op_client_roles WHERE user_id = ? ORDER BY client_id', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toClientRoleAssignment)
+  }
+
+  /** EVERY per-client assignment across accounts (TODO.identity-sso/01's
+   *  live access review). */
+  async listAllOpClientRoles(): Promise<OpClientRoleAssignment[]> {
+    const res = await this.stmt(
+      'SELECT * FROM op_client_roles ORDER BY user_id, client_id',
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toClientRoleAssignment)
+  }
+
+  /** The assignment for ONE client: NULL = no row (the account default);
+   *  an EMPTY array = the explicit "no roles on this client". */
+  async getOpClientRoles(userId: string, clientId: string): Promise<string[] | null> {
+    const row = await this.stmt(
+      'SELECT roles FROM op_client_roles WHERE user_id = ? AND client_id = ?', userId, clientId,
+    ).first<{ roles: string }>()
+    return row ? (JSON.parse(row.roles) as string[]) : null
+  }
+
+  async setOpClientRoles(userId: string, clientId: string, roles: string[], assignedBy: string | null): Promise<void> {
+    await this.stmt(
+      `INSERT INTO op_client_roles (user_id, client_id, roles, assigned_by)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT (user_id, client_id) DO UPDATE SET
+         roles = excluded.roles,
+         assigned_by = excluded.assigned_by,
+         updated_at = datetime('now')`,
+      userId, clientId, JSON.stringify(roles), assignedBy,
+    ).run()
+  }
+
+  async deleteOpClientRoles(userId: string, clientId: string): Promise<boolean> {
+    const res = await this.stmt('DELETE FROM op_client_roles WHERE user_id = ? AND client_id = ?', userId, clientId).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** The deactivation's revocation half: every live session, every issued
+   *  access token, every unconsumed code and pending authorization goes.
+   *  The user row STAYS (the history). */
+  async revokeOpUserCredentials(userId: string): Promise<{ sessions: number; accessTokens: number; codes: number; authorizations: number }> {
+    const sessions = await this.stmt('DELETE FROM sessions WHERE user_id = ?', userId).run()
+    const accessTokens = await this.stmt('DELETE FROM oidc_access_tokens WHERE user_id = ?', userId).run()
+    const codes = await this.stmt('DELETE FROM oidc_codes WHERE user_id = ? AND consumed_at IS NULL', userId).run()
+    const authorizations = await this.stmt('DELETE FROM oidc_authorizations WHERE user_id = ? AND decision IS NULL', userId).run()
+    return {
+      sessions: sessions.meta.changes ?? 0,
+      accessTokens: accessTokens.meta.changes ?? 0,
+      codes: codes.meta.changes ?? 0,
+      authorizations: authorizations.meta.changes ?? 0,
+    }
+  }
+
+  /** The registry's ERASURE act (the offboarding runbook's delete path):
+   *  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, null when absent. */
+  async eraseOpAccount(userId: string): Promise<OpAccountErasure | null> {
+    await this.ensureMembershipSupport()
+    const row = await this.stmt('SELECT 1 AS ok FROM users WHERE id = ?', userId).first<{ ok: number }>()
+    if (!row) return null
+    const revoked = await this.revokeOpUserCredentials(userId)
+    const links = await this.stmt('DELETE FROM identity_links WHERE user_id = ?', userId).run()
+    const clientRoles = await this.stmt('DELETE FROM op_client_roles WHERE user_id = ?', userId).run()
+    // TODO.identity/11: the memberships go too (the tombstone acts for
+    // no organization).
+    const memberships = await this.stmt('DELETE FROM org_memberships WHERE user_id = ?', userId).run()
+    const passwords = await this.stmt('DELETE FROM passwords WHERE user_id = ?', userId).run()
+    const enrollments = await this.stmt('DELETE FROM enrollment_tokens WHERE user_id = ?', userId).run()
+    const emailChanges = await this.stmt('DELETE FROM email_change_tokens WHERE user_id = ?', userId).run()
+    // TODO.identity-sso/02+03: the factor registry follows the account
+    // into erasure (passkeys, TOTP secrets, recovery codes, pending
+    // ceremony state).
+    const passkeys = await this.stmt('DELETE FROM webauthn_credentials WHERE user_id = ?', userId).run()
+    const totp = await this.stmt('DELETE FROM totp_secrets WHERE user_id = ?', userId).run()
+    const recovery = await this.stmt('DELETE FROM recovery_codes WHERE user_id = ?', userId).run()
+    const challenges = await this.stmt('DELETE FROM webauthn_challenges WHERE user_id = ?', userId).run()
+    const mfa = await this.stmt('DELETE FROM mfa_pending WHERE user_id = ?', userId).run()
+    await this.stmt(
+      `UPDATE users SET
+         email = ?, name = 'Deleted account', provider = 'erased',
+         role = 'viewer', roles = NULL, org_id = NULL,
+         avatar_url = NULL, email_verified_at = NULL, active = 0
+       WHERE id = ?`,
+      `deleted-${userId}@erased.invalid`, userId,
+    ).run()
+    return {
+      ...revoked,
+      links: links.meta.changes ?? 0,
+      clientRoles: clientRoles.meta.changes ?? 0,
+      memberships: memberships.meta.changes ?? 0,
+      tokens: (passwords.meta.changes ?? 0) + (enrollments.meta.changes ?? 0) + (emailChanges.meta.changes ?? 0),
+      factors: (passkeys.meta.changes ?? 0) + (totp.meta.changes ?? 0) + (recovery.meta.changes ?? 0)
+        + (challenges.meta.changes ?? 0) + (mfa.meta.changes ?? 0),
+    }
+  }
+
+  /** The registry's edit act (name/email). The email UNIQUE conflict
+   *  throws 'unique' (the route maps it to a 409, never a silent take). */
+  async updateOpAccount(id: string, input: { name?: string; email?: string }): Promise<boolean> {
+    if (input.email !== undefined) {
+      try {
+        // TODO.identity/06: an admin-set address never went through the
+        // verify-new-email ceremony, so the verification state resets.
+        await this.stmt('UPDATE users SET email = ?, email_verified_at = NULL WHERE id = ?', input.email.trim().toLowerCase(), id).run()
+      } catch (e) {
+        if (String((e as Error).message).includes('UNIQUE')) throw new Error(`unique: ${input.email}`)
+        throw e
+      }
+    }
+    if (input.name !== undefined) {
+      await this.stmt('UPDATE users SET name = ? WHERE id = ?', input.name.trim(), id).run()
+    }
+    const row = await this.stmt('SELECT 1 AS ok FROM users WHERE id = ?', id).first<{ ok: number }>()
+    return !!row
+  }
+
+  /** The last OP-side sign-in per account, FROM THE AUDIT CHAIN: the
+   *  newest auditEvents row whose action is a sign-in
+   *  ('account.sign_in' / 'upstream_sign_in') per entity_id. */
+  async lastAccountSignIns(): Promise<Record<string, string>> {
+    const res = await this.stmt(
+      `SELECT data FROM entities
+       WHERE store = 'auditEvents'
+         AND (data LIKE '%"action":"account.sign_in"%' OR data LIKE '%"action":"upstream_sign_in"%')`,
+    ).all<{ data: string }>()
+    const out: Record<string, string> = {}
+    for (const { data } of res.results) {
+      try {
+        const event = JSON.parse(data) as { entity_id?: string; timestamp?: string }
+        if (typeof event.entity_id !== 'string' || typeof event.timestamp !== 'string') continue
+        if (!out[event.entity_id] || event.timestamp > out[event.entity_id]!) {
+          out[event.entity_id] = event.timestamp
+        }
+      } catch { /* a malformed audit row is skipped, never trusted */ }
+    }
+    return out
+  }
+
+  // ── the account console (TODO.identity/06) ─────────────────────────
+
+  /** The profile edit's write (the display name). */
+  async updateUserName(userId: string, name: string): Promise<boolean> {
+    const res = await this.stmt('UPDATE users SET name = ? WHERE id = ?', name.trim(), userId).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** The avatar write (the account console's upload/remove; NULL = the
+   *  initials). */
+  async setUserAvatar(userId: string, avatarUrl: string | null): Promise<boolean> {
+    const res = await this.stmt('UPDATE users SET avatar_url = ? WHERE id = ?', avatarUrl, userId).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** Remove the account's password credential (the route holds the
+   *  at-least-one-method guard). */
+  async deletePasswordHash(userId: string): Promise<boolean> {
+    const res = await this.stmt('DELETE FROM passwords WHERE user_id = ?', userId).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** Revoke every session of the account EXCEPT the presenting one. */
+  async deleteOtherSessions(userId: string, keepToken: string): Promise<number> {
+    const res = await this.stmt('DELETE FROM sessions WHERE user_id = ? AND token != ?', userId, keepToken).run()
+    return res.meta.changes ?? 0
+  }
+
+  private static toEmailChangeToken(row: Record<string, unknown>): EmailChangeToken {
+    return {
+      token: row.token as string,
+      userId: row.user_id as string,
+      newEmail: row.new_email as string,
+      deliveredBy: row.delivered_by === 'mailer' ? 'mailer' : 'shown',
+      createdAt: row.created_at as string,
+      expiresAt: row.expires_at as string,
+      consumedAt: (row.consumed_at as string | null) ?? null,
+    }
+  }
+
+  /** Mint the ceremony's token; the account's earlier pending rows are
+   *  VOIDED first (only the newest link works). */
+  async createEmailChangeToken(input: {
+    token: string
+    userId: string
+    newEmail: string
+    deliveredBy: 'mailer' | 'shown'
+    ttlMs: number
+  }): Promise<EmailChangeToken> {
+    await this.stmt(
+      "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND consumed_at IS NULL",
+      input.userId,
+    ).run()
+    const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+    await this.stmt(
+      'INSERT INTO email_change_tokens (token, user_id, new_email, delivered_by, expires_at) VALUES (?, ?, ?, ?, ?)',
+      input.token, input.userId, input.newEmail.trim().toLowerCase(), input.deliveredBy, expiresAt,
+    ).run()
+    return (await this.getEmailChangeToken(input.token))!
+  }
+
+  async getEmailChangeToken(token: string): Promise<EmailChangeToken | null> {
+    const row = await this.stmt('SELECT * FROM email_change_tokens WHERE token = ?', token).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toEmailChangeToken(row) : null
+  }
+
+  /** The account's pending change (the newest live row), so the console
+   *  can show it. */
+  async getPendingEmailChange(userId: string): Promise<EmailChangeToken | null> {
+    const row = await this.stmt(
+      `SELECT * FROM email_change_tokens
+       WHERE user_id = ? AND consumed_at IS NULL AND expires_at > datetime('now')
+       ORDER BY created_at DESC LIMIT 1`,
+      userId,
+    ).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toEmailChangeToken(row) : null
+  }
+
+  /** Complete the ceremony: consume 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. A 'mailer'-delivered token verifies the
+   *  address; a shown one never does. */
+  async completeEmailChange(token: string): Promise<CompleteEmailChangeResult> {
+    const res = await this.stmt(
+      "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE token = ? AND consumed_at IS NULL", token,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return { kind: 'unknown' }
+    const row = (await this.getEmailChangeToken(token))!
+    if (new Date(row.expiresAt).getTime() <= Date.now()) return { kind: 'expired' }
+    const taken = await this.stmt('SELECT id FROM users WHERE email = ?', row.newEmail).first<{ id: string }>()
+    if (taken) return { kind: 'conflict' }
+    const verified = row.deliveredBy === 'mailer'
+    await this.stmt(
+      `UPDATE users SET email = ?, email_verified_at = ${verified ? "datetime('now')" : 'NULL'} WHERE id = ?`,
+      row.newEmail, row.userId,
+    ).run()
+    return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
+  }
+
+  // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03) ──
+  // The same SQL as the SQLite half (store/sqlite/factors-store.ts): the
+  // one-time consumes are guarded UPDATEs, the counter advance is the
+  // clone-guarded UPDATE, the throttles ride the rows — the database is
+  // the proof, never a per-isolate Map.
+
+  async createWebauthnChallenge(input: {
+    challenge: string
+    userId: string | null
+    kind: WebauthnChallenge['kind']
+    ttlMs: number
+  }): Promise<void> {
+    const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+    // The sweep rides the write (the putSsoState pattern).
+    await this.stmt("DELETE FROM webauthn_challenges WHERE expires_at <= datetime('now')").run()
+    await this.stmt(
+      'INSERT INTO webauthn_challenges (challenge, user_id, kind, expires_at) VALUES (?, ?, ?, ?)',
+      input.challenge, input.userId, input.kind, expiresAt,
+    ).run()
+  }
+
+  async consumeWebauthnChallenge(challenge: string): Promise<WebauthnChallenge | null> {
+    const res = await this.stmt(
+      "UPDATE webauthn_challenges SET consumed_at = datetime('now') WHERE challenge = ? AND consumed_at IS NULL", challenge,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    const row = await this.stmt('SELECT * FROM webauthn_challenges WHERE challenge = ?', challenge).first<Record<string, unknown>>()
+    if (!row) return null
+    if (new Date(row.expires_at as string).getTime() <= Date.now()) return null
+    return D1ServerStore.toWebauthnChallenge(row)
+  }
+
+  async createWebauthnCredential(input: {
+    credentialId: string
+    userId: string
+    name: string
+    publicKeyCose: string
+    signCount: number
+    aaguid: string | null
+    transports: string[]
+    ip?: string | null
+  }): Promise<WebauthnCredential | null> {
+    try {
+      await this.stmt(
+        `INSERT INTO webauthn_credentials
+           (credential_id, user_id, name, public_key, sign_count, aaguid, transports, last_ip)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+        input.credentialId, input.userId, input.name, input.publicKeyCose,
+        Math.max(0, Math.floor(input.signCount)), input.aaguid, JSON.stringify(input.transports),
+        input.ip ?? null,
+      ).run()
+    } catch (e) {
+      if (String((e as Error).message).includes('UNIQUE')) return null
+      throw e
+    }
+    return this.getWebauthnCredential(input.credentialId)
+  }
+
+  async listWebauthnCredentials(userId: string): Promise<WebauthnCredential[]> {
+    const res = await this.stmt(
+      'SELECT * FROM webauthn_credentials WHERE user_id = ? ORDER BY created_at, credential_id', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toWebauthnCredential)
+  }
+
+  async getWebauthnCredential(credentialId: string): Promise<WebauthnCredential | null> {
+    const row = await this.stmt(
+      'SELECT * FROM webauthn_credentials WHERE credential_id = ?', credentialId,
+    ).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toWebauthnCredential(row) : null
+  }
+
+  async deleteWebauthnCredential(userId: string, credentialId: string): Promise<boolean> {
+    const res = await this.stmt(
+      'DELETE FROM webauthn_credentials WHERE credential_id = ? AND user_id = ?', credentialId, userId,
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  async advanceWebauthnCounter(credentialId: string, newCount: number, opts?: { ip?: string | null }): Promise<AdvanceCounterResult> {
+    const count = Math.max(0, Math.floor(newCount))
+    const res = await this.stmt(
+      `UPDATE webauthn_credentials
+       SET sign_count = ?, last_used_at = datetime('now'), last_ip = ?
+       WHERE credential_id = ? AND ((sign_count = 0 AND ? = 0) OR sign_count < ?)`,
+      count, opts?.ip ?? null, credentialId, count, count,
+    ).run()
+    if ((res.meta.changes ?? 0) > 0) return 'ok'
+    return (await this.getWebauthnCredential(credentialId)) ? 'regressed' : 'unknown'
+  }
+
+  async createTotpSecret(input: { id: string; userId: string; name: string; secret: string }): Promise<TotpSecret> {
+    await this.stmt(
+      'INSERT INTO totp_secrets (id, user_id, name, secret) VALUES (?, ?, ?, ?)',
+      input.id, input.userId, input.name, input.secret,
+    ).run()
+    return (await this.getTotpSecret(input.id))!
+  }
+
+  async listTotpSecrets(userId: string): Promise<TotpSecret[]> {
+    const res = await this.stmt(
+      'SELECT * FROM totp_secrets WHERE user_id = ? ORDER BY created_at, id', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toTotpSecret)
+  }
+
+  async getTotpSecret(id: string): Promise<TotpSecret | null> {
+    const row = await this.stmt('SELECT * FROM totp_secrets WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toTotpSecret(row) : null
+  }
+
+  async markTotpSecretVerified(id: string, userId: string, name: string): Promise<boolean> {
+    const res = await this.stmt(
+      "UPDATE totp_secrets SET verified_at = datetime('now'), name = ? WHERE id = ? AND user_id = ? AND verified_at IS NULL",
+      name, id, userId,
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  async recordTotpEnrollFailure(id: string, userId: string): Promise<number> {
+    const res = await this.stmt(
+      "UPDATE totp_secrets SET fail_count = fail_count + 1, last_failure_at = datetime('now') WHERE id = ? AND user_id = ? AND verified_at IS NULL",
+      id, userId,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return 0
+    const row = await this.stmt('SELECT fail_count AS n FROM totp_secrets WHERE id = ?', id).first<{ n: number }>()
+    return row?.n ?? 0
+  }
+
+  async markTotpSecretUsed(id: string, opts?: { ip?: string | null }): Promise<void> {
+    await this.stmt(
+      "UPDATE totp_secrets SET last_used_at = datetime('now'), last_ip = ? WHERE id = ?",
+      opts?.ip ?? null, id,
+    ).run()
+  }
+
+  async deleteTotpSecret(userId: string, id: string): Promise<boolean> {
+    const res = await this.stmt('DELETE FROM totp_secrets WHERE id = ? AND user_id = ?', id, userId).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** The regenerate: the old batch goes, the new hashes land — D1's
+   *  batch is all-or-nothing (the sqlite half's transaction). */
+  async replaceRecoveryCodes(userId: string, batch: string, codeHashes: string[]): Promise<void> {
+    const statements: D1PreparedStatement[] = [
+      this.stmt('DELETE FROM recovery_codes WHERE user_id = ?', userId),
+      ...codeHashes.map(hash => this.stmt(
+        'INSERT INTO recovery_codes (id, user_id, batch, code_hash) VALUES (?, ?, ?, ?)',
+        crypto.randomUUID(), userId, batch, hash,
+      )),
+    ]
+    await this.db.batch(statements)
+  }
+
+  async recoveryCodeState(userId: string): Promise<RecoveryCodeState> {
+    const row = await this.stmt(
+      `SELECT COUNT(*) AS total,
+              SUM(CASE WHEN consumed_at IS NULL THEN 1 ELSE 0 END) AS remaining,
+              MAX(created_at) AS created_at
+       FROM recovery_codes WHERE user_id = ?`, userId,
+    ).first<{ total: number; remaining: number | null; created_at: string | null }>()
+    return {
+      total: row?.total ?? 0,
+      remaining: row?.remaining ?? 0,
+      createdAt: (row?.total ?? 0) > 0 ? (row?.created_at ?? null) : null,
+    }
+  }
+
+  async consumeRecoveryCode(userId: string, codeHash: string): Promise<boolean> {
+    const res = await this.stmt(
+      "UPDATE recovery_codes SET consumed_at = datetime('now') WHERE user_id = ? AND code_hash = ? AND consumed_at IS NULL",
+      userId, codeHash,
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  async createMfaPending(input: { token: string; userId: string; amr: string[]; ttlMs: number }): Promise<void> {
+    const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+    await this.stmt("DELETE FROM mfa_pending WHERE expires_at <= datetime('now')").run()
+    await this.stmt(
+      'INSERT INTO mfa_pending (token, user_id, amr, expires_at) VALUES (?, ?, ?, ?)',
+      input.token, input.userId, JSON.stringify(input.amr), expiresAt,
+    ).run()
+  }
+
+  async getMfaPending(token: string): Promise<MfaPending | null> {
+    const row = await this.stmt('SELECT * FROM mfa_pending WHERE token = ?', token).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toMfaPending(row) : null
+  }
+
+  async consumeMfaPending(token: string): Promise<MfaPending | null> {
+    const res = await this.stmt(
+      "UPDATE mfa_pending SET consumed_at = datetime('now') WHERE token = ? AND consumed_at IS NULL", token,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    const row = await this.stmt('SELECT * FROM mfa_pending WHERE token = ?', token).first<Record<string, unknown>>()
+    if (!row) return null
+    if (new Date(row.expires_at as string).getTime() <= Date.now()) return null
+    return D1ServerStore.toMfaPending(row)
+  }
+
+  async recordMfaPendingFailure(token: string): Promise<MfaPending | null> {
+    const res = await this.stmt(
+      "UPDATE mfa_pending SET fail_count = fail_count + 1, last_failure_at = datetime('now') WHERE token = ? AND consumed_at IS NULL",
+      token,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    const row = await this.stmt('SELECT * FROM mfa_pending WHERE token = ?', token).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toMfaPending(row) : null
+  }
+
+  // ── organization administration (TODO.identity/10) ────────────────
+
+  /** The store's time columns arrive in two shapes (datetime('now')'s
+   *  naive UTC 'YYYY-MM-DD HH:MM:SS' from the DEFAULT writes, and the ISO
+   *  strings the code paths write); the API answers ISO always —
+   *  Date.parse would read the naive shape as LOCAL time and the routes'
+   *  age math would misfire off-UTC. */
+  private static storeTimeToIso(value: string | null): string | null {
+    if (value === null) return null
+    if (value.includes('T')) return value
+    return value.replace(' ', 'T') + 'Z'
+  }
+
+  private static toWebauthnCredential(row: Record<string, unknown>): WebauthnCredential {
+    return {
+      credentialId: row.credential_id as string,
+      userId: row.user_id as string,
+      name: row.name as string,
+      publicKeyCose: row.public_key as string,
+      signCount: Number(row.sign_count ?? 0),
+      aaguid: (row.aaguid as string | null) ?? null,
+      transports: parseRoles((row.transports as string | null) ?? null) ?? [],
+      createdAt: D1ServerStore.storeTimeToIso(row.created_at as string)!,
+      lastUsedAt: D1ServerStore.storeTimeToIso((row.last_used_at as string | null) ?? null),
+      lastIp: (row.last_ip as string | null) ?? null,
+    }
+  }
+
+  private static toTotpSecret(row: Record<string, unknown>): TotpSecret {
+    return {
+      id: row.id as string,
+      userId: row.user_id as string,
+      name: row.name as string,
+      secret: row.secret as string,
+      failCount: Number(row.fail_count ?? 0),
+      lastFailureAt: D1ServerStore.storeTimeToIso((row.last_failure_at as string | null) ?? null),
+      createdAt: D1ServerStore.storeTimeToIso(row.created_at as string)!,
+      verifiedAt: D1ServerStore.storeTimeToIso((row.verified_at as string | null) ?? null),
+      lastUsedAt: D1ServerStore.storeTimeToIso((row.last_used_at as string | null) ?? null),
+      lastIp: (row.last_ip as string | null) ?? null,
+    }
+  }
+
+  private static toWebauthnChallenge(row: Record<string, unknown>): WebauthnChallenge {
+    return {
+      challenge: row.challenge as string,
+      userId: (row.user_id as string | null) ?? null,
+      kind: row.kind as WebauthnChallenge['kind'],
+      createdAt: D1ServerStore.storeTimeToIso(row.created_at as string)!,
+      expiresAt: D1ServerStore.storeTimeToIso(row.expires_at as string)!,
+      consumedAt: D1ServerStore.storeTimeToIso((row.consumed_at as string | null) ?? null),
+    }
+  }
+
+  private static toMfaPending(row: Record<string, unknown>): MfaPending {
+    return {
+      token: row.token as string,
+      userId: row.user_id as string,
+      amr: parseRoles((row.amr as string | null) ?? null) ?? [],
+      failCount: Number(row.fail_count ?? 0),
+      lastFailureAt: D1ServerStore.storeTimeToIso((row.last_failure_at as string | null) ?? null),
+      createdAt: D1ServerStore.storeTimeToIso(row.created_at as string)!,
+      expiresAt: D1ServerStore.storeTimeToIso(row.expires_at as string)!,
+      consumedAt: D1ServerStore.storeTimeToIso((row.consumed_at as string | null) ?? null),
+    }
+  }
+
+  private static toOrgJoinRequest(row: Record<string, unknown>): OrgJoinRequest {
+    return {
+      id: row.id as string,
+      name: row.name as string,
+      email: row.email as string,
+      orgId: (row.org_id as string | null) ?? null,
+      orgNameText: (row.org_name_text as string | null) ?? null,
+      requestedRole: row.requested_role as string,
+      note: (row.note as string | null) ?? null,
+      status: row.status as OrgJoinRequest['status'],
+      decidedBy: (row.decided_by as string | null) ?? null,
+      decidedAt: (row.decided_at as string | null) ?? null,
+      refusalReason: (row.refusal_reason as string | null) ?? null,
+      invitedUserId: (row.invited_user_id as string | null) ?? null,
+      createdAt: row.created_at as string,
+    }
+  }
+
+  async createOrgJoinRequest(input: {
+    name: string
+    email: string
+    orgId: string | null
+    orgNameText: string | null
+    requestedRole: string
+    note?: string | null
+  }): Promise<OrgJoinRequest> {
+    const id = crypto.randomUUID()
+    await this.stmt(
+      `INSERT INTO org_join_requests (id, name, email, org_id, org_name_text, requested_role, note)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      id, input.name, input.email, input.orgId, input.orgNameText, input.requestedRole, input.note ?? null,
+    ).run()
+    return (await this.getOrgJoinRequest(id))!
+  }
+
+  async getOrgJoinRequest(id: string): Promise<OrgJoinRequest | null> {
+    const row = await this.stmt('SELECT * FROM org_join_requests WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toOrgJoinRequest(row) : null
+  }
+
+  async listOrgJoinRequests(filter?: {
+    scope?: 'org' | 'unregistered' | 'all'
+    orgId?: string
+    status?: OrgJoinRequest['status']
+  }): Promise<OrgJoinRequest[]> {
+    const scope = filter?.scope ?? 'all'
+    const where: string[] = []
+    const args: unknown[] = []
+    if (scope === 'org') { where.push('org_id = ?'); args.push(filter?.orgId ?? '') }
+    if (scope === 'unregistered') where.push('org_id IS NULL')
+    if (filter?.status) { where.push('status = ?'); args.push(filter.status) }
+    const sql = `SELECT * FROM org_join_requests${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY created_at`
+    const res = await this.stmt(sql, ...args).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toOrgJoinRequest)
+  }
+
+  /** The decision — atomic on 'pending' (a double decide loses honestly). */
+  async decideOrgJoinRequest(
+    id: string,
+    decision: {
+      status: 'approved' | 'refused'
+      decidedBy: string
+      refusalReason?: string | null
+      invitedUserId?: string | null
+    },
+  ): Promise<OrgJoinRequest | null> {
+    const res = await this.stmt(
+      `UPDATE org_join_requests
+       SET status = ?, decided_by = ?, decided_at = datetime('now'), refusal_reason = ?, invited_user_id = ?
+       WHERE id = ? AND status = 'pending'`,
+      decision.status, decision.decidedBy, decision.refusalReason ?? null, decision.invitedUserId ?? null, id,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.getOrgJoinRequest(id)
+  }
+
+  async findPendingOrgJoinRequestByEmail(email: string): Promise<OrgJoinRequest | null> {
+    const row = await this.stmt(
+      "SELECT * FROM org_join_requests WHERE email = ? AND status = 'pending' ORDER BY created_at", email,
+    ).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toOrgJoinRequest(row) : null
+  }
+
+  // ── organization memberships (TODO.identity/11 — the multi-org model) ──
+  // The rows port directly (D1 is SQLite) — the same statements as the
+  // SQLite store's membership section. THE DUAL-READ DOCTRINE: the users
+  // row's org_id/roles columns stay the backward-compatible read (the
+  // PRIMARY membership's mirror); the mirror rides every legacy writer.
+
+  private static toOrgMembership(row: Record<string, unknown>): OrgMembership {
+    let roles: string[] = []
+    try {
+      const parsed = JSON.parse(row.roles as string) as unknown
+      if (Array.isArray(parsed)) roles = parsed.filter((v): v is string => typeof v === 'string')
+    } catch { /* a malformed roles cell reads as the empty set */ }
+    return {
+      id: row.id as string,
+      userId: row.user_id as string,
+      orgId: row.org_id as string,
+      roles,
+      state: row.state as OrgMembershipState,
+      isPrimary: row.is_primary === 1,
+      invitedBy: (row.invited_by as string | null) ?? null,
+      createdAt: row.created_at as string,
+      activatedAt: (row.activated_at as string | null) ?? null,
+      disabledAt: (row.disabled_at as string | null) ?? null,
+      disabledBy: (row.disabled_by as string | null) ?? null,
+    }
+  }
+
+  /** THE MIRROR (the dual-read doctrine's write half): re-project the
+   *  PRIMARY membership from the users row's legacy columns. A DISABLED
+   *  row keeps its state (only roles + the primary mark move). */
+  private async syncPrimaryMembership(userId: string): Promise<void> {
+    await this.ensureMembershipSupport()
+    const user = await this.stmt('SELECT id, role, roles, org_id FROM users WHERE id = ?', userId)
+      .first<{ id: string; role: string; roles: string | null; org_id: string | null }>()
+    if (!user || !user.org_id) return
+    const roles = parseRoles(user.roles) ?? [user.role]
+    await this.db.batch([
+      this.stmt('UPDATE org_memberships SET is_primary = 0 WHERE user_id = ? AND org_id != ? AND is_primary = 1', userId, user.org_id),
+      this.stmt(
+        `INSERT INTO org_memberships (id, user_id, org_id, roles, state, is_primary, activated_at)
+         VALUES (?, ?, ?, ?, 'active', 1, datetime('now'))
+         ON CONFLICT (user_id, org_id) DO UPDATE SET roles = excluded.roles, is_primary = 1`,
+        crypto.randomUUID(), userId, user.org_id, JSON.stringify(roles),
+      ),
+    ])
+  }
+
+  async listOrgMemberships(userId: string): Promise<OrgMembership[]> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt(
+      'SELECT * FROM org_memberships WHERE user_id = ? ORDER BY is_primary DESC, created_at', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toOrgMembership)
+  }
+
+  async listOrgMembers(orgId: string): Promise<OrgMembership[]> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt(
+      'SELECT * FROM org_memberships WHERE org_id = ? ORDER BY created_at', orgId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toOrgMembership)
+  }
+
+  async getOrgMembership(userId: string, orgId: string): Promise<OrgMembership | null> {
+    await this.ensureMembershipSupport()
+    const row = await this.stmt('SELECT * FROM org_memberships WHERE user_id = ? AND org_id = ?', userId, orgId)
+      .first<Record<string, unknown>>()
+    return row ? D1ServerStore.toOrgMembership(row) : null
+  }
+
+  /** Create the membership; NULL on the (user, org) conflict — the
+   *  honest "already a member". */
+  async createOrgMembership(input: {
+    userId: string
+    orgId: string
+    roles: string[]
+    state: OrgMembershipState
+    invitedBy?: string | null
+  }): Promise<OrgMembership | null> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt(
+      `INSERT OR IGNORE INTO org_memberships (id, user_id, org_id, roles, state, invited_by, activated_at)
+       VALUES (?, ?, ?, ?, ?, ?, CASE WHEN ? = 'active' THEN datetime('now') ELSE NULL END)`,
+      crypto.randomUUID(), input.userId, input.orgId, JSON.stringify(input.roles), input.state,
+      input.invitedBy ?? null, input.state,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.getOrgMembership(input.userId, input.orgId)
+  }
+
+  /** Replace the per-org role set; the PRIMARY membership's write mirrors
+   *  into the users row (the dual-write — the legacy read stays
+   *  identical). */
+  async setOrgMembershipRoles(userId: string, orgId: string, roles: string[]): Promise<boolean> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt('UPDATE org_memberships SET roles = ? WHERE user_id = ? AND org_id = ?',
+      JSON.stringify(roles), userId, orgId).run()
+    if ((res.meta.changes ?? 0) === 0) return false
+    const membership = await this.getOrgMembership(userId, orgId)
+    if (membership?.isPrimary) {
+      const user = await this.stmt('SELECT role FROM users WHERE id = ?', userId).first<{ role: string }>()
+      if (user) {
+        const primaryRole = roles.includes(user.role) ? user.role : (roles[0] ?? user.role)
+        await this.stmt('UPDATE users SET role = ?, roles = ? WHERE id = ?',
+          primaryRole, JSON.stringify(roles.length ? roles : [primaryRole]), userId).run()
+      }
+    }
+    return true
+  }
+
+  /** The lifecycle act (stamps; disabling also clears the account's
+   *  sessions' active-org stamps pointing at the org). */
+  async setOrgMembershipState(
+    userId: string,
+    orgId: string,
+    state: OrgMembershipState,
+    actor?: string | null,
+  ): Promise<OrgMembership | null> {
+    await this.ensureMembershipSupport()
+    const existing = await this.getOrgMembership(userId, orgId)
+    if (!existing) return null
+    if (state === 'active') {
+      await this.stmt(
+        "UPDATE org_memberships SET state = 'active', activated_at = datetime('now'), disabled_at = NULL, disabled_by = NULL WHERE user_id = ? AND org_id = ?",
+        userId, orgId,
+      ).run()
+    } else if (state === 'disabled') {
+      await this.db.batch([
+        this.stmt(
+          "UPDATE org_memberships SET state = 'disabled', disabled_at = datetime('now'), disabled_by = ? WHERE user_id = ? AND org_id = ?",
+          actor ?? null, userId, orgId,
+        ),
+        this.stmt('UPDATE sessions SET active_org = NULL WHERE user_id = ? AND active_org = ?', userId, orgId),
+      ])
+    } else {
+      await this.stmt("UPDATE org_memberships SET state = 'invited' WHERE user_id = ? AND org_id = ?", userId, orgId).run()
+    }
+    return this.getOrgMembership(userId, orgId)
+  }
+
+  /** Remove the row (the declined invitation; the erasure's cleanup). */
+  async deleteOrgMembership(userId: string, orgId: string): Promise<boolean> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt('DELETE FROM org_memberships WHERE user_id = ? AND org_id = ?', userId, orgId).run()
+    if ((res.meta.changes ?? 0) > 0) {
+      await this.stmt('UPDATE sessions SET active_org = NULL WHERE user_id = ? AND active_org = ?', userId, orgId).run()
+    }
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** The session's stamped active-org context (NULL = the primary
+   *  context; also NULL for an unknown/expired token). */
+  async getSessionActiveOrg(token: string): Promise<string | null> {
+    await this.ensureMembershipSupport()
+    const row = await this.stmt("SELECT active_org FROM sessions WHERE token = ? AND expires_at > datetime('now')", token)
+      .first<{ active_org: string | null }>()
+    return row?.active_org ?? null
+  }
+
+  /** Stamp the session's active-org context; NULL clears to the primary
+   *  context. */
+  async setSessionActiveOrg(token: string, orgId: string | null): Promise<boolean> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt("UPDATE sessions SET active_org = ? WHERE token = ? AND expires_at > datetime('now')",
+      orgId, token).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  // ── the organization registry (TODO.identity-features/05) ──────────
+  // The identity service's OWN org registry — the rows the membership
+  // graph references by id. The lifecycle acts are the routes'; these
+  // mirror the SQLite store's registry section one-for-one.
+
+  private static toOrgRegistryOrg(row: Record<string, unknown>): OrgRegistryOrg {
+    let contacts: OrgRegistryContact[] = []
+    try {
+      const parsed = JSON.parse((row.contacts as string) ?? '[]') as unknown
+      if (Array.isArray(parsed)) {
+        contacts = parsed
+          .filter((e): e is Record<string, unknown> => !!e && typeof e === 'object')
+          .map(e => ({ name: typeof e.name === 'string' && e.name.trim() ? e.name.trim() : null, email: typeof e.email === 'string' ? e.email.trim() : '' }))
+          .filter(e => e.email.includes('@'))
+      }
+    } catch { /* a malformed contacts cell reads as the empty list */ }
+    return {
+      id: row.id as string,
+      name: row.name as string,
+      shortName: (row.short_name as string | null) ?? null,
+      kind: (row.kind as string | null) ?? null,
+      country: (row.country as string | null) ?? null,
+      contacts,
+      participantRef: (row.participant_ref as string | null) ?? null,
+      state: row.state as OrgRegistryState,
+      createdAt: row.created_at as string,
+      createdBy: (row.created_by as string | null) ?? null,
+      updatedAt: (row.updated_at as string | null) ?? null,
+      updatedBy: (row.updated_by as string | null) ?? null,
+      disabledAt: (row.disabled_at as string | null) ?? null,
+      disabledBy: (row.disabled_by as string | null) ?? null,
+    }
+  }
+
+  async listOrgRegistryOrgs(): Promise<OrgRegistryOrg[]> {
+    await this.ensureOrgRegistrySupport()
+    const res = await this.stmt('SELECT * FROM org_registry').all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toOrgRegistryOrg).sort((a, b) => a.name.localeCompare(b.name))
+  }
+
+  async getOrgRegistryOrg(id: string): Promise<OrgRegistryOrg | null> {
+    await this.ensureOrgRegistrySupport()
+    const row = await this.stmt('SELECT * FROM org_registry WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toOrgRegistryOrg(row) : null
+  }
+
+  /** Add the organization; NULL on the id conflict (the slug is taken). */
+  async 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> {
+    await this.ensureOrgRegistrySupport()
+    const res = await this.stmt(
+      `INSERT OR IGNORE INTO org_registry (id, name, short_name, kind, country, contacts, participant_ref, created_by)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      input.id, input.name, input.shortName ?? null, input.kind ?? null, input.country ?? null,
+      JSON.stringify(input.contacts ?? []), input.participantRef ?? null, input.createdBy ?? null,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.getOrgRegistryOrg(input.id)
+  }
+
+  /** Edit the display data (the id never moves); stamps updated_at/by. */
+  async 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> {
+    await this.ensureOrgRegistrySupport()
+    const sets: string[] = []
+    const params: unknown[] = []
+    if (patch.name !== undefined) { sets.push('name = ?'); params.push(patch.name) }
+    if (patch.shortName !== undefined) { sets.push('short_name = ?'); params.push(patch.shortName) }
+    if (patch.kind !== undefined) { sets.push('kind = ?'); params.push(patch.kind) }
+    if (patch.country !== undefined) { sets.push('country = ?'); params.push(patch.country) }
+    if (patch.contacts !== undefined) { sets.push('contacts = ?'); params.push(JSON.stringify(patch.contacts)) }
+    if (patch.participantRef !== undefined) { sets.push('participant_ref = ?'); params.push(patch.participantRef) }
+    sets.push("updated_at = datetime('now')", 'updated_by = ?')
+    params.push(actor ?? null)
+    const res = await this.stmt(`UPDATE org_registry SET ${sets.join(', ')} WHERE id = ?`, ...params, id).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.getOrgRegistryOrg(id)
+  }
+
+  /** The lifecycle act (stamps; re-enable clears the disable stamps —
+   *  the memberships stay as they are). */
+  async setOrgRegistryOrgState(id: string, state: OrgRegistryState, actor?: string | null): Promise<OrgRegistryOrg | null> {
+    await this.ensureOrgRegistrySupport()
+    const existing = await this.getOrgRegistryOrg(id)
+    if (!existing) return null
+    if (state === 'disabled') {
+      await this.stmt("UPDATE org_registry SET state = 'disabled', disabled_at = datetime('now'), disabled_by = ? WHERE id = ?",
+        actor ?? null, id).run()
+    } else {
+      await this.stmt("UPDATE org_registry SET state = 'active', disabled_at = NULL, disabled_by = NULL WHERE id = ?",
+        id).run()
+    }
+    return this.getOrgRegistryOrg(id)
+  }
+
+  /** The erasure-adjacent hard delete (the route guards it). */
+  async deleteOrgRegistryOrg(id: string): Promise<boolean> {
+    await this.ensureOrgRegistrySupport()
+    const res = await this.stmt('DELETE FROM org_registry WHERE id = ?', id).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  // ── the register's holder-org attribution (TODO.register/02) ────────
+
+  private static toCertificateHolderOrg(row: Record<string, unknown>): CertificateHolderOrg {
+    return {
+      certificateId: row.certificate_id as string,
+      orgId: row.org_id as string,
+      orgName: row.org_name as string,
+      source: row.source as CertificateHolderOrg['source'],
+      attributedAt: row.attributed_at as string,
+      attributedBy: (row.attributed_by as string | null) ?? null,
+      claimId: (row.claim_id as string | null) ?? null,
+    }
+  }
+
+  /** INSERT-IF-ABSENT — the first attribution wins (NULL on an existing
+   *  row, never a silent overwrite). */
+  async attributeCertificateHolderOrg(input: {
+    certificateId: string
+    orgId: string
+    orgName: string
+    source: CertificateHolderOrg['source']
+    attributedAt: string
+    attributedBy?: string | null
+    claimId?: string | null
+  }): Promise<CertificateHolderOrg | null> {
+    await this.ensureHolderAttributionSupport()
+    const res = await this.stmt(
+      `INSERT OR IGNORE INTO certificate_holder_orgs
+         (certificate_id, org_id, org_name, source, attributed_at, attributed_by, claim_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      input.certificateId, input.orgId, input.orgName, input.source,
+      input.attributedAt, input.attributedBy ?? null, input.claimId ?? null,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.getCertificateHolderOrg(input.certificateId)
+  }
+
+  async getCertificateHolderOrg(certificateId: string): Promise<CertificateHolderOrg | null> {
+    await this.ensureHolderAttributionSupport()
+    const row = await this.stmt('SELECT * FROM certificate_holder_orgs WHERE certificate_id = ?', certificateId)
+      .first<Record<string, unknown>>()
+    return row ? D1ServerStore.toCertificateHolderOrg(row) : null
+  }
+
+  async listCertificateHolderOrgs(filter?: { orgId?: string }): Promise<CertificateHolderOrg[]> {
+    await this.ensureHolderAttributionSupport()
+    const res = filter?.orgId
+      ? await this.stmt('SELECT * FROM certificate_holder_orgs WHERE org_id = ?', filter.orgId).all<Record<string, unknown>>()
+      : await this.stmt('SELECT * FROM certificate_holder_orgs').all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toCertificateHolderOrg)
+  }
+
+  private static toCertificateHolderClaim(row: Record<string, unknown>): CertificateHolderClaim {
+    return {
+      id: row.id as string,
+      certificateId: row.certificate_id as string,
+      claimantOrgId: row.claimant_org_id as string,
+      claimantOrgName: row.claimant_org_name as string,
+      matchedHolderName: row.matched_holder_name as string,
+      claimedBy: row.claimed_by as string,
+      state: row.state as CertificateHolderClaim['state'],
+      decidedBy: (row.decided_by as string | null) ?? null,
+      decidedAt: (row.decided_at as string | null) ?? null,
+      refusalReason: (row.refusal_reason as string | null) ?? null,
+      createdAt: row.created_at as string,
+    }
+  }
+
+  async createCertificateHolderClaim(input: {
+    certificateId: string
+    claimantOrgId: string
+    claimantOrgName: string
+    matchedHolderName: string
+    claimedBy: string
+  }): Promise<CertificateHolderClaim> {
+    await this.ensureHolderAttributionSupport()
+    const id = crypto.randomUUID()
+    await this.stmt(
+      `INSERT INTO certificate_holder_claims
+         (id, certificate_id, claimant_org_id, claimant_org_name, matched_holder_name, claimed_by)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      id, input.certificateId, input.claimantOrgId, input.claimantOrgName, input.matchedHolderName, input.claimedBy,
+    ).run()
+    return (await this.getCertificateHolderClaim(id))!
+  }
+
+  async getCertificateHolderClaim(id: string): Promise<CertificateHolderClaim | null> {
+    await this.ensureHolderAttributionSupport()
+    const row = await this.stmt('SELECT * FROM certificate_holder_claims WHERE id = ?', id)
+      .first<Record<string, unknown>>()
+    return row ? D1ServerStore.toCertificateHolderClaim(row) : null
+  }
+
+  async listCertificateHolderClaims(filter?: {
+    state?: CertificateHolderClaim['state']
+    claimantOrgId?: string
+    certificateId?: string
+  }): Promise<CertificateHolderClaim[]> {
+    await this.ensureHolderAttributionSupport()
+    const where: string[] = []
+    const params: unknown[] = []
+    if (filter?.state) { where.push('state = ?'); params.push(filter.state) }
+    if (filter?.claimantOrgId) { where.push('claimant_org_id = ?'); params.push(filter.claimantOrgId) }
+    if (filter?.certificateId) { where.push('certificate_id = ?'); params.push(filter.certificateId) }
+    const res = await this.stmt(
+      `SELECT * FROM certificate_holder_claims${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY created_at`,
+      ...params,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toCertificateHolderClaim)
+  }
+
+  /** The estate admin's decision — ATOMIC on 'pending' (a double
+   *  decision loses the race, answering null). */
+  async decideCertificateHolderClaim(
+    id: string,
+    decision: { status: 'confirmed' | 'refused'; decidedBy: string; refusalReason?: string | null },
+  ): Promise<CertificateHolderClaim | null> {
+    await this.ensureHolderAttributionSupport()
+    const res = await this.stmt(
+      `UPDATE certificate_holder_claims
+       SET state = ?, decided_by = ?, decided_at = datetime('now'), refusal_reason = ?
+       WHERE id = ? AND state = 'pending'`,
+      decision.status, decision.decidedBy, decision.refusalReason ?? null, id,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.getCertificateHolderClaim(id)
+  }
+
+  async findPendingCertificateHolderClaim(certificateId: string): Promise<CertificateHolderClaim | null> {
+    await this.ensureHolderAttributionSupport()
+    const row = await this.stmt(
+      "SELECT * FROM certificate_holder_claims WHERE certificate_id = ? AND state = 'pending'",
+      certificateId,
+    ).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toCertificateHolderClaim(row) : null
+  }
+
+  // ── the instrument register (TODO.register/03) ─────────────────────
+  // The platform-side serial register — the rows the registration
+  // interface's cones read (the route's; browser/server/routes/
+  // registrations.ts). These mirror the SQLite store's register section
+  // one-for-one.
+
+  private static toInstrumentRegistration(row: Record<string, unknown>): InstrumentRegistration {
+    let designations: Record<string, unknown> = {}
+    try {
+      const parsed = JSON.parse((row.designations as string) ?? '{}') as unknown
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) designations = parsed as Record<string, unknown>
+    } catch { /* a malformed designations cell reads as the empty object, never trusted */ }
+    return {
+      id: row.id as string,
+      certificateId: row.certificate_id as string,
+      holderOrgId: row.holder_org_id as string,
+      standardId: row.standard_id as string,
+      serialNumber: row.serial_number as string,
+      manufactureDate: (row.manufacture_date as string | null) ?? null,
+      designations,
+      scopeStatus: row.scope_status as InstrumentRegistrationScopeStatus,
+      scopeDetail: (row.scope_detail as string | null) ?? null,
+      lifecycle: row.lifecycle as InstrumentRegistrationLifecycle,
+      registeredAt: row.registered_at as string,
+      registeredBy: (row.registered_by as string | null) ?? null,
+      updatedAt: (row.updated_at as string | null) ?? null,
+      updatedBy: (row.updated_by as string | null) ?? null,
+    }
+  }
+
+  async listInstrumentRegistrations(): Promise<InstrumentRegistration[]> {
+    await this.ensureInstrumentRegistrationSupport()
+    const res = await this.stmt('SELECT * FROM instrument_registrations').all<Record<string, unknown>>()
+    return res.results
+      .map(D1ServerStore.toInstrumentRegistration)
+      .sort((a, b) => a.certificateId.localeCompare(b.certificateId) || a.serialNumber.localeCompare(b.serialNumber))
+  }
+
+  async listInstrumentRegistrationsForCertificate(certificateId: string): Promise<InstrumentRegistration[]> {
+    await this.ensureInstrumentRegistrationSupport()
+    const res = await this.stmt('SELECT * FROM instrument_registrations WHERE certificate_id = ?', certificateId).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toInstrumentRegistration).sort((a, b) => a.serialNumber.localeCompare(b.serialNumber))
+  }
+
+  async listInstrumentRegistrationsForHolder(holderOrgId: string): Promise<InstrumentRegistration[]> {
+    await this.ensureInstrumentRegistrationSupport()
+    const res = await this.stmt('SELECT * FROM instrument_registrations WHERE holder_org_id = ?', holderOrgId).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toInstrumentRegistration).sort((a, b) => a.serialNumber.localeCompare(b.serialNumber))
+  }
+
+  async getInstrumentRegistration(id: string): Promise<InstrumentRegistration | null> {
+    await this.ensureInstrumentRegistrationSupport()
+    const row = await this.stmt('SELECT * FROM instrument_registrations WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toInstrumentRegistration(row) : null
+  }
+
+  /** Register the instrument; NULL on the (certificate, serial)
+   *  conflict (the route's honest 409). */
+  async 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> {
+    await this.ensureInstrumentRegistrationSupport()
+    const res = await this.stmt(
+      `INSERT OR IGNORE INTO instrument_registrations
+         (id, certificate_id, holder_org_id, standard_id, serial_number, manufacture_date, designations, scope_status, scope_detail, registered_by)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      input.id, input.certificateId, input.holderOrgId, input.standardId, input.serialNumber,
+      input.manufactureDate ?? null, JSON.stringify(input.designations ?? {}),
+      input.scopeStatus, input.scopeDetail ?? null, input.registeredBy ?? null,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.getInstrumentRegistration(input.id)
+  }
+
+  /** The lifecycle act (the transition rule is the route's); stamps
+   *  updated_at/by. NULL when the register does not carry the id. */
+  async setInstrumentRegistrationLifecycle(
+    id: string,
+    lifecycle: InstrumentRegistrationLifecycle,
+    actor?: string | null,
+  ): Promise<InstrumentRegistration | null> {
+    await this.ensureInstrumentRegistrationSupport()
+    const res = await this.stmt(
+      "UPDATE instrument_registrations SET lifecycle = ?, updated_at = datetime('now'), updated_by = ? WHERE id = ?",
+      lifecycle, actor ?? null, id,
+    ).run()
+    if ((res.meta.changes ?? 0) === 0) return null
+    return this.getInstrumentRegistration(id)
+  }
+
+  // ── the workflow entity store + change journal ───────────────────
+
+  async listEntities(store: string): Promise<EntityRow[]> {
+    const res = await this.stmt(
+      'SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ?', store,
+    ).all<EntityRow>()
+    return res.results
+  }
+
+  async getEntity(store: string, id: string): Promise<EntityRow | undefined> {
+    const row = await this.stmt(
+      'SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ? AND id = ?', store, id,
+    ).first<EntityRow>()
+    return row ?? undefined
+  }
+
+  async putEntity(store: string, id: string, orgId: string | null, data: string): Promise<void> {
+    // The upsert + its journal entry ride ONE batch — D1 batches are
+    // all-or-nothing, the same atomicity the SQLite path gets from its
+    // transaction.
+    await this.db.batch([
+      this.stmt(
+        `INSERT INTO entities (store, id, org_id, data, updated_at) VALUES (?, ?, ?, ?, datetime('now'))
+         ON CONFLICT (store, id) DO UPDATE SET org_id = excluded.org_id, data = excluded.data, updated_at = datetime('now')`,
+        store, id, orgId, data,
+      ),
+      this.stmt('INSERT INTO entity_changes (store, type, id) VALUES (?, ?, ?)', store, 'persist', id),
+    ])
+  }
+
+  async deleteEntity(store: string, id: string): Promise<boolean> {
+    const res = await this.stmt('DELETE FROM entities WHERE store = ? AND id = ?', store, id).run()
+    const gone = (res.meta.changes ?? 0) > 0
+    if (gone) {
+      await this.stmt('INSERT INTO entity_changes (store, type, id) VALUES (?, ?, ?)', store, 'remove', id).run()
+    }
+    return gone
+  }
+
+  async changesAfter(seq: number, limit = 500): Promise<EntityChange[]> {
+    const res = await this.stmt(
+      'SELECT seq, store, type, id, at FROM entity_changes WHERE seq > ? ORDER BY seq LIMIT ?', seq, limit,
+    ).all<EntityChange>()
+    return res.results
+  }
+
+  async latestChangeSeq(): Promise<number> {
+    const row = await this.stmt('SELECT MAX(seq) AS seq FROM entity_changes').first<{ seq: number | null }>()
+    return row?.seq ?? 0
+  }
+
+  // ── the platform event store (TODO.notify/01) ─────────────────────
+  // The event rows port directly (D1 is SQLite) — the same statements
+  // as sqlite/events.ts's sync half.
+
+  private static toPlatformEvent(row: Record<string, unknown>): PlatformEvent {
+    return {
+      seq: row.seq as number,
+      id: row.id as string,
+      domain: row.domain as string,
+      entityId: row.entity_id as string,
+      action: row.action as string,
+      payload: row.payload as string,
+      at: row.at as string,
+    }
+  }
+
+  async appendEvent(input: {
+    id: string
+    domain: string
+    entityId: string
+    action: string
+    payload: string
+  }): Promise<PlatformEvent> {
+    await this.stmt(
+      'INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?)',
+      input.id, input.domain, input.entityId, input.action, input.payload,
+    ).run()
+    const row = await this.stmt('SELECT * FROM events WHERE id = ?', input.id).first<Record<string, unknown>>()
+    return D1ServerStore.toPlatformEvent(row!)
+  }
+
+  async eventsAfter(seq: number, limit = 500): Promise<PlatformEvent[]> {
+    const res = await this.stmt(
+      'SELECT * FROM events WHERE seq > ? ORDER BY seq LIMIT ?', seq, limit,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toPlatformEvent)
+  }
+
+  async latestEventSeq(): Promise<number> {
+    const row = await this.stmt('SELECT MAX(seq) AS seq FROM events').first<{ seq: number | null }>()
+    return row?.seq ?? 0
+  }
+
+  async getEvent(id: string): Promise<PlatformEvent | null> {
+    const row = await this.stmt('SELECT * FROM events WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toPlatformEvent(row) : null
+  }
+
+  /** The subscription grammar's SQL resolution: the pinned columns match
+   *  by equality; the free legs stay out of the WHERE. */
+  async eventsMatching(filter: EventKeyFilter, limit = 500): Promise<PlatformEvent[]> {
+    const where: string[] = []
+    const args: unknown[] = []
+    if (filter.domain !== undefined) { where.push('domain = ?'); args.push(filter.domain) }
+    if (filter.entityId !== undefined) { where.push('entity_id = ?'); args.push(filter.entityId) }
+    if (filter.action !== undefined) { where.push('action = ?'); args.push(filter.action) }
+    const sql = `SELECT * FROM events${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY seq LIMIT ?`
+    const res = await this.stmt(sql, ...args, limit).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toPlatformEvent)
+  }
+
+  // ── the notification subscriptions store (TODO.notify/02) ─────────
+  // The SAME statements as sqlite/notify.ts's sync half (D1 is SQLite).
+
+  private static toNotifyRule(row: Record<string, unknown>): NotifyRule {
+    return {
+      id: row.id as string,
+      userId: row.user_id as string,
+      pattern: row.pattern as string,
+      domain: row.domain as string,
+      entityId: (row.entity_id as string | null) ?? null,
+      action: (row.action as string | null) ?? null,
+      mode: row.mode as NotifyRule['mode'],
+      channelOverrides: (row.channel_overrides as string | null) ?? null,
+      createdAt: row.created_at as string,
+    }
+  }
+
+  async listNotifyRules(userId: string): Promise<NotifyRule[]> {
+    const res = await this.stmt(
+      'SELECT * FROM notify_rules WHERE user_id = ? ORDER BY created_at, id', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toNotifyRule)
+  }
+
+  async putNotifyRule(input: {
+    id: string
+    userId: string
+    pattern: string
+    domain: string
+    entityId: string | null
+    action: string | null
+    mode: NotifyRule['mode']
+    channelOverrides: string | null
+  }): Promise<NotifyRule> {
+    await this.stmt(
+      `INSERT INTO notify_rules (id, user_id, pattern, domain, entity_id, action, mode, channel_overrides)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (user_id, pattern) DO UPDATE SET
+         domain = excluded.domain,
+         entity_id = excluded.entity_id,
+         action = excluded.action,
+         mode = excluded.mode,
+         channel_overrides = excluded.channel_overrides`,
+      input.id, input.userId, input.pattern, input.domain, input.entityId, input.action, input.mode, input.channelOverrides,
+    ).run()
+    const row = await this.stmt(
+      'SELECT * FROM notify_rules WHERE user_id = ? AND pattern = ?', input.userId, input.pattern,
+    ).first<Record<string, unknown>>()
+    return D1ServerStore.toNotifyRule(row!)
+  }
+
+  async deleteNotifyRule(userId: string, pattern: string): Promise<boolean> {
+    const res = await this.stmt(
+      'DELETE FROM notify_rules WHERE user_id = ? AND pattern = ?', userId, pattern,
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** The resolution's reverse match: a rule covers the event when its
+   *  pinned legs equal the event's columns (NULL = the wild leg). */
+  async notifyRulesForEvent(filter: { domain: string; entityId: string; action: string }): Promise<NotifyRule[]> {
+    const res = await this.stmt(
+      `SELECT * FROM notify_rules
+       WHERE domain = ? AND (entity_id IS NULL OR entity_id = ?) AND (action IS NULL OR action = ?)
+       ORDER BY created_at, id`,
+      filter.domain, filter.entityId, filter.action,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toNotifyRule)
+  }
+
+  private static toNotifyEntityMute(row: Record<string, unknown>): NotifyEntityMute {
+    return {
+      id: row.id as string,
+      userId: row.user_id as string,
+      domain: row.domain as string,
+      entityId: row.entity_id as string,
+      createdAt: row.created_at as string,
+    }
+  }
+
+  async listNotifyEntityMutes(userId: string): Promise<NotifyEntityMute[]> {
+    const res = await this.stmt(
+      'SELECT * FROM notify_entity_mutes WHERE user_id = ? ORDER BY created_at, id', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toNotifyEntityMute)
+  }
+
+  async putNotifyEntityMute(input: { id: string; userId: string; domain: string; entityId: string }): Promise<NotifyEntityMute> {
+    await this.stmt(
+      `INSERT INTO notify_entity_mutes (id, user_id, domain, entity_id) VALUES (?, ?, ?, ?)
+       ON CONFLICT (user_id, domain, entity_id) DO NOTHING`,
+      input.id, input.userId, input.domain, input.entityId,
+    ).run()
+    const row = await this.stmt(
+      'SELECT * FROM notify_entity_mutes WHERE user_id = ? AND domain = ? AND entity_id = ?',
+      input.userId, input.domain, input.entityId,
+    ).first<Record<string, unknown>>()
+    return D1ServerStore.toNotifyEntityMute(row!)
+  }
+
+  async deleteNotifyEntityMute(userId: string, domain: string, entityId: string): Promise<boolean> {
+    const res = await this.stmt(
+      'DELETE FROM notify_entity_mutes WHERE user_id = ? AND domain = ? AND entity_id = ?',
+      userId, domain, entityId,
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  async notifyEntityMutesForEvent(domain: string, entityId: string): Promise<NotifyEntityMute[]> {
+    const res = await this.stmt(
+      'SELECT * FROM notify_entity_mutes WHERE domain = ? AND entity_id = ? ORDER BY created_at, id',
+      domain, entityId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toNotifyEntityMute)
+  }
+
+  private static toNotifyPreferences(row: Record<string, unknown>): NotifyPreferences {
+    return {
+      userId: row.user_id as string,
+      channels: row.channels as string,
+      updatedAt: row.updated_at as string,
+    }
+  }
+
+  async getNotifyPreferences(userId: string): Promise<NotifyPreferences | null> {
+    const row = await this.stmt(
+      'SELECT * FROM notify_preferences WHERE user_id = ?', userId,
+    ).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toNotifyPreferences(row) : null
+  }
+
+  async putNotifyPreferences(userId: string, channels: string): Promise<NotifyPreferences> {
+    await this.stmt(
+      `INSERT INTO notify_preferences (user_id, channels) VALUES (?, ?)
+       ON CONFLICT (user_id) DO UPDATE SET channels = excluded.channels, updated_at = datetime('now')`,
+      userId, channels,
+    ).run()
+    const row = await this.stmt(
+      'SELECT * FROM notify_preferences WHERE user_id = ?', userId,
+    ).first<Record<string, unknown>>()
+    return D1ServerStore.toNotifyPreferences(row!)
+  }
+
+  // ── the inbox state (TODO.notify/03) ──────────────────────────────
+  // The SAME statements as sqlite/notify.ts's sync half (D1 is SQLite).
+
+  private static toNotifyInboxState(row: Record<string, unknown>): NotifyInboxState {
+    return {
+      userId: row.user_id as string,
+      eventId: row.event_id as string,
+      readAt: (row.read_at as string | null) ?? null,
+      doneAt: (row.done_at as string | null) ?? null,
+      createdAt: row.created_at as string,
+    }
+  }
+
+  async listNotifyInboxStates(userId: string): Promise<NotifyInboxState[]> {
+    const res = await this.stmt(
+      'SELECT * FROM notify_inbox_state WHERE user_id = ? ORDER BY created_at, event_id', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toNotifyInboxState)
+  }
+
+  /** The marker write: each PRESENT flag stamps (datetime('now')) or
+   *  clears (NULL) its column; absent flags keep. */
+  async putNotifyInboxState(input: {
+    userId: string
+    eventId: string
+    read?: boolean
+    done?: boolean
+  }): Promise<NotifyInboxState> {
+    await this.stmt(
+      'INSERT OR IGNORE INTO notify_inbox_state (user_id, event_id) VALUES (?, ?)',
+      input.userId, input.eventId,
+    ).run()
+    if (input.read !== undefined) {
+      await this.stmt(
+        "UPDATE notify_inbox_state SET read_at = CASE WHEN ? THEN datetime('now') ELSE NULL END WHERE user_id = ? AND event_id = ?",
+        input.read ? 1 : 0, input.userId, input.eventId,
+      ).run()
+    }
+    if (input.done !== undefined) {
+      await this.stmt(
+        "UPDATE notify_inbox_state SET done_at = CASE WHEN ? THEN datetime('now') ELSE NULL END WHERE user_id = ? AND event_id = ?",
+        input.done ? 1 : 0, input.userId, input.eventId,
+      ).run()
+    }
+    const row = await this.stmt(
+      'SELECT * FROM notify_inbox_state WHERE user_id = ? AND event_id = ?',
+      input.userId, input.eventId,
+    ).first<Record<string, unknown>>()
+    return D1ServerStore.toNotifyInboxState(row!)
+  }
+
+  // ── provisioning / dev support ───────────────────────────────────
+
+  async wipeWorkflowStores(range?: { after: number; through: number }): Promise<number> {
+    // The register table joins the wipe defensively (a dev D1 migrated
+    // from before migration 0016 lacks it — the ensure posture).
+    await this.ensureInstrumentRegistrationSupport()
+    // The wipe's tables in one batch (all-or-nothing, the putEntity
+    // pattern). A ranged round charges one bounded statement per table;
+    // the range-less form is the direct-call default (small stores,
+    // tests) — the budgeted reset phase always passes a range.
+    const statements = range
+      ? WIPE_TABLES.map(t => this.db.prepare(`DELETE FROM ${t} WHERE rowid > ? AND rowid <= ?`).bind(range.after, range.through))
+      : WIPE_TABLES.map(t => this.db.prepare(`DELETE FROM ${t}`))
+    const results = await this.db.batch(statements)
+    return results.reduce((rows, r) => rows + (r.meta.changes ?? 0), 0)
+  }
+
+  async workflowStoreRowCeiling(): Promise<number> {
+    await this.ensureInstrumentRegistrationSupport()
+    const row = await this.stmt(
+      `SELECT MAX(ceiling) AS ceiling FROM (
+         SELECT MAX(rowid) AS ceiling FROM entity_changes
+         UNION ALL SELECT MAX(rowid) FROM evidence_records
+         UNION ALL SELECT MAX(rowid) FROM entities
+         UNION ALL SELECT MAX(rowid) FROM events
+         UNION ALL SELECT MAX(rowid) FROM instrument_registrations)`,
+    ).first<{ ceiling: number | null }>()
+    return row?.ceiling ?? 0
+  }
+
+  async countEntities(): Promise<number> {
+    const row = await this.stmt('SELECT COUNT(*) AS n FROM entities').first<{ n: number }>()
+    return row?.n ?? 0
+  }
+}
+
+/** The worker entry's install: one store per binding, memoized (the
+ *  store is a stateless facade over the binding — safe to share across
+ *  the isolate's concurrent requests). */
+const byBinding = new WeakMap<D1Database, D1ServerStore>()
+
+export function d1StoreFor(binding: D1Database): D1ServerStore {
+  let store = byBinding.get(binding)
+  if (!store) {
+    store = new D1ServerStore(binding)
+    byBinding.set(binding, store)
+  }
+  return store
+}