@substrat-run/adapter-cloudflare 0.153.0 → 0.155.0

package/dist/host.js

@@ -1,9 +1,9 @@
 import { env as ambientEnv } from 'cloudflare:workers';
 import { isRewindRefusal, REWIND_REFUSED } from './rewind-refusal.js';
 import { isSystemDoorMoved, SYSTEM_DOOR_MOVED, SYSTEM_DOOR_REGATES } from './system-door.js';
-import { delegatedReadParams, operationSeriesCount, fromWireFailure, isSubstratError, exportReadInput, exportedBatch, importBatch, importResult, importState, importsOfManifestJson, exportsOfManifestJson, assertNoBindingShapeBreak, importCursorMove, importCursorMoveAt, importCursorMoved, accessLogEntry, adminLogEntry, opsFailureEntry, opsFailureFingerprint, issueEntry, findingEntry, findingRuleEntry, sweepRunEntry, FRESHNESS_HEARTBEAT_MINUTES, sweepRunsPayload, modelUsageEntry, attachmentRecord, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, verticalChannel, verticalVersion, connection, capabilityExchange, mintedCapability, boundedBecomeMint, boundedBecomeRevoke, boundedUnbind, entityRef, becomeLinkState, principalBecomeCapabilityInput, capabilityGrant, principalId, connectionGrant, connectionGrantRecord, connectionSecret, systemGrant, systemSwitch, systemSwitchOutcome, systemScheduleEntry, systemSwitchRecord, entitlementGrant, entitlementGrantInput, capabilityFilter, instant, meterReading, scopeStorageSample, subjectRef, createConnectionInput, connectLinkFilter, connectLinkKey, consumeConnectLinkInput, mintConnectLinkInput, projectedConnectionGrant, projectedConnectionKey, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, identityMembership, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, delegatedReadRecord, ownerTransferAudit, memberChangeAudit, peerBindingAudit, connectionBindingAudit, copyMarkAudit, orphanSweepAudit, subjectShredReceipt, connectorDispatchKind, callsOfManifestJson, outboundOfManifestJson, SCOPE_GATE_REASONS, substratError, redrainEventsInput, coverage, peerCoverage, peerGrantsEntry, peerSwitch, peerSwitchOutcome, verticalCaller, verticalResolution, peerInstanceResolution, peerBinding as peerBindingSchema, verticalSlug, entityObjectRef, ATTACHMENT_BLOB_BINDING, blobStoreBindingName, lifecycleDelivery, scopeLifecycle, } from '@substrat-run/contracts';
+import { delegatedReadParams, operationSeriesCount, fromWireFailure, isSubstratError, exportReadInput, exportedBatch, importBatch, importResult, importState, importsOfManifestJson, connectionLandingsOfManifestJson, exportsOfManifestJson, assertNoBindingShapeBreak, importCursorMove, importCursorMoveAt, importCursorMoved, accessLogEntry, adminLogEntry, opsFailureEntry, opsFailureFingerprint, issueEntry, findingEntry, findingRuleEntry, sweepRunEntry, FRESHNESS_HEARTBEAT_MINUTES, sweepRunsPayload, modelUsageEntry, attachmentRecord, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, verticalChannel, verticalVersion, connection, capabilityExchange, mintedCapability, boundedBecomeMint, boundedBecomeRevoke, boundedUnbind, entityRef, becomeLinkState, principalBecomeCapabilityInput, capabilityGrant, principalId, connectionGrant, connectionGrantRecord, connectionSecret, systemGrant, systemSwitch, systemSwitchOutcome, systemScheduleEntry, systemSwitchRecord, entitlementGrant, entitlementGrantInput, capabilityFilter, instant, meterReading, scopeStorageSample, subjectRef, createConnectionInput, connectLinkFilter, connectLinkKey, consumeConnectLinkInput, mintConnectLinkInput, projectedConnectionGrant, projectedConnectionKey, moduleManifest, org as orgSchema, orgMembership, resolvedIdentity, identityMembership, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, delegatedReadRecord, ownerTransferAudit, memberChangeAudit, peerBindingAudit, connectionBindingAudit, copyMarkAudit, orphanSweepAudit, subjectShredReceipt, connectorDispatchKind, callsOfManifestJson, outboundOfManifestJson, SCOPE_GATE_REASONS, substratError, redrainEventsInput, coverage, peerCoverage, peerGrantsEntry, peerSwitch, peerSwitchOutcome, verticalCaller, verticalResolution, peerInstanceResolution, peerBinding as peerBindingSchema, verticalSlug, entityObjectRef, ATTACHMENT_BLOB_BINDING, blobStoreBindingName, lifecycleDelivery, scopeLifecycle, } from '@substrat-run/contracts';
 import { normalizeHostname, toRouteTarget } from './route-resolver.js';
