@substrat-run/adapter-cloudflare 0.161.0 → 0.163.0

package/dist/host.js

@@ -1,7 +1,7 @@
 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, 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, 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 { fenceAttachmentSweep, missingAttachmentStore, sweepOrphanAttachments, unsettledCopyRefusal } from '@substrat-run/kernel';
@@ -75,6 +75,24 @@ const connectionGrantsSkippedLine = (tenantId, scopeId, skipped) => ({
  * classification is the platform directory's; the vertical applies the same `isPrimaryScope` to
  * it, so a primary can be marked only by a request that misstates its lineage, never by default.
  */
+/** A vertical's role definitions as a CP-less projection writes them (`applyProjection`'s rows). */
+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');
@@ -1124,7 +1142,7 @@ 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));
+        const out = await this.loadLocal(scopeId, opts, (load, repair) => repair ? this.scopeStub(scopeId).importDumpJudged(tables, scopeId, load, repair) : this.scopeStub(scopeId).importDumpChecked(tables, scopeId, load));
         return { ...out, tables: tables.length };
     }
     /**
@@ -1146,7 +1164,9 @@ export class CloudflareScopeHost {
     }
     /** `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));
+        return this.loadLocal(scopeId, opts, (load, repair) => repair
+            ? this.scopeStub(scopeId).commitStagedDumpJudged(stageId, scopeId, load, repair)
+            : this.scopeStub(scopeId).commitStagedDumpChecked(stageId, scopeId, load));
     }
     /** Drop the dump staged under `stageId` (#2450), if it is still there. */
     async discardStagedScopeLocal(scopeId, stageId) {
@@ -1156,6 +1176,11 @@ export class CloudflareScopeHost {
     async loadLocal(scopeId, opts, run) {
         if (opts?.markCopy)
             assertCopyLineage(opts.markCopy);
+        if (opts?.roles && !opts.tenantId) {
+            throw substratError('validation_failed', 'restore refused: a role repair needs the tenant it is projected for; nothing was loaded');
+        }
+        // #2531: the repair the load judges and projects in its own transaction.
+        const repair = opts?.roles && opts.tenantId ? { tenantId: opts.tenantId, roles: projectedRoleRows(opts.roles), judge: this.roleJudge() } : undefined;
         // #2314: a load replaces the scope's rows, so the orphan sweep is fenced first, as for a rewind.
         await this.fenceOrphanSweep(scopeId, opts?.tenantId);
         const carry = opts ? recordedOffFromWire(opts) : undefined;
@@ -1173,14 +1198,22 @@ export class CloudflareScopeHost {
             ...load,
             ...(opts?.expect ? { expect: opts.expect } : {}),
             ...(opts?.fence ? { fence: opts.fence } : {}),
-        });
+        }, repair);
         if (out.refused === false) {
-            return { tables: out.tables ?? 0, ...(carry ? { switchedOff: out.switchedOff } : {}) };
+            return {
+                tables: out.tables ?? 0,
+                ...(carry ? { switchedOff: out.switchedOff } : {}),
+                // Only a load that ran the judged method can say the repair landed in it.
+                ...(repair && out.rolesProjected === true ? { rolesProjected: true } : {}),
+            };
         }
         if (out.refused === 'kept')
             throw substratError('conflict', KEPT_COPY_REFUSAL);
         if (out.refused === 'tenant')
             throw substratError('conflict', out.message);
+        // #2531: the repair's role set, refused on the seats the load wrote; the whole load rolled back.
+        if (out.refused === 'roles')
+            throw substratError('conflict', `the vertical's roles cannot be defined here: ${out.message}`);
         if (out.refused === 'lapsed')
             throw substratError('precondition_failed', COPY_RESTORE_FENCE_LAPSED);
         // A retry of a load that already committed (its answer was lost on the way back) is
