@substrat-run/adapter-cloudflare 0.5.0 → 0.7.0

package/dist/host.d.ts

@@ -1,5 +1,5 @@
 import { type PlatformActorId, type PrincipalId, type ScopeId, type TenantId } from '@substrat-run/contracts';
-import { type HostAdmin, type ModuleRegistration, type OperationHandler, type PermissionChecker, type ProvisionScopeInput, type ScopeHost, type ScopeStub } from '@substrat-run/kernel';
+import { type ExecutorHandler, type HostAdmin, type ModuleRegistration, type OperationHandler, type PermissionChecker, type ProvisionScopeInput, type ScopeHost, type ScopeStub } from '@substrat-run/kernel';
 export interface CloudflareScopeHostOptions {
     scope: DurableObjectNamespace;
     controlPlane: DurableObjectNamespace;
@@ -17,9 +17,40 @@ export declare class CloudflareScopeHost implements ScopeHost {
     private readonly moduleIds;
     private readonly operations;
     private readonly predicateNames;
+    /** Executor id → {eventType, handler} (K-22 §4.2). Coordinator-side, not in the DO. */
+    private readonly executors;
+    /**
+     * The event currently being effected, stamped onto admin rows the executor writes.
+     * Ambient rather than threaded through every HostAdmin signature: set and cleared
+     * around one await, with executors running sequentially, so there is no window
+     * where it belongs to a different event.
+     */
+    private causedBy;
     private readonly withdrawn;
     private readonly operationEntitlement;
+    /**
+     * MUST be constructed per request. Never cache an instance across requests.
+     *
+     * The stub below is a Durable Object stub, which is an I/O object owned by the
+     * request that created it — reusing one throws "Cannot perform I/O on behalf of a
+     * different request". Every worker in this repo rebuilds the host per request
+     * (`hostFor(env)`), which is what makes this safe, and it is the only thing that
+     * does. The router learned this the expensive way: it memoised a resolver that
+     * closed over a stub, the first request after each cold start succeeded, and every
+     * request after that returned 1101 in production.
+     */
     constructor(options: CloudflareScopeHostOptions);
+    registerExecutor(id: string, eventType: string, handler: ExecutorHandler): void;
+    /**
+     * Drain this scope's outbox into the registered executors (K-22 §4.2).
+     *
+     * Runs on the coordinator because executors act through `HostAdmin`, which the
+     * ScopeDO cannot reach. Prompt: called inline after the operation returns, so the
+     * common case completes inside the request. A throwing executor leaves the
+     * delivery unjournaled and is retried on the next drain — the outbox is the
+     * backstop, not a substitute for idempotent handlers.
+     */
+    private drainExecutors;
     registerModule(registration: ModuleRegistration): void;
     defineOperation<I, O>(name: string, _handler: OperationHandler<I, O>): void;
     private bindOperation;
@@ -29,11 +60,20 @@ export declare class CloudflareScopeHost implements ScopeHost {
      * (§5.4: fleet questions never fan out). The ScopeDO reports null when nothing
      * was pending, which skips the write — otherwise every stub mint would cost an
      * extra control-plane RPC to store a number that did not change.
+     *
+     * A failure is recorded and then RETHROWN (#32): the scope still fails closed,
+     * but the directory learns which `module@version` broke and how many attempts it
+     * has taken, instead of keeping a stale `schema_version` that renders as healthy.
      */
     private migrateAndRecord;
     getScope(principal: PrincipalId, tenantId: TenantId, scopeId: ScopeId): Promise<ScopeStub>;
     close(): Promise<void>;
     private buildAdmin;
+    /**
+     * Record a staff read (K-24). `params` is a bounded summary, capped so one query
+     * cannot write an unbounded row.
+     */
+    private recordAccess;
     private recordAdmin;
     private writeScopeTuple;
     private scopeStub;

package/dist/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAkBL,KAAK,eAAe,EACpB,KAAK,WAAW,EAKhB,KAAK,OAAO,EAGZ,KAAK,QAAQ,EAGd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAGxB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAuH9B,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,YAAY,EAAE,sBAAsB,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED,qBAAa,mBAAoB,YAAW,SAAS;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IAItC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;gBAEtD,OAAO,EAAE,0BAA0B;IAU/C,cAAc,CAAC,YAAY,EAAE,kBAAkB,GAAG,IAAI;IAgDtD,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAI3E,OAAO,CAAC,aAAa;IAQf,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBvF;;;;;OAKG;YACW,gBAAgB;IAKxB,QAAQ,CACZ,SAAS,EAAE,WAAW,EACtB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,SAAS,CAAC;IA6Bf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,OAAO,CAAC,UAAU;YA8QJ,WAAW;YAoBX,eAAe;IAU7B,OAAO,CAAC,SAAS;CAKlB"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAqCL,KAAK,eAAe,EACpB,KAAK,WAAW,EAYhB,KAAK,OAAO,EAGZ,KAAK,QAAQ,EAGd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAGxB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AA+M9B,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,YAAY,EAAE,sBAAsB,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED,qBAAa,mBAAoB,YAAW,SAAS;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IAItC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsE;IAChG;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAElE;;;;;;;;;;OAUG;gBACS,OAAO,EAAE,0BAA0B;IAU/C,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAK/E;;;;;;;;OAQG;YACW,cAAc;IAkB5B,cAAc,CAAC,YAAY,EAAE,kBAAkB,GAAG,IAAI;IAgDtD,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAI3E,OAAO,CAAC,aAAa;IAQf,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBvF;;;;;;;;;OASG;YACW,gBAAgB;IAwBxB,QAAQ,CACZ,SAAS,EAAE,WAAW,EACtB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,SAAS,CAAC;IAqCf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,OAAO,CAAC,UAAU;IAmqBlB;;;OAGG;YACW,YAAY;YAmBZ,WAAW;YAqBX,eAAe;IAU7B,OAAO,CAAC,SAAS;CAKlB"}

package/dist/host.js

@@ -1,4 +1,5 @@
-import { adminLogEntry, createTenantInput, identityLink, moduleManifest, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, } from '@substrat-run/contracts';
+import { accessLogEntry, adminLogEntry, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindHostnameInput, hostnameBinding, publishVersionInput, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, } from '@substrat-run/contracts';
+import { normalizeHostname, toRouteTarget } from './route-resolver.js';
 import { resolveScopeRecord, ulid, } from '@substrat-run/kernel';
 export class CloudflareScopeHost {
     admin;
@@ -9,14 +10,67 @@ export class CloudflareScopeHost {
     moduleIds = new Set();
     operations = new Set();
     predicateNames = new Map(); // name → module
+    /** Executor id → {eventType, handler} (K-22 §4.2). Coordinator-side, not in the DO. */
+    executors = new Map();
+    /**
+     * The event currently being effected, stamped onto admin rows the executor writes.
+     * Ambient rather than threaded through every HostAdmin signature: set and cleared
+     * around one await, with executors running sequentially, so there is no window
+     * where it belongs to a different event.
+     */
+    causedBy = null;
     withdrawn = new Map(); // operation → module
     operationEntitlement = new Map();
+    /**
+     * MUST be constructed per request. Never cache an instance across requests.
+     *
+     * The stub below is a Durable Object stub, which is an I/O object owned by the
+     * request that created it — reusing one throws "Cannot perform I/O on behalf of a
+     * different request". Every worker in this repo rebuilds the host per request
+     * (`hostFor(env)`), which is what makes this safe, and it is the only thing that
+     * does. The router learned this the expensive way: it memoised a resolver that
+     * closed over a stub, the first request after each cold start succeeded, and every
+     * request after that returned 1101 in production.
+     */
     constructor(options) {
         this.scopeNs = options.scope;
         this.cp = options.controlPlane.get(options.controlPlane.idFromName('control-plane'));
         this.admin = this.buildAdmin();
     }
     // -- registration mechanics (validation only) -----------------------------
+    registerExecutor(id, eventType, handler) {
+        if (this.executors.has(id))
+            throw new Error(`executor '${id}' is already registered`);
+        this.executors.set(id, { eventType, handler });
+    }
+    /**
+     * Drain this scope's outbox into the registered executors (K-22 §4.2).
+     *
+     * Runs on the coordinator because executors act through `HostAdmin`, which the
+     * ScopeDO cannot reach. Prompt: called inline after the operation returns, so the
+     * common case completes inside the request. A throwing executor leaves the
+     * delivery unjournaled and is retried on the next drain — the outbox is the
+     * backstop, not a substitute for idempotent handlers.
+     */
+    async drainExecutors(scopeId) {
+        if (this.executors.size === 0)
+            return;
+        const stub = this.scopeStub(scopeId);
+        for (const [id, executor] of this.executors) {
+            const deliveryId = `executor:${id}`;
+            const events = await stub.pendingExecutorEvents(deliveryId, executor.eventType);
+            for (const event of events) {
+                this.causedBy = event.id;
+                try {
+                    await executor.handler(this.admin, event);
+                }
+                finally {
+                    this.causedBy = null;
+                }
+                await stub.markExecutorDelivered(event.id, deliveryId);
+            }
+        }
+    }
     registerModule(registration) {
         const manifest = moduleManifest.parse(registration.manifest);
         if (this.moduleIds.has(manifest.id)) {
@@ -87,11 +141,36 @@ export class CloudflareScopeHost {
      * (§5.4: fleet questions never fan out). The ScopeDO reports null when nothing
      * was pending, which skips the write — otherwise every stub mint would cost an
      * extra control-plane RPC to store a number that did not change.
+     *
+     * A failure is recorded and then RETHROWN (#32): the scope still fails closed,
+     * but the directory learns which `module@version` broke and how many attempts it
+     * has taken, instead of keeping a stale `schema_version` that renders as healthy.
      */
     async migrateAndRecord(scopeId) {
-        const applied = await this.scopeStub(scopeId).migrate();
-        if (applied !== null)
-            await this.cp.setSchemaVersion(scopeId, String(applied));
+        const stub = this.scopeStub(scopeId);
+        try {
+            const applied = await stub.migrate();
+            if (applied !== null)
+                await this.cp.setMigrationState(scopeId, String(applied), null);
+        }
+        catch (err) {
+            // Best-effort: a scope that failed to migrate may also fail to answer, and a
+            // broken recorder must not replace the migration error with its own — that
+            // trades a diagnosable failure for a confusing one.
+            try {
+                const failure = await stub.migrationFailure();
+                if (failure) {
+                    await this.cp.setMigrationState(scopeId, String(failure.applied), {
+                        version: failure.version,
+                        error: failure.error,
+                    });
+                }
+            }
+            catch {
+                // deliberately swallowed — the rethrow below is the real signal
+            }
+            throw err;
+        }
     }
     async getScope(principal, tenantId, scopeId) {
         // Lifecycle gates (control-plane.md §4.1/§4.2), the K-3 fail-closed path,
@@ -111,7 +190,9 @@ export class CloudflareScopeHost {
                 if (requiredKey && !(await cp.tenantHoldsEntitlement(tenantId, requiredKey))) {
                     return Promise.reject(new Error(`operation not entitled: ${operation} — tenant does not hold '${requiredKey}'`));
                 }
-                return stub.invoke(operation, input, principal, tenantId, scopeId);
+                const result = (await stub.invoke(operation, input, principal, tenantId, scopeId));
+                await this.drainExecutors(scopeId);
+                return result;
             },
         };
     }
@@ -125,6 +206,48 @@ export class CloudflareScopeHost {
         // table) while the contract requires them, so this parse is where that gap is
         // held shut — and it is the same parse the pure adapter does, which is what
         // makes the shared contract suite meaningful.
+        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,
+        });
+        const mapVertical = (r) => verticalSchema.parse({ slug: r.slug, name: r.name, source: r.source, createdAt: r.created_at });
+        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 mapOrg = (r) => orgSchema.parse({
+            id: r.org_id,
+            tenantId: r.tenant_id,
+            slug: r.slug,
+            name: r.name,
+            createdAt: r.created_at,
+        });
+        /**
+         * Fail closed on an org that does not exist in this tenant. Scoped by tenant, not
+         * just by id: an org from another tenant must read as absent, or grantToOrg would
+         * reach across the boundary the record exists to make explicit.
+         */
+        const requireOrg = async (tenant, id) => {
+            if (!(await this.cp.readOrg(tenant, id))) {
+                throw new Error(`unknown org ${id} in tenant ${tenant}`);
+            }
+        };
         const mapScope = (r) => scopeSchema.parse({
             id: r.scope_id,
             tenantId: r.tenant_id,
@@ -137,6 +260,15 @@ export class CloudflareScopeHost {
             jurisdiction: r.jurisdiction,
             vertical: r.vertical,
             schemaVersion: r.schema_version,
+            verticalVersionId: r.vertical_version_id,
+            migrationFailure: r.migration_failed_version && r.migration_last_attempt_at
+                ? {
+                    version: r.migration_failed_version,
+                    error: r.migration_error ?? '',
+                    attempts: r.migration_attempts,
+                    lastAttemptAt: r.migration_last_attempt_at,
+                }
+                : null,
             createdAt: r.created_at,
         });
         const transitionScope = async (actor, action, tenantId, scopeId, from, to) => {
@@ -164,8 +296,9 @@ export class CloudflareScopeHost {
                 const before = await this.cp.defineRole(tenantId, parsed);
                 await this.recordAdmin(actor, 'defineRole', { tenantId }, before, parsed);
             },
-            listRoles: async (filter) => {
+            listRoles: async (actor, filter) => {
                 const rows = await this.cp.listRoles({ tenantId: filter?.tenantId, source: filter?.source });
+                await this.recordAccess(actor, 'listRoles', { tenantId: filter?.tenantId ?? null }, filter, rows.length);
                 // Parsed, not cast — the same parse the pure adapter does, which is what
                 // makes the shared contract suite mean anything.
                 return rows.map((r) => tenantRole.parse({
@@ -190,13 +323,213 @@ export class CloudflareScopeHost {
                 await 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 looks
+                // applied, resolves for nobody, and still shows up in the permission diff.
+                await requireOrg(node.tenantId, orgId);
                 await writeGrant(`org:${orgId}`, permission, node, entity);
                 await 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 = await this.cp.getScopeRecord(parsed.tenantId, parsed.scopeId);
+                if (!scope) {
+                    throw new Error(`unknown scope ${parsed.scopeId} in tenant ${parsed.tenantId}`);
+                }
+                const existing = await this.cp.readHostname(parsed.hostname);
+                if (existing && existing.scope_id !== parsed.scopeId) {
+                    // A hostname routes to exactly one place; silently rebinding would move
+                    // another tenant's traffic.
+                    throw new Error(`hostname '${parsed.hostname}' is already bound to another scope`);
+                }
+                // Exactly one canonical per (scope, surface).
+                if (parsed.canonical)
+                    await this.cp.demoteCanonical(parsed.scopeId, parsed.surface);
+                await this.cp.upsertHostname({
+                    hostname: parsed.hostname,
+                    tenantId: parsed.tenantId,
+                    scopeId: parsed.scopeId,
+                    verticalSlug: scope.vertical,
+                    surface: parsed.surface,
+                    region: parsed.region,
+                    canonical: parsed.canonical,
+                    createdAt: new Date().toISOString(),
+                });
+                await 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 = await this.cp.readHostname(hostname);
+                if (!row)
+                    throw new Error(`unknown hostname '${hostname}'`);
+                if (row.status === status)
+                    return; // idempotent, unaudited
+                await this.cp.setHostnameStatus(hostname, status, note ?? null);
+                await this.recordAdmin(actor, 'setHostnameStatus', { tenantId: row.tenant_id, scopeId: row.scope_id }, { status: row.status }, { status, note: note ?? null });
+            },
+            listHostnames: async (actor, filter) => {
+                const rows = await this.cp.listHostnames({
+                    tenantId: filter?.tenantId,
+                    scopeId: filter?.scopeId,
+                });
+                await 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 — the same machine-path
+            // carve-out resolveIdentity has (K-24). Shares its mapping with the router's
+            // own resolver so the two cannot disagree on what resolves.
+            toRouteTarget(await this.cp.readHostname(normalizeHostname(raw))),
+            registerVertical: async (actor, input) => {
+                const parsed = registerVerticalInput.parse(input);
+                const existing = await this.cp.readVertical(parsed.slug);
+                if (existing) {
+                    if (existing.source === parsed.source && existing.name === parsed.name)
+                        return;
+                    throw new Error(`vertical '${parsed.slug}' is already registered as ${existing.source}`);
+                }
+                await this.cp.insertVertical(parsed.slug, parsed.name, parsed.source, new Date().toISOString());
+                await this.recordAdmin(actor, 'registerVertical', { tenantId: null }, null, parsed);
+            },
+            listVerticals: async (actor) => {
+                const rows = await this.cp.listVerticals();
+                await this.recordAccess(actor, 'listVerticals', {}, null, rows.length);
+                return rows.map(mapVertical);
+            },
+            publishVersion: async (actor, input) => {
+                const parsed = publishVersionInput.parse(input);
+                if (!(await this.cp.readVertical(parsed.verticalSlug))) {
+                    throw new Error(`unknown vertical '${parsed.verticalSlug}'`);
+                }
+                // Lands PENDING — a push is not a deploy.
+                await this.cp.insertVersion({ ...parsed, createdAt: new Date().toISOString() });
+                await this.recordAdmin(actor, 'publishVersion', { tenantId: null }, null, parsed);
+            },
+            listVersions: async (actor, verticalSlug) => {
+                const rows = await this.cp.listVersions(verticalSlug);
+                await this.recordAccess(actor, 'listVersions', {}, { verticalSlug }, rows.length);
+                return rows.map(mapVersion);
+            },
+            admitVersion: async (actor, versionId) => {
+                const v = await this.cp.readVersion(versionId);
+                if (!v)
+                    throw new Error(`unknown version ${versionId}`);
+                if (v.admission === 'admitted')
+                    return;
+                if (v.admission === 'rejected') {
+                    throw new Error(`version ${versionId} was rejected — publish a new one`);
+                }
+                await this.cp.setAdmission(versionId, 'admitted', null);
+                await this.recordAdmin(actor, 'admitVersion', { tenantId: null }, { admission: v.admission }, { admission: 'admitted' });
+            },
+            rejectVersion: async (actor, versionId, note) => {
+                const v = await this.cp.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;
+                await this.cp.setAdmission(versionId, 'rejected', note);
+                await this.recordAdmin(actor, 'rejectVersion', { tenantId: null }, { admission: v.admission }, { admission: 'rejected', note });
+            },
+            promoteVersion: async (actor, verticalSlug, channel, versionId, acknowledge) => {
+                const incoming = await this.cp.readVersion(versionId);
+                if (!incoming)
+                    throw new Error(`unknown version ${versionId}`);
+                if (incoming.vertical_slug !== verticalSlug) {
+                    throw new Error(`version ${versionId} belongs to '${incoming.vertical_slug}'`);
+                }
+                if (incoming.admission !== 'admitted') {
+                    throw new Error(`version ${versionId} is ${incoming.admission}, not admitted — it cannot be promoted`);
+                }
+                const current = await this.cp.readChannel(verticalSlug, channel);
+                const outgoing = current ? await this.cp.readVersion(current.version_id) : undefined;
+                const ack = promotionAcknowledgement.parse(acknowledge ?? {});
+                // §4's checkpoints, at the moment of exposure. A first promotion has
+                // nothing to diff against — the gate is about change, not existence.
+                if (outgoing) {
+                    if (outgoing.permission_digest !== incoming.permission_digest && !ack.permissionChange) {
+                        throw new Error(`promotion changes the permission surface (${outgoing.permission_digest} → ` +
+                            `${incoming.permission_digest}) — acknowledge it explicitly to promote`);
+                    }
+                    if (outgoing.migration_digest !== incoming.migration_digest && !ack.migrationChange) {
+                        throw new Error(`promotion changes migrations (${outgoing.migration_digest} → ` +
+                            `${incoming.migration_digest}) — acknowledge it explicitly to promote`);
+                    }
+                }
+                await this.cp.setChannel(verticalSlug, channel, versionId, new Date().toISOString());
+                await 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 = await this.cp.listChannels(verticalSlug);
+                await 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 = await this.cp.readVersion(versionId);
+                if (!v)
+                    throw new Error(`unknown version ${versionId}`);
+                // The refusal the registry exists for.
+                if (v.admission !== 'admitted') {
+                    throw new Error(`version ${versionId} is ${v.admission}, not admitted — it cannot be bound to a scope`);
+                }
+                const scope = await this.cp.getScopeRecord(tenantId, scopeId);
+                if (!scope)
+                    throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                await this.cp.bindScopeVersion(scopeId, versionId, v.vertical_slug);
+                await this.recordAdmin(actor, 'bindScopeVersion', { tenantId, scopeId }, null, {
+                    versionId, vertical: v.vertical_slug, version: v.version,
+                });
+            },
+            createOrg: async (actor, input) => {
+                const parsed = createOrgInput.parse(input);
+                const created = await this.cp.createOrg(parsed.id, parsed.tenantId, parsed.slug, parsed.name, new Date().toISOString());
+                if (!created)
+                    return; // idempotent, and a no-op is not audited
+                await this.recordAdmin(actor, 'createOrg', { tenantId: parsed.tenantId }, null, parsed);
+            },
+            listOrgs: async (actor, tenantId) => {
+                const orgs = (await this.cp.listOrgs(tenantId)).map(mapOrg);
+                await this.recordAccess(actor, 'listOrgs', { tenantId }, null, orgs.length);
+                return orgs;
+            },
+            getOrg: async (actor, tenantId, orgId) => {
+                const r = await this.cp.readOrg(tenantId, orgId);
+                await this.recordAccess(actor, 'getOrg', { tenantId }, { orgId }, r ? 1 : 0);
+                return r ? mapOrg(r) : undefined;
+            },
             addMember: async (actor, tenantId, principal, orgId) => {
+                await requireOrg(tenantId, orgId);
                 await this.cp.writeTenantTuple(tenantId, `principal:${principal}`, 'member', `org:${orgId}`, null);
                 await this.recordAdmin(actor, 'addMember', { tenantId }, null, { principal, orgId });
             },
+            removeMember: async (actor, tenantId, principal, orgId) => {
+                await requireOrg(tenantId, orgId);
+                // Tombstone (K-21), never DELETE. The DO reports whether anything changed
+                // so a repeat revoke stays a silent no-op rather than a second audit row.
+                const changed = await this.cp.revokeMember(tenantId, `principal:${principal}`, `org:${orgId}`, new Date().toISOString());
+                if (!changed)
+                    return;
+                await this.recordAdmin(actor, 'removeMember', { tenantId }, { principal, orgId }, null);
+            },
+            listMembers: async (actor, tenantId, orgId, options) => {
+                await requireOrg(tenantId, orgId);
+                const rows = await this.cp.listMembers(tenantId, `org:${orgId}`, options?.includeRevoked ?? false);
+                await 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);
                 const created = await this.cp.createTenant(parsed.id, parsed.slug, parsed.name, new Date().toISOString());
@@ -209,12 +542,18 @@ export class CloudflareScopeHost {
                 const before = await this.cp.setTenantStatus(tenantId, status);
                 await this.recordAdmin(actor, 'setTenantStatus', { tenantId }, { status: before }, { status });
             },
-            listTenants: async () => (await this.cp.listTenants()).map((t) => tenantSchema.parse(t)),
-            getTenant: async (tenantId) => {
+            listTenants: async (actor) => {
+                const tenants = (await this.cp.listTenants()).map((t) => tenantSchema.parse(t));
+                // Enumerating every tenant on the platform is the read this log exists for.
+                await this.recordAccess(actor, 'listTenants', {}, null, tenants.length);
+                return tenants;
+            },
+            getTenant: async (actor, tenantId) => {
                 const t = await this.cp.getTenant(tenantId);
+                await this.recordAccess(actor, 'getTenant', { tenantId }, null, t ? 1 : 0);
                 return t ? tenantSchema.parse(t) : undefined;
             },
-            listScopes: async (filter) => {
+            listScopes: async (actor, filter) => {
                 const rows = await this.cp.listScopes({
                     tenantId: filter?.tenantId,
                     status: filter?.status
@@ -224,10 +563,12 @@ export class CloudflareScopeHost {
                         : undefined,
                     vertical: filter?.vertical,
                 });
+                await this.recordAccess(actor, 'listScopes', { tenantId: filter?.tenantId ?? null }, filter, rows.length);
                 return rows.map(mapScope);
             },
-            getScopeRecord: async (tenantId, scopeId) => {
+            getScopeRecord: async (actor, tenantId, scopeId) => {
                 const row = await this.cp.getScopeRecord(tenantId, scopeId);
+                await this.recordAccess(actor, 'getScopeRecord', { tenantId, scopeId }, null, row ? 1 : 0);
                 return row ? mapScope(row) : undefined;
             },
             suspendScope: async (actor, tenantId, scopeId) => transitionScope(actor, 'suspendScope', tenantId, scopeId, ['active'], 'suspended'),
@@ -246,26 +587,92 @@ export class CloudflareScopeHost {
                     return; // nothing held, nothing changed
                 await this.recordAdmin(actor, 'revokeEntitlement', { tenantId }, { entitlementKey }, null);
             },
-            listEntitlements: async (tenantId) => this.cp.listEntitlements(tenantId),
+            listEntitlements: async (actor, tenantId) => {
+                const keys = await this.cp.listEntitlements(tenantId);
+                await this.recordAccess(actor, 'listEntitlements', { tenantId }, null, keys.length);
+                return keys;
+            },
+            registerIdentityPool: async (actor, input) => {
+                const parsed = identityPool.parse(input);
+                const created = await this.cp.registerIdentityPool(parsed.provider, parsed.topology, parsed.tenantId, new Date().toISOString());
+                if (!created)
+                    return; // identical registration is idempotent, unaudited
+                // Null tenant for a central pool: it belongs to no single tenant, which is
+                // what made the admin log's tenantId nullable.
+                await this.recordAdmin(actor, 'registerIdentityPool', { tenantId: parsed.tenantId }, null, parsed);
+            },
+            getIdentityPool: async (actor, provider) => {
+                const r = await this.cp.readPool(provider);
+                await this.recordAccess(actor, 'getIdentityPool', {}, { provider }, r ? 1 : 0);
+                return r
+                    ? identityPool.parse({ provider: r.provider, topology: r.topology, tenantId: r.tenant_id })
+                    : undefined;
+            },
+            listIdentityTenants: async (actor, provider, externalId) => {
+                const r = await this.cp.readPool(provider);
+                if (!r)
+                    throw new Error(`identity pool '${provider}' is not registered`);
+                if (r.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 = (await this.cp.identityTenants(provider, externalId));
+                await this.recordAccess(actor, 'listIdentityTenants', {}, { provider }, tenants.length);
+                return tenants;
+            },
             linkIdentity: async (actor, input) => {
                 const parsed = identityLink.parse(input);
+                const pool = await this.cp.readPool(parsed.provider);
+                if (!pool) {
+                    throw new Error(`identity pool '${parsed.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.tenant_id !== parsed.tenantId) {
+                    throw new Error(`identity pool '${parsed.provider}' is bound to tenant ${pool.tenant_id} and cannot link into ${parsed.tenantId}`);
+                }
                 const changed = await this.cp.linkIdentity(parsed.provider, parsed.externalId, parsed.principal, parsed.tenantId, parsed.scopeId ?? null, new Date().toISOString());
                 // Idempotent: an identity already bound is a no-op, not audited.
                 if (!changed)
                     return;
                 await this.recordAdmin(actor, 'linkIdentity', { tenantId: parsed.tenantId, scopeId: parsed.scopeId }, null, { provider: parsed.provider, externalId: parsed.externalId, principal: parsed.principal });
             },
-            resolveIdentity: async (provider, externalId) => {
-                const row = await this.cp.resolveIdentity(provider, externalId);
+            resolveIdentity: async (tenantId, provider, externalId) => {
+                const row = await this.cp.resolveIdentity(tenantId, provider, externalId);
                 if (!row)
                     return undefined;
-                return resolvedIdentity.parse({
-                    principal: row.principal,
-                    tenantId: row.tenantId,
-                    scopeId: row.scopeId,
+                return resolvedIdentity.parse({ principal: row.principal, scopeId: row.scopeId });
+            },
+            accessLog: async (actor, filter) => {
+                const rows = await this.cp.accessLog({
+                    actor: filter?.actor,
+                    tenantId: filter?.tenantId,
+                    method: filter?.method,
+                    limit: filter?.limit,
                 });
+                // Reading the access log is itself a read. Recorded before returning, so
+                // the row describing this call is not in its own result.
+                await 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) => {
+                const pruned = await this.cp.pruneAccessLog(limit);
+                if (pruned > 0) {
+                    await this.recordAdmin(actor, 'pruneAccessLog', { tenantId: null }, { pruned }, null);
+                }
+                return pruned;
             },
-            auditLog: async (filter) => {
+            auditLog: async (actor, filter) => {
                 const rows = await this.cp.auditLog({
                     tenantId: filter?.tenantId,
                     scopeId: filter?.scopeId,
@@ -282,17 +689,36 @@ export class CloudflareScopeHost {
                     cursor: filter?.cursor,
                     order: filter?.order,
                 });
+                // Reading the audit trail is itself audited.
+                await this.recordAccess(actor, 'auditLog', { tenantId: filter?.tenantId ?? null, scopeId: filter?.scopeId ?? null }, filter, rows.length);
                 return rows.map((r) => adminLogEntry.parse(r));
             },
         };
     }
     // -- helpers --------------------------------------------------------------
+    /**
+     * Record a staff read (K-24). `params` is a bounded summary, capped so one query
+     * cannot write an unbounded row.
+     */
+    async recordAccess(actor, method, target, params, resultCount) {
+        await this.cp.recordAccess({
+            id: ulid(),
+            actor,
+            method,
+            tenantId: target.tenantId ?? null,
+            scopeId: target.scopeId ?? null,
+            params: params == null ? null : JSON.stringify(params).slice(0, 500),
+            resultCount,
+            at: new Date().toISOString(),
+        });
+    }
     async recordAdmin(actor, action, target, before, after) {
         await this.cp.recordAdmin({
             id: ulid(),
             actor,
             action,
             tenantId: target.tenantId,
+            causedBy: this.causedBy,
             scopeId: target.scopeId ?? null,
             vertical: target.vertical ?? null,
             before: before ?? null,