@substrat-run/adapter-sqlite 0.39.0 → 0.41.0

package/dist/index.js

@@ -1,8 +1,8 @@
-import { mkdirSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import Database from 'better-sqlite3';
-import { accessLogEntry, adminLogEntry, createTenantInput, domainEvent, domainEventInput, entitlementGrant, entitlementGrantInput, eventId, platformRequestInput, platformRequestId, platformRequest, MAX_PENDING_PLATFORM_REQUESTS, identityLink, identityPool, instant, connection, connectionGrant, connectionSecret, systemGrant, subjectRef, createConnectionInput, moduleManifest, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, routeTarget, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, objectRef, grantRefFromProof, org as orgSchema, orgMembership, principalId, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, SCOPE_TABLE_PAGE_DEFAULT, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, verticalServingState, } from '@substrat-run/contracts';
-import { asPrincipal, assertReadOnlyQuery, resolveScopeRecord, ulid, backoffAt, resolveRetryPolicy, unconfiguredSecretBox, PermissionDenied, } from '@substrat-run/kernel';
+import { accessLogEntry, adminLogEntry, ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, createTenantInput, domainEvent, domainEventInput, entitlementGrant, entitlementGrantInput, eventId, platformRequestInput, platformRequestId, platformRequest, MAX_PENDING_PLATFORM_REQUESTS, identityLink, identityPool, instant, connection, connectionGrant, connectionSecret, systemGrant, subjectRef, createConnectionInput, moduleManifest, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, routeTarget, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, objectRef, grantRefFromProof, org as orgSchema, orgMembership, principalId, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, SCOPE_TABLE_PAGE_DEFAULT, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, verticalServingState, } from '@substrat-run/contracts';
+import { asPrincipal, assertAllowed, assertReadOnlyQuery, attachmentBlobKey, resolveScopeRecord, ulid, backoffAt, resolveRetryPolicy, unconfiguredSecretBox, PermissionDenied, } from '@substrat-run/kernel';
 import { ScopeActor } from './actor.js';
 import { createTupleChecker } from './checker.js';
 const KERNEL_DDL = `
@@ -88,6 +88,24 @@ const KERNEL_DDL = `
     next_attempt_at TEXT,
     PRIMARY KEY (event_id, consumer_module)
   );
