@substrat-run/adapter-sqlite 0.5.0 → 0.7.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import Database from 'better-sqlite3';
-import { adminLogEntry, createTenantInput, domainEvent, domainEventInput, eventId, identityLink, instant, moduleManifest, objectRef, principalId, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, } from '@substrat-run/contracts';
+import { accessLogEntry, adminLogEntry, createTenantInput, domainEvent, domainEventInput, eventId, identityLink, identityPool, instant, moduleManifest, createOrgInput, promotionAcknowledgement, bindHostnameInput, hostnameBinding, publishVersionInput, routeTarget, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, objectRef, org as orgSchema, orgMembership, principalId, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, } from '@substrat-run/contracts';
 import { resolveScopeRecord, ulid, } from '@substrat-run/kernel';
 import { ScopeActor } from './actor.js';
 import { createTupleChecker } from './checker.js';
@@ -32,6 +32,10 @@ const KERNEL_DDL = `
     relation TEXT NOT NULL,
     object TEXT NOT NULL,
     expires_at TEXT,
+    -- K-21: revocation TOMBSTONES. The row stays and the walk skips it, because a
+    -- tuple that once granted access is evidence of why an access was allowed
+    -- (K-4) and D-32's compliance product has to produce that evidence.
+    revoked_at TEXT,
     PRIMARY KEY (subject, relation, object)
   );
   CREATE TABLE IF NOT EXISTS _substrat_deliveries (
@@ -42,6 +46,36 @@ const KERNEL_DDL = `
     PRIMARY KEY (event_id, consumer_module)
   );
 `;
+/**
+ * The four migration-health columns → the contract's nullable `migrationFailure`.
+ * All-null is the healthy case (never attempted, or the last attempt succeeded and
+ * cleared them); a version present means the scope failed closed and did not serve.
+ *
+ * Returns the *unparsed* shape — `scopeSchema.parse` brands `lastAttemptAt` into an
+ * `Instant`, the same way every other row value in `mapScope` is branded on read.
+ */
+function mapMigrationFailure(r) {
+    if (!r.migration_failed_version || !r.migration_last_attempt_at)
+        return null;
+    return {
+        version: r.migration_failed_version,
+        error: r.migration_error ?? '',
+        attempts: r.migration_attempts,
+        lastAttemptAt: r.migration_last_attempt_at,
+    };
+}
+const mapHostname = (r) => hostnameBinding.parse({
+    hostname: r.hostname,
+    tenantId: r.tenant_id,
+    scopeId: r.scope_id,
+    verticalSlug: r.vertical_slug,
+    surface: r.surface,
+    region: r.region,
+    status: r.status,
+    statusNote: r.status_note,
+    canonical: r.canonical === 1,
+    createdAt: r.created_at,
+});
 export class SqliteScopeHost {
     admin;
     dir;
@@ -61,6 +95,15 @@ export class SqliteScopeHost {
     /** operation name → its owning module's entitlementKey (§4.3 gate). */
     operationEntitlement = new Map();
     roles = new Map(); // 'tenantId/roleKey'
+    /** Executor id → {eventType, handler} (K-22 §4.2). Host code, not module code. */
+    executors = new Map();
+    /**
+     * The event currently being effected by an executor, stamped onto any admin rows
+     * it writes. Ambient rather than threaded through every HostAdmin signature: it is
+     * set and cleared immediately around one `await`, and executors run sequentially,
+     * so there is no window where it belongs to a different event.
+     */
+    causedBy = null;
     systemPrincipal = principalId.parse(ulid());
     constructor(options) {
         this.dir = options.dir;
@@ -96,6 +139,80 @@ export class SqliteScopeHost {
         jurisdiction TEXT,
         status TEXT NOT NULL DEFAULT 'active',
         schema_version TEXT NOT NULL DEFAULT '0',
+        vertical_version_id TEXT,
+        -- Last FAILED migration attempt (§5.3). All null / 0 = healthy. Written on
+        -- the failure path so a scope that fails closed stops rendering as active;
+        -- cleared on the next success. See applyPendingMigrations.
+        migration_failed_version TEXT,
+        migration_error TEXT,
+        migration_attempts INTEGER NOT NULL DEFAULT 0,
+        migration_last_attempt_at TEXT,
+        created_at TEXT NOT NULL
+      );
+      -- The hostname map (K-26). A single environment-wide router resolves against
+      -- this before dispatching to the vertical's worker.
+      --
+      -- The surface column is why one hostname per scope was not enough: the shop
+      -- fronts a storefront AND a back office from one scope. The region column is
+      -- Regional Services, which Cloudflare configures per hostname — the reason
+      -- residency lives here rather than in a router deployed per jurisdiction.
+      CREATE TABLE IF NOT EXISTS hostnames (
+        hostname      TEXT PRIMARY KEY,
+        tenant_id     TEXT NOT NULL,
+        scope_id      TEXT NOT NULL,
+        vertical_slug TEXT,
+        surface       TEXT NOT NULL,
+        region        TEXT,
+        status        TEXT NOT NULL,
+        status_note   TEXT,
+        canonical     INTEGER NOT NULL DEFAULT 0,
+        created_at    TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS hostnames_scope ON hostnames (scope_id, surface);
+      -- The vertical + version registry (#31). A scope binds to a VERSION, so
+      -- dev/staging/prod are the same vertical pinned differently, and a preview
+      -- deployment is a version nothing has been promoted to yet.
+      CREATE TABLE IF NOT EXISTS verticals (
+        slug       TEXT PRIMARY KEY,
+        name       TEXT NOT NULL,
+        source     TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+      -- admission: 'pending' until the gates pass. A push is not a deploy, and
+      -- bind_scope_version refuses anything not admitted -- which is what makes
+      -- that sentence structural rather than a convention.
+      CREATE TABLE IF NOT EXISTS vertical_versions (
+        id                TEXT PRIMARY KEY,
+        vertical_slug     TEXT NOT NULL,
+        version           TEXT NOT NULL,
+        manifest_digest   TEXT NOT NULL,
+        permission_digest TEXT NOT NULL,
+        migration_digest  TEXT NOT NULL,
+        deployment_ref    TEXT,
+        admission         TEXT NOT NULL,
+        admission_note    TEXT,
+        created_at        TEXT NOT NULL,
+        UNIQUE (vertical_slug, version)
+      );
+      -- Channels (#31 step 2): a named pointer per vertical. Promotion moves it,
+      -- and promotion is where the migration and permission diffs fire — the
+      -- moment a change reaches anyone, rather than the moment it was typed.
+      CREATE TABLE IF NOT EXISTS vertical_channels (
+        vertical_slug TEXT NOT NULL,
+        channel       TEXT NOT NULL,
+        version_id    TEXT NOT NULL,
+        updated_at    TEXT NOT NULL,
+        PRIMARY KEY (vertical_slug, channel)
+      );
+      -- Organizations inside a tenant (K-22). Membership tuples point at these and
+      -- grantToOrg targets them. Before this the id was a free-form string with no
+      -- record, so a typo addressed a phantom org. The tenant_id column is also
+      -- kernel-design §4.3's required orgId <-> tenantId join.
+      CREATE TABLE IF NOT EXISTS orgs (
+        org_id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        slug TEXT NOT NULL,
+        name TEXT NOT NULL,
         created_at TEXT NOT NULL
       );
       CREATE TABLE IF NOT EXISTS _substrat_tenant_tuples (
@@ -104,6 +221,9 @@ export class SqliteScopeHost {
         relation TEXT NOT NULL,
         object TEXT NOT NULL,
         expires_at TEXT,
+        -- K-21: see the note on _substrat_tuples. Membership lives here, so this
+        -- is the column removeMember writes.
+        revoked_at TEXT,
         PRIMARY KEY (tenant_id, subject, relation, object)
       );
       CREATE TABLE IF NOT EXISTS _substrat_roles (
@@ -125,6 +245,16 @@ export class SqliteScopeHost {
       -- principal + home node. Provider-keyed so Better Auth, an OIDC issuer, or
       -- several at once coexist. Authentication input only — authorization stays
       -- in the tuples above.
+      -- Registered identity pools (K-23). A provider declares its topology before it
+      -- may link, so the directory knows whether the same externalId in two tenants is
+      -- one human (central) or two (tenant-bound). tenant_id is non-null exactly when
+      -- tenant-bound.
+      CREATE TABLE IF NOT EXISTS _substrat_identity_pools (
+        provider   TEXT PRIMARY KEY,
+        topology   TEXT NOT NULL,
+        tenant_id  TEXT,
+        created_at TEXT NOT NULL
+      );
       CREATE TABLE IF NOT EXISTS _substrat_identities (
         provider     TEXT NOT NULL,
         external_id  TEXT NOT NULL,
@@ -132,20 +262,50 @@ export class SqliteScopeHost {
         tenant_id    TEXT NOT NULL,
         scope_id     TEXT,
         created_at   TEXT NOT NULL,
-        PRIMARY KEY (provider, external_id)
+        PRIMARY KEY (tenant_id, provider, external_id)
       );
       -- Append-only control-plane audit trail (control-plane.md §4.4). Lives in
       -- the directory, not a scope DB: it records cross-tenant staff actions and
       -- is stamped host-side. Never UPDATEd, never DELETEd.
+      -- Staff READS (K-24). Separate from the admin log because they are two
+      -- things: a mutation is permanent evidence, a read is operational history.
+      -- One table would force one retention policy on both, the stricter would
+      -- win, and read noise would bury the mutation rows an auditor came for.
+      --
+      -- drained_at marks a row shipped to Tier 2. ONLY drained rows may be
+      -- pruned: expiring on age alone would destroy evidence while calling
+      -- itself retention. Until that sink exists nothing drains, so nothing
+      -- prunes and the window is unbounded — a stated limitation, not a policy.
+      CREATE TABLE IF NOT EXISTS _substrat_access_log (
+        id           TEXT PRIMARY KEY,
+        actor        TEXT NOT NULL,
+        method       TEXT NOT NULL,
+        tenant_id    TEXT,
+        scope_id     TEXT,
+        params       TEXT,
+        -- What separates navigation from an incident: "called listScopes" against
+        -- "enumerated 4,000 tenants". A log that cannot tell them apart is a log
+        -- nobody reads.
+        result_count INTEGER NOT NULL,
+        drained_at   TEXT,
+        at           TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS _substrat_access_log_actor ON _substrat_access_log (actor, id);
+      CREATE INDEX IF NOT EXISTS _substrat_access_log_tenant ON _substrat_access_log (tenant_id, id);
       CREATE TABLE IF NOT EXISTS _substrat_admin_log (
         id TEXT PRIMARY KEY,
         actor TEXT NOT NULL,
         action TEXT NOT NULL,
-        tenant_id TEXT NOT NULL,
+        -- Nullable: a platform-level action targets no tenant (K-23).
+        tenant_id TEXT,
         scope_id TEXT,
         vertical TEXT,
         before TEXT,
         after TEXT,
+        -- The event that caused this action, when one did (K-22 §4.2). This is
+        -- what joins the connector seam's two halves: the module's emit and the
+        -- executor's effect. Null for a staff member acting directly.
+        caused_by TEXT,
         at TEXT NOT NULL
       );
       -- Read-path indexes for the console (control-plane.md §4.5). The admin log
@@ -169,6 +329,11 @@ export class SqliteScopeHost {
                 });
         this.admin = this.buildAdmin();
     }
+    registerExecutor(id, eventType, handler) {
+        if (this.executors.has(id))
+            throw new Error(`executor '${id}' is already registered`);
+        this.executors.set(id, { eventType, handler });
+    }
     registerModule(registration) {
         const manifest = moduleManifest.parse(registration.manifest);
         if (this.modules.has(manifest.id)) {
@@ -353,8 +518,12 @@ export class SqliteScopeHost {
                         rt.db.exec('ROLLBACK');
                         throw err;
                     }
-                    // Post-commit, still inside the actor task: drain outbox → consumers.
+                    // Post-commit, still inside the actor task: drain outbox → consumers,
+                    // then → executors. Prompt dispatch (K-22 §4.2): the common case
+                    // completes inside this request, with the outbox as the retry backstop
+                    // if it does not.
                     await this.dispatch(rt);
+                    await this.dispatchExecutors(rt);
                     return structuredClone(result);
                 });
             },
@@ -393,6 +562,47 @@ export class SqliteScopeHost {
     // Event dispatch (testrun spec §9.2.3): at-least-once, kernel-journaled,
     // consumers run as system-actor operations in their own transactions.
     // -------------------------------------------------------------------------
+    /**
+     * Run executors over this scope's outbox (K-22 §4.2) — the connector half of the
+     * seam. Same at-least-once journal as consumers, keyed on a distinct delivery id
+     * so an executor and a module consumer on the same event do not shadow each other.
+     *
+     * Runs OUTSIDE the scope's transaction, and deliberately so: the executor acts on
+     * the directory, which is not part of the scope's serialization domain. The
+     * atomicity that matters already happened — the event only exists because the
+     * emitting transaction committed.
+     *
+     * A throwing executor leaves the delivery unjournaled, so it is retried on the
+     * next dispatch. That is the backstop; it is not a substitute for idempotent
+     * handlers, which at-least-once still requires.
+     */
+    async dispatchExecutors(rt) {
+        for (const [id, executor] of this.executors) {
+            const deliveryId = `executor:${id}`;
+            const rows = rt.db
+                .prepare(`SELECT * FROM _substrat_outbox o
+           WHERE o.type = ?
+             AND NOT EXISTS (
+               SELECT 1 FROM _substrat_deliveries d
+               WHERE d.event_id = o.id AND d.consumer_module = ?
+             )
+           ORDER BY o.id`)
+                .all(executor.eventType, deliveryId);
+            for (const row of rows) {
+                const event = this.parseOutboxRow(row);
+                this.causedBy = event.id;
+                try {
+                    await executor.handler(this.admin, event);
+                }
+                finally {
+                    this.causedBy = null;
+                }
+                rt.db
+                    .prepare('INSERT OR IGNORE INTO _substrat_deliveries (event_id, consumer_module, delivered_at) VALUES (?, ?, ?)')
+                    .run(row.id, deliveryId, new Date().toISOString());
+            }
+        }
+    }
     async dispatch(rt) {
         for (let round = 0; round < 50; round++) {
             let deliveredAny = false;
@@ -463,12 +673,27 @@ export class SqliteScopeHost {
      * remembering a call per method. `before` is captured only where cheaply
      * readable; idempotent upserts with no cheap prior state pass `before: null`.
      */
+    /**
+     * Record a staff read (K-24). Called by every read on `HostAdmin`, which is why
+     * they all take an actor: a read the log cannot attribute is unrepresentable.
+     *
+     * `params` is a bounded summary, not the raw filter — enough to know what was
+     * asked, capped so one query cannot write an unbounded row.
+     */
+    recordAccess(actor, method, target, params, resultCount) {
+        const summary = params == null ? null : JSON.stringify(params).slice(0, 500);
+        this.directory
+            .prepare(`INSERT INTO _substrat_access_log
+           (id, actor, method, tenant_id, scope_id, params, result_count, drained_at, at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?)`)
+            .run(ulid(), actor, method, target.tenantId ?? null, target.scopeId ?? null, summary, resultCount, new Date().toISOString());
+    }
     recordAdmin(actor, action, target, before, after) {
         this.directory
             .prepare(`INSERT INTO _substrat_admin_log
