@substrat-run/adapter-cloudflare 0.118.0 → 0.120.0

package/dist/scope-do.js

@@ -1,10 +1,10 @@
 import { DurableObject } from 'cloudflare:workers';
 import { ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, domainEvent, domainEventInput, eventId, instant, objectRef, toWireFailure, grantRefFromProof, principalId, scopeId as scopeIdOf, tenantId as tenantIdOf, platformRequestInput, platformRequestId, MAX_PENDING_PLATFORM_REQUESTS, MAX_PENDING_SWEEP_RUNS, SWEEP_RUNS_KIND, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, listLimitOf, requestFingerprint, substratError, assertReplayableDump, REDRAIN_BATCH, } from '@substrat-run/contracts';
-import { ulid, createUlid, assertAllowed, ConnectionSealingKeyUnavailableError, noSealingKeyMessage, sealTo, assertReadOnlyQuery, entitlementDenial, platformRequestHistoryQuery, platformRequestOf, PLATFORM_REQUEST_COLUMNS, PLATFORM_REQUEST_REDACTION_SQL, platformRequestRedactionParams, platformRequestRedactionQuery, intentPayloadCarriesSubject, redactSubjectJobRuns, JOB_RUN_PATCH_SQL, JOB_STEP_RECORD_SQL, DELIVERY_ERROR_REDACTION_SQL, REDACTED_DELIVERY_NOTE, seatScopeTuple, effectiveRoleGrantQuery, switchSystemSchedules, systemScheduleState, systemSwitchedOff, denialListQuery, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialSummaryBuckets, PermissionDenied, assertImpersonationWrites, assertModuleEnqueueableKind, impersonationStampOf, createAtomic, NotSearchable, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, searchLimit, searchMatchExpression, searchQuery, IDEMPOTENCY_DDL, assertIdempotencyKey, assertPermissionKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, SCHEDULE_STATE_DDL, SCHEDULE_STATE_REBUILD, scheduleStateHasKind, JOB_RUN_DDL, jobRunListLimit, } from '@substrat-run/kernel';
+import { ulid, createUlid, assertAllowed, ConnectionSealingKeyUnavailableError, noSealingKeyMessage, sealTo, assertReadOnlyQuery, entitlementDenial, platformRequestHistoryQuery, platformRequestOf, PLATFORM_REQUEST_COLUMNS, PLATFORM_REQUEST_REDACTION_SQL, platformRequestRedactionParams, platformRequestRedactionQuery, intentPayloadCarriesSubject, redactSubjectJobRuns, JOB_RUN_PATCH_SQL, JOB_STEP_RECORD_SQL, DELIVERY_ERROR_REDACTION_SQL, REDACTED_DELIVERY_NOTE, seatScopeTuple, effectiveRoleGrantQuery, switchSystemSchedules, peerGrantsStatus, systemGrantsStatus, systemScheduleState, systemSwitchedOff, denialListQuery, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialSummaryBuckets, PermissionDenied, assertImpersonationWrites, assertModuleEnqueueableKind, impersonationStampOf, createAtomic, NotSearchable, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, searchLimit, searchMatchExpression, searchQuery, IDEMPOTENCY_DDL, assertIdempotencyKey, assertPermissionKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, SCHEDULE_STATE_DDL, SCHEDULE_STATE_REBUILD, scheduleStateHasKind, VERTICAL_EVENTS_DDL, EXPORT_HOPS_SQL, IMPORT_CURSORS_SQL, IMPORT_CURSOR_OF_SQL, IMPORT_CURSOR_ADVANCE_SQL, IMPORT_RECORD_SQL, CrossVerticalRegistry, exportReadPlan, exportReadQuery, planExportBatch, withheldNote, JOB_RUN_DDL, jobRunListLimit, } from '@substrat-run/kernel';
 import { isUpgradeRequest, readSubscription, LIVE_FANOUT_LIMIT, LIVE_MODE_HEADER, LIVE_PRINCIPAL_HEADER, LIVE_SCOPE_HEADER, LIVE_SUBSCRIBE_PATH, LIVE_TENANT_HEADER, } from './live-reads.js';
 import { OperationQueue } from './serialization.js';
 import { doScopedSql, doSpineSql } from './sql.js';