+  -- Attachment metadata facts (#473): one row per object in the per-tenant blob store,
+  -- keyed to the owning entity a module manifest declared as an attachmentTarget. Lives
+  -- INSIDE the scope database on purpose — scope pull / restore / PITR carry the rows
+  -- like any other scope fact; sha256 is the integrity witness for the bytes outside.
+  CREATE TABLE IF NOT EXISTS _substrat_attachments (
+    id TEXT PRIMARY KEY,
+    entity_type TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    filename TEXT NOT NULL,
+    content_type TEXT NOT NULL,
+    size INTEGER NOT NULL,
+    sha256 TEXT NOT NULL,
+    visibility TEXT NOT NULL,
+    created_by TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS _substrat_attachments_entity
+    ON _substrat_attachments (entity_type, entity_id);
 `;
 /** Row → contract shape. Never reads the secrets table — that is the point of the split. */
 const toConnection = (r) => connection.parse({
@@ -139,6 +157,26 @@ const mapHostname = (r) => hostnameBinding.parse({
     customHostnameId: r.custom_hostname_id,
     validationRecords: r.validation_records ? JSON.parse(r.validation_records) : [],
 });
+/**
+ * Fold keyset page params (contracts pagination.ts) into an in-progress WHERE
+ * build and return the `ORDER BY … [LIMIT ?]` tail. The cursor is EXCLUSIVE —
+ * strictly after it ascending, strictly before it descending — and an unset
+ * limit stays unbounded: internal callers mean "everything", and a silent cap
+ * would let them mistake a page for the whole set.
+ */
+function keysetTail(where, params, key, page, defaultOrder = 'asc') {
+    const order = (page?.order ?? defaultOrder) === 'desc' ? 'DESC' : 'ASC';
+    if (page?.cursor) {
+        where.push(order === 'DESC' ? `${key} < ?` : `${key} > ?`);
+        params.push(page.cursor);
+    }
+    let tail = ` ORDER BY ${key} ${order}`;
+    if (page?.limit !== undefined) {
+        tail += ' LIMIT ?';
+        params.push(page.limit);
+    }
+    return tail;
+}
 /** Map a stored platform-request row to the `PlatformRequest` contract shape (JSON columns parsed). */
 function rowToPlatformRequest(r) {
     return platformRequest.parse({
@@ -174,6 +212,8 @@ export class SqliteScopeHost {
     /** operation names whose default binding some manifest withdrew (K-17). */
     withdrawn = new Map(); // operation → withdrawing module
     relations = new Map();
+    /** entityType → the declared attachment gate (#473): read key + write key (default: read). */
+    attachmentTargets = new Map();
     /** operation name → its owning module's entitlementKey (§4.3 gate). */
     operationEntitlement = new Map();
     roles = new Map(); // 'tenantId/roleKey'
@@ -291,6 +331,18 @@ export class SqliteScopeHost {
         created_at TEXT NOT NULL,
         PRIMARY KEY (tenant_id, vertical, binding)
       );
+      -- Per-tenant blob stores (#473) — the tenant_stores twin for attachment bytes.
+      -- ref is the opaque handle: a per-tenant directory token here, an R2 bucket name
+      -- on Cloudflare. Same idempotency + reap ledger role.
+      CREATE TABLE IF NOT EXISTS blob_stores (
+        tenant_id  TEXT NOT NULL,
+        vertical   TEXT NOT NULL,
+        binding    TEXT NOT NULL,
+        kind       TEXT NOT NULL,
+        ref        TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (tenant_id, vertical, binding)
+      );
       -- 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.
@@ -458,11 +510,15 @@ export class SqliteScopeHost {
         created_at           TEXT NOT NULL,
         revoked_at           TEXT
       );
-      -- One LIVE connection per (tenant, vertical, provider). Revoked rows are
-      -- kept as evidence (K-21's tombstone rule) and must not block a successor,
-      -- which is why the index is partial rather than a table constraint.
-      CREATE UNIQUE INDEX IF NOT EXISTS _substrat_connections_live
-        ON _substrat_connections (tenant_id, vertical, provider)
+      -- One LIVE connection per (tenant, vertical, provider, account). Revoked
+      -- rows are kept as evidence (K-21's tombstone rule) and must not block a
+      -- successor, which is why the index is partial rather than a table
+      -- constraint. The account leg is COALESCEd so providers that never set an
+      -- external_account_ref keep the original singleton semantics (all their
+      -- NULLs collide on ''), while a multi-namespace provider (GitHub) holds
+      -- one live connection PER account — the Vercel git-namespace shape.
+      CREATE UNIQUE INDEX IF NOT EXISTS _substrat_connections_live_account
+        ON _substrat_connections (tenant_id, vertical, provider, COALESCE(external_account_ref, ''))
         WHERE revoked_at IS NULL;
       -- Sealed credentials, in their own table so that reading a connection's
       -- METADATA never touches ciphertext. Nothing above SecretBox sees plaintext.
@@ -693,6 +749,22 @@ export class SqliteScopeHost {
             parents.add(rel.parentType);
             this.relations.set(rel.entityType, parents);
         }
+        // Attachment targets (#473): entityType → the permission gate the kernel's attachment
+        // surface enforces. Two modules re-declaring the same entityType with the SAME gate is
+        // tolerated (idempotent); with different gates it is refused — ambiguous authority
+        // over who may read an entity's attachments must not depend on registration order.
+        for (const target of manifest.attachmentTargets) {
+            const gate = {
+                read: target.readPermission,
+                write: target.writePermission ?? target.readPermission,
+            };
+            const existing = this.attachmentTargets.get(target.entityType);
+            if (existing && (existing.read !== gate.read || existing.write !== gate.write)) {
+                throw new Error(`conflicting attachmentTargets for '${target.entityType}': ` +
+                    `(${existing.read}/${existing.write}) vs (${gate.read}/${gate.write})`);
+            }
+            this.attachmentTargets.set(target.entityType, gate);
+        }
         // WITHDRAWAL (K-17): suppress another module's default binding. Order
         // independent — a manifest may withdraw an operation whose module has not
         // registered yet (recorded here, skipped at defineOperation) or one already
@@ -864,6 +936,289 @@ export class SqliteScopeHost {
         }
         return db;
     }
+    async provisionBlobStore(actor, input) {
+        // Same fail-closed tenant gate and (tenant, vertical, binding) idempotency as
+        // provisionTenantStore (#301) — the blob store is the fourth store shape, not a
+        // new lifecycle (#473).
+        const tenantRow = this.directory
+            .prepare('SELECT status FROM tenants WHERE tenant_id = ?')
+            .get(input.tenantId);
+        if (!tenantRow) {
+            throw new Error(`cannot provision blob store under unknown tenant: ${input.tenantId}`);
+        }
+        if (tenantRow.status !== 'active') {
+            throw new Error(`cannot provision blob store under non-active tenant (status: ${tenantRow.status}): ${input.tenantId}`);
+        }
+        const existing = this.directory
+            .prepare('SELECT ref FROM blob_stores WHERE tenant_id = ? AND vertical = ? AND binding = ?')
+            .get(input.tenantId, input.vertical, input.binding);
+        if (existing) {
+            return { binding: input.binding, kind: 'blob', ref: existing.ref };
+        }
+        // The opaque `ref` is a bare directory name under `dir`, prefixed `blob__` so it can
+        // never collide with a scope DB or a tenant store file. On Cloudflare the ref is an
+        // R2 bucket name; here it is a per-tenant directory — the same file-per-unit grain
+        // the scope DBs use, so the whole path runs in dev/CI without Cloudflare.
+        const safeVertical = input.vertical.replace(/[^A-Za-z0-9_-]+/g, '-');
+        const ref = `blob__${input.tenantId}__${safeVertical}__${input.binding}__${ulid()}`;
+        mkdirSync(join(this.dir, ref), { recursive: true });
+        this.directory
+            .prepare(`INSERT INTO blob_stores (tenant_id, vertical, binding, kind, ref, created_at)
+         VALUES (?, ?, ?, 'blob', ?, ?)`)
+            .run(input.tenantId, input.vertical, input.binding, ref, new Date().toISOString());
+        this.recordAdmin(actor, 'provisionBlobStore', { tenantId: input.tenantId, vertical: input.vertical }, null, { binding: input.binding, kind: 'blob', ref });
+        return { binding: input.binding, kind: 'blob', ref };
+    }
+    /** A `TenantBlobStore` over the per-tenant directory a `ref` names (#473). Keys are
+     *  platform-derived (`attachmentBlobKey`), but both `ref` and key are still guarded at
+     *  the open boundary (parse, don't trust) so neither can escape `this.dir`. */
+    blobStore(ref) {
+        if (ref.includes('/') || ref.includes('\\') || ref.includes('..')) {
+            throw new Error(`invalid blob-store ref (must be a bare directory name): ${ref}`);
+        }
+        const root = join(this.dir, ref);
+        const resolveKey = (key) => {
+            if (key.startsWith('/') || key.includes('\\') || key.split('/').some((s) => s === '' || s === '.' || s === '..')) {
+                throw new Error(`invalid blob key: ${key}`);
+            }
+            return join(root, key);
+        };
+        const walk = (d, rel, out) => {
+            if (!existsSync(d))
+                return;
+            for (const e of readdirSync(d, { withFileTypes: true })) {
+                const r = rel ? `${rel}/${e.name}` : e.name;
+                if (e.isDirectory())
+                    walk(join(d, e.name), r, out);
+                else if (!e.name.endsWith('.meta'))
+                    out.push(r);
+            }
+        };
+        return {
+            put: async (key, body, opts) => {
+                const p = resolveKey(key);
+                mkdirSync(dirname(p), { recursive: true });
+                writeFileSync(p, body);
+                writeFileSync(`${p}.meta`, JSON.stringify({ contentType: opts?.contentType ?? null }));
+            },
+            get: async (key) => {
+                const p = resolveKey(key);
+                if (!existsSync(p))
+                    return null;
+                const body = new Uint8Array(readFileSync(p));
+                let contentType;
+                try {
+                    const meta = JSON.parse(readFileSync(`${p}.meta`, 'utf8'));
+                    contentType = meta.contentType ?? undefined;
+                }
+                catch {
+                    // No sidecar (or unreadable): the caller falls back to the metadata row.
+                }
+                return contentType !== undefined ? { body, contentType } : { body };
+            },
+            delete: async (key) => {
+                const p = resolveKey(key);
+                rmSync(p, { force: true });
+                rmSync(`${p}.meta`, { force: true });
+            },
+            list: async (prefix) => {
+                const out = [];
+                walk(root, '', out);
+                return out.filter((k) => k.startsWith(prefix)).sort();
+            },
+        };
+    }
+    /** Resolve the blob store that carries a scope's attachments (#473): the platform-minted
+     *  store for (tenant, the scope's vertical). Fails loudly when none was provisioned —
+     *  the K-31 posture — and refuses ambiguity when several are, unless one is named
+     *  ATTACHMENTS (the convention the deploy vocabulary documents). */
+    attachmentStore(tenantId, vertical) {
+        if (!vertical) {
+            throw new Error('scope runs no vertical; attachments need the vertical\'s platform blob store (#473)');
+        }
+        const rows = this.directory
+            .prepare('SELECT binding, ref FROM blob_stores WHERE tenant_id = ? AND vertical = ? ORDER BY binding')
+            .all(tenantId, vertical);
+        if (rows.length === 0) {
+            throw new Error(`no blob store provisioned for (${tenantId}, ${vertical}) — declare runtimeNeeds.blobStores ` +
+                `and provision it in the tenant lifecycle (provisionBlobStore, #473)`);
+        }
+        const chosen = rows.length === 1 ? rows[0] : rows.find((r) => r.binding === 'ATTACHMENTS');
+        if (!chosen) {
+            throw new Error(`multiple blob stores provisioned for (${tenantId}, ${vertical}); name the one that ` +
+                `carries attachments ATTACHMENTS`);
+        }
+        return this.blobStore(chosen.ref);
+    }
+    async attachments(principal, tenantId, scopeId) {
+        // Same fail-closed (tenantId, scopeId) pair + lifecycle gates + lazy-migration
+        // retry as minting a stub — getScope IS that gate, so go through it.
+        await this.getScope(principal, tenantId, scopeId);
+        const rt = this.runtime(tenantId, scopeId);
+        const scopeRow = this.directory
+            .prepare('SELECT vertical FROM scopes WHERE scope_id = ?')
+            .get(scopeId);
+        const store = this.attachmentStore(tenantId, scopeRow?.vertical ?? null);
+        return this.buildAttachments(rt, asPrincipal(principal), store);
+    }
+    /**
+     * The attachment surface (#473) — `attachmentTargets` consumed at last. Metadata facts
+     * live in `_substrat_attachments` inside the scope DB and move under the scope's strict
+     * serialization, permission-checked as the ambient principal with the owning entity as
+     * the per-entity ref, with a spine event in the same transaction. Bytes go straight to
+     * the per-tenant blob store — never through the scope pipe (the issue's point).
+     */
+    buildAttachments(rt, subject, store) {
+        const targetGate = (entityType) => {
+            const gate = this.attachmentTargets.get(entityType);
+            if (!gate) {
+                throw new Error(`no registered module declares '${entityType}' in attachmentTargets — attachments bind ` +
+                    `only to declared entity types`);
+            }
+            return gate;
+        };
+        const rowToRecord = (row) => attachmentRecord.parse({
+            id: row.id,
+            entity: { entityType: row.entity_type, entityId: row.entity_id },
+            filename: row.filename,
+            contentType: row.content_type,
+            size: row.size,
+            sha256: row.sha256,
+            visibility: row.visibility,
+            createdBy: row.created_by,
+            createdAt: row.created_at,
+        });
+        const sha256Hex = async (body) => {
+            const digest = await globalThis.crypto.subtle.digest('SHA-256', body);
+            return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+        };
+        // One attachment mutation/read = one serialized scope task, transactional exactly
+        // like an operation invoke (including K-35 denial recording and prompt dispatch of
+        // the events it emitted).
+        const guarded = (operation, fn) => rt.actor.enqueue(async () => {
+            const ctx = this.operationContext(rt, subject);
+            rt.db.exec('BEGIN IMMEDIATE');
+            let result;
+            try {
+                result = await fn(ctx);
+                rt.db.exec('COMMIT');
+            }
+            catch (err) {
+                rt.db.exec('ROLLBACK');
+                if (err instanceof PermissionDenied)
+                    this.recordDenial(rt, subject, operation, err);
+                throw err;
+            }
+            await this.dispatch(rt);
+            await this.dispatchExecutors(rt);
+            return result;
+        });
+        return {
+            upload: async (input) => {
+                const gate = targetGate(input.entity.entityType);
+                const id = ulid();
+                const key = attachmentBlobKey(rt.scopeId, id);
+                const record = attachmentRecord.parse({
+                    id,
+                    entity: input.entity,
+                    filename: input.filename,
+                    contentType: input.contentType,
+                    size: input.body.byteLength,
+                    sha256: await sha256Hex(input.body),
+                    visibility: input.visibility,
+                    createdBy: subject.id,
+                    createdAt: new Date().toISOString(),
+                });
+                // Bytes first, row second: a crash between the two leaves an orphaned object
+                // (harmless, GC-able via list), never a row without bytes. A refused check
+                // compensates the object away below.
+                await store.put(key, input.body, { contentType: input.contentType });
+                try {
+                    return await guarded('attachments.upload', async (ctx) => {
+                        assertAllowed(await ctx.check(gate.write, input.entity));
+                        rt.db
+                            .prepare(`INSERT INTO _substrat_attachments
+                   (id, entity_type, entity_id, filename, content_type, size, sha256,
+                    visibility, created_by, created_at)
+                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                            .run(record.id, record.entity.entityType, record.entity.entityId, record.filename, record.contentType, record.size, record.sha256, record.visibility, record.createdBy, record.createdAt);
+                        ctx.emit({
+                            type: ATTACHMENT_ADDED,
+                            schemaVersion: 1,
+                            entity: input.entity,
+                            piiClass: 'none',
+                            payload: { attachment: record },
+                        });
+                        return record;
+                    });
+                }
+                catch (err) {
+                    await store.delete(key).catch(() => { });
+                    throw err;
+                }
+            },
+            list: async (entity) => {
+                const gate = targetGate(entity.entityType);
+                return guarded('attachments.list', async (ctx) => {
+                    assertAllowed(await ctx.check(gate.read, entity));
+                    const rows = rt.db
+                        .prepare(`SELECT * FROM _substrat_attachments WHERE entity_type = ? AND entity_id = ?
+               ORDER BY id DESC`)
+                        .all(entity.entityType, entity.entityId);
+                    return rows.map(rowToRecord);
+                });
+            },
+            open: async (attachmentId) => {
+                const record = await guarded('attachments.open', async (ctx) => {
+                    const row = rt.db
+                        .prepare('SELECT * FROM _substrat_attachments WHERE id = ?')
+                        .get(attachmentId);
+                    if (!row)
+                        return null;
+                    const gate = targetGate(row.entity_type);
+                    assertAllowed(await ctx.check(gate.read, { entityType: row.entity_type, entityId: row.entity_id }));
+                    return rowToRecord(row);
+                });
+                if (!record)
+                    return null;
+                const obj = await store.get(attachmentBlobKey(rt.scopeId, record.id));
+                if (!obj) {
+                    throw new Error(`attachment ${record.id}: bytes missing from the blob store — the metadata row ` +
+                        `survived something the object did not (rewind/reap); see the #473 integrity notes`);
+                }
+                if ((await sha256Hex(obj.body)) !== record.sha256) {
+                    throw new Error(`attachment ${record.id}: bytes do not match the recorded sha256`);
+                }
+                return { record, body: obj.body, contentType: obj.contentType ?? record.contentType };
+            },
+            remove: async (attachmentId) => {
+                const removed = await guarded('attachments.remove', async (ctx) => {
+                    const row = rt.db
+                        .prepare('SELECT * FROM _substrat_attachments WHERE id = ?')
+                        .get(attachmentId);
+                    if (!row)
+                        return null;
+                    const gate = targetGate(row.entity_type);
+                    assertAllowed(await ctx.check(gate.write, { entityType: row.entity_type, entityId: row.entity_id }));
+                    rt.db.prepare('DELETE FROM _substrat_attachments WHERE id = ?').run(attachmentId);
+                    const record = rowToRecord(row);
+                    ctx.emit({
+                        type: ATTACHMENT_REMOVED,
+                        schemaVersion: 1,
+                        entity: record.entity,
+                        piiClass: 'none',
+                        payload: { attachment: record },
+                    });
+                    return record;
+                });
+                // Row (and event) first, bytes second: at worst an orphaned object, never a
+                // dangling row.
+                if (removed)
+                    await store.delete(attachmentBlobKey(rt.scopeId, removed.id)).catch(() => { });
+                return removed;
+            },
+        };
+    }
     async importScope(actor, input, dump) {
         // Create the destination scope (directory row + storage). Its migration step
         // creates some tables; the dump then replaces them wholesale, so the end state
@@ -1006,7 +1361,7 @@ export class SqliteScopeHost {
             kind: rec.kind,
         });
     }
-    async getScope(principal, tenantId, scopeId) {
+    async getScope(principal, tenantId, scopeId, options) {
         const row = this.directory
             .prepare('SELECT tenant_id, status FROM scopes WHERE scope_id = ?')
             .get(scopeId);
@@ -1045,7 +1400,7 @@ export class SqliteScopeHost {
             // the migration's own message, which is the one an operator needs.
             throw new Error(`scope not active (status: ${row.status}): ${scopeId}`);
         }
-        return this.buildStub(tenantId, scopeId, rt, asPrincipal(principal));
+        return this.buildStub(tenantId, scopeId, rt, asPrincipal(principal), options);
     }
     /**
      * A scope stub whose authority is a CONNECTION (#97).
@@ -1190,12 +1545,12 @@ export class SqliteScopeHost {
         return report;
     }
     /** The stub body, shared by the principal and connection doors. */
-    buildStub(tenantId, scopeId, rt, subject) {
+    buildStub(tenantId, scopeId, rt, subject, options) {
         const operations = this.operations;
         return {
             tenantId,
             scopeId,
-            invoke: (operation, input) => {
+            invoke: async (operation, input) => {
                 const handler = operations.get(operation);
                 if (!handler)
                     return Promise.reject(new Error(`unknown operation: ${operation}`));
@@ -1207,10 +1562,14 @@ export class SqliteScopeHost {
                 if (requiredKey && !this.tenantHoldsEntitlement(tenantId, requiredKey)) {
                     return Promise.reject(new Error(`operation not entitled: ${operation} — tenant does not hold '${requiredKey}'`));
                 }
-                return rt.actor.enqueue(async () => {
+                // #458: per-invoke tally of `ctx.requestPlatform` calls. Reported to the
+                // harness only after the enqueue task resolves — i.e. after COMMIT — so a
+                // rolled-back intent never signals.
+                const signals = { platformRequests: 0 };
+                const invoked = await rt.actor.enqueue(async () => {
                     // Fresh per operation: the context carries the K-34 authorization accumulator,
                     // which must not leak across operations (invokes are serialized per scope).
-                    const ctx = this.operationContext(rt, subject);
+                    const ctx = this.operationContext(rt, subject, undefined, signals);
                     const clonedInput = structuredClone(input);
                     rt.db.exec('BEGIN IMMEDIATE');
                     let result;
@@ -1238,6 +1597,9 @@ export class SqliteScopeHost {
                     await this.dispatchExecutors(rt);
                     return structuredClone(result);
                 });
+                if (signals.platformRequests > 0)
+                    options?.onPlatformRequests?.(signals.platformRequests);
+                return invoked;
             },
         };
     }
@@ -1831,9 +2193,24 @@ export class SqliteScopeHost {
                     where.push('source = ?');
                     params.push(filter.source);
                 }
-                const sql = 'SELECT tenant_id, role_key, permissions, source FROM _substrat_roles' +
+                const order = (filter?.order ?? 'asc') === 'desc' ? 'DESC' : 'ASC';
+                if (filter?.cursor) {
+                    // Composite sort key `${tenantId}|${roleKey}` (pagination.ts) — the
+                    // tenant id is a ULID and never contains '|', so split on the FIRST.
+                    const split = filter.cursor.indexOf('|');
+                    const afterTenant = split === -1 ? filter.cursor : filter.cursor.slice(0, split);
+                    const afterKey = split === -1 ? '' : filter.cursor.slice(split + 1);
+                    const cmp = order === 'DESC' ? '<' : '>';
+                    where.push(`(tenant_id ${cmp} ? OR (tenant_id = ? AND role_key ${cmp} ?))`);
+                    params.push(afterTenant, afterTenant, afterKey);
+                }
+                let sql = 'SELECT tenant_id, role_key, permissions, source FROM _substrat_roles' +
                     (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
-                    ' ORDER BY tenant_id, role_key';
+                    ` ORDER BY tenant_id ${order}, role_key ${order}`;
+                if (filter?.limit !== undefined) {
+                    sql += ' LIMIT ?';
+                    params.push(filter.limit);
+                }
                 const rows = this.directory.prepare(sql).all(...params);
                 // 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
@@ -2047,10 +2424,11 @@ export class SqliteScopeHost {
                     where.push('status = ?');
                     params.push(filter.status);
                 }
+                const tail = keysetTail(where, params, 'hostname', filter);
                 let sql = 'SELECT * FROM hostnames';
                 if (where.length)
                     sql += ` WHERE ${where.join(' AND ')}`;
-                sql += ' ORDER BY hostname';
+                sql += tail;
                 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);
@@ -2135,11 +2513,13 @@ export class SqliteScopeHost {
                     .run(parsed.slug, parsed.name, parsed.source, parsed.ownerTenant, envSpecJson, installSpecJson, parsed.listed ? 1 : 0, 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);
+            listVerticals: async (actor, page) => {
+                const where = [];
+                const params = [];
+                const tail = keysetTail(where, params, 'slug', page);
+                const sql = 'SELECT * FROM verticals' + (where.length ? ` WHERE ${where.join(' AND ')}` : '') + tail;
+                const rows = this.directory.prepare(sql).all(...params);
+                this.recordAccess(actor, 'listVerticals', {}, page ?? null, rows.length);
                 return rows.map(mapVertical);
             },
             publishVersion: async (actor, input) => {
@@ -2167,10 +2547,13 @@ export class SqliteScopeHost {
                     admission: selfAdmits ? 'admitted' : 'pending',
                 });
             },
-            listVersions: async (actor, verticalSlug) => {
+            listVersions: async (actor, verticalSlug, page) => {
+                const where = ['vertical_slug = ?'];
+                const params = [verticalSlug];
+                const tail = keysetTail(where, params, 'id', page);
                 const rows = this.directory
-                    .prepare('SELECT * FROM vertical_versions WHERE vertical_slug = ? ORDER BY id')
-                    .all(verticalSlug);
+                    .prepare(`SELECT * FROM vertical_versions WHERE ${where.join(' AND ')}${tail}`)
+                    .all(...params);
                 this.recordAccess(actor, 'listVersions', {}, { verticalSlug }, rows.length);
                 return rows.map(mapVersion);
             },
@@ -2226,13 +2609,22 @@ export class SqliteScopeHost {
                 const existing = 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. The count names the blast radius.
+                // Refuse while any restorable scope is bound: a deleted registry row would strand
+                // those scopes' version pins and routing. An `archived` scope (a deleted app) still
+                // blocks — unarchive can bring it back — but the refusal names reap/restore, not
+                // "delete", because the app itself is already gone. `reaped` is terminal history
+                // and never blocks. The count names the blast radius.
                 const bound = this.directory
-                    .prepare('SELECT COUNT(*) AS n FROM scopes WHERE vertical = ?')
+                    .prepare('SELECT ' +
+                    "COUNT(*) FILTER (WHERE status NOT IN ('archived', 'reaped')) AS live, " +
+                    "COUNT(*) FILTER (WHERE status = 'archived') AS archived " +
+                    'FROM scopes WHERE vertical = ?')
                     .get(slug);
-                if (bound.n > 0) {
-                    throw new Error(`vertical '${slug}' still backs ${bound.n} scope(s) — delete or rebind them first`);
+                if (bound.live > 0) {
+                    throw new Error(`vertical '${slug}' still backs ${bound.live} scope(s) — delete or rebind them first`);
+                }
+                if (bound.archived > 0) {
+                    throw new Error(`vertical '${slug}' still backs ${bound.archived} archived scope(s) — reap or restore them first`);
                 }
                 // Deployed dispatch scripts are NOT reaped here — they become orphans for the
                 // cleanup script (#248), never destroyed alongside a registry row.
@@ -2369,10 +2761,13 @@ export class SqliteScopeHost {
                 // "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) => {
+            listChannels: async (actor, verticalSlug, page) => {
+                const where = ['vertical_slug = ?'];
+                const params = [verticalSlug];
+                const tail = keysetTail(where, params, 'channel', page);
                 const rows = this.directory
-                    .prepare('SELECT * FROM vertical_channels WHERE vertical_slug = ? ORDER BY channel')
-                    .all(verticalSlug);
+                    .prepare(`SELECT * FROM vertical_channels WHERE ${where.join(' AND ')}${tail}`)
+                    .all(...params);
                 // The serving script runs ONE version (#286); surface it on the prod row so a
                 // failed in-place serve reads honestly instead of claiming the new version is
                 // live (#321). Parity with the Cloudflare host.
@@ -2388,14 +2783,18 @@ export class SqliteScopeHost {
                     servingVersionId: r.channel === 'prod' ? serving : null,
                 }));
             },
-            listChannelHistory: async (actor, verticalSlug, channel) => {
-                const rows = (channel
-                    ? this.directory
-                        .prepare('SELECT * FROM vertical_channel_history WHERE vertical_slug = ? AND channel = ? ORDER BY id DESC')
-                        .all(verticalSlug, channel)
-                    : this.directory
-                        .prepare('SELECT * FROM vertical_channel_history WHERE vertical_slug = ? ORDER BY id DESC')
-                        .all(verticalSlug));
+            listChannelHistory: async (actor, verticalSlug, channel, page) => {
+                const where = ['vertical_slug = ?'];
+                const params = [verticalSlug];
+                if (channel) {
+                    where.push('channel = ?');
+                    params.push(channel);
+                }
+                // Newest first is the shipped order, so 'desc' is the DEFAULT here.
+                const tail = keysetTail(where, params, 'id', page, 'desc');
+                const rows = this.directory
+                    .prepare(`SELECT * FROM vertical_channel_history WHERE ${where.join(' AND ')}${tail}`)
+                    .all(...params);
                 this.recordAccess(actor, 'listChannelHistory', {}, { verticalSlug, channel }, rows.length);
                 return rows.map((r) => channelHistoryEntry.parse({
                     id: r.id,
@@ -2630,10 +3029,14 @@ export class SqliteScopeHost {
                 this.directory.prepare('UPDATE tenants SET name = ? WHERE tenant_id = ?').run(name, tenantId);
                 this.recordAdmin(actor, 'setTenantName', { tenantId }, { name: before.name }, { name });
             },
-            listTenants: async (actor) => {
-                const rows = this.directory.prepare('SELECT * FROM tenants ORDER BY tenant_id').all().map(mapTenant);
+            listTenants: async (actor, page) => {
+                const where = [];
+                const params = [];
+                const tail = keysetTail(where, params, 'tenant_id', page);
+                const sql = 'SELECT * FROM tenants' + (where.length ? ` WHERE ${where.join(' AND ')}` : '') + tail;
+                const rows = this.directory.prepare(sql).all(...params).map(mapTenant);
                 // Enumerating every tenant on the platform is the read this log exists for.
-                this.recordAccess(actor, 'listTenants', {}, null, rows.length);
+                this.recordAccess(actor, 'listTenants', {}, page ?? null, rows.length);
                 return rows;
             },
             getTenant: async (actor, tenantId) => {
@@ -2661,9 +3064,8 @@ export class SqliteScopeHost {
                     where.push('vertical = ?');
                     params.push(filter.vertical);
                 }
-                const sql = 'SELECT * FROM scopes' +
-                    (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
-                    ' ORDER BY scope_id';
+                const tail = keysetTail(where, params, 'scope_id', filter);
+                const sql = 'SELECT * FROM scopes' + (where.length ? ` WHERE ${where.join(' AND ')}` : '') + tail;
                 const scopes = this.directory.prepare(sql).all(...params).map(mapScope);
                 this.recordAccess(actor, 'listScopes', { tenantId: filter?.tenantId ?? null }, filter, scopes.length);
                 return scopes;
@@ -2694,6 +3096,32 @@ export class SqliteScopeHost {
                     createdAt: r.created_at,
                 }));
             },
+            listBlobStores: async (actor, filter) => {
+                const where = [];
+                const params = [];
+                if (filter?.tenantId) {
+                    where.push('tenant_id = ?');
+                    params.push(filter.tenantId);
+                }
+                if (filter?.vertical) {
+                    where.push('vertical = ?');
+                    params.push(filter.vertical);
+                }
+                const rows = this.directory
+                    .prepare('SELECT * FROM blob_stores' +
+                    (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
+                    ' ORDER BY tenant_id, vertical, binding')
+                    .all(...params);
+                this.recordAccess(actor, 'listBlobStores', { tenantId: filter?.tenantId ?? null }, filter, rows.length);
+                return rows.map((r) => ({
+                    tenantId: r.tenant_id,
+                    vertical: r.vertical,
+                    binding: r.binding,
+                    kind: 'blob',
+                    ref: r.ref,
+                    createdAt: r.created_at,
+                }));
+            },
             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
@@ -3020,8 +3448,11 @@ export class SqliteScopeHost {
                 }
                 catch (err) {
                     if (/UNIQUE constraint failed/i.test(err.message)) {
+                        const account = input.externalAccountRef
+                            ? ` under account '${input.externalAccountRef}'`
+                            : '';
                         throw new Error(`tenant ${input.tenantId} already has a live '${input.provider}' connection ` +
-                            `for vertical '${input.vertical}' — revoke it before connecting another`);
+                            `for vertical '${input.vertical}'${account} — revoke it before connecting another`);
                     }
                     throw err;
                 }
@@ -3051,6 +3482,8 @@ export class SqliteScopeHost {
                     (where.push('vertical = ?'), params.push(f.vertical));
                 if (f.provider)
                     (where.push('provider = ?'), params.push(f.provider));
+                if (f.externalAccountRef)
+                    (where.push('external_account_ref = ?'), params.push(f.externalAccountRef));
                 if (!f.includeRevoked)
                     where.push('revoked_at IS NULL');
                 const rows = this.directory
@@ -3099,11 +3532,22 @@ export class SqliteScopeHost {
                     .run(id);
                 this.recordAdmin(actor, 'revokeConnection', { tenantId: row.tenant_id, vertical: row.vertical }, { status: row.status }, { id, provider: row.provider, status: 'revoked', revokedAt: now });
             },
-            openConnection: async (tenantId, vertical, provider) => {
-                const row = this.directory
+            openConnection: async (tenantId, vertical, provider, externalAccountRef) => {
+                const rows = this.directory
                     .prepare(`SELECT * FROM _substrat_connections
-             WHERE tenant_id = ? AND vertical = ? AND provider = ? AND revoked_at IS NULL`)
-                    .get(tenantId, vertical, provider);
+             WHERE tenant_id = ? AND vertical = ? AND provider = ? AND revoked_at IS NULL
+             ${externalAccountRef === undefined ? '' : 'AND external_account_ref = ?'}
+             LIMIT 2`)
+                    .all(...(externalAccountRef === undefined
+                    ? [tenantId, vertical, provider]
+                    : [tenantId, vertical, provider, externalAccountRef]));
+                // Several live accounts and no selector: failing beats acting against
+                // an arbitrary one of the tenant's provider accounts (scope-host.ts).
+                if (rows.length > 1) {
+                    throw new Error(`tenant ${tenantId} has multiple live '${provider}' connections for vertical ` +
+                        `'${vertical}' — pass externalAccountRef to select one`);
+                }
+                const row = rows[0];
                 if (!row)
                     return undefined;
                 const sealed = this.directory
@@ -3220,14 +3664,12 @@ export class SqliteScopeHost {
                     where.push('method = ?');
                     params.push(filter.method);
                 }
+                // Cursor + order mirror auditLog: the id is a ULID, so it IS the cursor.
+                const tail = keysetTail(where, params, 'id', filter);
                 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);
-                }
+                sql += tail;
                 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.
@@ -3412,6 +3854,11 @@ export class SqliteScopeHost {
     ensureDirectoryColumns() {
         this.ensureIdentityKey();
         this.ensureAdminLogTenantNullable();
+        // The pre-account-aware live-uniqueness index: superseded by
+        // _substrat_connections_live_account (created in the bootstrap DDL), which
+        // adds the external-account leg so one tenant can hold the same provider
+        // under several accounts. Existing data always satisfies the wider key.
+        this.directory.exec('DROP INDEX IF EXISTS _substrat_connections_live');
         this.ensureColumn(this.directory, '_substrat_admin_log', 'caused_by', 'caused_by TEXT');
         // §4.8's grace-window timestamp on tenants (mirrors scopes' archived_at).
         this.ensureColumn(this.directory, 'tenants', 'deleting_at', 'deleting_at TEXT');
@@ -3508,7 +3955,9 @@ export class SqliteScopeHost {
      * can never disagree about who acted (#97). `overrideActor` remains for the
      * system-actor path, where the acting module is the honest answer.
      */
-    operationContext(rt, subject, overrideActor) {
+    operationContext(rt, subject, overrideActor, 
+    /** #458: per-invoke tally of `ctx.requestPlatform` calls; absent for consumer dispatch. */
+    signals) {
         const principal = subject.id;
         const checker = this.checker;
         const relations = this.relations;
@@ -3567,6 +4016,8 @@ export class SqliteScopeHost {
                (id, kind, payload, requested_by, status, attempts, requested_at)
              VALUES (?, ?, ?, ?, 'pending', 0, ?)`)
                     .run(id, input.kind, JSON.stringify(input.payload ?? null), JSON.stringify(requestedBy), instant.parse(new Date().toISOString()));
+                if (signals)
+                    signals.platformRequests += 1;
                 return id;
             },
             check: async (permission, entity) => {