@substrat-run/adapter-cloudflare 0.162.0 → 0.164.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, connectionLandingsOfManifestJson, exportsOfManifestJson, assertNoBindingShapeBreak, importCursorMove, importCursorMoveAt, importCursorMoved, accessLogEntry, adminLogEntry, opsFailureEntry, opsFailureFingerprint, issueEntry, findingEntry, findingRuleEntry, sweepRunEntry, FRESHNESS_HEARTBEAT_MINUTES, sweepRunsPayload, modelUsageEntry, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, deploymentWireAuth, 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, requestDay, requestRollupDay, meterDay, meterDayTake, verticalOwnerPeriod, 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, errorCodeOf, 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, connectorsOfManifestJson, exportsOfManifestJson, assertNoBindingShapeBreak, importCursorMove, importCursorMoveAt, importCursorMoved, accessLogEntry, adminLogEntry, opsFailureEntry, opsFailureFingerprint, issueEntry, findingEntry, findingRuleEntry, sweepRunEntry, FRESHNESS_HEARTBEAT_MINUTES, sweepRunsPayload, modelUsageEntry, createTenantInput, identityLink, identityPool, createOrgInput, promotionAcknowledgement, bindAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, registerVerticalInput, vertical as verticalSchema, verticalServingState, deploymentWireAuth, 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, requestDay, requestRollupDay, meterDay, meterDayTake, verticalOwnerPeriod, 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, errorCodeOf, 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, bytesStream, isSizedByteStream, openAttachmentByteStream, putAttachmentBytes, entitlementDenial, requiredEntitlementFor, foldMeterReading, parseValidationRecords, readableScopes, resolveScopeRecord, ulid, withheldOpsFailure, 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, fetchLikeOf, deadlineFetch, 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, servingRaceRefusal, 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, scopeNotHeldRefusal, isPrimaryScope, isPrimaryScopeRow, asyncInvocationId, asyncLinePass, assertNoCallerPurge, purgeReportOf, purgeStillDue, assertBoundOperations, registerTrashTargets, assertModuleDeclared, noteDeclaredKeys, noteReservedKeys, reservedGrantRefusal, reservedRoleRefusal, reservedRoleSetRefusal, reservedShapeRefusal, SEAT_HOLDING_SCOPE_STATUSES, dumpRoleRefusal, dumpRoleState, memberAddedAudit, shapeTopUpBatch, verticalOwnerNow, } from '@substrat-run/kernel';
+import { attachmentBlobKey, normalizeUploadMediaType, redeemOrReplayUploadLink, attachmentSha256, bytesStream, isSizedByteStream, openAttachmentByteStream, putAttachmentBytes, entitlementDenial, requiredEntitlementFor, foldMeterReading, parseValidationRecords, readableScopes, resolveScopeRecord, ulid, withheldOpsFailure, 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, fetchLikeOf, deadlineFetch, 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, servingRaceRefusal, migratesFrom, servedFromRow, 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, scopeNotHeldRefusal, isPrimaryScope, isPrimaryScopeRow, asyncInvocationId, asyncLinePass, assertNoCallerPurge, purgeReportOf, purgeStillDue, assertBoundOperations, registerTrashTargets, assertModuleDeclared, noteDeclaredKeys, noteReservedKeys, reservedGrantRefusal, reservedRoleRefusal, reservedRoleSetRefusal, reservedShapeRefusal, SEAT_HOLDING_SCOPE_STATUSES, dumpRoleRefusal, dumpRoleState, memberAddedAudit, shapeTopUpBatch, verticalOwnerNow, } from '@substrat-run/kernel';
 import { fenceAttachmentSweep, missingAttachmentStore, sweepOrphanAttachments, unsettledCopyRefusal } from '@substrat-run/kernel';
 import { assertWireAuthFilter, wireAuthAccessTarget, COPY_RESTORE_FENCE_LAPSED, scopeScriptCopyOf } from '@substrat-run/kernel';
 import { attributedView, isModuleErasureCounts, moduleErasurePlan, moduleRowsErased, callReservedStoreOperation, callScopeStore, observeStoreCall, replayStoreErasures, scopeStoreLifecycleOf, scopeStoreRunnersOf } from '@substrat-run/kernel';