-import { actorOf, assertNoSecret, CAPABILITY_DDL, CAPABILITY_EXCHANGE_OPERATION, createCapabilityVerbs, exchangeCapability, guardSecrets, mintBecomeCapability, redactSecrets, resolveCapabilitySession, revokeCapabilityAsPlatform, domainEventOf, facetEvents, readDeadLetters, readHistory, readInvocation, readUndrainedOutbox, walkEventCause, walkEventEffects, } from '@substrat-run/kernel';
+import { actorOf, admitPeer, collectPeers, switchPeer, assertNoSecret, CAPABILITY_DDL, CAPABILITY_EXCHANGE_OPERATION, capabilityAttachmentWriteRefused, createCapabilityVerbs, exchangeCapability, guardSecrets, mintBecomeCapability, redactSecrets, resolveCapabilitySession, revokeCapabilityAsPlatform, domainEventOf, facetEvents, readDeadLetters, readHistory, readInvocation, readUndrainedOutbox, walkEventCause, walkEventEffects, } from '@substrat-run/kernel';
 import { createDoTupleChecker, createLocalControlPlaneReader } from './checker.js';
 /**
  * The key marking a scope DO whose storage was destroyed (`destroyStorage`).
@@ -150,6 +150,10 @@ const KERNEL_DDL = `
   -- builds and the shape a self-host builds cannot part company; the column
   -- comments, and the reason coalescing is NOT a unique index, are in there.
   ${JOB_RUN_DDL}
+  -- #1705: cross-vertical delivery. The consumer's journal of what it received (envelope
+  -- only) and its watermark per producer, plus the producer-side (type, id) outbox index the
+  -- export read seeks on. Shared with the pure adapter from @substrat-run/kernel.
+  ${VERTICAL_EVENTS_DDL}
   CREATE TABLE IF NOT EXISTS _substrat_migrations (
     module_id TEXT NOT NULL,
     version TEXT NOT NULL,
@@ -487,6 +491,18 @@ export function defineScopeDO(modules, bareOps) {
         /** #116: the operations that declared `idempotency: false` — refusals, not participants. */
         operationIdempotencyOptOut = new Set();
         modules = new Map();
+        /** #1705: what this deployment exports to other verticals and imports from them. */
+        crossVertical = new CrossVerticalRegistry();
+        /**
+         * #1706: every registered module's `peers`, as declared. The door's admission reads the
+         * union (`collectPeers`), built once on first use: registration finishes in the
+         * constructor, before any call can reach the door.
+         */
+        peerSources = [];
+        peerUnion;
+        get peers() {
+            return (this.peerUnion ??= collectPeers(this.peerSources));
+        }
         guards = new Map();
         predicates = new Map();
         withdrawn = new Map();