@@ -1311,9 +1344,33 @@ export class CloudflareScopeHost {
      * safe; scope-level tuples (the restored grants) are never touched.
      */
     async projectRolesLocal(tenantId, scopeId, roles) {
-        // #2447: the role set is defined here, so it is judged here, before anything is projected.
+        // #2447: the role set is defined here, so it is judged here, before anything is projected, and
+        // (#2531) again inside the projection's unit, on the seats the scope holds as it writes.
         await this.refuseReservedRoleSet(roles, tenantId, scopeId);
-        unwrapReply(await this.scopeStub(scopeId).applyProjectionReply(tenantId, roles.map((r) => ({ role_key: r.key, permissions: JSON.stringify(r.permissions), source: r.source, holder: r.holder === 'system' ? 'system' : 'person' })), []));
+        await this.projectJudged(tenantId, scopeId, projectedRoleRows(roles), []);
+    }
+    /**
+     * #2531: what this host's own modules reserve and declare, for a unit that judges a role set in the
+     * scope (`RoleJudge`); the scope class's are joined there.
+     */
+    roleJudge() {
+        return { reserved: [...this.reservedKeys], declared: [...this.declaredKeys] };
+    }
+    /**
+     * #2531: `applyProjectionReply` with the role set judged in its unit (`applyJudgedProjectionReply`).
+     * A refusal there answers with the staff-facing prefix `refuseReservedRoleSet` gives a pre-check's.
+     * A ScopeDO from before the judged method refuses the call itself, with nothing written.
+     */
+    async projectJudged(tenantId, scopeId, ...rest) {
+        try {
+            return unwrapReply(await this.scopeStub(scopeId).applyJudgedProjectionReply(this.roleJudge(), tenantId, ...rest));
+        }
+        catch (e) {
+            if (errorCodeOf(e) === 'forbidden') {
+                throw substratError('forbidden', `tenant ${tenantId}, scope ${scopeId}: the vertical's roles cannot be defined here: ${e.message}`);
+            }
+            throw e;
+        }
     }
     /**
      * Wipe one scope DO's storage in THIS deployment — the reap half of an orchestrated
@@ -1463,6 +1520,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
@@ -1692,6 +1761,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
@@ -1747,6 +1820,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
@@ -2132,19 +2206,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.
@@ -2154,6 +2262,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
@@ -2163,21 +2273,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;
     }
     /**
@@ -3762,7 +3876,9 @@ export class CloudflareScopeHost {
                 await this.writeScopeTuple(node.scopeId, subject, `granted:${permission}`, `scope:${node.scopeId}`, expiresAt ?? null);
             }
             else {
-                await this.cp.writeTenantTuple(node.tenantId, subject, `granted:${permission}`, `tenant:${node.tenantId}`, expiresAt ?? null);
+                // #2526: a tenant-level grant is a directory tuple, written by the ControlPlaneDO in the
+                // unit that writes its admin row — never through here.
+                throw new Error('writeGrant: a tenant-level grant is written with its row in the ControlPlaneDO');
             }
         };
         /**
@@ -4294,11 +4410,11 @@ export class CloudflareScopeHost {
                 // `defineRoleOrRefusal`, not the legacy `defineRole` an older coordinator reads. A ControlPlaneDO from
                 // before #2447, met in a deploy's restart window, has no such method, so the call fails loudly rather
                 // than being misread.
-                const defined = await this.cp.defineRoleOrRefusal(tenantId, parsed, context.reservation, context.seatedInScopes);
+                // #2526: through `reply`, with the row, which the DO writes in the definition's unit, its
+                // `before` the role it read there. A DO from before #2526 does not list the method, and refuses.
+                const defined = await this.directory('defineRoleOrRefusal', tenantId, parsed, context.reservation, context.seatedInScopes, this.adminEntry(actor, 'defineRole', { tenantId }, null, parsed));
                 if ('refused' in defined)
                     throw substratError('forbidden', defined.refused);
-                const before = defined.before;
-                await this.recordAdmin(actor, 'defineRole', { tenantId }, before, parsed);
                 await this.fanOut(tenantId); // role definitions are projected into the tenant's scopes
             },
             listRoles: async (actor, filter) => {
@@ -4323,29 +4439,22 @@ 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);
-                }
-                else {
-                    await this.cp.writeTenantTuple(assignment.node.tenantId, subject, `role:${assignment.roleKey}`, `tenant:${assignment.node.tenantId}`, null);
+                // reservations (it answers null when it has none). At the tenant node, against this host's,
+                // in the ControlPlaneDO's unit that writes the tuple and its row (#2526).
+                const { tenantId, scopeId } = assignment.node;
+                if (!scopeId) {
+                    const assigned = await this.directory('assignTenantRole', tenantId, assignment.principalId, assignment.roleKey, [...this.reservedKeys], this.adminEntry(actor, 'assignRole', { tenantId, scopeId }, null, assignment));
+                    if (assigned.refused)
+                        throw substratError('forbidden', assigned.refused);
+                    // A tenant-level assignment changes the projected set and must fan out.
+                    await this.fanOut(tenantId);
+                    return;
                 }
-                await this.recordAdmin(actor, 'assignRole', { tenantId: assignment.node.tenantId, scopeId: assignment.node.scopeId }, null, assignment);
-                // A scope-level assignment writes a scope tuple (already local); only a
-                // tenant-level one changes the projected set and must fan out.
-                if (!assignment.node.scopeId)
-                    await this.fanOut(assignment.node.tenantId);
+                const refusal = await this.scopeStub(scopeId).reservedRoleRefusalFor(tenantId, assignment.roleKey, 'platform');
+                if (refusal)
+                    throw substratError('forbidden', refusal);
+                await this.writeScopeTuple(scopeId, `principal:${assignment.principalId}`, `role:${assignment.roleKey}`, `scope:${scopeId}`, null);
+                await this.recordAdmin(actor, 'assignRole', { tenantId, scopeId }, null, assignment);
             },
             unassignRole: async (actor, assignment) => {
                 // Tombstone (K-21) — the checker skips revoked rows. A no-op returns false so
@@ -4372,12 +4481,18 @@ export class CloudflareScopeHost {
                 // 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
-                // grants write scope tuples (already local), so they need no fan-out.
-                if (!grant.node.scopeId)
+                const subject = `principal:${grant.principalId}`;
+                const target = { tenantId: grant.node.tenantId, scopeId: grant.node.scopeId };
+                if (!grant.node.scopeId && !grant.entity) {
+                    // #2526: a directory tuple, written with its row in one ControlPlaneDO unit. Tenant-level
+                    // → it changes the projected set, so it fans out.
+                    await this.directory('writeTenantTuple', grant.node.tenantId, subject, `granted:${grant.permission}`, `tenant:${grant.node.tenantId}`, grant.expiresAt ?? null, this.adminEntry(actor, 'grant', target, null, grant));
                     await this.fanOut(grant.node.tenantId);
+                    return;
+                }
+                // Scope-level and entity grants write scope tuples (already local): no fan-out.
+                await writeGrant(subject, grant.permission, grant.node, grant.entity, grant.expiresAt);
+                await this.recordAdmin(actor, 'grant', target, null, grant);
             },
             grantEntityShape: async (actor, grant) => {
                 await this.grantEntityShapeLocal(grant.node.scopeId, grant.principalId, grant.entity, grant.permissions);
@@ -4427,27 +4542,37 @@ export class CloudflareScopeHost {
                 // fails below is still gathered by the next provision/reconcile — the
                 // repair channel — instead of vanishing. The tuple stays the only thing
                 // the permission checker reads; this row is what the platform gathers
-                // from so scopes provisioned AFTER the grant receive it too.
-                await this.cp.recordConnectionGrant({
+                // from so scopes provisioned AFTER the grant receive it too. #2526: the
+                // record, the checks above made again, the admin row and — at the tenant
+                // node — the tuple are one ControlPlaneDO unit.
+                const { vertical } = await this.directory('grantConnectionInDirectory', {
                     connectionId: grant.connectionId,
                     tenantId: grant.node.tenantId,
-                    vertical: conn.vertical,
                     permission: grant.permission,
                     scopeId: grant.node.scopeId ?? null,
                     expiresAt: grant.expiresAt ?? null,
                     grantedBy: grant.grantedBy,
                     grantedAt: new Date().toISOString(),
-                });
+                }, this.adminEntry(actor, 'grantToConnection', { tenantId: grant.node.tenantId, scopeId: grant.node.scopeId, vertical: conn.vertical }, null, {
+                    connectionId: grant.connectionId,
+                    provider: conn.provider,
+                    permission: grant.permission,
+                    node: grant.node,
+                }));
+                if (!grant.node.scopeId) {
+                    // A tenant tuple changes the projected set, as its siblings' do: it fans out.
+                    await this.fanOut(grant.node.tenantId);
+                    return;
+                }
                 // #574: a scope-level grant is a SCOPE tuple, and the scope's DO lives in the
                 // deployment serving it — for the shared control plane that is the vertical's
-                // dispatch script, so the tuple write rides the delegation seam. Tenant-level
-                // grants stay directory-side either way.
-                if (this.connectorDelegation && grant.node.scopeId) {
+                // dispatch script, so the tuple write rides the delegation seam.
+                if (this.connectorDelegation) {
                     await this.connectorDelegation.grant({
                         connectionId: grant.connectionId,
                         tenantId: grant.node.tenantId,
                         scopeId: grant.node.scopeId,
-                        vertical: conn.vertical,
+                        vertical,
                         permission: grant.permission,
                         expiresAt: grant.expiresAt,
                     });
@@ -4455,17 +4580,13 @@ export class CloudflareScopeHost {
                 else {
                     await writeGrant(subjectRef({ kind: 'connection', id: grant.connectionId }), grant.permission, grant.node, undefined, grant.expiresAt);
                 }
-                await this.recordAdmin(actor, 'grantToConnection', { tenantId: grant.node.tenantId, scopeId: grant.node.scopeId, vertical: conn.vertical }, null, {
-                    connectionId: grant.connectionId,
-                    provider: conn.provider,
-                    permission: grant.permission,
-                    node: grant.node,
-                });
             },
             grantToSystem: async (actor, raw) => {
                 // The scheduler's grant (#383) — mirror of grantToConnection. Narrow: one
                 // module, one permission; tombstones on revoke; shows in the permission diff.
                 const grant = systemGrant.parse(raw);
+                const target = { tenantId: grant.node.tenantId, scopeId: grant.node.scopeId };
+                const after = { moduleId: grant.moduleId, permission: grant.permission, node: grant.node };
                 if (grant.node.scopeId) {
                     // #1666: refused while the module is switched off on this scope — checked and
                     // written in one DO unit. Restore is the lever; a grant is not.
@@ -4473,18 +4594,17 @@ export class CloudflareScopeHost {
                     if (!written) {
                         throw substratError('conflict', systemSwitchedOffMessage(grant.moduleId, grant.node.scopeId));
                     }
+                    await this.recordAdmin(actor, 'grantToSystem', target, null, after);
+                    return;
                 }
-                else {
-                    // #1743: refused while the record holds the module off on any scope — checked and
-                    // written in one control-plane call, where the record and the tenant tuple both live.
-                    const off = await this.cp.writeTenantSystemGrant(grant.node.tenantId, grant.moduleId, `granted:${grant.permission}`, grant.expiresAt ?? null);
-                    if (off.length > 0) {
-                        throw substratError('conflict', tenantSystemSwitchedOffMessage(grant.moduleId, off));
-                    }
+                // #1743: refused while the record holds the module off on any scope — checked and
+                // written in one control-plane call, where the record and the tenant tuple both live,
+                // and (#2526) the admin row with them.
+                const off = await this.directory('writeTenantSystemGrant', grant.node.tenantId, grant.moduleId, `granted:${grant.permission}`, grant.expiresAt ?? null, this.adminEntry(actor, 'grantToSystem', target, null, after));
+                if (off.length > 0) {
+                    throw substratError('conflict', tenantSystemSwitchedOffMessage(grant.moduleId, off));
                 }
-                await this.recordAdmin(actor, 'grantToSystem', { tenantId: grant.node.tenantId, scopeId: grant.node.scopeId }, null, { moduleId: grant.moduleId, permission: grant.permission, node: grant.node });
-                if (!grant.node.scopeId)
-                    await this.fanOut(grant.node.tenantId);
+                await this.fanOut(grant.node.tenantId);
             },
             // #1666: the schedule kill switch and its lever back — `system-switch.ts` is the
             // whole rule, shared with the pure adapter; this is the directory check, the reach
@@ -4572,88 +4692,54 @@ export class CloudflareScopeHost {
                 // 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)
+                const target = { tenantId: node.tenantId, scopeId: node.scopeId };
+                const after = { orgId, permission, node, entity };
+                if (!node.scopeId && !entity) {
+                    // #2526: the org checked again, the tuple and its row, in one ControlPlaneDO unit.
+                    await this.directory('writeOrgTenantTuple', node.tenantId, orgId, `org:${orgId}`, `granted:${permission}`, `tenant:${node.tenantId}`, null, this.adminEntry(actor, 'grantToOrg', target, null, after));
                     await this.fanOut(node.tenantId);
+                    return;
+                }
+                await writeGrant(`org:${orgId}`, permission, node, entity);
+                await this.recordAdmin(actor, 'grantToOrg', target, null, after);
             },
             // -- vertical + version registry (#31) ---------------------------------
             // -- 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({
@@ -4857,7 +4943,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}`);
@@ -4931,7 +5017,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,
@@ -4939,7 +5026,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
@@ -5265,10 +5352,8 @@ export class CloudflareScopeHost {
             },
             createOrg: async (actor, input) => {
                 const parsed = createOrgInput.parse(input);
-                const created = await this.directory('createOrg', parsed.id, parsed.tenantId, parsed.slug, parsed.name, new Date().toISOString());
-                if (!created)
-                    return; // idempotent, and a no-op is not audited
-                await this.recordAdmin(actor, 'createOrg', { tenantId: parsed.tenantId }, null, parsed);
+                // #2526: the org and its row in one unit; an org that exists already writes neither.
+                await this.directory('insertOrg', parsed.id, parsed.tenantId, parsed.slug, parsed.name, new Date().toISOString(), this.adminEntry(actor, 'createOrg', { tenantId: parsed.tenantId }, null, parsed));
             },
             listOrgs: async (actor, tenantId) => {
                 const orgs = (await this.cp.listOrgs(tenantId)).map(mapOrg);
@@ -5281,10 +5366,9 @@ export class CloudflareScopeHost {
                 return r ? mapOrg(r) : undefined;
             },
             addMember: async (actor, tenantId, principal, orgId, opts) => {
-                await requireOrg(tenantId, orgId);
                 const expiresAt = opts?.expiresAt ?? null;
-                await this.cp.writeTenantTuple(tenantId, `principal:${principal}`, 'member', `org:${orgId}`, expiresAt);
-                await this.recordAdmin(actor, 'addMember', { tenantId }, null, memberAddedAudit(principal, orgId, expiresAt));
+                // #2526: the org's check, the tuple and its row, in one ControlPlaneDO unit.
+                await this.directory('writeOrgTenantTuple', tenantId, orgId, `principal:${principal}`, 'member', `org:${orgId}`, expiresAt, this.adminEntry(actor, 'addMember', { tenantId }, null, memberAddedAudit(principal, orgId, expiresAt)));
                 await this.fanOut(tenantId); // membership is a tenant-level tuple
             },
             applyMembership: async (actor, change) => {
@@ -6008,32 +6092,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);
@@ -7690,9 +7764,11 @@ export class CloudflareScopeHost {
             throw substratError('forbidden', `the owner's seat: ${ownerRefusal}`);
         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)
-        const switchedOff = unwrapReply(await stub.applyProjectionReply(input.tenantId, input.roles.map((r) => ({ role_key: r.key, permissions: JSON.stringify(r.permissions), source: r.source, holder: r.holder === 'system' ? 'system' : 'person' })), [], // no tenant-level tuples — a CP-less vertical grants at scope level only
+        // #2531: judged again in the projection's own unit, on the roles and seats the scope holds as it
+        // writes, so a seat made since the pre-check above is seen. The module migrations above have
+        // already run when that refuses; they are this host's own setup, and the projection writes nothing.
+        const switchedOff = await this.projectJudged(input.tenantId, input.scopeId, projectedRoleRows(input.roles), [], // no tenant-level tuples — a CP-less vertical grants at scope level only
         // Only PROJECT (and thereby switch on strict enforcement) when the platform actually
         // supplies entitlements. Omitting them leaves the scope un-projected and trusting-
         // upstream, so a vertical whose provision path predates #304 is never denied — it
@@ -7752,7 +7828,7 @@ export class CloudflareScopeHost {
             : undefined, 
         // #1742: the recorded-off modules and (#2029) peers, switched off after the seat in the
         // same unit, on the scope this call provisions — the one the seat's tuples name.
-        carry ? { scopeId: input.scopeId, at: new Date().toISOString(), ...carry } : undefined, services?.map((id) => `principal:${id}`)));
+        carry ? { scopeId: input.scopeId, at: new Date().toISOString(), ...carry } : undefined, services?.map((id) => `principal:${id}`));
         const shapes = input.entityGrants
             ? await this.topUpEntityGrantShapesLocal(input.tenantId, input.scopeId, input.entityGrants)
             : null;
@@ -7831,7 +7907,8 @@ export class CloudflareScopeHost {
      * which replaces whatever the scope stores now, so what the set is judged against is the DUMP's
      * roles and seats for `dump.tenantId` (`dumpRoleState`), when the caller has the dump in hand. A
      * staged restore has not (its pages are already in the scope), so it is judged as a set alone
-     * here, and `projectRolesLocal` judges again after the import, against what the dump brought.
+     * here. The load given the vertical's `roles` judges again in its own transaction, against what
+     * the dump brought (#2531), and `projectRolesLocal` does in its unit where the load did not.
      */
     async roleSetRefusalLocal(scopeId, roles, dump) {
         const here = await this.scopeStub(scopeId).reservationHere();
@@ -7860,6 +7937,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
@@ -7875,9 +8041,9 @@ export class CloudflareScopeHost {
      * and the roles the scope stores for the tenant now with their seats there. Answers the reserved
      * keys it judged with, for the seats the same call makes.
      *
-     * A stated residual: the scope state is read in one RPC (`roleStateHere`) and written in another
-     * (`applyProjectionReply`), so a seat made between the two is not seen. The window is one call
-     * wide, and a reconcile runs again every pass.
+     * The scope state is read in one RPC (`roleStateHere`) and written in another, so this is the
+     * first check, for its detailed wording; the write judges the set again inside its own unit
+     * (`projectJudged`, #2531), where a seat made between the two is seen.
      */
     async refuseReservedRoleSet(roles, tenantId, scopeId) {
         const stub = this.scopeStub(scopeId);