-import { attachmentBlobKey, normalizeUploadMediaType, redeemOrReplayUploadLink, attachmentSha256, entitlementDenial, requiredEntitlementFor, foldMeterReading, parseValidationRecords, resolveScopeRecord, ulid, KEPT_COPY_REFUSAL, capabilityTokenHash, checkBecomeInput, assertBecomeLinkStateIds, plausibleSessionToken, foldModelUsage, backoffAt, resolveRetryPolicy, executorOutcomeOf, isDeliveryRefusal, refusalJournalText, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, openSealed, ImpersonationRefused, assertSessionUsable, impersonationRowValues, mapImpersonationRow, newImpersonationSession, jobRunOf, assertLeaseMs, runDueJobRuns, SYSTEM_DOOR_WAIT, startJobRun, attachmentTextJob, assertAttachmentExtractors, resolveAttachmentTextBounds, assertJobRegistrable, ATTACHMENT_TEXT_BACKFILL_JOB, ATTACHMENT_TEXT_JOB, kernelJobFor, attachmentTextBackfillJob, searchLimit, searchMatchExpression, globalFetch, assertRedrainWindow, platformRequestOf, undrainedEventsOf, inUnitMovesToAudit, staleCarryRevertRow, staleCarryReverts, recordedOffFromWire, peerSubjectRef, SWITCH_KINDS, reassertActionOf, reassertEntry, reassertOffRow, reassertOnRow, switchActionOf, switchAuditSubject, recordAuditOutcome, auditedCapabilityRevoke, auditWarningOf, switchNotFoundMessage, recordWriteSuperseded, switchSubjectOf, switchSupersededMessage, withRecorded, systemSwitchedOffMessage, tenantSystemSwitchedOffMessage, CrossVerticalRegistry, importCursorSourceOf, exportBreaksOf, exportBreakRefusal, assertPromoteReviewCurrent, promoteRaceRefusal, rebindRaceRefusal, bindExportBreaksOf, bindExportBreakRefusal, scopeMoveOf, runningVersionOf, strandJudgmentsOf, boundShapesOfColumn, installReconciled, collectPeers, peerCallerAt, peerSeats, connectorCallRecord, noopConnectorCallRecorder, recordConnectorCall, settleConnectionUse, splitManifestMigrations, publishedMigrationDigest, migrationChangeRefusal, unknownRoleError, assertRowLimit, assertRowOffset, emptyImportResult, INERT_SCOPE_REASON, lifecycleReceipt, lifecycleRefusal, isPrimaryScope, isPrimaryScopeRow, asyncInvocationId, asyncLinePass, assertNoCallerPurge, purgeReportOf, purgeStillDue, assertBoundOperations, registerTrashTargets, memberAddedAudit, shapeTopUpBatch, } from '@substrat-run/kernel';
+import { attachmentBlobKey, normalizeUploadMediaType, redeemOrReplayUploadLink, attachmentSha256, entitlementDenial, requiredEntitlementFor, foldMeterReading, parseValidationRecords, resolveScopeRecord, ulid, KEPT_COPY_REFUSAL, capabilityTokenHash, checkBecomeInput, assertBecomeLinkStateIds, plausibleSessionToken, foldModelUsage, backoffAt, resolveRetryPolicy, executorOutcomeOf, isDeliveryRefusal, refusalJournalText, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, openSealed, ImpersonationRefused, assertSessionUsable, impersonationRowValues, mapImpersonationRow, newImpersonationSession, jobRunOf, assertLeaseMs, runDueJobRuns, SYSTEM_DOOR_WAIT, startJobRun, attachmentTextJob, assertAttachmentExtractors, resolveAttachmentTextBounds, assertJobRegistrable, ATTACHMENT_TEXT_BACKFILL_JOB, ATTACHMENT_TEXT_JOB, kernelJobFor, attachmentTextBackfillJob, searchLimit, searchMatchExpression, globalFetch, assertRedrainWindow, platformRequestOf, undrainedEventsOf, inUnitMovesToAudit, staleCarryRevertRow, staleCarryReverts, recordedOffFromWire, peerSubjectRef, SWITCH_KINDS, reassertActionOf, reassertEntry, reassertOffRow, reassertOnRow, switchActionOf, switchAuditSubject, recordAuditOutcome, auditedCapabilityRevoke, auditWarningOf, switchNotFoundMessage, recordWriteSuperseded, switchSubjectOf, switchSupersededMessage, withRecorded, systemSwitchedOffMessage, tenantSystemSwitchedOffMessage, CrossVerticalRegistry, importCursorSourceOf, exportBreaksOf, exportBreakRefusal, assertPromoteReviewCurrent, promoteRaceRefusal, rebindRaceRefusal, bindExportBreaksOf, bindExportBreakRefusal, scopeMoveOf, runningVersionOf, strandJudgmentsOf, boundShapesOfColumn, installReconciled, collectPeers, peerCallerAt, peerSeats, connectorCallRecord, noopConnectorCallRecorder, recordConnectorCall, settleConnectionUse, splitManifestMigrations, publishedMigrationDigest, migrationChangeRefusal, unknownRoleError, assertRowLimit, assertRowOffset, emptyImportResult, INERT_SCOPE_REASON, lifecycleReceipt, lifecycleRefusal, isPrimaryScope, isPrimaryScopeRow, asyncInvocationId, asyncLinePass, assertNoCallerPurge, purgeReportOf, purgeStillDue, assertBoundOperations, registerTrashTargets, assertModuleDeclared, noteReservedKeys, reservedGrantRefusal, reservedRoleRefusal, reservedShapeRefusal, memberAddedAudit, shapeTopUpBatch, } from '@substrat-run/kernel';
 import { fenceAttachmentSweep, missingAttachmentStore, sweepOrphanAttachments, unsettledCopyRefusal } from '@substrat-run/kernel';
 import { COPY_RESTORE_FENCE_LAPSED, scopeScriptCopyOf } from '@substrat-run/kernel';
 import { attributedView, isModuleErasureCounts, moduleErasurePlan, moduleRowsErased, callReservedStoreOperation, callScopeStore, observeStoreCall, replayStoreErasures, scopeStoreLifecycleOf, scopeStoreRunnersOf } from '@substrat-run/kernel';