-           (id, actor, action, tenant_id, scope_id, vertical, before, after, at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(ulid(), actor, action, target.tenantId, target.scopeId ?? null, target.vertical ?? null, before == null ? null : JSON.stringify(before), after == null ? null : JSON.stringify(after), new Date().toISOString());
+           (id, actor, action, tenant_id, scope_id, vertical, before, after, caused_by, at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(ulid(), actor, action, target.tenantId ?? null, target.scopeId ?? null, target.vertical ?? null, before == null ? null : JSON.stringify(before), after == null ? null : JSON.stringify(after), this.causedBy, new Date().toISOString());
     }
     tenantHoldsEntitlement(tenantId, key) {
         return (this.directory
@@ -487,6 +712,88 @@ export class SqliteScopeHost {
             const r = this.directory.prepare('SELECT * FROM tenants WHERE tenant_id = ?').get(id);
             return r ? mapTenant(r) : undefined;
         };
+        const readPool = (provider) => {
+            const r = this.directory
+                .prepare('SELECT provider, topology, tenant_id FROM _substrat_identity_pools WHERE provider = ?')
+                .get(provider);
+            return r
+                ? identityPool.parse({ provider: r.provider, topology: r.topology, tenantId: r.tenant_id })
+                : undefined;
+        };
+        /**
+         * A pool must be registered before it may link, and a tenant-bound pool may only
+         * link into its own tenant. Resolution needs no equivalent check — K-22's
+         * (tenantId, provider, externalId) key already scopes reads — so this is the one
+         * place the topology is established rather than merely assumed.
+         */
+        const requirePoolServes = (provider, tenant) => {
+            const pool = readPool(provider);
+            if (!pool) {
+                throw new Error(`identity pool '${provider}' is not registered — a pool must declare its ` +
+                    `topology before it may link (central vs tenant-bound decides whether the ` +
+                    `same externalId in two tenants is one person or two)`);
+            }
+            if (pool.topology === 'tenant-bound' && pool.tenantId !== tenant) {
+                throw new Error(`identity pool '${provider}' is bound to tenant ${pool.tenantId} and cannot link into ${tenant}`);
+            }
+        };
+        const mapVertical = (r) => verticalSchema.parse({
+            slug: r.slug,
+            name: r.name,
+            source: r.source,
+            createdAt: r.created_at,
+        });
+        const readVertical = (slugValue) => {
+            const r = this.directory
+                .prepare('SELECT * FROM verticals WHERE slug = ?')
+                .get(slugValue);
+            return r ? mapVertical(r) : undefined;
+        };
+        const mapVersion = (r) => verticalVersion.parse({
+            id: r.id,
+            verticalSlug: r.vertical_slug,
+            version: r.version,
+            manifestDigest: r.manifest_digest,
+            permissionDigest: r.permission_digest,
+            migrationDigest: r.migration_digest,
+            deploymentRef: r.deployment_ref,
+            admission: r.admission,
+            admissionNote: r.admission_note,
+            createdAt: r.created_at,
+        });
+        const readVersion = (id) => {
+            const r = this.directory
+                .prepare('SELECT * FROM vertical_versions WHERE id = ?')
+                .get(id);
+            return r ? mapVersion(r) : undefined;
+        };
+        const mapOrg = (r) => orgSchema.parse({
+            id: r.org_id,
+            tenantId: r.tenant_id,
+            slug: r.slug,
+            name: r.name,
+            createdAt: r.created_at,
+        });
+        // Scoped by tenant, not just by id: an org id from another tenant must read as
+        // absent here, or `grantToOrg` would reach across the boundary the record exists
+        // to make explicit.
+        const readOrg = (tenant, id) => {
+            const r = this.directory
+                .prepare('SELECT * FROM orgs WHERE tenant_id = ? AND org_id = ?')
+                .get(tenant, id);
+            return r ? mapOrg(r) : undefined;
+        };
+        /**
+         * Fail closed on an org that does not exist in this tenant. This is what the
+         * record buys: before it, membership and grants accepted any string, so a typo
+         * produced a tuple pointing at a phantom that silently granted nothing and
+         * appeared in no listing.
+         */
+        const requireOrg = (tenant, id) => {
+            if (!readOrg(tenant, id)) {
+                throw new Error(`unknown org ${id} in tenant ${tenant}`);
+            }
+        };
         // The directory row → the `scope` contract. Parsed, not cast: the columns are
         // nullable in SQLite (ALTER TABLE cannot add NOT NULL to a populated table)
         // while the contract requires them, so this parse is where that gap is held
@@ -504,6 +811,8 @@ export class SqliteScopeHost {
             jurisdiction: r.jurisdiction,
             vertical: r.vertical,
             schemaVersion: r.schema_version,
+            verticalVersionId: r.vertical_version_id,
+            migrationFailure: mapMigrationFailure(r),
             createdAt: r.created_at,
         });
         // Scope lifecycle transition (control-plane.md §4.2): validate ownership,
@@ -564,7 +873,7 @@ export class SqliteScopeHost {
                 this.roles.set(`${tenantId}/${parsed.key}`, parsed);
                 this.recordAdmin(actor, 'defineRole', { tenantId }, before, parsed);
             },
-            listRoles: async (filter) => {
+            listRoles: async (actor, filter) => {
                 const where = [];
                 const params = [];
                 if (filter?.tenantId) {
@@ -582,6 +891,7 @@ export class SqliteScopeHost {
                 // Parsed, not cast: `permissions` is a JSON blob in a TEXT column, so the
                 // contract is the only thing standing between a corrupted row and the
                 // console rendering a role with permissions nobody declared.
+                this.recordAccess(actor, 'listRoles', { tenantId: filter?.tenantId ?? null }, filter, rows.length);
                 return rows.map((r) => tenantRole.parse({
                     tenantId: r.tenant_id,
                     key: r.role_key,
@@ -604,13 +914,316 @@ export class SqliteScopeHost {
                 this.recordAdmin(actor, 'grant', { tenantId: grant.node.tenantId, scopeId: grant.node.scopeId }, null, grant);
             },
             grantToOrg: async (actor, orgId, permission, node, entity) => {
+                // The org must exist in the node's tenant. A grant to a phantom org is
+                // worse than an error: it looks applied, resolves for nobody, and shows up
+                // in the permission diff as though access were conferred.
+                requireOrg(node.tenantId, orgId);
                 writeGrant(`org:${orgId}`, permission, node, entity);
                 this.recordAdmin(actor, 'grantToOrg', { tenantId: node.tenantId, scopeId: node.scopeId }, null, { orgId, permission, node, entity });
             },
+            // -- vertical + version registry (#31) ---------------------------------
+            // -- the hostname map (K-26) -------------------------------------------
+            bindHostname: async (actor, input) => {
+                const parsed = bindHostnameInput.parse(input);
+                const scope = this.directory
+                    .prepare('SELECT tenant_id, vertical FROM scopes WHERE scope_id = ?')
+                    .get(parsed.scopeId);
+                if (!scope || scope.tenant_id !== parsed.tenantId) {
+                    throw new Error(`unknown scope ${parsed.scopeId} in tenant ${parsed.tenantId}`);
+                }
+                const existing = this.directory
+                    .prepare('SELECT scope_id FROM hostnames WHERE hostname = ?')
+                    .get(parsed.hostname);
+                if (existing && existing.scope_id !== parsed.scopeId) {
+                    // A hostname is globally unique and routes to exactly one place. Silently
+                    // rebinding it would move another tenant's traffic.
+                    throw new Error(`hostname '${parsed.hostname}' is already bound to another scope`);
+                }
+                // Exactly one canonical per (scope, surface): "which one do certs and
+                // redirects use" has to have one answer, so a new canonical demotes the old.
+                if (parsed.canonical) {
+                    this.directory
+                        .prepare('UPDATE hostnames SET canonical = 0 WHERE scope_id = ? AND surface = ?')
+                        .run(parsed.scopeId, parsed.surface);
+                }
+                this.directory
+                    .prepare(`INSERT OR REPLACE INTO hostnames
+               (hostname, tenant_id, scope_id, vertical_slug, surface, region,
+                status, status_note, canonical, created_at)
+             VALUES (?, ?, ?, ?, ?, ?, 'pending', NULL, ?, ?)`)
+                    .run(parsed.hostname, parsed.tenantId, parsed.scopeId, scope.vertical, parsed.surface, parsed.region, parsed.canonical ? 1 : 0, new Date().toISOString());
+                this.recordAdmin(actor, 'bindHostname', { tenantId: parsed.tenantId, scopeId: parsed.scopeId, vertical: scope.vertical }, null, parsed);
+            },
+            setHostnameStatus: async (actor, raw, status, note) => {
+                const hostname = raw.toLowerCase(); // DNS is case-insensitive; the map is normalized
+                const row = this.directory
+                    .prepare('SELECT tenant_id, scope_id, status FROM hostnames WHERE hostname = ?')
+                    .get(hostname);
+                if (!row)
+                    throw new Error(`unknown hostname '${hostname}'`);
+                if (row.status === status)
+                    return; // idempotent, and a no-op is not audited
+                this.directory
+                    .prepare('UPDATE hostnames SET status = ?, status_note = ? WHERE hostname = ?')
+                    .run(status, note ?? null, hostname);
+                this.recordAdmin(actor, 'setHostnameStatus', { tenantId: row.tenant_id, scopeId: row.scope_id }, { status: row.status }, { status, note: note ?? null });
+            },
+            listHostnames: async (actor, filter) => {
+                const where = [];
+                const params = [];
+                if (filter?.tenantId) {
+                    where.push('tenant_id = ?');
+                    params.push(filter.tenantId);
+                }
+                if (filter?.scopeId) {
+                    where.push('scope_id = ?');
+                    params.push(filter.scopeId);
+                }
+                let sql = 'SELECT * FROM hostnames';
+                if (where.length)
+                    sql += ` WHERE ${where.join(' AND ')}`;
+                sql += ' ORDER BY hostname';
+                const rows = this.directory.prepare(sql).all(...params);
+                this.recordAccess(actor, 'listHostnames', { tenantId: filter?.tenantId ?? null, scopeId: filter?.scopeId ?? null }, filter, rows.length);
+                return rows.map(mapHostname);
+            },
+            resolveHostname: async (raw) => {
+                // The router's per-request read. No actor, not logged — same carve-out as
+                // resolveIdentity (K-24): this is a machine path, not a staff read.
+                const hostname = raw.toLowerCase();
+                const r = this.directory
+                    .prepare(`SELECT tenant_id, scope_id, vertical_slug, surface, region
+             FROM hostnames WHERE hostname = ? AND status = 'active'`)
+                    .get(hostname);
+                if (!r)
+                    return undefined;
+                return routeTarget.parse({
+                    tenantId: r.tenant_id,
+                    scopeId: r.scope_id,
+                    verticalSlug: r.vertical_slug,
+                    surface: r.surface,
+                    region: r.region,
+                });
+            },
+            registerVertical: async (actor, input) => {
+                const parsed = registerVerticalInput.parse(input);
+                const existing = readVertical(parsed.slug);
+                if (existing) {
+                    // Idempotent on an identical registration. A conflicting one throws:
+                    // changing a vertical's source silently rebinds what every scope on it
+                    // is understood to be running.
+                    if (existing.source === parsed.source && existing.name === parsed.name)
+                        return;
+                    throw new Error(`vertical '${parsed.slug}' is already registered as ${existing.source}`);
+                }
+                this.directory
+                    .prepare('INSERT INTO verticals (slug, name, source, created_at) VALUES (?, ?, ?, ?)')
+                    .run(parsed.slug, parsed.name, parsed.source, new Date().toISOString());
+                this.recordAdmin(actor, 'registerVertical', { tenantId: null }, null, parsed);
+            },
+            listVerticals: async (actor) => {
+                const rows = this.directory
+                    .prepare('SELECT * FROM verticals ORDER BY slug')
+                    .all();
+                this.recordAccess(actor, 'listVerticals', {}, null, rows.length);
+                return rows.map(mapVertical);
+            },
+            publishVersion: async (actor, input) => {
+                const parsed = publishVersionInput.parse(input);
+                if (!readVertical(parsed.verticalSlug)) {
+                    throw new Error(`unknown vertical '${parsed.verticalSlug}'`);
+                }
+                // Lands PENDING. A push is not a deploy — the gates decide, and binding a
+                // scope is a separate, reviewable step.
+                this.directory
+                    .prepare(`INSERT INTO vertical_versions
+               (id, vertical_slug, version, manifest_digest, permission_digest,
+                migration_digest, deployment_ref, admission, admission_note, created_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', NULL, ?)`)
+                    .run(parsed.id, parsed.verticalSlug, parsed.version, parsed.manifestDigest, parsed.permissionDigest, parsed.migrationDigest, parsed.deploymentRef, new Date().toISOString());
+                this.recordAdmin(actor, 'publishVersion', { tenantId: null }, null, parsed);
+            },
+            listVersions: async (actor, verticalSlug) => {
+                const rows = this.directory
+                    .prepare('SELECT * FROM vertical_versions WHERE vertical_slug = ? ORDER BY id')
+                    .all(verticalSlug);
+                this.recordAccess(actor, 'listVersions', {}, { verticalSlug }, rows.length);
+                return rows.map(mapVersion);
+            },
+            admitVersion: async (actor, versionId) => {
+                const v = readVersion(versionId);
+                if (!v)
+                    throw new Error(`unknown version ${versionId}`);
+                if (v.admission === 'admitted')
+                    return; // idempotent
+                if (v.admission === 'rejected') {
+                    throw new Error(`version ${versionId} was rejected — publish a new one`);
+                }
+                this.directory
+                    .prepare("UPDATE vertical_versions SET admission = 'admitted' WHERE id = ?")
+                    .run(versionId);
+                this.recordAdmin(actor, 'admitVersion', { tenantId: null }, { admission: v.admission }, {
+                    admission: 'admitted',
+                });
+            },
+            rejectVersion: async (actor, versionId, note) => {
+                const v = readVersion(versionId);
+                if (!v)
+                    throw new Error(`unknown version ${versionId}`);
+                if (v.admission === 'admitted') {
+                    throw new Error(`version ${versionId} is already admitted — it may be bound`);
+                }
+                if (v.admission === 'rejected')
+                    return; // idempotent
+                this.directory
+                    .prepare("UPDATE vertical_versions SET admission = 'rejected', admission_note = ? WHERE id = ?")
+                    .run(note, versionId);
+                this.recordAdmin(actor, 'rejectVersion', { tenantId: null }, { admission: v.admission }, {
+                    admission: 'rejected',
+                    note,
+                });
+            },
+            promoteVersion: async (actor, verticalSlug, channel, versionId, acknowledge) => {
+                const incoming = readVersion(versionId);
+                if (!incoming)
+                    throw new Error(`unknown version ${versionId}`);
+                if (incoming.verticalSlug !== verticalSlug) {
+                    throw new Error(`version ${versionId} belongs to '${incoming.verticalSlug}'`);
+                }
+                if (incoming.admission !== 'admitted') {
+                    throw new Error(`version ${versionId} is ${incoming.admission}, not admitted — it cannot be promoted`);
+                }
+                const current = this.directory
+                    .prepare('SELECT version_id FROM vertical_channels WHERE vertical_slug = ? AND channel = ?')
+                    .get(verticalSlug, channel);
+                const outgoing = current ? readVersion(current.version_id) : undefined;
+                const ack = promotionAcknowledgement.parse(acknowledge ?? {});
+                // §4's two checkpoints, fired where the blast radius is. A FIRST promotion
+                // has nothing to diff against, so there is nothing to acknowledge — the
+                // gate is about change, not about existence.
+                if (outgoing) {
+                    if (outgoing.permissionDigest !== incoming.permissionDigest && !ack.permissionChange) {
+                        throw new Error(`promotion changes the permission surface (${outgoing.permissionDigest} → ` +
+                            `${incoming.permissionDigest}) — acknowledge it explicitly to promote`);
+                    }
+                    if (outgoing.migrationDigest !== incoming.migrationDigest && !ack.migrationChange) {
+                        throw new Error(`promotion changes migrations (${outgoing.migrationDigest} → ` +
+                            `${incoming.migrationDigest}) — acknowledge it explicitly to promote`);
+                    }
+                }
+                this.directory
+                    .prepare(`INSERT INTO vertical_channels (vertical_slug, channel, version_id, updated_at)
+             VALUES (?, ?, ?, ?)
+             ON CONFLICT (vertical_slug, channel) DO UPDATE SET version_id = ?, updated_at = ?`)
+                    .run(verticalSlug, channel, versionId, new Date().toISOString(), versionId, new Date().toISOString());
+                // The acknowledgement is recorded, not just enforced: that is what turns
+                // "someone reviewed the permission change" into evidence.
+                this.recordAdmin(actor, 'promoteVersion', { tenantId: null, vertical: verticalSlug }, outgoing ? { versionId: outgoing.id, version: outgoing.version } : null, { channel, versionId, version: incoming.version, acknowledged: ack });
+            },
+            listChannels: async (actor, verticalSlug) => {
+                const rows = this.directory
+                    .prepare('SELECT * FROM vertical_channels WHERE vertical_slug = ? ORDER BY channel')
+                    .all(verticalSlug);
+                this.recordAccess(actor, 'listChannels', {}, { verticalSlug }, rows.length);
+                return rows.map((r) => verticalChannel.parse({
+                    verticalSlug: r.vertical_slug,
+                    channel: r.channel,
+                    versionId: r.version_id,
+                    updatedAt: r.updated_at,
+                }));
+            },
+            bindScopeVersion: async (actor, tenantId, scopeId, versionId) => {
+                const v = readVersion(versionId);
+                if (!v)
+                    throw new Error(`unknown version ${versionId}`);
+                // The refusal this registry exists for. Without it, "a push lands pending"
+                // is a convention, and D-30's argument is that we cannot afford conventions
+                // where lockstep upgrades are the failure mode.
+                if (v.admission !== 'admitted') {
+                    throw new Error(`version ${versionId} is ${v.admission}, not admitted — it cannot be bound to a scope`);
+                }
+                const scope = this.directory
+                    .prepare('SELECT tenant_id FROM scopes WHERE scope_id = ?')
+                    .get(scopeId);
+                if (!scope || scope.tenant_id !== tenantId) {
+                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                }
+                this.directory
+                    .prepare('UPDATE scopes SET vertical_version_id = ?, vertical = ? WHERE scope_id = ?')
+                    .run(versionId, v.verticalSlug, scopeId);
+                this.recordAdmin(actor, 'bindScopeVersion', { tenantId, scopeId }, null, {
+                    versionId,
+                    vertical: v.verticalSlug,
+                    version: v.version,
+                });
+            },
+            createOrg: async (actor, input) => {
+                const parsed = createOrgInput.parse(input);
+                if (readOrg(parsed.tenantId, parsed.id))
+                    return; // idempotent, unaudited
+                // Checked explicitly rather than left to the UNIQUE index: OR IGNORE would
+                // swallow a collision from a DIFFERENT id and report success, silently not
+                // creating the org the caller asked for. Fail closed instead (as createTenant).
+                const slugOwner = this.directory
+                    .prepare('SELECT org_id FROM orgs WHERE tenant_id = ? AND slug = ?')
+                    .get(parsed.tenantId, parsed.slug);
+                if (slugOwner) {
+                    throw new Error(`org slug '${parsed.slug}' already taken by ${slugOwner.org_id} (slugs are unique per tenant)`);
+                }
+                this.directory
+                    .prepare('INSERT INTO orgs (org_id, tenant_id, slug, name, created_at) VALUES (?, ?, ?, ?, ?)')
+                    .run(parsed.id, parsed.tenantId, parsed.slug, parsed.name, new Date().toISOString());
+                this.recordAdmin(actor, 'createOrg', { tenantId: parsed.tenantId }, null, parsed);
+            },
+            listOrgs: async (actor, tenantId) => {
+                const rows = this.directory
+                    .prepare('SELECT * FROM orgs WHERE tenant_id = ? ORDER BY slug')
+                    .all(tenantId).map(mapOrg);
+                this.recordAccess(actor, 'listOrgs', { tenantId }, null, rows.length);
+                return rows;
+            },
+            getOrg: async (actor, tenantId, orgId) => {
+                const o = readOrg(tenantId, orgId);
+                this.recordAccess(actor, 'getOrg', { tenantId }, { orgId }, o ? 1 : 0);
+                return o;
+            },
             addMember: async (actor, tenantId, principal, orgId) => {
+                requireOrg(tenantId, orgId);
+                // INSERT OR REPLACE, so re-adding a revoked member clears the tombstone —
+                // they are a member again. The add/revoke history is not lost: it lives in
+                // the append-only admin log, which is where "what happened" belongs. The
+                // tuple carries "what is true now" plus enough to explain a live proof.
                 writeTenantTuple(tenantId, `principal:${principal}`, 'member', `org:${orgId}`);
                 this.recordAdmin(actor, 'addMember', { tenantId }, null, { principal, orgId });
             },
+            removeMember: async (actor, tenantId, principal, orgId) => {
+                requireOrg(tenantId, orgId);
+                // Tombstone (K-21), never DELETE. Guarded on `revoked_at IS NULL` so a
+                // repeat revoke neither moves the timestamp nor writes a second audit row.
+                const info = this.directory
+                    .prepare(`UPDATE _substrat_tenant_tuples SET revoked_at = ?
+             WHERE tenant_id = ? AND subject = ? AND relation = 'member' AND object = ?
+               AND revoked_at IS NULL`)
+                    .run(new Date().toISOString(), tenantId, `principal:${principal}`, `org:${orgId}`);
+                if (info.changes === 0)
+                    return; // never a member, or already revoked
+                this.recordAdmin(actor, 'removeMember', { tenantId }, { principal, orgId }, null);
+            },
+            listMembers: async (actor, tenantId, orgId, options) => {
+                requireOrg(tenantId, orgId);
+                const rows = this.directory
+                    .prepare(`SELECT subject, revoked_at FROM _substrat_tenant_tuples
+             WHERE tenant_id = ? AND relation = 'member' AND object = ?
+             ${options?.includeRevoked ? '' : 'AND revoked_at IS NULL'}
+             ORDER BY subject`)
+                    .all(tenantId, `org:${orgId}`);
+                this.recordAccess(actor, 'listMembers', { tenantId }, { orgId, ...options }, rows.length);
+                return rows.map((r) => orgMembership.parse({
+                    principal: r.subject.slice('principal:'.length),
+                    orgId,
+                    revokedAt: r.revoked_at,
+                }));
+            },
             createTenant: async (actor, input) => {
                 const parsed = createTenantInput.parse(input);
                 // Idempotent: re-creating an existing tenant is a no-op, and a no-op is
@@ -642,9 +1255,18 @@ export class SqliteScopeHost {
                     .run(status, tenantId);
                 this.recordAdmin(actor, 'setTenantStatus', { tenantId }, { status: before.status }, { status });
             },
-            listTenants: async () => this.directory.prepare('SELECT * FROM tenants ORDER BY tenant_id').all().map(mapTenant),
-            getTenant: async (tenantId) => readTenant(tenantId),
-            listScopes: async (filter) => {
+            listTenants: async (actor) => {
+                const rows = this.directory.prepare('SELECT * FROM tenants ORDER BY tenant_id').all().map(mapTenant);
+                // Enumerating every tenant on the platform is the read this log exists for.
+                this.recordAccess(actor, 'listTenants', {}, null, rows.length);
+                return rows;
+            },
+            getTenant: async (actor, tenantId) => {
+                const t = readTenant(tenantId);
+                this.recordAccess(actor, 'getTenant', { tenantId }, null, t ? 1 : 0);
+                return t;
+            },
+            listScopes: async (actor, filter) => {
                 const where = [];
                 const params = [];
                 if (filter?.tenantId) {
@@ -667,13 +1289,17 @@ export class SqliteScopeHost {
                 const sql = 'SELECT * FROM scopes' +
                     (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
                     ' ORDER BY scope_id';
-                return this.directory.prepare(sql).all(...params).map(mapScope);
+                const scopes = this.directory.prepare(sql).all(...params).map(mapScope);
+                this.recordAccess(actor, 'listScopes', { tenantId: filter?.tenantId ?? null }, filter, scopes.length);
+                return scopes;
             },
-            getScopeRecord: async (tenantId, scopeId) => {
+            getScopeRecord: async (actor, tenantId, scopeId) => {
                 const r = this.directory.prepare('SELECT * FROM scopes WHERE scope_id = ?').get(scopeId);
                 // Cross-check the pair (K-3): a scope that exists under a DIFFERENT tenant
                 // reads as absent, never as itself. Same rule as getScope's stub mint.
-                if (!r || r.tenant_id !== tenantId)
+                const found = r && r.tenant_id === tenantId;
+                this.recordAccess(actor, 'getScopeRecord', { tenantId, scopeId }, null, found ? 1 : 0);
+                if (!found)
                     return undefined;
                 return mapScope(r);
             },
@@ -699,35 +1325,139 @@ export class SqliteScopeHost {
                     return; // nothing held, nothing changed
                 this.recordAdmin(actor, 'revokeEntitlement', { tenantId }, { entitlementKey }, null);
             },
-            listEntitlements: async (tenantId) => this.directory
-                .prepare('SELECT entitlement_key FROM _substrat_entitlements WHERE tenant_id = ? ORDER BY entitlement_key')
-                .all(tenantId).map((r) => r.entitlement_key),
+            listEntitlements: async (actor, tenantId) => {
+                const keys = this.directory
+                    .prepare('SELECT entitlement_key FROM _substrat_entitlements WHERE tenant_id = ? ORDER BY entitlement_key')
+                    .all(tenantId).map((r) => r.entitlement_key);
+                this.recordAccess(actor, 'listEntitlements', { tenantId }, null, keys.length);
+                return keys;
+            },
+            registerIdentityPool: async (actor, input) => {
+                const parsed = identityPool.parse(input);
+                const existing = readPool(parsed.provider);
+                if (existing) {
+                    // Idempotent on an identical registration. A CONFLICTING one throws:
+                    // flipping a live pool's topology silently reinterprets every row it owns
+                    // — the same externalId across tenants would change from one human to two.
+                    if (existing.topology === parsed.topology && existing.tenantId === parsed.tenantId) {
+                        return;
+                    }
+                    throw new Error(`identity pool '${parsed.provider}' is already registered as ${existing.topology}` +
+                        `${existing.tenantId ? ` for tenant ${existing.tenantId}` : ''}`);
+                }
+                this.directory
+                    .prepare('INSERT INTO _substrat_identity_pools (provider, topology, tenant_id, created_at) VALUES (?, ?, ?, ?)')
+                    .run(parsed.provider, parsed.topology, parsed.tenantId, new Date().toISOString());
+                this.recordAdmin(actor, 'registerIdentityPool', 
+                // Null for a central pool: it belongs to no single tenant, which is what
+                // made the admin log's tenantId nullable.
+                { tenantId: parsed.tenantId }, null, parsed);
+            },
+            getIdentityPool: async (actor, provider) => {
+                const pool = readPool(provider);
+                this.recordAccess(actor, 'getIdentityPool', {}, { provider }, pool ? 1 : 0);
+                return pool;
+            },
+            listIdentityTenants: async (actor, provider, externalId) => {
+                const pool = readPool(provider);
+                if (!pool)
+                    throw new Error(`identity pool '${provider}' is not registered`);
+                if (pool.topology !== 'central') {
+                    throw new Error(`identity pool '${provider}' is tenant-bound — enumerating tenants is only ` +
+                        `meaningful on a central pool, where the same externalId is the same person`);
+                }
+                const tenants = this.directory
+                    .prepare('SELECT tenant_id FROM _substrat_identities WHERE provider = ? AND external_id = ? ORDER BY tenant_id')
+                    .all(provider, externalId).map((r) => r.tenant_id);
+                // Which tenants a given login touches — a cross-tenant question, and one
+                // worth being able to ask who asked.
+                this.recordAccess(actor, 'listIdentityTenants', {}, { provider }, tenants.length);
+                return tenants;
+            },
             linkIdentity: async (actor, input) => {
                 const parsed = identityLink.parse(input);
-                const info = this.directory
-                    .prepare(`INSERT OR IGNORE INTO _substrat_identities
+                requirePoolServes(parsed.provider, parsed.tenantId);
+                // Read before write. `INSERT OR IGNORE` alone cannot tell "already bound to the
+                // same principal" (idempotent) from "already bound to someone else" (a
+                // collision), and silently ignoring the second resolves one person as another.
+                const existing = this.directory
+                    .prepare(`SELECT principal_id FROM _substrat_identities
+             WHERE tenant_id = ? AND provider = ? AND external_id = ?`)
+                    .get(parsed.tenantId, parsed.provider, parsed.externalId);
+                if (existing) {
+                    if (existing.principal_id === parsed.principal)
+                        return; // idempotent, unaudited
+                    throw new Error(`identity ${parsed.provider}:${parsed.externalId} in tenant ${parsed.tenantId} ` +
+                        `is already bound to ${existing.principal_id}`);
+                }
+                this.directory
+                    .prepare(`INSERT INTO _substrat_identities
                (provider, external_id, principal_id, tenant_id, scope_id, created_at)
              VALUES (?, ?, ?, ?, ?, ?)`)
                     .run(parsed.provider, parsed.externalId, parsed.principal, parsed.tenantId, parsed.scopeId ?? null, new Date().toISOString());
-                // Idempotent: an identity already bound is a no-op, and a no-op is not audited.
-                if (info.changes === 0)
-                    return;
                 this.recordAdmin(actor, 'linkIdentity', { tenantId: parsed.tenantId, scopeId: parsed.scopeId }, null, { provider: parsed.provider, externalId: parsed.externalId, principal: parsed.principal });
             },
-            resolveIdentity: async (provider, externalId) => {
+            resolveIdentity: async (tenantId, provider, externalId) => {
                 const row = this.directory
-                    .prepare(`SELECT principal_id, tenant_id, scope_id FROM _substrat_identities
-             WHERE provider = ? AND external_id = ?`)
-                    .get(provider, externalId);
+                    .prepare(`SELECT principal_id, scope_id FROM _substrat_identities
+             WHERE tenant_id = ? AND provider = ? AND external_id = ?`)
+                    .get(tenantId, provider, externalId);
                 if (!row)
                     return undefined;
-                return resolvedIdentity.parse({
-                    principal: row.principal_id,
-                    tenantId: row.tenant_id,
-                    scopeId: row.scope_id,
-                });
+                return resolvedIdentity.parse({ principal: row.principal_id, scopeId: row.scope_id });
+            },
+            accessLog: async (actor, filter) => {
+                const where = [];
+                const params = [];
+                if (filter?.actor) {
+                    where.push('actor = ?');
+                    params.push(filter.actor);
+                }
+                if (filter?.tenantId) {
+                    where.push('tenant_id = ?');
+                    params.push(filter.tenantId);
+                }
+                if (filter?.method) {
+                    where.push('method = ?');
+                    params.push(filter.method);
+                }
+                let sql = 'SELECT * FROM _substrat_access_log';
+                if (where.length)
+                    sql += ` WHERE ${where.join(' AND ')}`;
+                sql += ' ORDER BY id';
+                if (filter?.limit !== undefined) {
+                    sql += ' LIMIT ?';
+                    params.push(filter.limit);
+                }
+                const rows = this.directory.prepare(sql).all(...params);
+                // Reading the access log is itself a read. Recorded BEFORE the rows are
+                // returned, so the row describing this call is not in its own result.
+                this.recordAccess(actor, 'accessLog', { tenantId: filter?.tenantId ?? null }, filter, rows.length);
+                return rows.map((r) => accessLogEntry.parse({
+                    id: r.id,
+                    actor: r.actor,
+                    method: r.method,
+                    tenantId: r.tenant_id,
+                    scopeId: r.scope_id,
+                    params: r.params,
+                    resultCount: r.result_count,
+                    drainedAt: r.drained_at,
+                    at: r.at,
+                }));
+            },
+            pruneAccessLog: async (actor, limit) => {
+                // ONLY drained rows. Age alone is not a licence to delete evidence.
+                const info = this.directory
+                    .prepare(`DELETE FROM _substrat_access_log WHERE id IN (
+               SELECT id FROM _substrat_access_log WHERE drained_at IS NOT NULL ORDER BY id LIMIT ?
+             )`)
+                    .run(limit);
+                if (info.changes > 0) {
+                    this.recordAdmin(actor, 'pruneAccessLog', { tenantId: null }, { pruned: info.changes }, null);
+                }
+                return info.changes;
             },
-            auditLog: async (filter) => {
+            auditLog: async (actor, filter) => {
                 const where = [];
                 const params = [];
                 if (filter?.tenantId) {
@@ -772,6 +1502,9 @@ export class SqliteScopeHost {
                     params.push(filter.limit);
                 }
                 const rows = this.directory.prepare(sql).all(...params);
+                // Reading the audit trail is itself audited. Who examined the record of
+                // who did what is exactly the question an incident asks second.
+                this.recordAccess(actor, 'auditLog', { tenantId: filter?.tenantId ?? null, scopeId: filter?.scopeId ?? null }, filter, rows.length);
                 return rows.map((r) => adminLogEntry.parse({
                     id: r.id,
                     actor: r.actor,
@@ -781,6 +1514,7 @@ export class SqliteScopeHost {
                     vertical: r.vertical,
                     before: r.before === null ? null : JSON.parse(r.before),
                     after: r.after === null ? null : JSON.parse(r.after),
+                    causedBy: r.caused_by,
                     at: r.at,
                 }));
             },
@@ -796,7 +1530,92 @@ export class SqliteScopeHost {
      * within tenant"). Idempotent: on a fresh directory every column already
      * exists and every UPDATE matches nothing.
      */
+    /**
+     * Additive column migration for a table that already exists in someone's data
+     * directory. `PRAGMA table_info` is available in the pure adapter (the DO adapter
+     * has to attempt-and-tolerate instead — see its `ensureDirectoryColumns`).
+     */
+    ensureColumn(db, table, column, ddl) {
+        const existing = db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === column);
+        if (!existing)
+            db.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
+    }
+    /**
+     * Rebuild `_substrat_identities` when it still carries the pre-K-22 global key.
+     * A PRIMARY KEY cannot be ALTERed, so this is create-copy-drop-rename.
+     *
+     * The old shape is detected from `sqlite_master.sql` rather than `PRAGMA table_info`
+     * (which reports PK membership but not composition readably), and because the same
+     * check works on DO SQLite, where PRAGMA is restricted — so both adapters can use
+     * one detection strategy.
+     *
+     * Rows carry `tenant_id` already, so the copy is lossless: what changes is which
+     * columns are unique, not what is stored. Two pools that both issued `123` were
+     * previously ONE row (the second link silently ignored); after the rebuild the
+     * surviving row keeps its tenant and the other tenant's link can be made again.
+     */
+    ensureIdentityKey() {
+        const row = this.directory
+            .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?")
+            .get('_substrat_identities');
+        if (!row || row.sql.includes('PRIMARY KEY (tenant_id, provider, external_id)'))
+            return;
+        this.directory.exec(`
+      CREATE TABLE _substrat_identities_new (
+        provider     TEXT NOT NULL,
+        external_id  TEXT NOT NULL,
+        principal_id TEXT NOT NULL,
+        tenant_id    TEXT NOT NULL,
+        scope_id     TEXT,
+        created_at   TEXT NOT NULL,
+        PRIMARY KEY (tenant_id, provider, external_id)
+      );
+      INSERT OR IGNORE INTO _substrat_identities_new
+        (provider, external_id, principal_id, tenant_id, scope_id, created_at)
+        SELECT provider, external_id, principal_id, tenant_id, scope_id, created_at
+        FROM _substrat_identities;
+      DROP TABLE _substrat_identities;
+      ALTER TABLE _substrat_identities_new RENAME TO _substrat_identities;
+    `);
+    }
+    /**
+     * Drop the admin log's `tenant_id NOT NULL` (K-23). SQLite cannot relax a column
+     * constraint in place, so this is the same create-copy-drop-rename the identity key
+     * uses, detected the same way — from `sqlite_master.sql`, which works on DO SQLite
+     * too. Rows are copied verbatim: the log stays append-only in content, this only
+     * widens what a future row may say.
+     */
+    ensureAdminLogTenantNullable() {
+        const row = this.directory
+            .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?")
+            .get('_substrat_admin_log');
+        if (!row || !/tenant_id TEXT NOT NULL/.test(row.sql))
+            return;
+        this.directory.exec(`
+      CREATE TABLE _substrat_admin_log_new (
+        id TEXT PRIMARY KEY,
+        actor TEXT NOT NULL,
+        action TEXT NOT NULL,
+        tenant_id TEXT,
+        scope_id TEXT,
+        vertical TEXT,
+        before TEXT,
+        after TEXT,
+        at TEXT NOT NULL
+      );
+      INSERT INTO _substrat_admin_log_new
+        SELECT id, actor, action, tenant_id, scope_id, vertical, before, after, at
+        FROM _substrat_admin_log;
+      DROP TABLE _substrat_admin_log;
+      ALTER TABLE _substrat_admin_log_new RENAME TO _substrat_admin_log;
+    `);
+    }
     ensureDirectoryColumns() {
+        this.ensureIdentityKey();
+        this.ensureAdminLogTenantNullable();
+        this.ensureColumn(this.directory, '_substrat_admin_log', 'caused_by', 'caused_by TEXT');
+        // K-21's tombstone on tenant-level tuples (membership lives here).
+        this.ensureColumn(this.directory, '_substrat_tenant_tuples', 'revoked_at', 'revoked_at TEXT');
         const existing = new Set(this.directory.prepare('PRAGMA table_info(scopes)').all().map((c) => c.name));
         for (const [column, ddl] of [
             ['parent_scope_id', 'parent_scope_id TEXT'],
@@ -804,6 +1623,11 @@ export class SqliteScopeHost {
             ['kind', 'kind TEXT'],
             ['name', 'name TEXT'],
             ['vertical', 'vertical TEXT'],
+            ['vertical_version_id', 'vertical_version_id TEXT'],
+            ['migration_failed_version', 'migration_failed_version TEXT'],
+            ['migration_error', 'migration_error TEXT'],
+            ['migration_attempts', 'migration_attempts INTEGER NOT NULL DEFAULT 0'],
+            ['migration_last_attempt_at', 'migration_last_attempt_at TEXT'],
         ]) {
             if (!existing.has(column))
                 this.directory.exec(`ALTER TABLE scopes ADD COLUMN ${ddl}`);
@@ -819,6 +1643,7 @@ export class SqliteScopeHost {
         // duplicates it exists to forbid (SQLite treats NULLs as distinct).
         this.directory.exec('CREATE UNIQUE INDEX IF NOT EXISTS scopes_tenant_slug ON scopes (tenant_id, slug)');
         this.directory.exec('CREATE UNIQUE INDEX IF NOT EXISTS tenants_slug ON tenants (slug)');
+        this.directory.exec('CREATE UNIQUE INDEX IF NOT EXISTS orgs_tenant_slug ON orgs (tenant_id, slug)');
     }
     loadRoles() {
         const rows = this.directory
@@ -896,38 +1721,71 @@ export class SqliteScopeHost {
         // registers legitimately sits at schema_version '0'.
         if (pending.length === 0)
             return;
-        await rt.actor.enqueue(() => {
-            for (const { moduleId, migration } of pending) {
-                const key = `${moduleId}@${migration.version}`;
-                if (rt.appliedMigrations.has(key))
-                    continue;
-                rt.db.exec('BEGIN IMMEDIATE');
-                try {
-                    const already = rt.db
-                        .prepare('SELECT 1 FROM _substrat_migrations WHERE module_id = ? AND version = ?')
-                        .get(moduleId, migration.version);
-                    if (!already) {
-                        rt.db.exec(migration.sql);
-                        rt.db
-                            .prepare('INSERT INTO _substrat_migrations (module_id, version, applied_at) VALUES (?, ?, ?)')
-                            .run(moduleId, migration.version, new Date().toISOString());
+        // The failing `module@version` and its cause, captured structurally rather than
+        // re-parsed out of the thrown message — the directory record has to name both.
+        let failure;
+        try {
+            await rt.actor.enqueue(() => {
+                for (const { moduleId, migration } of pending) {
+                    const key = `${moduleId}@${migration.version}`;
+                    if (rt.appliedMigrations.has(key))
+                        continue;
+                    rt.db.exec('BEGIN IMMEDIATE');
+                    try {
+                        const already = rt.db
+                            .prepare('SELECT 1 FROM _substrat_migrations WHERE module_id = ? AND version = ?')
+                            .get(moduleId, migration.version);
+                        if (!already) {
+                            rt.db.exec(migration.sql);
+                            rt.db
+                                .prepare('INSERT INTO _substrat_migrations (module_id, version, applied_at) VALUES (?, ?, ?)')
+                                .run(moduleId, migration.version, new Date().toISOString());
+                        }
+                        rt.db.exec('COMMIT');
                     }
-                    rt.db.exec('COMMIT');
-                }
-                catch (err) {
-                    rt.db.exec('ROLLBACK');
-                    throw new Error(`migration failed for ${key} — scope fails closed: ${err.message}`);
+                    catch (err) {
+                        rt.db.exec('ROLLBACK');
+                        failure = { version: key, error: err.message };
+                        throw new Error(`migration failed for ${key} — scope fails closed: ${err.message}`);
+                    }
+                    rt.appliedMigrations.add(key);
                 }
-                rt.appliedMigrations.add(key);
-            }
-        });
-        // The scope's migration state, projected into the directory so the fleet
-        // question ("which scopes are behind?") is answerable from the index alone —
-        // §5.4's "fleet questions never fan out". Written here, at the one place
-        // migrations are applied, so it cannot drift from the journal it summarises.
+            });
+        }
+        finally {
+            // `finally`, not the success path: a scope that failed closed is exactly the
+            // one the fleet needs to see, and projecting only on success is what let a
+            // half-migrated scope keep a stale `schema_version` and render as healthy
+            // (#32). The throw still propagates — recording is not recovering.
+            this.recordMigrationState(rt, failure);
+        }
+    }
+    /**
+     * Project a scope's migration state into the directory — §5.4's "fleet questions
+     * never fan out", so the index answers "which scopes are behind" and "which
+     * failed" without waking anything.
+     *
+     * `appliedMigrations.size` is written on both paths: after a partial failure it
+     * is the count that actually landed, which is more truthful than the pre-attempt
+     * value. On success the failure columns are cleared, so `attempts` counts
+     * *consecutive* failures — what the sweep's backoff (#49) needs.
+     */
+    recordMigrationState(rt, failure) {
+        const version = String(rt.appliedMigrations.size);
+        if (!failure) {
+            this.directory
+                .prepare(`UPDATE scopes SET schema_version = ?, migration_failed_version = NULL,
+             migration_error = NULL, migration_attempts = 0, migration_last_attempt_at = NULL
+           WHERE scope_id = ?`)
+                .run(version, rt.scopeId);
+            return;
+        }
         this.directory
-            .prepare('UPDATE scopes SET schema_version = ? WHERE scope_id = ?')
-            .run(String(rt.appliedMigrations.size), rt.scopeId);
+            .prepare(`UPDATE scopes SET schema_version = ?, migration_failed_version = ?,
+           migration_error = ?, migration_attempts = migration_attempts + 1,
+           migration_last_attempt_at = ?
+         WHERE scope_id = ?`)
+            .run(version, failure.version, failure.error, new Date().toISOString(), rt.scopeId);
     }
     runtime(tenantId, scopeId) {
         const key = `${tenantId}/${scopeId}`;
@@ -937,6 +1795,9 @@ export class SqliteScopeHost {
         const db = new Database(join(this.dir, `${tenantId}__${scopeId}.sqlite`));
         db.pragma('journal_mode = WAL');
         db.exec(KERNEL_DDL);
+        // KERNEL_DDL is all IF NOT EXISTS, so a scope DB created before K-21 keeps the
+        // old shape — ALTER the tombstone in.
+        this.ensureColumn(db, '_substrat_tuples', 'revoked_at', 'revoked_at TEXT');
         const appliedMigrations = new Set(db.prepare('SELECT module_id, version FROM _substrat_migrations').all().map((r) => `${r.module_id}@${r.version}`));
         const created = { tenantId, scopeId, db, actor: new ScopeActor(), appliedMigrations };
         this.scopes.set(key, created);