@substrat-run/adapter-cloudflare 0.13.0 → 0.16.0

package/dist/host.js

@@ -1,4 +1,4 @@
-import { accessLogEntry, adminLogEntry, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindHostnameInput, hostnameBinding, publishVersionInput, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, connection, connectionGrant, connectionSecret, subjectRef, createConnectionInput, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, } from '@substrat-run/contracts';
+import { accessLogEntry, adminLogEntry, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, connection, connectionGrant, connectionSecret, subjectRef, createConnectionInput, 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, backoffAt, resolveRetryPolicy, unconfiguredSecretBox, } from '@substrat-run/kernel';
 /** DO row → contract shape. Never reads the secrets table — that is the split. */
@@ -235,6 +235,57 @@ export class CloudflareScopeHost {
         await this.migrateAndRecord(scopeId);
         return this.scopeStub(scopeId).executorDeadLetters();
     }
+    /**
+     * Read-only introspection of a scope's OWN database, reaching the scope DO directly
+     * (kernel-design §5.4's admin-query RPC). Unlike `admin.listScopeTables`, this does
+     * NOT consult the control-plane directory — so it works in a **CP-less vertical**, the
+     * deployment that actually holds the scope's data (its ScopeDO runs the modules). The
+     * vertical's platform-gated `/internal/tables` route calls it; authorization is that
+     * gate (the caller is the control plane, which did the K-3 check + audit on its side).
+     */
+    async introspectScopeTables(scopeId) {
+        return this.scopeStub(scopeId).introspectTables();
+    }
+    async introspectScopeTable(scopeId, input) {
+        return this.scopeStub(scopeId).introspectTable(input.table, input.limit, input.offset);
+    }
+    /** The SQL console's CP-less path (#219) — same trust line as the pair above. */
+    async introspectScopeQuery(scopeId, input) {
+        return this.scopeStub(scopeId).introspectQuery(input.sql);
+    }
+    /**
+     * Copy one scope's data into a fresh scope DO, entirely within THIS deployment —
+     * the data half of an orchestrated snapshot (preview-and-snapshots.md §9). Like the
+     * introspection pair above it consults no control plane: the vertical's platform-
+     * gated `/internal/snapshot` route calls it, and the directory half (provenance row,
+     * activation, version bind) stays on the control plane's side. Because source and
+     * destination sit in the same SCOPE namespace, no scope bytes ever leave the
+     * deployment — the §9 property the trust line rests on.
+     */
+    async snapshotScopeLocal(sourceScopeId, destScopeId) {
+        const tables = await this.scopeStub(sourceScopeId).exportDump();
+        await this.scopeStub(destScopeId).importDump(tables);
+        return { tables: tables.length };
+    }
+    /**
+     * Wipe one scope DO's storage in THIS deployment — the reap half of an orchestrated
+     * deleteSnapshot (§9). The fork-only refusal and the directory cleanup live on the
+     * control plane, which calls the vertical's `/internal/delete-scope` before deleting
+     * the row; this end just destroys its own bytes.
+     */
+    async deleteScopeLocal(scopeId) {
+        await this.scopeStub(scopeId).destroyStorage();
+    }
+    /**
+     * Dump one scope's tables from THIS deployment — the data half of a governed
+     * `scope pull` (preview-and-snapshots.md §8/§9). Unlike the snapshot verb, this one
+     * DOES move scope bytes across the boundary — that is its purpose, and why the
+     * control-plane route in front of it is the gated, audited, masked-by-default
+     * path (§6). The vertical's platform-gated `/internal/export` route calls it.
+     */
+    async exportScopeLocal(scopeId) {
+        return this.scopeStub(scopeId).exportDump();
+    }
     registerModule(registration) {
         const manifest = moduleManifest.parse(registration.manifest);
         if (this.moduleIds.has(manifest.id)) {
@@ -304,6 +355,64 @@ export class CloudflareScopeHost {
             await this.recordAdmin(actor, 'provisionScope', { tenantId: input.tenantId, scopeId: input.scopeId, vertical: record.vertical }, null, record);
         }
     }
+    async importScope(actor, input, dump) {
+        // Create the destination scope (directory row + DO + lazy migrate); the DO then
+        // replaces its provisioned schema with the dump wholesale (drop-then-replay), so
+        // the end state is the dump, at the source's frontier. Provenance is stamped from
+        // the dump unless the caller set it (§3: a fork always records its origin).
+        await this.provisionScope(actor, {
+            ...input,
+            forkedFrom: input.forkedFrom ?? dump.scopeId,
+            forkedAt: input.forkedAt ?? dump.capturedAt,
+        });
+        await this.scopeStub(input.scopeId).importDump(dump.tables);
+        await this.admin.activateScope(actor, input.tenantId, input.scopeId);
+        await this.recordAdmin(actor, 'importScope', { tenantId: input.tenantId, scopeId: input.scopeId }, null, { sourceScopeId: dump.scopeId, tables: dump.tables.length, capturedAt: dump.capturedAt });
+    }
+    async snapshotScope(actor, tenantId, scopeId, opts) {
+        const source = await this.admin.getScopeRecord(actor, tenantId, scopeId);
+        if (!source)
+            throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+        const dump = await this.admin.exportScope(actor, tenantId, scopeId);
+        const snapshotId = ulid();
+        await this.importScope(actor, {
+            tenantId,
+            scopeId: snapshotId,
+            kind: opts?.kind ?? 'archive',
+            vertical: source.vertical,
+            jurisdiction: source.jurisdiction,
+            expiresAt: opts?.expiresAt,
+            // forkedFrom/forkedAt are stamped from the dump by importScope.
+        }, dump);
+        // Bind the snapshot to the source's current version so it is a runnable copy at the
+        // same frontier (a fresh bind, so it never re-triggers the snapshot path).
+        if (source.verticalVersionId) {
+            await this.admin.bindScopeVersion(actor, tenantId, snapshotId, source.verticalVersionId);
+        }
+        return snapshotId;
+    }
+    async deleteSnapshot(actor, tenantId, scopeId) {
+        // The refusal that keeps this narrow: only a FORK may be hard-deleted. Everything
+        // else keeps the platform's tombstone-only rule.
+        const rec = await this.admin.getScopeRecord(actor, tenantId, scopeId);
+        if (!rec)
+            throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+        if (!rec.forkedFrom) {
+            throw new Error(`scope ${scopeId} is not a fork (forkedFrom is null) — only snapshots may be deleted; ` +
+                `archive a primary scope instead`);
+        }
+        // Storage BEFORE the directory row: a crash between the two leaves a visible row
+        // over empty storage — re-running deleteSnapshot converges — never orphaned bytes
+        // with no record (the §9 hazard). Hostname rows go with the directory delete.
+        await this.scopeStub(scopeId).destroyStorage();
+        await this.cp.deleteScopeDirectory(scopeId);
+        await this.recordAdmin(actor, 'deleteSnapshot', { tenantId, scopeId }, null, {
+            forkedFrom: rec.forkedFrom,
+            forkedAt: rec.forkedAt,
+            expiresAt: rec.expiresAt,
+            kind: rec.kind,
+        });
+    }
     /**
      * Migrate a scope and project its resulting migration count into the directory
      * (§5.4: fleet questions never fan out). The ScopeDO reports null when nothing
@@ -422,7 +531,18 @@ export class CloudflareScopeHost {
             canonical: r.canonical === 1,
             createdAt: r.created_at,
         });
-        const mapVertical = (r) => verticalSchema.parse({ slug: r.slug, name: r.name, source: r.source, ownerTenant: r.owner_tenant, createdAt: r.created_at });
+        const mapVertical = (r) => verticalSchema.parse({
+            slug: r.slug,
+            name: r.name,
+            source: r.source,
+            ownerTenant: r.owner_tenant,
+            ...(r.env_spec ? { envSpec: JSON.parse(r.env_spec) } : {}),
+            ...(r.install_spec ? JSON.parse(r.install_spec) : {}),
+            listed: !!r.listed,
+            ...(r.publish_requested_at ? { publishRequestedAt: r.publish_requested_at } : {}),
+            installsBlocked: !!r.installs_blocked,
+            createdAt: r.created_at,
+        });
         const mapVersion = (r) => verticalVersion.parse({
             id: r.id,
             verticalSlug: r.vertical_slug,
@@ -475,6 +595,9 @@ export class CloudflareScopeHost {
                     lastAttemptAt: r.migration_last_attempt_at,
                 }
                 : null,
+            forkedFrom: r.forked_from,
+            forkedAt: r.forked_at,
+            expiresAt: r.expires_at,
             createdAt: r.created_at,
         });
         const transitionScope = async (actor, action, tenantId, scopeId, from, to) => {
@@ -636,6 +759,14 @@ export class CloudflareScopeHost {
                 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 });
             },
+            unbindHostname: async (actor, raw) => {
+                const hostname = raw.toLowerCase(); // DNS is case-insensitive; the map is normalized
+                const row = await this.cp.readHostname(hostname);
+                if (!row)
+                    return; // idempotent, and a no-op is not audited
+                await this.cp.deleteHostname(hostname);
+                await this.recordAdmin(actor, 'unbindHostname', { tenantId: row.tenant_id, scopeId: row.scope_id }, { hostname, status: row.status }, null);
+            },
             listHostnames: async (actor, filter) => {
                 const rows = await this.cp.listHostnames({
                     tenantId: filter?.tenantId,
@@ -651,20 +782,40 @@ export class CloudflareScopeHost {
             toRouteTarget(await this.cp.readHostname(normalizeHostname(raw))),
             registerVertical: async (actor, input) => {
                 const parsed = registerVerticalInput.parse(input);
+                const envSpecJson = parsed.envSpec ? JSON.stringify(parsed.envSpec) : null;
+                // The four registry-driven-install fields ride as one JSON blob (marketplace-publish.md §3).
+                const installSpec = {};
+                if (parsed.entitlements)
+                    installSpec.entitlements = parsed.entitlements;
+                if (parsed.ownerGrants)
+                    installSpec.ownerGrants = parsed.ownerGrants;
+                if (parsed.provides)
+                    installSpec.provides = parsed.provides;
+                if (parsed.requires)
+                    installSpec.requires = parsed.requires;
+                const installSpecJson = Object.keys(installSpec).length ? JSON.stringify(installSpec) : null;
                 const existing = await this.cp.readVertical(parsed.slug);
                 if (existing) {
                     // Idempotent on an identical registration; a changed source OR owner conflicts —
                     // claim-on-first-push (builder-plane.md): a slug's owner is fixed at first push.
                     if (existing.source === parsed.source &&
                         existing.name === parsed.name &&
-                        existing.owner_tenant === parsed.ownerTenant)
+                        existing.owner_tenant === parsed.ownerTenant) {
+                        // The env-spec evolves with the manifest — refresh it on an otherwise-identical
+                        // re-registration so a declared config change propagates without a conflict.
+                        // For BUILTIN verticals `listed` is seed metadata too (derived from the catalog's
+                        // `connected` flag), so it refreshes alongside — without this, rows registered
+                        // before they were listable stay unlisted forever (the empty-marketplace bug).
+                        // A pushed vertical's `listed` is the staff publish decision — never touched.
+                        await this.cp.updateVerticalManifestMeta(parsed.slug, envSpecJson, installSpecJson, parsed.source === 'builtin' ? (parsed.listed ? 1 : 0) : null);
                         return;
+                    }
                     if (existing.owner_tenant !== parsed.ownerTenant) {
                         throw new Error(`vertical '${parsed.slug}' is owned by ${existing.owner_tenant ?? 'the platform'}, not ${parsed.ownerTenant ?? 'the platform'}`);
                     }
                     throw new Error(`vertical '${parsed.slug}' is already registered as ${existing.source}`);
                 }
-                await this.cp.insertVertical(parsed.slug, parsed.name, parsed.source, parsed.ownerTenant, new Date().toISOString());
+                await this.cp.insertVertical(parsed.slug, parsed.name, parsed.source, parsed.ownerTenant, envSpecJson, installSpecJson, parsed.listed ? 1 : 0, new Date().toISOString());
                 await this.recordAdmin(actor, 'registerVertical', { tenantId: null }, null, parsed);
             },
             listVerticals: async (actor) => {
@@ -674,24 +825,90 @@ export class CloudflareScopeHost {
             },
             publishVersion: async (actor, input) => {
                 const parsed = publishVersionInput.parse(input);
-                if (!(await this.cp.readVertical(parsed.verticalSlug))) {
+                const owning = await this.cp.readVertical(parsed.verticalSlug);
+                if (!owning) {
                     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);
+                // Lands PENDING — a push is not a deploy — except for a PRIVATE vertical
+                // (tenant-owned, not listed), whose blast radius is its own tenant: there the
+                // sandbox contract is the gate and the version self-admits, noted so the
+                // publish seam can tell a staff vouch from this shortcut.
+                const selfAdmits = owning.owner_tenant !== null && !owning.listed;
+                await this.cp.insertVersion({
+                    ...parsed,
+                    admission: selfAdmits ? 'admitted' : 'pending',
+                    admissionNote: selfAdmits ? AUTO_ADMISSION_NOTE : null,
+                    createdAt: new Date().toISOString(),
+                });
+                await this.recordAdmin(actor, 'publishVersion', { tenantId: null }, null, {
+                    ...parsed,
+                    admission: selfAdmits ? 'admitted' : 'pending',
+                });
             },
             listVersions: async (actor, verticalSlug) => {
                 const rows = await this.cp.listVersions(verticalSlug);
                 await this.recordAccess(actor, 'listVersions', {}, { verticalSlug }, rows.length);
                 return rows.map(mapVersion);
             },
+            setVerticalListed: async (actor, slug, listed) => {
+                const existing = await this.cp.readVertical(slug);
+                if (!existing)
+                    throw new Error(`unknown vertical '${slug}'`);
+                // Listing is the moment other tenants start trusting this code, so the
+                // version they would install must carry a real staff vouch — an auto-admitted
+                // prod version has never been read by anyone but its author.
+                if (listed) {
+                    const prod = await this.cp.readChannel(slug, 'prod');
+                    const prodVersion = prod ? await this.cp.readVersion(prod.version_id) : undefined;
+                    if (prodVersion?.admission_note === AUTO_ADMISSION_NOTE) {
+                        throw new Error(`vertical '${slug}' prod version ${prodVersion.id} is auto-admitted (private self-serve) — ` +
+                            `a staff admit must vouch for it before listing`);
+                    }
+                }
+                await this.cp.updateVerticalListed(slug, listed ? 1 : 0); // also resolves any pending request
+                await this.recordAdmin(actor, 'setVerticalListed', { tenantId: null }, { listed: !!existing.listed }, { listed });
+            },
+            requestPublish: async (actor, slug) => {
+                const existing = await this.cp.readVertical(slug);
+                if (!existing)
+                    throw new Error(`unknown vertical '${slug}'`);
+                await this.cp.updateVerticalPublishRequest(slug, new Date().toISOString());
+                await this.recordAdmin(actor, 'requestPublish', { tenantId: null }, null, { slug });
+            },
+            setVerticalInstallsBlocked: async (actor, slug, blocked) => {
+                const existing = await this.cp.readVertical(slug);
+                if (!existing)
+                    throw new Error(`unknown vertical '${slug}'`);
+                await this.cp.updateVerticalInstallsBlocked(slug, blocked ? 1 : 0);
+                await this.recordAdmin(actor, 'setVerticalInstallsBlocked', { tenantId: null }, { installsBlocked: !!existing.installs_blocked }, { installsBlocked: blocked });
+            },
+            deleteVertical: async (actor, slug) => {
+                const existing = await this.cp.readVertical(slug);
+                if (!existing)
+                    throw new Error(`unknown vertical '${slug}'`);
+                // Refuse while any scope is bound: a deleted registry row would strand those
+                // scopes' version pins and routing. Deployed dispatch scripts are NOT reaped
+                // here — they become orphans for the cleanup script (#248).
+                const bound = await this.cp.countScopesForVertical(slug);
+                if (bound > 0) {
+                    throw new Error(`vertical '${slug}' still backs ${bound} scope(s) — delete or rebind them first`);
+                }
+                await this.cp.deleteVertical(slug);
+                await this.recordAdmin(actor, 'deleteVertical', { tenantId: null }, { slug, source: existing.source, ownerTenant: existing.owner_tenant }, null);
+            },
             admitVersion: async (actor, versionId) => {
                 const v = await this.cp.readVersion(versionId);
                 if (!v)
                     throw new Error(`unknown version ${versionId}`);
-                if (v.admission === 'admitted')
+                if (v.admission === 'admitted') {
+                    // Idempotent — except an AUTO-admitted version, which this upgrades to a
+                    // manual vouch by clearing the note (what the publish seam requires).
+                    if (v.admission_note !== AUTO_ADMISSION_NOTE)
+                        return;
+                    await this.cp.setAdmission(versionId, 'admitted', null);
+                    await this.recordAdmin(actor, 'admitVersion', { tenantId: null }, { admission: v.admission, note: v.admission_note }, { admission: 'admitted', note: null });
                     return;
+                }
                 if (v.admission === 'rejected') {
                     throw new Error(`version ${versionId} was rejected — publish a new one`);
                 }
@@ -735,7 +952,42 @@ export class CloudflareScopeHost {
                             `${incoming.migration_digest}) — acknowledge it explicitly to promote`);
                     }
                 }
-                await this.cp.setChannel(verticalSlug, channel, versionId, new Date().toISOString());
+                const promotedAt = new Date().toISOString();
+                await this.cp.setChannel(verticalSlug, channel, versionId, promotedAt);
+                // The timeline row: what makes rollback a choice among recorded moments, and
+                // `at` the PITR anchor a data rollback would rewind to.
+                await this.cp.insertChannelHistory({
+                    id: ulid(),
+                    vertical_slug: verticalSlug,
+                    channel,
+                    version_id: versionId,
+                    from_version_id: outgoing?.id ?? null,
+                    actor,
+                    at: promotedAt,
+                });
+                // For a PRIVATE vertical, prod IS what the owner's apps run: re-point the
+                // owning tenant's live scopes in the same act, so merge-to-main (push +
+                // promote) is a complete deploy and a rollback promote reaches the running
+                // app. D-30's lockstep concern is a SHARED vertical's many tenants, which a
+                // private vertical cannot have — this fires for no one else. Snapshots and
+                // forks (forked_from set) keep their frontier untouched, and a rebind that
+                // crosses a migration digest snapshots first (fork-before-promote, §4).
+                if (channel === 'prod') {
+                    const owning = await this.cp.readVertical(verticalSlug);
+                    if (owning && owning.owner_tenant !== null && !owning.listed) {
+                        const bound = (await this.cp.listScopes({ tenantId: owning.owner_tenant, vertical: verticalSlug, status: ['active'] })).filter((s) => !s.forked_from);
+                        for (const s of bound) {
+                            if (s.vertical_version_id === versionId)
+                                continue;
+                            const prev = s.vertical_version_id ? await this.cp.readVersion(s.vertical_version_id) : undefined;
+                            if (prev && prev.migration_digest !== incoming.migration_digest) {
+                                await this.snapshotScope(actor, s.tenant_id, s.scope_id);
+                            }
+                            await this.cp.bindScopeVersion(s.scope_id, versionId, verticalSlug);
+                            await this.recordAdmin(actor, 'bindScopeVersion', { tenantId: s.tenant_id, scopeId: s.scope_id }, prev ? { versionId: prev.id, version: prev.version } : null, { versionId, vertical: verticalSlug, version: incoming.version, via: 'promoteVersion' });
+                        }
+                    }
+                }
                 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) => {
@@ -748,7 +1000,20 @@ export class CloudflareScopeHost {
                     updatedAt: r.updated_at,
                 }));
             },
-            bindScopeVersion: async (actor, tenantId, scopeId, versionId) => {
+            listChannelHistory: async (actor, verticalSlug, channel) => {
+                const rows = await this.cp.listChannelHistory(verticalSlug, channel);
+                await this.recordAccess(actor, 'listChannelHistory', {}, { verticalSlug, channel }, rows.length);
+                return rows.map((r) => channelHistoryEntry.parse({
+                    id: r.id,
+                    verticalSlug: r.vertical_slug,
+                    channel: r.channel,
+                    versionId: r.version_id,
+                    fromVersionId: r.from_version_id,
+                    actor: r.actor,
+                    at: r.at,
+                }));
+            },
+            bindScopeVersion: async (actor, tenantId, scopeId, versionId, opts) => {
                 const v = await this.cp.readVersion(versionId);
                 if (!v)
                     throw new Error(`unknown version ${versionId}`);
@@ -759,6 +1024,14 @@ export class CloudflareScopeHost {
                 const scope = await this.cp.getScopeRecord(tenantId, scopeId);
                 if (!scope)
                     throw new Error(`unknown scope ${scopeId} in tenant ${tenantId}`);
+                // Fork-before-promote (§4): snapshot the pre-migration data if this rebind
+                // crosses a migration boundary. Gated on a real digest change and on opt-in.
+                if (opts?.snapshot && scope.vertical_version_id) {
+                    const outgoing = await this.cp.readVersion(scope.vertical_version_id);
+                    if (outgoing && outgoing.migration_digest !== v.migration_digest) {
+                        await this.snapshotScope(actor, tenantId, scopeId);
+                    }
+                }
                 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,
@@ -848,6 +1121,46 @@ export class CloudflareScopeHost {
                 await this.recordAccess(actor, 'getScopeRecord', { tenantId, scopeId }, null, row ? 1 : 0);
                 return row ? mapScope(row) : undefined;
             },
+            listScopeTables: async (actor, tenantId, scopeId) => {
+                // K-3 cross-check on the shared directory BEFORE reaching the scope DO: a pair
+                // that does not resolve is unreachable, never another tenant's database.
+                const row = await this.cp.getScopeRecord(tenantId, scopeId);
+                if (!row)
+                    throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+                const tables = await this.scopeStub(scopeId).introspectTables();
+                await this.recordAccess(actor, 'listScopeTables', { tenantId, scopeId }, null, tables.length);
+                return tables;
+            },
+            readScopeTable: async (actor, tenantId, scopeId, input) => {
+                const row = await this.cp.getScopeRecord(tenantId, scopeId);
+                if (!row)
+                    throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+                const page = await this.scopeStub(scopeId).introspectTable(input.table, input.limit, input.offset);
+                await this.recordAccess(actor, 'readScopeTable', { tenantId, scopeId }, { table: input.table, limit: page.limit, offset: page.offset }, page.rows.length);
+                return page;
+            },
+            queryScope: async (actor, tenantId, scopeId, input) => {
+                const row = await this.cp.getScopeRecord(tenantId, scopeId);
+                if (!row)
+                    throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+                const result = await this.scopeStub(scopeId).introspectQuery(input.sql);
+                // The statement is the logged argument: the access log is the evidence trail,
+                // and for a console read the SQL is the whole story.
+                await this.recordAccess(actor, 'queryScope', { tenantId, scopeId }, { sql: input.sql }, result.rows.length);
+                return result;
+            },
+            exportScope: async (actor, tenantId, scopeId) => {
+                // K-3 cross-check on the shared directory BEFORE reaching the scope DO, exactly
+                // as the introspection reads: an unresolved pair is unreachable, never another
+                // tenant's database. The DO returns the tables; the coordinator, which knows the
+                // scope's identity, stamps the dump.
+                const row = await this.cp.getScopeRecord(tenantId, scopeId);
+                if (!row)
+                    throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
+                const tables = await this.scopeStub(scopeId).exportDump();
+                await this.recordAccess(actor, 'exportScope', { tenantId, scopeId }, null, tables.length);
+                return { tenantId, scopeId, capturedAt: new Date().toISOString(), tables };
+            },
             activateScope: async (actor, tenantId, scopeId) => {
                 // Idempotent on `active`, unaudited because nothing changed. Provisioning is
                 // a two-phase creation that the reconciliation sweep re-runs (K-31), so a