@@ -558,6 +574,8 @@ export function defineScopeDO(modules, bareOps) {
         // -- module registration (port of SqliteScopeHost.registerModule) ---------
         registerModule(registration) {
             const manifest = registration.manifest;
+            if (manifest.peers?.length)
+                this.peerSources.push({ peers: manifest.peers });
             // #827: the FTS indexes `searchables` declares, appended after the module's
             // own migrations so the content table exists when the trigger references it.
             // Same derivation as the pure adapter — both call the kernel, neither owns
@@ -579,6 +597,8 @@ export function defineScopeDO(modules, bareOps) {
                 }
                 this.listPlans.set(plan.entityType, plan);
             }
+            // #1705: the same registry, the same refusals, as the coordinator and the pure host.
+            this.crossVertical.register(manifest, registration.imports);
             this.modules.set(manifest.id, {
                 id: manifest.id,
                 migrations: [
@@ -811,6 +831,167 @@ export function defineScopeDO(modules, bareOps) {
          * `drainEvents` admin receipt only when this is nonzero, so a retried pass records
          * no egress it did not actually perform.
          */
+        /**
+         * #1705: the producer's release to `input.consumer`, decided by THIS deployment's own
+         * declarations. The pure adapter's `readExports`, row for row. The plan and the decision
+         * are the kernel's, so the two hosts cannot release different rows from the same outbox.
+         *
+         * On the queue, so no operation is mid-transaction while the outbox is read. An event
+         * must not reach another vertical before the transaction that wrote it has committed.
+         */
+        async exportedEventsRead(input, tenantId, scopeId) {
+            await this.ensureMigrations();
+            const plan = exportReadPlan(this.crossVertical.exports(), input.wants);
+            const quiet = {
+                events: [],
+                withheld: [],
+                unexported: plan.unexported,
+                paused: null,
+                next: input.after,
+                more: false,
+            };
+            if (plan.types.length === 0)
+                return quiet;
+            const missing = (await this.peerCovers(tenantId, scopeId, input.consumer, plan.keys))
+                .filter((c) => !c.held)
+                .map((c) => c.permission);
+            if (missing.length > 0)
+                return { ...quiet, paused: { missing } };
+            return await this.queue.enqueue(() => {
+                const q = exportReadQuery(plan.types, input.after, input.limit);
+                const rows = this.sql.exec(q.sql, ...q.params).toArray();
+                const batch = planExportBatch({
+                    rows,
+                    wanted: plan.wanted,
+                    after: input.after,
+                    limit: input.limit,
+                    hopsBefore: (row) => row.caused_by
+                        ? ((this.sql.exec(EXPORT_HOPS_SQL, row.caused_by).toArray()[0]?.hops) ?? 0)
+                        : 0,
+                });
+                return { ...batch, unexported: plan.unexported, paused: null };
+            });
+        }
+        /** #1705: what this deployment imports, and this scope's watermark per producer. */
+        async importStateRead() {
+            await this.ensureMigrations();
+            const consumes = this.crossVertical.consumes();
+            if (consumes.length === 0)
+                return { consumes: [], cursors: [] };
+            const cursors = this.sql
+                .exec(IMPORT_CURSORS_SQL)
+                .toArray()
+                .map((r) => ({
+                source: r.source_scope_id,
+                vertical: r.source_vertical,
+                cursor: r.cursor,
+                updatedAt: r.updated_at,
+            }));
+            return { consumes, cursors };
+        }
+        /**
+         * #1705: apply a batch another vertical exported. The pure adapter's `deliverToPeer`
+         * body, on this scope's queue: the compare-and-set on the watermark, a dead letter per
+         * importing module for each withheld event, one storage transaction per (event, module)
+         * with its journal row, the watermark moved last, then the post-commit tail.
+         *
+         * The coordinator parses the batch before it gets here and runs the executors after.
+         * Executors live on the coordinator here, as they do after an invoke.
+         */
+        async importApply(batch, tenantId, scopeId) {
+            await this.ensureMigrations();
+            const source = batch.source;
+            return await this.queue.enqueue(async () => {
+                const liveSince = this.liveHighWaterMark();
+                const result = {
+                    delivered: 0,
+                    deadLettered: 0,
+                    duplicates: 0,
+                    withheld: 0,
+                    cursor: batch.after,
+                    stale: false,
+                    paused: null,
+                };
+                // #1706's door, for a delivery (`operation: null`), inside the queued body: the producer
+                // is a declared peer with its switch on, or nothing runs and the edge pauses.
+                let peerSubject;
+                try {
+                    peerSubject = admitPeer(this.switchSql(), this.peers, { vertical: source.vertical, scope: source.scopeId }, null);
+                }
+                catch (err) {
+                    return { ...result, paused: { reason: err instanceof Error ? err.message : String(err) } };
+                }
+                const current = (this.sql.exec(IMPORT_CURSOR_OF_SQL, source.scopeId).toArray()[0]
+                    ?.cursor ?? null);
+                if (current !== batch.after)
+                    return { ...result, cursor: current, stale: true };
+                const at = new Date().toISOString();
+                const journaled = (id, moduleId) => this.sql
+                    .exec('SELECT 1 FROM _substrat_deliveries WHERE event_id = ? AND consumer_module = ?', id, moduleId)
+                    .toArray().length > 0;
+                const deadLetter = (id, moduleId, when, error) => {
+                    this.sql.exec(`INSERT OR IGNORE INTO _substrat_deliveries
+               (event_id, consumer_module, delivered_at, error, invocation_id)
+             VALUES (?, ?, ?, ?, NULL)`, id, moduleId, when, error);
+                };
+                for (const w of batch.withheld) {
+                    this.sql.exec(IMPORT_RECORD_SQL, w.id, source.scopeId, source.vertical, w.type, w.schemaVersion, w.occurredAt, w.entity.entityType, w.entity.entityId, 0, w.reason, at);
+                    for (const moduleId of this.crossVertical.modulesImporting(source.vertical, w.type)) {
+                        deadLetter(w.id, moduleId, at, withheldNote(w.reason, source.vertical));
+                    }
+                    result.withheld += 1;
+                }
+                for (const e of batch.events) {
+                    this.sql.exec(IMPORT_RECORD_SQL, e.id, source.scopeId, source.vertical, e.type, e.schemaVersion, e.occurredAt, e.entity.entityType, e.entity.entityId, e.hops, null, at);
+                    let ran = false;
+                    for (const imp of this.crossVertical.handlersFor(source.vertical, e.type)) {
+                        if (journaled(e.id, imp.moduleId))
+                            continue;
+                        ran = true;
+                        if (imp.schemaVersion !== e.schemaVersion) {
+                            deadLetter(e.id, imp.moduleId, at, withheldNote('version', source.vertical));
+                            result.deadLettered += 1;
+                            continue;
+                        }
+                        const { hops: _hops, ...fact } = e;
+                        const event = structuredClone({ ...fact, source });
+                        this.causedBy = e.id;
+                        try {
+                            await this.ctx.storage.transaction(async () => {
+                                // As the producer's principal: real checks against the grants this vertical's
+                                // `peers` gave it; its emits carry `{ vertical, scope }` and what they passed.
+                                await imp.handler(this.importContext(tenantId, scopeId, peerSubject), event);
+                                this.sql.exec(`INSERT INTO _substrat_deliveries (event_id, consumer_module, delivered_at, invocation_id)
+                   VALUES (?, ?, ?, NULL)`, e.id, imp.moduleId, new Date().toISOString());
+                            });
+                            result.delivered += 1;
+                        }
+                        catch (err) {
+                            // Dead-letter (v0), outside the rolled-back transaction.
+                            deadLetter(e.id, imp.moduleId, new Date().toISOString(), String(err));
+                            result.deadLettered += 1;
+                        }
+                        finally {
+                            this.causedBy = null;
+                        }
+                    }
+                    if (!ran)
+                        result.duplicates += 1;
+                }
+                this.sql.exec(IMPORT_CURSOR_ADVANCE_SQL, source.scopeId, source.vertical, batch.next, at);
+                result.cursor = batch.next;
+                await this.settleCommitted(tenantId, scopeId, liveSince, null);
+                return result;
+            });
+        }
+        /**
+         * #1705: the context an import handler runs in: the peer door's subject, as the invoke path
+         * passes it (#1706). `principal` is a placeholder that the subject never reads, and there is
+         * no operation, so the emitted rows' `operation` is NULL, as it is for any consumer.
+         */
+        importContext(tenantId, scopeId, peerSubject) {
+            return this.operationContext(principalId.parse(ulid()), tenantId, scopeId, undefined, undefined, undefined, undefined, undefined, undefined, undefined, [], undefined, peerSubject);
+        }
         async markEventsDrained(eventIds, at) {
             if (eventIds.length === 0)
                 return 0;
@@ -1122,19 +1303,28 @@ export function defineScopeDO(modules, bareOps) {
          * `capability.honoured`: an old DO that ignored this argument would run the call as
          * that placeholder, and the coordinator refuses a success without the acknowledgement.
          */
-        capabilitySession) {
+        capabilitySession, 
+        /**
+         * #1706: set when the caller is ANOTHER VERTICAL of the same tenant — the platform's
+         * word for who is calling, carried through the coordinator. Admitted INSIDE the queued
+         * body on every call (`admitPeer`: declared, switched on, operation allowlisted).
+         * `principal` is then a random placeholder that holds nothing, and the reply carries
+         * `vertical.honoured`: an old DO that ignored this argument would run the call as that
+         * placeholder, and the coordinator refuses a success without the acknowledgement.
+         */
+        verticalCaller) {
             if (!failureEnvelope) {
                 // Legacy path, byte-for-byte what it was: rewrapped so a non-plain error (a
                 // ZodError, whose `message` is a getter) still arrives with its message.
                 try {
-                    return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions, impersonation, capabilitySession);
+                    return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions, impersonation, capabilitySession, verticalCaller);
                 }
                 catch (err) {
                     throw toRpcError(err);
                 }
             }
             try {
-                return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions, impersonation, capabilitySession);
+                return await this.invokeOrThrow(operation, input, principal, tenantId, scopeId, connectionId, requiredEntitlement, systemModuleId, invokeOptions, impersonation, capabilitySession, verticalCaller);
             }
             catch (err) {
                 // The ONE place the error keeps its structure: flattened here, rebuilt by the
@@ -1148,7 +1338,9 @@ export function defineScopeDO(modules, bareOps) {
         /** K-42: the session, resolved coordinator-side. See `invoke` above. */
         impersonation, 
         /** #1672: a capability session's hash. See `invoke` above. */
-        capabilitySession) {
+        capabilitySession, 
+        /** #1706: the calling vertical, as the platform named it. See `invoke` above. */
+        verticalCaller) {
             await this.ensureMigrations();
             const handler = this.operations.get(operation);
             // `not_found`, not a bare throw (#113): every vertical hand-matched this message
@@ -1241,6 +1433,14 @@ export function defineScopeDO(modules, bareOps) {
                         capabilityId = resolveCapabilitySession(doSpineSql(this.sql), capabilitySession, instant.parse(new Date().toISOString()), operation);
                         idempotencySubjectRef = { kind: 'capability', id: capabilityId };
                     }
+                    // #1706: the peer door's admission, on the capability door's terms — every call,
+                    // here, before anything opens. An undeclared peer, a switched-off one and an
+                    // operation off its allowlist are refused `forbidden`; none is a K-35 denial.
+                    let peerSubject;
+                    if (verticalCaller !== undefined) {
+                        peerSubject = admitPeer(this.switchSql(), this.peers, verticalCaller, operation);
+                        idempotencySubjectRef = peerSubject;
+                    }
                     // #1672: the secrets this call mints — withheld from its idempotency recording, and
                     // what the tripwire on its writes looks for.
                     const minted = [];
@@ -1286,7 +1486,7 @@ export function defineScopeDO(modules, bareOps) {
                     // emitted events back as one — verified across `await` in workerd.
                     try {
                         await this.ctx.storage.transaction(async () => {
-                            const ctx = this.operationContext(principal, tenantId, scopeId, undefined, connectionId, systemModuleId, signals, impersonation, operation, capabilityId, minted);
+                            const ctx = this.operationContext(principal, tenantId, scopeId, undefined, connectionId, systemModuleId, signals, impersonation, operation, capabilityId, minted, undefined, peerSubject);
                             // #116: a retry is answered from the recording, and nothing else runs
                             // — not the guards, not the handler, not the permission check inside
                             // it. Keyed by SUBJECT, so a caller only ever reaches its own
@@ -1353,6 +1553,7 @@ export function defineScopeDO(modules, bareOps) {
                                 platformRequests: 0,
                                 impersonation: { honoured: true },
                                 ...(capabilitySession !== undefined ? { capability: { honoured: true } } : {}),
+                                ...(verticalCaller !== undefined ? { vertical: { honoured: true } } : {}),
                                 ...(idempotencyKey !== undefined
                                     ? { idempotency: { keyHonoured: true, replayed } }
                                     : {}),
@@ -1399,6 +1600,8 @@ export function defineScopeDO(modules, bareOps) {
                         ...(impersonation ? { impersonation: { honoured: true } } : {}),
                         // #1672: the acknowledgement the coordinator's skew check reads — see `invoke`.
                         ...(capabilitySession !== undefined ? { capability: { honoured: true } } : {}),
+                        // #1706: the same, for the peer door.
+                        ...(verticalCaller !== undefined ? { vertical: { honoured: true } } : {}),
                         // The acknowledgement the coordinator's skew check reads (#116), on the
                         // same reasoning as `ifMatchChecked` below and with a sharper failure: a
                         // DO too old to know about keys would EXECUTE THE OPERATION AGAIN and
@@ -1878,6 +2081,89 @@ export function defineScopeDO(modules, bareOps) {
                 return record;
             });
         }
+        // -- attachments through a capability (#1686) -------------------------------
+        // The coordinator hashed the session token; only the hash arrives. Each verb resolves it
+        // INSIDE the queue, as `invoke` does, so nothing can revoke between the resolution and
+        // the check — and a revoke or an expiry refuses the very next call. Reads are the
+        // ordinary checker's, as `{ capability }`: its keys, its subtree, its minter's authority
+        // now. Writes are refused whatever the keys say. No verb here takes a use.
+        /**
+         * Resolve the session and run `fn` as the capability; a refused check lands in the
+         * denial log against `{ capability }`. A dead session throws before `fn` (no K-35 row).
+         *
+         * THE ORDER, for every verb: the session (here), then the target lookup, then the
+         * check. So `attachmentGate` is only ever called inside `fn`: a dead link is told
+         * `unauthenticated` and learns nothing about which entity types take attachments.
+         *
+         * The answer is an ENVELOPE, `invoke`'s: a failure travels as a value (`toWireFailure`)
+         * because a throw across this boundary keeps only its message, and the caller has to
+         * tell `permission_denied` from `unauthenticated` from `forbidden` — a 403, a 401 and a
+         * 403 of a different kind to whoever is downloading.
+         */
+        asCapability(sessionHash, tenantId, scopeId, operation, fn) {
+            return this.queue.enqueue(async () => {
+                let capability;
+                try {
+                    capability = resolveCapabilitySession(doSpineSql(this.sql), sessionHash, instant.parse(new Date().toISOString()), operation);
+                }
+                catch (err) {
+                    return { failure: toWireFailure(err) };
+                }
+                try {
+                    const ctx = this.operationContext(
+                    // A placeholder the subject never reads, as on the invoke path: `capabilityId`
+                    // is what the context acts as.
+                    capability, tenantId, scopeId, undefined, undefined, undefined, undefined, undefined, operation, capability);
+                    return { value: await fn(ctx, capability) };
+                }
+                catch (err) {
+                    if (err instanceof PermissionDenied) {
+                        this.recordDenial({ kind: 'capability', id: capability }, tenantId, operation, err, null);
+                    }
+                    return { failure: toWireFailure(err) };
+                }
+            });
+        }
+        async capabilityAttachmentList(entity, sessionHash, tenantId, scopeId) {
+            await this.ensureMigrations();
+            return this.asCapability(sessionHash, tenantId, scopeId, 'attachments.list', async (ctx) => {
+                const gate = this.attachmentGate(entity.entityType);
+                assertAllowed(await ctx.check(gate.read, entity));
+                const rows = this.sql
+                    .exec(`SELECT id FROM _substrat_attachments WHERE entity_type = ? AND entity_id = ?
+             ORDER BY id DESC`, entity.entityType, entity.entityId)
+                    .toArray();
+                return rows
+                    .map((r) => this.attachmentRow(r.id))
+                    .filter((r) => r !== null);
+            });
+        }
+        /** The record of an attachment the capability may read, or null for an unknown id. */
+        async capabilityAttachmentOpen(attachmentId, sessionHash, tenantId, scopeId) {
+            await this.ensureMigrations();
+            return this.asCapability(sessionHash, tenantId, scopeId, 'attachments.open', async (ctx) => {
+                const record = this.attachmentRow(attachmentId);
+                if (!record)
+                    return null;
+                const gate = this.attachmentGate(record.entity.entityType);
+                assertAllowed(await ctx.check(gate.read, record.entity));
+                return record;
+            });
+        }
+        /**
+         * Refuse an upload or a remove through a capability, and record it. Throws for an
+         * unknown attachment id too — the same answer either way — but only a known target has
+         * a write key for the denial log to record.
+         */
+        async capabilityAttachmentRefuseWrite(sessionHash, tenantId, scopeId, operation, target) {
+            await this.ensureMigrations();
+            return this.asCapability(sessionHash, tenantId, scopeId, operation, async (_ctx, capability) => {
+                const entityType = 'entityType' in target
+                    ? target.entityType
+                    : this.attachmentRow(target.attachmentId)?.entity.entityType;
+                throw capabilityAttachmentWriteRefused(capability, operation, { tenantId, scopeId }, entityType === undefined ? undefined : this.attachmentGate(entityType).write);
+            });
+        }
         /** The kernel's schedule-switch SQL (#1666), over this DO's storage. */
         switchSql() {
             return {
@@ -1929,6 +2215,44 @@ export function defineScopeDO(modules, bareOps) {
         async switchSystemSchedules(moduleId, scopeId, to, at) {
             return this.queue.enqueue(() => this.ctx.storage.transactionSync(() => switchSystemSchedules(this.switchSql(), { moduleId, scopeId, to, at })));
         }
+        /**
+         * Move one PEER's kill switch on this scope (#1706) — the kernel's `switchPeer`, which is
+         * the schedule switch's statement with a `vertical:` subject. Queued, one transaction.
+         */
+        async switchPeer(vertical, scopeId, to, at) {
+            return this.queue.enqueue(() => this.ctx.storage.transactionSync(() => switchPeer(this.switchSql(), { vertical, scopeId, to, at })));
+        }
+        /**
+         * Does peer `vertical` hold each key at this scope's node now (#1706) — the checker's own
+         * `covers`, queued so no invoke's open transaction is read half-done. The subject's `scope`
+         * is the target scope only to satisfy the type: `covers` records nothing, and the tuple ref
+         * it walks is the slug alone.
+         */
+        async peerCovers(tenantId, scopeId, vertical, permissions) {
+            await this.ensureMigrations();
+            return this.queue.enqueue(async () => {
+                const coverage = await this.checker.covers({ kind: 'vertical', id: vertical, scope: scopeId }, permissions, { tenantId, scopeId });
+                const missing = new Set(coverage.covered ? [] : coverage.missing);
+                return permissions.map((permission) => ({ permission, held: !missing.has(permission) }));
+            });
+        }
+        /**
+         * Every module this scope holds or has held system authority for, and where each
+         * stands (#1674) — the kernel's `systemGrantsStatus`, over this DO's own storage. A
+         * plain read like `systemScheduleState` above, not queued: nothing here decides a
+         * write.
+         */
+        async systemGrantsStatus() {
+            return systemGrantsStatus(this.switchSql(), new Date().toISOString());
+        }
+        /**
+         * Where every peer this scope holds or has held grants for stands (#1706) — the
+         * kernel's `peerGrantsStatus`, over this DO's own storage, and the same plain
+         * unqueued read as the line above: nothing here decides a write.
+         */
+        async peerGrantsStatus() {
+            return peerGrantsStatus(this.switchSql(), new Date().toISOString());
+        }
         /**
          * The exchange (#1672) — a capability's secret traded for a session, or for the
          * principal a `become` capability yields. Runs the kernel's `exchangeCapability`, the
@@ -3170,7 +3494,13 @@ export function defineScopeDO(modules, bareOps) {
          * the instant its row write used, so the `capability.exercised` event's `occurredAt`
          * and the row's `last_used_at` are the same value — a second read could disagree.
          */
-        instantOverride) {
+        instantOverride, 
+        /**
+         * #1706: set when the caller is a PEER vertical — the subject `admitPeer` returned inside
+         * the queued body. Mutually exclusive with the other non-person callers; `principal` is
+         * then a placeholder that the subject below never reads.
+         */
+        peerSubject) {
             const checker = this.checker;
             const relations = this.relations;
             const searchPlans = this.searchPlans;
@@ -3188,13 +3518,15 @@ export function defineScopeDO(modules, bareOps) {
             // The permission subject and the derived event actor for a NON-override caller
             // (#383/#97): a scheduled module, a connection, or a person. `systemActor` (the
             // override, used only by consumer dispatch) stays a separate bypass path below.
-            const subject = capabilityId
-                ? { kind: 'capability', id: capabilityId }
-                : systemModuleId
-                    ? { kind: 'system', id: systemModuleId }
-                    : connectionId
-                        ? { kind: 'connection', id: connectionId }
-                        : { kind: 'principal', id: principal };
+            const subject = peerSubject
+                ? peerSubject
+                : capabilityId
+                    ? { kind: 'capability', id: capabilityId }
+                    : systemModuleId
+                        ? { kind: 'system', id: systemModuleId }
+                        : connectionId
+                            ? { kind: 'connection', id: connectionId }
+                            : { kind: 'principal', id: principal };
             const derivedActor = actorOf(subject);
             // #304: entitlement reads pick the same local-vs-RPC reader the permission checker
             // uses (projected scope → local table; console-managed → CP over RPC), resolved per