@@ -58,6 +58,18 @@ export const tenantUnrecordedLine = (tenantId, scopeId) => ({
     scopeId,
     message: 'admitted to a scope whose tenant is not recorded; a reconcile or lifecycle delivery records it',
 });
+/**
+ * #2430: the line a host writes when a provision or reconcile skips delivered connection grants that
+ * name a key reserved to a system principal here. Ids and keys only.
+ */
+const connectionGrantsSkippedLine = (tenantId, scopeId, skipped) => ({
+    substrat: 'connection-grants-skipped',
+    level: 'warn',
+    tenantId,
+    scopeId,
+    skipped,
+    message: 'delivered connection grants naming a key reserved to a system principal were not seated',
+});
 /**
  * Refuse to mark a scope a copy unless the request classifies it non-primary (#2005). The
  * classification is the platform directory's; the vertical applies the same `isPrimaryScope` to
@@ -332,6 +344,10 @@ export class CloudflareScopeHost {
     // Registration-mechanics bookkeeping (validation only — the DO executes).
     // Code-time, derived from the bundled modules, NOT durable directory state.
     moduleIds = new Set();
+    /** #2430: what a registered module declares `holder: 'system'` — `assignRole`'s refusal reads it. */
+    reservedKeys = new Set();
+    /** #2430: the declared permission surface `registerModule` holds each module to, when given. */
+    permissions;
     /**
      * #1705: this deployment's cross-vertical declarations. The DO holds the handlers and makes
      * every decision. The coordinator keeps its own copy for two reasons: registration refuses
@@ -427,6 +443,10 @@ export class CloudflareScopeHost {
      */
     constructor(options) {
         this.servicePrincipals = options.servicePrincipals;
+        this.permissions = options.permissions;
+        // #2430: what the declared surface reserves holds here too, whatever is registered under its ids.
+        for (const m of options.permissions?.modules ?? [])
+            noteReservedKeys(this.reservedKeys, m.manifest);
         this.secretBox = options.secretBox ?? unconfiguredSecretBox;
         this.tenantStores = options.tenantStores;
         this.blobStores = options.blobStores;
@@ -1055,6 +1075,36 @@ export class CloudflareScopeHost {
      *  #2016: `tenantId`, the tenant the platform restores for: recorded as the scope's receipt in
      *  the load's own transaction, and a store provisioned for another tenant refuses the load. */
     opts) {
+        const out = await this.loadLocal(scopeId, opts, (load) => this.scopeStub(scopeId).importDumpChecked(tables, scopeId, load));
+        return { ...out, tables: tables.length };
+    }
+    /**
+     * One page of this scope's dump from THIS deployment (#2450), behind the vertical's
+     * `/internal/export-page`: `exportScopeStampedLocal` a page at a time, for a scope too large to
+     * cross in one call. With `stamp`, the first page (`cursor` null) mints the load stamp.
+     */
+    async exportScopePageLocal(scopeId, cursor, 
+    /** `maxBytes`: a smaller page than `SCOPE_DUMP_PAGE_MAX_BYTES`, for a test that wants many. */
+    opts) {
+        return unwrapReply(await this.scopeStub(scopeId).exportDumpPage(cursor, {
+            stamp: opts?.stamp === true,
+            ...(opts?.maxBytes !== undefined ? { maxBytes: opts.maxBytes } : {}),
+        }));
+    }
+    /** Stage one page of a dump into a scope in THIS deployment (#2450), for `restoreStagedScopeLocal`. */
+    async stageScopePageLocal(scopeId, stageId, seq, tables) {
+        return unwrapReply(await this.scopeStub(scopeId).stageDumpPage(stageId, seq, tables));
+    }
+    /** `restoreScopeLocal` from the dump staged under `stageId` (#2450), with the same fences and answers. */
+    async restoreStagedScopeLocal(scopeId, stageId, opts) {
+        return this.loadLocal(scopeId, opts, (load) => this.scopeStub(scopeId).commitStagedDumpChecked(stageId, scopeId, load));
+    }
+    /** Drop the dump staged under `stageId` (#2450), if it is still there. */
+    async discardStagedScopeLocal(scopeId, stageId) {
+        return this.scopeStub(scopeId).discardStagedDump(stageId);
+    }
+    /** The restore both `restoreScopeLocal` and `restoreStagedScopeLocal` run around their load. */
+    async loadLocal(scopeId, opts, run) {
         if (opts?.markCopy)
             assertCopyLineage(opts.markCopy);
         // #2314: a load replaces the scope's rows, so the orphan sweep is fenced first, as for a rewind.
@@ -1070,13 +1120,13 @@ export class CloudflareScopeHost {
         };
         // The refusals come back as values (a throw over the RPC carries only its message) and are
         // thrown here, in the vertical's own isolate, so its route answers 409 or 412, not a fault.
-        const out = await this.scopeStub(scopeId).importDumpChecked(tables, scopeId, {
+        const out = await run({
             ...load,
             ...(opts?.expect ? { expect: opts.expect } : {}),
             ...(opts?.fence ? { fence: opts.fence } : {}),
         });
         if (out.refused === false) {
-            return { tables: tables.length, ...(carry ? { switchedOff: out.switchedOff } : {}) };
+            return { tables: out.tables ?? 0, ...(carry ? { switchedOff: out.switchedOff } : {}) };
         }
         if (out.refused === 'kept')
             throw substratError('conflict', KEPT_COPY_REFUSAL);
@@ -1092,7 +1142,7 @@ export class CloudflareScopeHost {
         if (!opts?.loadStamp || now.loadStamp !== opts.loadStamp) {
             throw substratError('precondition_failed', 'scope store changed since the carry read it; nothing was loaded (#1722)');
         }
-        return { tables: tables.length };
+        return { tables: out.tables ?? 0 };
     }
     /** The kept-copy marker of this scope's store in THIS deployment (#1722), or null. */
     async keptCopyLocal(scopeId) {
@@ -1498,6 +1548,7 @@ export class CloudflareScopeHost {
         if (this.moduleIds.has(manifest.id)) {
             throw new Error(`module already registered: ${manifest.id}`);
         }
+        assertModuleDeclared(this.permissions, manifest.id); // #2430
         // #2068: the same refusal the ScopeDO applies at code time, here at registration, so a
         // misdeclared erasure fails where it is registered on both hosts.
         moduleErasurePlan(registration);
@@ -1531,6 +1582,7 @@ export class CloudflareScopeHost {
         // #1705: after the checks above, so a refused module leaves nothing registered here.
         this.crossVertical.register(manifest, registration.imports);
         this.moduleIds.add(manifest.id);
+        noteReservedKeys(this.reservedKeys, manifest);
         if (manifest.schedules && manifest.schedules.length > 0) {
             this.moduleSchedules.set(manifest.id, manifest.schedules);
         }
@@ -2791,6 +2843,10 @@ export class CloudflareScopeHost {
             throw unknownScopeForTenant(tenantId, scopeId);
         }
         await this.peerScopeGate(tenantId, scopeId, 'canAssign');
+        // #2430: the answer a person's door would give — a role carrying a reserved key is refused.
+        const refused = await this.scopeStub(scopeId).reservedRoleRefusalFor(tenantId, roleKey, 'person');
+        if (refused)
+            throw substratError('forbidden', refused);
         const bound = await this.scopeStub(scopeId).canAssignFor(tenantId, scopeId, principalId.parse(principal), roleKey);
         if (!bound)
             throw unknownRoleError(roleKey);
@@ -2804,6 +2860,8 @@ export class CloudflareScopeHost {
         const bound = await this.scopeStub(scopeId).assignScopeRoleBoundedFor(tenantId, scopeId, principalId.parse(caller), principalId.parse(assignee), roleKey);
         if (!bound)
             throw unknownRoleError(roleKey);
+        if ('refused' in bound)
+            throw substratError('forbidden', bound.refused);
         return coverage.parse(bound);
     }
     async listScopeRoleHolders(tenantId, scopeId, principal) {
@@ -2818,6 +2876,8 @@ export class CloudflareScopeHost {
             throw substratError('conflict', `${target} does not hold '${from}' at this scope`);
         if (bound === 'unknown-to')
             throw unknownRoleError(to);
+        if ('refused' in bound)
+            throw substratError('forbidden', bound.refused);
         return coverage.parse(bound);
     }
     async revokeScopeRolesBounded(tenantId, scopeId, caller, principal) {
@@ -3155,10 +3215,12 @@ export class CloudflareScopeHost {
                     // call and transaction — and the SCOPE decides which are due and runs them, so purge
                     // authority is never an argument any stub can pass (`runPurgeSweep`).
                     // #2192: under the run's own id, so the purges and their deliveries join this run's line.
-                    // #2431: what the purges enqueue is not counted (`ScheduleRunReport.platformRequests`).
+                    // #2431: the purges' own requests run inside the scope, which reports no count for them;
+                    // the deliveries their events route to the platform are counted below, as an invoke's are.
                     const pass = await door.through((instance) => stub.runPurgeSweep(schedule.operation, tenantId, scopeId, instance, invocationId));
                     // The purges' events, delivered the way each invoke's own tail delivers them.
-                    await this.drainExecutors(tenantId, scopeId, invocationId);
+                    const delivered = await this.drainExecutors(tenantId, scopeId, invocationId);
+                    platformRequests += delivered.routedToPlatform ?? 0;
                     stillDue = purgeStillDue(pass);
                     const outcome = purgeReportOf(schedule.operation, schedule.purge.entityType, pass);
                     report.errors.push(...outcome.errors);
@@ -4127,6 +4189,19 @@ export class CloudflareScopeHost {
                 }));
             },
             assignRole: async (actor, assignment) => {
+                // #2430: the platform's door — a role mixing reserved and other keys is refused (K-55).
+                // At a scope node, read where the checker reads the role, against the scope class's own
+                // reservations (it answers null when it has none). At the tenant node, against this host's.
+                {
+                    const { tenantId, scopeId } = assignment.node;
+                    const refusal = scopeId
+                        ? await this.scopeStub(scopeId).reservedRoleRefusalFor(tenantId, assignment.roleKey, 'platform')
+                        : this.reservedKeys.size > 0
+                            ? await this.cp.getRole(tenantId, assignment.roleKey).then((role) => role && reservedRoleRefusal(role, this.reservedKeys, 'platform'))
+                            : null;
+                    if (refusal)
+                        throw substratError('forbidden', refusal);
+                }
                 const subject = `principal:${assignment.principalId}`;
                 if (assignment.node.scopeId) {
                     await this.writeScopeTuple(assignment.node.scopeId, subject, `role:${assignment.roleKey}`, `scope:${assignment.node.scopeId}`, null);
@@ -4164,6 +4239,7 @@ export class CloudflareScopeHost {
                 // trust: the parse is where an `expiresAt` carrying a UTC offset is normalised
                 // to Z text (#963), and liveness here is a lexicographic `expires_at > ?`.
                 const grant = capabilityGrant.parse(raw);
+                await this.refuseReservedGrant([grant.permission], grant.node.scopeId); // #2430
                 await writeGrant(`principal:${grant.principalId}`, grant.permission, grant.node, grant.entity, grant.expiresAt);
                 await this.recordAdmin(actor, 'grant', { tenantId: grant.node.tenantId, scopeId: grant.node.scopeId }, null, grant);
                 // Tenant-level grant → changes the projected set. Scope-level + entity
@@ -4209,6 +4285,12 @@ export class CloudflareScopeHost {
                             `${grant.node.scopeId} runs '${scope.vertical ?? 'none'}'`);
                     }
                 }
+                // #2430: a connection acts for the external provider holding its token, so it is never
+                // given a key reserved to a system principal — refused before the directory record, so a
+                // refused grant is gathered by no later provision. Against this host's reservations, and
+                // the scope class's when the scope is served here; a delegated scope's deployment judges
+                // its own at delivery (`connectorGrantLocal`). A grant recorded before stays.
+                await this.refuseReservedGrant([grant.permission], this.connectorDelegation ? null : (grant.node.scopeId ?? null));
                 // #592: the directory-side record FIRST, so a grant whose tuple delivery
                 // fails below is still gathered by the next provision/reconcile — the
                 // repair channel — instead of vanishing. The tuple stays the only thing
@@ -4357,6 +4439,7 @@ export class CloudflareScopeHost {
                 // The org must exist in the node's tenant. A grant to a phantom org looks
                 // applied, resolves for nobody, and still shows up in the permission diff.
                 await requireOrg(node.tenantId, orgId);
+                await this.refuseReservedGrant([permission], node.scopeId); // #2430: an org's members are people
                 await writeGrant(`org:${orgId}`, permission, node, entity);
                 await this.recordAdmin(actor, 'grantToOrg', { tenantId: node.tenantId, scopeId: node.scopeId }, null, { orgId, permission, node, entity });
                 if (!node.scopeId)
@@ -5115,7 +5198,9 @@ export class CloudflareScopeHost {
                     : this.adminEntry(actor, 'unassignRole', { tenantId, scopeId: null }, assignment, null), 
                 // #2047: the org's own row, when the change joins or leaves one. The unit fills in its
                 // `before`/`after` and writes it only for what it does — a join's carries the expiry.
-                orgId ? this.adminEntry(actor, op === 'add' ? 'addMember' : 'removeMember', { tenantId }, null, null) : undefined);
+                orgId ? this.adminEntry(actor, op === 'add' ? 'addMember' : 'removeMember', { tenantId }, null, null) : undefined, 
+                // #2430: what this host's modules reserve, so the unit refuses an add of a role carrying it.
+                [...this.reservedKeys]);
                 // The tenant-level tuple, or its tombstone, reaches the projections.
                 if (result.applied && (op === 'add' || result.changed))
                     await this.fanOut(tenantId);
@@ -7475,6 +7560,10 @@ export class CloudflareScopeHost {
      */
     async provisionScopeLocal(input) {
         const carry = recordedOffFromWire(input);
+        // #2430: refused before anything is written, rather than at the top-up after the projection.
+        if (input.entityGrants)
+            await this.refuseReservedShapes(input.entityGrants, input.scopeId);
+        const connections = await this.seatableConnectionGrants(input.tenantId, input.scopeId, input.connectionGrants);
         const services = await this.servicePrincipals?.(input.tenantId, input.scopeId);
         const stub = this.scopeStub(input.scopeId);
         await this.migrateAndRecord(input.scopeId); // create the module tables (setMigrationState no-ops on a null CP)
@@ -7511,7 +7600,7 @@ export class CloudflareScopeHost {
                 expires_at: null,
                 lockout_reseat: true,
             },
-            ...this.declaredSeatsLocal(input.scopeId, input.connectionGrants),
+            ...this.declaredSeatsLocal(input.scopeId, connections.seat),
         ], 
         // #406: identity links, delivered by the platform with provisioning exactly as
         // entitlements are (#310). Preserve-on-undefined, so an absent field never wipes
@@ -7546,8 +7635,31 @@ export class CloudflareScopeHost {
             ...(carry ? { switchedOff } : {}),
             ...(shapes ? { retirementsLeftOpen: shapes.retirementsLeftOpen ?? 0 } : {}),
             ...(shapes?.boundEver ? { boundShapeTypes: shapes.boundEver } : {}),
+            ...(connections.skipped.length ? { skippedConnectionGrants: connections.skipped } : {}),
         };
     }
+    /**
+     * #2430: the delivered connection grants a provision or reconcile may seat, and those it skips. A
+     * connection acts for the external provider holding its token, so a grant naming a key reserved
+     * to a system principal here (this host's reservations, or the scope class's) is never seated.
+     * The directory may have recorded it before these checks existed, so it is skipped and reported
+     * (in the answer and as a warn line), never a failed provision: one such grant must not stop a
+     * promote or a reconcile seating everything else.
+     */
+    async seatableConnectionGrants(tenantId, scopeId, grants) {
+        if (!grants?.length)
+            return { seat: grants, skipped: [] };
+        const permissions = [...new Set(grants.map((g) => g.permission))];
+        const reserved = new Set([
+            ...permissions.filter((p) => this.reservedKeys.has(p)),
+            ...(await this.scopeStub(scopeId).reservedAmong(permissions)),
+        ]);
+        if (reserved.size === 0)
+            return { seat: grants, skipped: [] };
+        const skipped = grants.filter((g) => reserved.has(g.permission)).map((g) => ({ connectionId: g.connectionId, permission: g.permission }));
+        console.warn(JSON.stringify(connectionGrantsSkippedLine(tenantId, scopeId, skipped)));
+        return { seat: grants.filter((g) => !reserved.has(g.permission)), skipped };
+    }
     /**
      * The tuples this deployment's code declares for one scope, seated by every provision and
      * reconcile: each module's SCHEDULE grants (#383, #461 — without them the grant-is-the-switch
@@ -7591,9 +7703,13 @@ export class CloudflareScopeHost {
         if (!(await stub.servesTenant(input.tenantId)))
             throw unknownScopeForTenant(input.tenantId, input.scopeId);
         const carry = recordedOffFromWire(input);
+        const connections = await this.seatableConnectionGrants(input.tenantId, input.scopeId, input.connectionGrants); // #2430
         await this.migrateAndRecord(input.scopeId);
-        const switchedOff = await stub.seatTuples(this.declaredSeatsLocal(input.scopeId, input.connectionGrants), carry ? { scopeId: input.scopeId, at: new Date().toISOString(), ...carry } : undefined);
-        return carry ? { switchedOff } : {};
+        const switchedOff = await stub.seatTuples(this.declaredSeatsLocal(input.scopeId, connections.seat), carry ? { scopeId: input.scopeId, at: new Date().toISOString(), ...carry } : undefined);
+        return {
+            ...(carry ? { switchedOff } : {}),
+            ...(connections.skipped.length ? { skippedConnectionGrants: connections.skipped } : {}),
+        };
     }
     /**
      * Resolve an external identity from a scope's PROJECTED links (#406) — the CP-less
@@ -7618,6 +7734,12 @@ export class CloudflareScopeHost {
      * already projected (via `provisionScopeLocal`), or the local checker expands it to nothing.
      */
     async assignScopeRole(scopeId, principal, roleKey) {
+        // #2430: a platform door, as `HostAdmin.assignRole` is — a role mixing reserved and other keys
+        // is refused, against the scope class's own reservations and the role as the checker reads it
+        // for the tenant the scope's receipt names (`reservedRoleRefusalHere` says what happens without one).
+        const refusal = await this.scopeStub(scopeId).reservedRoleRefusalHere(roleKey, 'platform');
+        if (refusal)
+            throw substratError('forbidden', refusal);
         unwrapReply(await this.scopeStub(scopeId).writeTuple(`principal:${principal}`, `role:${roleKey}`, `scope:${scopeId}`, null));
     }
     /**
@@ -7677,6 +7799,7 @@ export class CloudflareScopeHost {
      * (writeTuple is INSERT OR REPLACE), so it is safe to re-issue on every link.
      */
     async grantEntityLocal(scopeId, principal, permission, entity) {
+        await this.refuseReservedGrant([permission], scopeId); // #2430
         unwrapReply(await this.scopeStub(scopeId).writeTuple(`principal:${principal}`, `granted:${permission}`, entityObjectRef(entity, 'grantEntityLocal'), // #1856
         null));
     }
@@ -7689,8 +7812,29 @@ export class CloudflareScopeHost {
      * like `grantEntityLocal`: it brings back a key or a marker a revoke tombstoned.
      */
     async grantEntityShapeLocal(scopeId, principal, entity, permissions) {
+        await this.refuseReservedGrant(permissions, scopeId); // #2430
         await this.scopeStub(scopeId).grantEntityShape(principal, entity, permissions);
     }
+    /**
+     * #2430: refuse a raw grant of a reserved key (`reservedGrantRefusal`): against this host's
+     * reservations, and at a scope node against the scope class's own, which may name more.
+     */
+    async refuseReservedGrant(permissions, scopeId) {
+        const refusal = reservedGrantRefusal(permissions, this.reservedKeys) ??
+            (scopeId ? await this.scopeStub(scopeId).reservedGrantRefusalFor([...permissions]) : null);
+        if (refusal)
+            throw substratError('forbidden', refusal);
+    }
+    /**
+     * #2430: refuse a reconcile of declared shapes when one holds a reserved key in `permissions`
+     * (`reservedShapeRefusal`): against this host's reservations, then the scope class's own.
+     */
+    async refuseReservedShapes(shapes, scopeId) {
+        const refusal = reservedShapeRefusal(shapes, this.reservedKeys) ??
+            (await this.scopeStub(scopeId).reservedShapeRefusalFor(shapes.map((s) => ({ entityType: s.entityType, permissions: [...s.permissions] }))));
+        if (refusal)
+            throw substratError('forbidden', refusal);
+    }
     /**
      * Top every holder of each declared shape up to the shape as it is now (#2071), in bounded
      * passes — at most `batch` rows of work per scope transaction (default 500, at most 5000;
@@ -7702,6 +7846,7 @@ export class CloudflareScopeHost {
      */
     async topUpEntityGrantShapesLocal(tenantId, scopeId, shapes, batch) {
         const limit = shapeTopUpBatch(batch);
+        await this.refuseReservedShapes(shapes, scopeId); // #2430
         let toppedUp = 0;
         let retired = 0;
         let retirementsLeftOpen = 0;
@@ -7775,6 +7920,8 @@ export class CloudflareScopeHost {
      * while the tuple remains; `expiresAt` bounds the tuple itself.
      */
     async connectorGrantLocal(connectionId, scopeId, permission, expiresAt) {
+        // #2430: against the reservations of the scope served here, as `grantToConnection` asks.
+        await this.refuseReservedGrant([permission], scopeId);
         await this.writeScopeTuple(scopeId, subjectRef({ kind: 'connection', id: connectionId }), `granted:${permission}`, `scope:${scopeId}`, expiresAt ?? null);
     }
     /** #2045 (Codex r3): every switch mover here honours the fence — what `/internal/switch-fence` reports. */
@@ -8071,6 +8218,18 @@ export class CloudflareScopeHost {
         }
         return importsOfManifestJson(v.manifest_json);
     }
+    /**
+     * What one pushed version declares about connection landings (#2316), from its stored manifest:
+     * the connector pass reads it for each install's running version. Unaudited for the reason
+     * {@link versionImports} is: it is the platform's own code metadata, read every pass.
+     */
+    async versionConnectionLandings(verticalSlug, versionId) {
+        const v = await this.cp.readVersion(versionId);
+        if (!v || v.vertical_slug !== verticalSlug) {
+            throw substratError('not_found', `unknown version ${versionId} for vertical '${verticalSlug}'`);
+        }
+        return connectionLandingsOfManifestJson(v.manifest_json);
+    }
 }
 /** A ledger row -> the wire entry, the attribution re-nested (#1054). */
 function modelUsageEntryOf(r) {