@@ -79,6 +79,20 @@ const connectionGrantsSkippedLine = (tenantId, scopeId, skipped) => ({
 function projectedRoleRows(roles) {
     return roles.map((r) => ({ role_key: r.key, permissions: JSON.stringify(r.permissions), source: r.source, holder: r.holder === 'system' ? 'system' : 'person' }));
 }
+/** #2555: a control-plane-full load whose role set was refused in its unit (`loadProjected`), told apart by identity. */
+const loadRoleRefusals = new WeakSet();
+/**
+ * #2555: what a refused second read tells staff. The load landed and judged the older set, and the
+ * next fan-out, which is not judged (K-55), would write the refused definition over the seats.
+ */
+const SECOND_READ_REMEDY = "The load landed with the roles it judged, and holds only until the next fan-out: take the dump's seats in that role back, or define the role person-held again (K-55)";
+/**
+ * #2555: a load projection's directory state as one comparable text; its judge is not state. Each
+ * list is compared as a set: the directory reads some of them in no fixed order.
+ */
+function projectionDigest({ judge: _judge, ...state }) {
+    return JSON.stringify(Object.entries(state).map(([k, v]) => [k, Array.isArray(v) ? v.map((x) => JSON.stringify(x)).sort() : v]));
+}
 function assertCopyLineage(lineage) {
     if (isPrimaryScope(lineage)) {
         throw substratError('conflict', 'mark-copy refused: the directory classifies this scope as primary, not as a copy');
@@ -151,9 +165,11 @@ export const SWITCH_HOLD_SNAPSHOT_MS = 2_000;
  * one older than `SWITCH_HOLD_SNAPSHOT_MS`. A state read that met rewound storage therefore
  * finished at least this long after the hold was written, so a snapshot taken before the hold
  * is past its age by then and is re-read. Each side measures a duration on its own clock;
- * nothing compares two clocks.
+ * nothing compares two clocks. Derived from the snapshot age, never set on its own, so no host
+ * can be given a settle that does not outlast its snapshot (`switchHoldSnapshotMs`).
  */
-export const SWITCH_HOLD_SETTLE_MS = SWITCH_HOLD_SNAPSHOT_MS + 1_000;
+export const switchHoldSettleMs = (snapshotMs) => (snapshotMs * 3) / 2;
+export const SWITCH_HOLD_SETTLE_MS = switchHoldSettleMs(SWITCH_HOLD_SNAPSHOT_MS);
 /**
  * #1839: how many times a rewind waits again, after its settle, for a row a late OFF added to its
  * claim to be `SWITCH_HOLD_SETTLE_MS` old. The settle argument above holds per ROW, so a row
@@ -465,6 +481,9 @@ export class CloudflareScopeHost {
      * join this one read rather than each sending their own.
      */
     holdRefresh = null;
+    /** #1819: `SWITCH_HOLD_SNAPSHOT_MS` and `SWITCH_HOLD_SETTLE_MS`, unless `switchHoldSnapshotMs` is given. */
+    holdSnapshotMs;
+    holdSettleMs;
     /**
      * MUST be constructed per request. Never cache an instance across requests.
      *
@@ -495,6 +514,12 @@ export class CloudflareScopeHost {
         // #2498: whatever fetch is injected, a sized stream body reaches it converted (`fetchLikeOf`).
         this.fetchImpl = fetchLikeOf(options.fetch ?? globalFetch);
         this.streamIdleMs = options.streamIdleTimeoutMs;
+        this.holdSnapshotMs = options.switchHoldSnapshotMs ?? SWITCH_HOLD_SNAPSHOT_MS;
+        // NaN or Infinity never expires a snapshot; zero or less settles for nothing.
+        if (!Number.isFinite(this.holdSnapshotMs) || this.holdSnapshotMs <= 0) {
+            throw new RangeError(`switchHoldSnapshotMs must be a positive, finite number of milliseconds, got ${this.holdSnapshotMs}`);
+        }
+        this.holdSettleMs = switchHoldSettleMs(this.holdSnapshotMs);
         this.connectorCalls = options.connectorCalls ?? noopConnectorCallRecorder;
         this.scopeLocalPermissions = options.scopeLocalPermissions ?? false;
         this.scopeNs = options.scope;
@@ -1506,6 +1531,18 @@ export class CloudflareScopeHost {
     async redrainCountLocal(scopeId, drainedBefore) {
         return heldOrRefused(scopeId, await this.scopeStub(scopeId).redrainCountIfHeld(drainedBefore));
     }
+    /**
+     * RFC wire-signing §4: spend a signed call's nonce in this scope's own object, the one the
+     * call's handler reaches through the same stub. The platform's entry calls it, through the host
+     * the vertical registered, only after every other check of the envelope passed, and only for
+     * the scope the verified envelope names. `true` once per nonce, `false` for a nonce already spent
+     * or a claim after `until`, and a throw when the store is at its cap. The tenant is the one the
+     * envelope names beside the scope; the object is keyed by the scope alone, so it is not read here.
+     * No provisioned check: the call that provisions a scope spends its nonce there too.
+     */
+    async claimWireNonceLocal(_tenantId, scopeId, nonce, until) {
+        return this.scopeStub(scopeId).claimWireNonce(nonce, until);
+    }
     /**
      * The PITR bookmarks one scope recorded before its migration passes (#286) — the
      * rewind points a backout UI offers. Behind the vertical's platform-gated
@@ -1735,6 +1772,10 @@ export class CloudflareScopeHost {
     }
     // -- scope lifecycle ------------------------------------------------------
     async provisionScope(actor, input) {
+        await this.provisionScopeCreating(actor, input);
+    }
+    /** `provisionScope`, answering whether this call created the directory row (#2555: an import's teardown). */
+    async provisionScopeCreating(actor, input) {
         // Shared with the pure adapter so the defaults cannot drift between them.
         const record = resolveScopeRecord(input);
         // Fail-closed tenant gate throws out of the awaited cp call BEFORE migrate
@@ -1790,6 +1831,7 @@ export class CloudflareScopeHost {
         if (created) {
             await this.recordAdmin(actor, 'provisionScope', { tenantId: input.tenantId, scopeId: input.scopeId, vertical: record.vertical }, null, record);
         }
+        return created;
     }
     // Per-tenant relational stores (#301, PR-2 — the live D1 path). The coordinator holds
     // the platform's D1 credential (the same split secretBox uses: the DO records, it never
@@ -2175,19 +2217,53 @@ export class CloudflareScopeHost {
         // replaces its provisioned schema with the dump wholesale (drop-then-replay), so
         // the end state is the dump, at the source's frontier. Provenance is stamped from
         // the dump unless the caller set it (§3: a fork always records its origin).
-        await this.provisionScope(actor, {
+        const created = await this.provisionScopeCreating(actor, {
             ...input,
             forkedFrom: input.forkedFrom ?? dump.scopeId,
             forkedAt: input.forkedAt ?? dump.capturedAt,
         });
-        await this.scopeStub(input.scopeId).importDump(dump.tables, input.scopeId, {
-            sourceScopeId: dump.scopeId,
-            // A fork: its callers (snapshotScope) hand it a dump the platform exported.
-            exact: true,
-        });
+        // A fork: its callers (snapshotScope) hand it a dump the platform exported.
+        const load = { sourceScopeId: dump.scopeId, exact: true };
+        // #2555: an import lands with the directory's current permission state, as a restore does. A
+        // snapshot is left as it was: a same-instant copy of a live scope the fan-out keeps current.
+        const projection = judge ? await this.loadProjectionFor(input.tenantId, input.vertical) : undefined;
+        let reprojected;
+        if (projection === undefined)
+            await this.scopeStub(input.scopeId).importDump(dump.tables, input.scopeId, load);
+        else {
+            try {
+                await this.loadProjected(input.scopeId, dump.tables, load, projection, 'import');
+            }
+            catch (e) {
+                if (loadRoleRefusals.has(e))
+                    await this.dropRefusedImport(actor, input.tenantId, input.scopeId, created);
+                throw e;
+            }
+        }
+        // The second read comes before the stores, so a scope taken down here has none of the dump's
+        // store rows either.
+        if (projection) {
+            const converged = await this.convergeLoadedProjection(input.tenantId, input.scopeId, input.vertical, projection, 'import');
+            reprojected = converged.reprojected;
+            if ('error' in converged) {
+                // A scope this call created is not activated, and goes as a refused import does. One that
+                // existed has had its rows replaced by the committed load, so its stores follow the load
+                // (as a restore's do) and the import is recorded first.
+                if (created)
+                    await this.dropRefusedImport(actor, input.tenantId, input.scopeId, created);
+                else {
+                    await this.importScopeStores(input.tenantId, input.scopeId, dump.stores);
+                    await this.recordImport(actor, input, dump, reprojected);
+                }
+                throw converged.error;
+            }
+        }
         await this.importScopeStores(input.tenantId, input.scopeId, dump.stores);
         await this.admin.activateScope(actor, input.tenantId, input.scopeId);
-        await this.recordAdmin(actor, 'importScope', { tenantId: input.tenantId, scopeId: input.scopeId }, null, { sourceScopeId: dump.scopeId, tables: dump.tables.length, capturedAt: dump.capturedAt });
+        await this.recordImport(actor, input, dump, reprojected);
+    }
+    async recordImport(actor, input, dump, reprojected) {
+        await this.recordAdmin(actor, 'importScope', { tenantId: input.tenantId, scopeId: input.scopeId }, null, { sourceScopeId: dump.scopeId, tables: dump.tables.length, capturedAt: dump.capturedAt, ...(reprojected ? { reprojected } : {}) });
     }
     async restoreScope(actor, tenantId, scopeId, dump, opts) {
         // Restore never creates a scope (that is importScope) — an unknown target fails closed.
@@ -2197,6 +2273,8 @@ export class CloudflareScopeHost {
         this.refuseUnusableScopeStores(dump.stores, existing.vertical);
         // #2555: judged before the fence, so a refused restore moves nothing.
         await this.refuseDumpRoles(tenantId, scopeId, dump);
+        // #2555: the directory's state the load projects, judged again in its unit against the seats it loads.
+        const projection = await this.loadProjectionFor(tenantId, existing.vertical);
         // #2314: the load replaces the scope's rows, so the orphan sweep is fenced first.
         await this.fenceOrphanSweep(scopeId, tenantId);
         // #1742: a dump from before a switch was pulled brings the module's grants back live, so
@@ -2206,21 +2284,25 @@ export class CloudflareScopeHost {
         const ownStore = this.cpLess || existing.vertical === null;
         const replayAt = new Date().toISOString();
         const carry = ownStore ? await this.recordedOffCarry(tenantId, scopeId, replayAt) : undefined;
-        const switchedOff = await this.scopeStub(scopeId).importDump(dump.tables, scopeId, {
-            switchOff: carry ? { at: replayAt, ...carry } : undefined,
-            sourceScopeId: opts?.sourceScopeId ?? dump.scopeId,
-        });
+        const switchedOff = await this.loadProjected(scopeId, dump.tables, { switchOff: carry ? { at: replayAt, ...carry } : undefined, sourceScopeId: opts?.sourceScopeId ?? dump.scopeId }, projection, 'restore');
         await this.importScopeStores(tenantId, scopeId, dump.stores);
         const replay = await this.replayShreddedStoreErasures(actor, tenantId, scopeId, (opts?.sourceScopeId ?? dump.scopeId));
+        // The load has committed, so a re-projection refused or failed is recorded with the restore and
+        // the switches still go back off below; it is thrown last, loud.
+        const converged = projection ? await this.convergeLoadedProjection(tenantId, scopeId, existing.vertical, projection, 'restore') : {};
+        const reprojected = converged.reprojected;
         await this.recordAdmin(actor, 'restoreScope', { tenantId, scopeId }, null, {
             sourceScopeId: dump.scopeId,
             tables: dump.tables.length,
             capturedAt: dump.capturedAt,
             ...replay,
+            ...(reprojected ? { reprojected } : {}),
         });
         if (carry) {
             await this.admin.reassertSystemSwitches(actor, { tenantId, scopeId }, { appliedInUnit: switchedOff });
         }
+        if ('error' in converged)
+            throw converged.error;
         return replay;
     }
     /**
@@ -4636,79 +4718,39 @@ export class CloudflareScopeHost {
             // -- the hostname map (K-26) -------------------------------------------
             bindHostname: async (actor, input) => {
                 const parsed = bindHostnameInput.parse(input);
-                const scope = await this.cp.getScopeRecord(parsed.tenantId, parsed.scopeId);
-                if (!scope) {
-                    throw substratError('not_found', `unknown scope ${parsed.scopeId} in tenant ${parsed.tenantId}`);
-                }
-                const existing = await this.cp.readHostname(parsed.hostname);
-                // The holder's own status decides whether the name is reclaimable. Read it from
-                // the scope record rather than joining it onto the hostname read: the router
-                // shares that read's shape, and a scope status it can see is an invitation to
-                // re-check suspension there (route-resolver's `readRoute` deliberately has none).
-                const holder = existing && existing.scope_id !== parsed.scopeId
-                    ? await this.cp.getScopeRecord(existing.tenant_id, existing.scope_id)
-                    : undefined;
-                const holderReleased = holder?.status === 'archived' || holder?.status === 'reaped';
-                if (existing && existing.scope_id !== parsed.scopeId && !holderReleased) {
-                    // A hostname routes to exactly one place; silently rebinding would move
-                    // another tenant's traffic. Exception: the holder is ARCHIVED or REAPED (a
-                    // deleted app, storage since wiped) — it has released the name, so the rebind
-                    // reclaims it.
-                    throw substratError('conflict', `hostname '${parsed.hostname}' is already bound to another scope`);
-                }
-                // Exactly one canonical per (scope, surface).
-                if (parsed.canonical)
-                    await this.cp.demoteCanonical(parsed.scopeId, parsed.surface);
-                await this.cp.upsertHostname({
+                // #2526: the scope, the holder whose status decides whether the name is reclaimable
+                // (archived or reaped released it), the canonical's demotion, the bind and its row are one
+                // ControlPlaneDO unit; the row's vertical is the scope's as that unit read it.
+                await this.directory('bindHostnameInDirectory', {
                     hostname: parsed.hostname,
                     tenantId: parsed.tenantId,
                     scopeId: parsed.scopeId,
-                    verticalSlug: scope.vertical,
                     surface: parsed.surface,
                     region: parsed.region,
                     canonical: parsed.canonical,
                     createdAt: new Date().toISOString(),
-                });
-                await this.recordAdmin(actor, 'bindHostname', { tenantId: parsed.tenantId, scopeId: parsed.scopeId, vertical: scope.vertical }, null, parsed);
+                }, this.adminEntry(actor, 'bindHostname', { tenantId: parsed.tenantId, scopeId: parsed.scopeId }, null, parsed));
             },
+            // #2526: the three below read their row in the unit that writes it (refusing an unbound name
+            // `not_found`, judging the no-op, filling the row's target and `before`), so the template
+            // carries no tenant or scope of its own.
             setHostnameStatus: async (actor, raw, status, note) => {
                 const hostname = raw.toLowerCase(); // DNS is case-insensitive; the map is normalized
-                const row = await this.cp.readHostname(hostname);
-                if (!row)
-                    throw substratError('not_found', `unknown hostname '${hostname}'`);
-                if (row.status === status)
-                    return; // idempotent, unaudited
-                await this.cp.setHostnameStatus(hostname, status, note ?? null);
-                await this.recordAdmin(actor, 'setHostnameStatus', { tenantId: row.tenant_id, scopeId: row.scope_id }, { status: row.status }, { status, note: note ?? null });
+                await this.directory('setHostnameStatus', hostname, status, note ?? null, this.adminEntry(actor, 'setHostnameStatus', { tenantId: null }, null, { status, note: note ?? null }));
             },
             setHostnameIssuance: async (actor, raw, fields) => {
                 const hostname = raw.toLowerCase(); // DNS is case-insensitive; the map is normalized
-                const row = await this.cp.readHostname(hostname);
-                if (!row)
-                    throw substratError('not_found', `unknown hostname '${hostname}'`);
-                // A poll that finds nothing changed (same status, same records, id already set)
-                // is not an event — skip the write and the audit entry, so the reconcile sweep
-                // does not flood the admin log with no-op rows every interval.
-                const recordsJson = JSON.stringify(fields.validationRecords);
-                const idUnchanged = fields.customHostnameId === undefined || fields.customHostnameId === row.custom_hostname_id;
-                if (row.status === fields.status && (row.validation_records ?? '[]') === recordsJson && idUnchanged) {
-                    return;
-                }
-                await this.cp.setHostnameIssuance(hostname, {
+                await this.directory('setHostnameIssuance', hostname, {
                     status: fields.status,
                     note: fields.note ?? null,
                     customHostnameId: fields.customHostnameId,
-                    validationRecords: fields.validationRecords.length ? recordsJson : null,
-                });
-                await this.recordAdmin(actor, 'setHostnameIssuance', { tenantId: row.tenant_id, scopeId: row.scope_id }, { status: row.status }, { status: fields.status, note: fields.note ?? null });
+                    validationRecords: fields.validationRecords.length ? JSON.stringify(fields.validationRecords) : null,
+                }, this.adminEntry(actor, 'setHostnameIssuance', { tenantId: null }, null, { status: fields.status, note: fields.note ?? null }));
             },
             unbindHostname: async (actor, raw, owner) => {
                 const hostname = raw.toLowerCase(); // DNS is case-insensitive; the map is normalized
                 // The row the delete removed, so an owner is judged by the delete itself (#2285).
-                const row = await this.cp.deleteHostname(hostname, owner);
-                if (!row)
-                    return; // idempotent, and a no-op is not audited
-                await this.recordAdmin(actor, 'unbindHostname', { tenantId: row.tenant_id, scopeId: row.scope_id }, { hostname, status: row.status }, null);
+                await this.directory('deleteHostname', hostname, owner, this.adminEntry(actor, 'unbindHostname', { tenantId: null }, null, null));
             },
             listHostnames: async (actor, filter) => {
                 const rows = await this.cp.listHostnames({
@@ -4761,6 +4803,9 @@ export class CloudflareScopeHost {
                     installSpec.provides = parsed.provides;
                 if (parsed.requires)
                     installSpec.requires = parsed.requires;
+                // The declared vertical-defined connectors (vertical-connectors.md §7.2), the dashboard's door.
+                if (parsed.connectors)
+                    installSpec.connectors = parsed.connectors;
                 // Declared provisioner intent (#455) — the request half of the tenant-provisioner
                 // capability; the grant is its own column, never part of this refreshable bag.
                 if (parsed.provisions)
@@ -4912,7 +4957,7 @@ export class CloudflareScopeHost {
                 // Judged in the DO's unit (#2528): an admitted version is refused, a rejected one is a no-op.
                 await this.directory('rejectVersion', versionId, note, this.adminEntry(actor, 'rejectVersion', { tenantId: null }, null, { admission: 'rejected', note }));
             },
-            promoteVersion: async (actor, verticalSlug, channel, versionId, acknowledge) => {
+            promoteVersion: async (actor, verticalSlug, channel, versionId, acknowledge, options) => {
                 const incoming = await this.cp.readVersion(versionId);
                 if (!incoming)
                     throw substratError('not_found', `unknown version ${versionId}`);
@@ -4958,6 +5003,7 @@ export class CloudflareScopeHost {
                     ack,
                     channel,
                     baseId: outgoing?.id ?? null,
+                    permissionsChange: outgoing !== undefined && outgoing.permission_digest !== incoming.permission_digest,
                     migrationsChange: outgoing !== undefined && outgoing.migration_digest !== incoming.migration_digest,
                     read: async () => ({ base: outgoing ? await reviewed(outgoing) : null, incoming: await reviewed(incoming) }),
                 });
@@ -4986,7 +5032,8 @@ export class CloudflareScopeHost {
                 // only if the pointer still names `outgoing`; the promote that lost the race is refused as
                 // stale and writes nothing. Its admin row commits with the move, ahead of the rebinds below,
                 // which record their own — and the acknowledgement is recorded, not just enforced.
-                const moved = await this.cp.moveChannel(outgoing?.id ?? null, {
+                // #2565: the listing's rule and the `unlistedOnly` door are judged in that unit too.
+                const moved = await this.directory('promoteChannel', outgoing?.id ?? null, {
                     id: ulid(),
                     vertical_slug: verticalSlug,
                     channel,
@@ -4994,7 +5041,7 @@ export class CloudflareScopeHost {
                     from_version_id: outgoing?.id ?? null,
                     actor,
                     at: promotedAt,
-                }, this.adminEntry(actor, 'promoteVersion', { tenantId: null, vertical: verticalSlug }, outgoing ? { versionId: outgoing.id, version: outgoing.version } : null, { channel, versionId, version: incoming.version, acknowledged: ack }));
+                }, options?.unlistedOnly === true, this.adminEntry(actor, 'promoteVersion', { tenantId: null, vertical: verticalSlug }, outgoing ? { versionId: outgoing.id, version: outgoing.version } : null, { channel, versionId, version: incoming.version, acknowledged: ack }));
                 if (!moved)
                     throw promoteRaceRefusal(channel);
                 // For a PRIVATE vertical, prod IS what the owner's apps run: re-point the
@@ -5175,11 +5222,14 @@ export class CloudflareScopeHost {
                     migrationTag: r.serving_migration_tag,
                 });
             },
-            setVerticalServing: async (actor, verticalSlug, state) => {
+            setVerticalServing: async (actor, verticalSlug, state, expected) => {
                 const parsed = verticalServingState.parse(state);
                 const r = await this.cp.readVertical(verticalSlug);
                 if (!r)
                     throw substratError('not_found', `unknown vertical '${verticalSlug}'`);
+                // #2577: the caller's upload diffed its DO-class migration from `expected`'s class set and tag.
+                if (expected !== undefined && !migratesFrom(r, expected))
+                    throw servingRaceRefusal(verticalSlug);
                 // #2178: every install on the serving script runs the new version from this moment.
                 if (r.serving_version_id) {
                     const incoming = await this.cp.readVersion(parsed.versionId);
@@ -5187,14 +5237,15 @@ export class CloudflareScopeHost {
                         await this.assertNoStrandFrom([r.serving_version_id], incoming.id, incoming, r.serving_ref ? await this.cp.provisionedVersionsOf(verticalSlug, { ref: r.serving_ref, versionId: r.serving_version_id }, null) : []);
                     }
                 }
-                // #2528: a compare-and-set on the serving ref and version the gate above judged, across
-                // awaits another serve can run in. The DO fills the row's `before` from the state it moves.
+                // #2528/#2577: a compare-and-set on the serving state the gate above judged, its class set
+                // and tag included, across awaits another serve can run in. The DO fills the row's `before`
+                // from the state it moves.
                 const moved = await this.directory('setVerticalServing', verticalSlug, {
                     ref: parsed.ref,
                     versionId: parsed.versionId,
                     doClassesJson: JSON.stringify(parsed.doClasses),
                     migrationTag: parsed.migrationTag,
-                }, this.adminEntry(actor, 'setVerticalServing', { tenantId: null }, null, { vertical: verticalSlug, ref: parsed.ref, versionId: parsed.versionId }), { ref: r.serving_ref ?? null, versionId: r.serving_version_id ?? null });
+                }, this.adminEntry(actor, 'setVerticalServing', { tenantId: null }, null, { vertical: verticalSlug, ref: parsed.ref, versionId: parsed.versionId }), servedFromRow(r));
                 if (!moved)
                     throw servingRaceRefusal(verticalSlug);
             },
@@ -6060,32 +6111,22 @@ export class CloudflareScopeHost {
             },
             grantEntitlement: async (actor, tenantId, entitlementKey, plan) => {
                 const input = entitlementGrantInput.parse(plan ?? {});
-                const result = await this.cp.grantEntitlement(tenantId, entitlementKey, input, actor);
+                // #2526: the held grant (the row's `before`, and the no-op judgement), the upsert and the
+                // row are one ControlPlaneDO unit, which fills `before` and `after`.
+                const result = await this.directory('grantEntitlement', tenantId, entitlementKey, input, actor, this.adminEntry(actor, 'grantEntitlement', { tenantId }, null, null));
                 if (!result.changed)
                     return; // idempotent — an unchanged grant is not audited
-                await this.recordAdmin(actor, 'grantEntitlement', { tenantId }, result.before
-                    ? {
-                        entitlementKey,
-                        expiresAt: result.before.expires_at,
-                        quota: result.before.quota,
-                        plan: result.before.plan,
-                    }
-                    : null, {
-                    entitlementKey,
-                    expiresAt: result.after.expires_at,
-                    quota: result.after.quota,
-                    plan: result.after.plan,
-                });
                 // #304: an entitlement change is a tenant-level write, so it fans out into the
                 // tenant's projected scopes — the invalidation half of the OQ5 answer. A no-op
-                // unless scope-local projection is on; the reconcile sweep repairs any drop.
+                // unless scope-local projection is on; the reconcile sweep repairs any drop. It runs
+                // after the grant and its row have committed.
                 await this.fanOut(tenantId);
             },
             revokeEntitlement: async (actor, tenantId, entitlementKey) => {
-                const removed = await this.cp.revokeEntitlement(tenantId, entitlementKey);
+                // #2526: the delete and its row, `before` the grant it removed, are one unit.
+                const removed = await this.directory('revokeEntitlement', tenantId, entitlementKey, this.adminEntry(actor, 'revokeEntitlement', { tenantId }, null, null));
                 if (!removed)
                     return; // nothing held, nothing changed
-                await this.recordAdmin(actor, 'revokeEntitlement', { tenantId }, { entitlementKey, expiresAt: removed.expires_at, quota: removed.quota, plan: removed.plan }, null);
                 // The revoke must reach the projected scopes so a running vertical stops honouring
                 // the entitlement — a dropped fan-out here would leave it enforcing a stale grant.
                 await this.fanOut(tenantId);
@@ -7208,12 +7249,12 @@ export class CloudflareScopeHost {
     async switchHeld(scopeId, holdKey) {
         const at = Date.now();
         let error;
-        if (!this.holdSnapshot || at - this.holdSnapshot.at > SWITCH_HOLD_SNAPSHOT_MS) {
+        if (!this.holdSnapshot || at - this.holdSnapshot.at > this.holdSnapshotMs) {
             const inflight = this.holdRefresh;
             // Join a read that went out within the snapshot age of this consult: its result is then as
             // fresh as one this consult would take itself, which is what the settle argument needs.
             // Only the consult that sent the read reports its failure.
-            if (inflight && at - inflight.at <= SWITCH_HOLD_SNAPSHOT_MS) {
+            if (inflight && at - inflight.at <= this.holdSnapshotMs) {
                 await inflight.done;
             }
             else {
@@ -7455,7 +7496,7 @@ export class CloudflareScopeHost {
      * claimed by the re-read.
      */
     async settleClaim(holds, scopeId, claimId) {
-        await new Promise((resolve) => setTimeout(resolve, SWITCH_HOLD_SETTLE_MS));
+        await new Promise((resolve) => setTimeout(resolve, this.holdSettleMs));
         for (let waits = 0;; waits++) {
             const token = await holds.switchHoldToken();
             const off = await this.offInStorage(scopeId);
@@ -7464,14 +7505,14 @@ export class CloudflareScopeHost {
                 this.holdSnapshot = null;
             }
             const youngest = await holds.switchHoldYoungestMs(scopeId, claimId);
-            if (youngest === null || youngest >= SWITCH_HOLD_SETTLE_MS)
+            if (youngest === null || youngest >= this.holdSettleMs)
                 return;
             if (waits === SWITCH_HOLD_EXTRA_WAITS) {
                 throw new Error(`${REWIND_REFUSED}schedule switches kept being pulled off while this rewind waited for them to ` +
                     `settle (${waits} extra waits); nothing was rewound, and those switches stay off. Retry the rewind`);
             }
             // Never longer than one settle, even if the hold object's clock moved back under a restart.
-            await new Promise((resolve) => setTimeout(resolve, SWITCH_HOLD_SETTLE_MS - Math.max(0, youngest)));
+            await new Promise((resolve) => setTimeout(resolve, this.holdSettleMs - Math.max(0, youngest)));
         }
     }
     // -- live reads (#938): the door ------------------------------------------
@@ -7915,6 +7956,95 @@ export class CloudflareScopeHost {
         if (refusal)
             throw substratError('forbidden', refusal);
     }
+    /**
+     * #2555: what a control-plane-full restore or import projects into a scope of `vertical` in the
+     * load's own transaction: the directory's current state for `tenantId`, exactly what a fan-out
+     * sends (`tenantProjection` and the vertical's connection keys), with this host's reservations to
+     * judge its roles by. Null on a host that does not project permissions into its scopes: there the
+     * load only keeps the destination's permission flags.
+     */
+    async loadProjectionFor(tenantId, vertical) {
+        if (!this.scopeLocalPermissions)
+            return null;
+        const [state, connectionKeys] = await Promise.all([this.tenantProjection(tenantId), this.connectionKeyRows(tenantId, vertical)]);
+        return { tenantId, ...state, connectionKeys, judge: this.roleJudge() };
+    }
+    /**
+     * #2555: `importDumpProjected`, a failure rethrown with its code. The role set refused in the
+     * load's unit is `forbidden`, worded for the verb (`restore refused: `, `import refused: `), and
+     * told apart by identity (`loadRoleRefusals`); the scope keeps its rows.
+     */
+    async loadProjected(scopeId, tables, opts, projection, verb) {
+        const loaded = unwrapReply(await this.scopeStub(scopeId).importDumpProjected(tables, scopeId, opts, projection));
+        if ('switchedOff' in loaded)
+            return loaded.switchedOff;
+        const refused = substratError('forbidden', `${verb} refused: ${loaded.refusedRoles}`);
+        loadRoleRefusals.add(refused);
+        throw refused;
+    }
+    /**
+     * #2555: an import that cannot finish (its load refused its role set, or its re-projection
+     * refused or failed) takes down the scope it created for itself: only one this call created
+     * (`created`) and still `provisioning`, never activated, so an import pointed at an existing
+     * scope never touches it. Its directory row goes, as the pure host takes such a scope down, so a
+     * retry with the same id imports. The storage object is left for that retry's load to replace;
+     * until then it holds what the provision projected into it (the tenant's roles, tuples,
+     * entitlements, identity links and connection keys) and, after a load, the dump, and no
+     * directory row leads a later tenant deletion to it. Best effort: the refusal is the answer
+     * whatever this does. A teardown that fails is a staff-only ops row (no tenant on it), with the
+     * scope left in `provisioning` for staff to reap. No admin row: the import never happened, and
+     * its `provisionScope` row stays as the record of the attempt.
+     */
+    async dropRefusedImport(actor, tenantId, scopeId, created) {
+        if (!created)
+            return;
+        try {
+            // Judged again in the directory's own unit, so a concurrent call that activated it keeps it; the
+            // read before it is what an older directory, which ignores the condition, is held to.
+            if ((await this.cp.getScopeRecord(tenantId, scopeId))?.status !== 'provisioning')
+                return;
+            await this.cp.deleteScopeDirectory(scopeId, 'provisioning');
+        }
+        catch (teardown) {
+            await this.admin
+                .recordOpsFailure({
+                actor,
+                operation: 'importScope',
+                stage: 'refused-import-teardown',
+                scopeId,
+                message: `a refused import's scope could not be taken down: ${teardown instanceof Error ? teardown.message : String(teardown)}`,
+            })
+                .catch(() => {
+                // Nothing more to do here: the refusal is still the answer.
+            });
+        }
+    }
+    /**
+     * #2555: the directory read again once the load has committed. A tenant-level write made between
+     * the first read and the load fanned out before the load replaced it, so when the directory has
+     * moved, the scope is projected once more, judged in its own unit against the seats the load
+     * brought (`applyJudgedProjectionReply`): a role the directory redefined in the window, which its
+     * own door judged without those seats, is judged with them here. Once at most: a write after this
+     * read fans out to the scope itself. Answers `reprojected` (`true` when it re-projected), and the
+     * error with `'refused'` or `'failed'` when the re-projection could not land, which leaves the
+     * scope on the set the load judged until the next fan-out, which is not judged (K-55); the
+     * refusal says what staff do about it. Ordering projections by a per-tenant revision (#2595)
+     * would make the second read unnecessary.
+     */
+    async convergeLoadedProjection(tenantId, scopeId, vertical, loaded, verb) {
+        try {
+            const now = await this.loadProjectionFor(tenantId, vertical);
+            if (!now || projectionDigest(now) === projectionDigest(loaded))
+                return {};
+            unwrapReply(await this.scopeStub(scopeId).applyJudgedProjectionReply(this.roleJudge(), tenantId, now.roles, now.tuples, now.entitlements, undefined, now.identities, now.connectionKeys));
+            return { reprojected: true };
+        }
+        catch (error) {
+            if (errorCodeOf(error) !== 'forbidden')
+                return { reprojected: 'failed', error };
+            return { reprojected: 'refused', error: substratError('forbidden', `${verb} refused: ${error.message}. ${SECOND_READ_REMEDY}`) };
+        }
+    }
     /**
      * #2446: the roles `scopeId` stores for `tenantId` and the role keys anyone but a system principal
      * holds a live seat in there: what `refuseReservedRoleSet` judges a reconcile's role set against
@@ -8562,6 +8692,18 @@ export class CloudflareScopeHost {
         }
         return connectionLandingsOfManifestJson(v.manifest_json);
     }
+    /**
+     * What one pushed version declares about vertical-defined connectors (vertical-connectors.md
+     * §6.4), from its stored manifest: the connector proxy reads it for the running version on every
+     * call. Unaudited for the reason {@link versionImports} is.
+     */
+    async versionConnectors(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 connectorsOfManifestJson(v.manifest_json);
+    }
 }
 /** A ledger row -> the wire entry, the attribution re-nested (#1054). */
 function modelUsageEntryOf(r) {