@substrat-run/adapter-cloudflare 0.161.0 → 0.163.0

package/dist/scope-do.js

@@ -2,7 +2,7 @@ import { REWIND_REFUSED } from './rewind-refusal.js';
 import { SYSTEM_DOOR_MOVED } from './system-door.js';
 import { DurableObject } from 'cloudflare:workers';
 import { ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, domainEvent, domainEventInput, eventId, instant, objectRef, entityObjectRef, assertModuleEmittableType, assertKernelAuthoredType, toWireFailure, grantRefFromProof, principalId, principalBecomeCapabilityInput, scopeId as scopeIdOf, tenantId as tenantIdOf, platformRequestInput, platformRequestId, MAX_PENDING_PLATFORM_REQUESTS, MAX_PENDING_SWEEP_RUNS, SWEEP_RUNS_KIND, SCOPE_DUMP_PAGE_MAX_BYTES, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, listLimitOf, pageOf, countedPageOf, requestFingerprint, substratError, errorCodeOf, assertReplayableDump, REDRAIN_BATCH, } from '@substrat-run/contracts';
-import { ulid, DO_SQL_LIMITS, unknownRoleError, createUlid, assertAllowed, ConnectionSealingKeyUnavailableError, noSealingKeyMessage, sealTo, assertReadOnlyQuery, entitlementDenial, platformRequestHistoryQuery, platformRequestOf, PLATFORM_REQUEST_COLUMNS, PLATFORM_REQUEST_REDACTION_SQL, platformRequestRedactionParams, platformRequestRedactionQuery, intentPayloadCarriesSubject, redactSubjectJobRuns, eraseSubjectFromModules, moduleErasurePlan, redactSubjectScopeText, assertRowLimit, assertRowOffset, JOB_RUN_PATCH_SQL, JOB_RUN_CLAIM_SQL, JOB_RUN_RENEW_SQL, JOB_RUN_BEGIN_SQL, JOB_RUN_MISS_SQL, JOB_RUN_MISS_SETTLE_SQL, admissionMissOutcome, JOB_LEASE_EXPIRED_NOTE, JOB_STEP_RECORD_SQL, DELIVERY_ERROR_REDACTION_SQL, REDACTED_DELIVERY_NOTE, seatScopeTuple, delegatedRevokeSql, writeExplicitTupleIn, grantEntityShapeIn, topUpEntityGrantShapes, applyScopeRoleChange, changeScopeRole, revokeScopeRoles, scopeRoleHolders, assertModuleDeclared, noteDeclaredKeys, noteReservedKeys, SCOPE_SEATED_ROLES_SQL, reservedGrantRefusal, reservedRoleRefusal, reservedShapeRefusal, effectiveRoleGrantQuery, switchRecordedOff, switchSystemSchedules, peerGrantsStatus, systemGrantsStatus, systemScheduleState, systemSwitchedOff, denialListQuery, refusalListQuery, mapRefusalRow, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialSummaryBuckets, PermissionDenied, assertImpersonationWrites, assertModuleEnqueueableKind, impersonationStampOf, createAtomic, NotSearchable, isSearchIndexTable, searchIndexPlans, NotListable, listIndexPlans, moduleMigrations, MIGRATION_DIGEST_FENCE_DDL, MIGRATION_DIGEST_MARK_LEGACY, assertJournalDumpCoherent, assertMigrationSql, migrationDivergence, migrationFailedError, migrationSetDivergence, migrationSteps, planMigrations, listQuery, cursorOf, searchLimit, searchMatchExpression, searchQuery, ATTACHMENT_TEXT_DDL, ATTACHMENT_BYTES_SQL, ATTACHMENT_CONDEMNED_DDL, ATTACHMENT_SWEEP_LICENCE_DDL, ATTACHMENT_SWEEP_LICENCE_TABLE, clearOrphanSweepLicence, condemnLicensedOrphanAttachments, consumeOrphanSweepLicence, licensedOrphanIds, recordOrphanSweepLicence, refuseUnlicensedOrphanSweep, refuseCondemnedAttachment, refuseCondemnedInDump, rowlessAttachmentIds, attachmentRecordOfRow, enqueueAttachmentText, reconcileAttachmentText, queueAttachmentTextBackfill, startAttachmentTextBackfill, recordAttachmentText, searchAttachments, IDEMPOTENCY_DDL, REFUSALS_TABLE_DDL, REFUSALS_INDEX, refusalInsert, refusalOf, markGuardRefusal, REFUSALS_REBUILD, refusalsAdmitGuards, assertIdempotencyKey, assertPermissionKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, SCHEDULE_STATE_DDL, SCHEDULE_STATE_REBUILD, scheduleStateHasKind, VERTICAL_EVENTS_DDL, EXPORT_HOPS_SQL, emptyImportResult, IMPORT_CURSORS_SQL, IMPORT_CURSOR_OF_SQL, OUTBOX_MARK_SQL, exportedSinceQuery, emittedSinceQuery, emittedReportOf, EMITTED_REPORT_CAP, IMPORT_CURSOR_ADVANCE_SQL, IMPORT_RECORD_SQL, moveImportCursor, CrossVerticalRegistry, exportReadPlan, exportReadQuery, planExportBatch, withheldNote, JOB_RUN_DDL, JOB_RUN_DUE_AT, jobRunListLimit, SYSTEM_DOOR_WAIT, ancestorsWithin, } from '@substrat-run/kernel';
+import { ulid, DO_SQL_LIMITS, unknownRoleError, createUlid, assertAllowed, ConnectionSealingKeyUnavailableError, noSealingKeyMessage, sealTo, assertReadOnlyQuery, entitlementDenial, platformRequestHistoryQuery, platformRequestOf, PLATFORM_REQUEST_COLUMNS, PLATFORM_REQUEST_REDACTION_SQL, platformRequestRedactionParams, platformRequestRedactionQuery, intentPayloadCarriesSubject, redactSubjectJobRuns, eraseSubjectFromModules, moduleErasurePlan, redactSubjectScopeText, assertRowLimit, assertRowOffset, JOB_RUN_PATCH_SQL, JOB_RUN_CLAIM_SQL, JOB_RUN_RENEW_SQL, JOB_RUN_BEGIN_SQL, JOB_RUN_MISS_SQL, JOB_RUN_MISS_SETTLE_SQL, admissionMissOutcome, JOB_LEASE_EXPIRED_NOTE, JOB_STEP_RECORD_SQL, DELIVERY_ERROR_REDACTION_SQL, REDACTED_DELIVERY_NOTE, seatScopeTuple, delegatedRevokeSql, writeExplicitTupleIn, grantEntityShapeIn, topUpEntityGrantShapes, applyScopeRoleChange, changeScopeRole, revokeScopeRoles, scopeRoleHolders, assertModuleDeclared, noteDeclaredKeys, noteReservedKeys, SCOPE_SEATED_ROLES_SQL, inUnitRoleRefusal, loadedRoleSetRefusedRole, reservedRoleSetRefusedRole, reservedGrantRefusal, reservedRoleRefusal, reservedShapeRefusal, effectiveRoleGrantQuery, switchRecordedOff, switchSystemSchedules, peerGrantsStatus, systemGrantsStatus, systemScheduleState, systemSwitchedOff, denialListQuery, refusalListQuery, mapRefusalRow, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialSummaryBuckets, PermissionDenied, assertImpersonationWrites, assertModuleEnqueueableKind, impersonationStampOf, createAtomic, NotSearchable, isSearchIndexTable, searchIndexPlans, NotListable, listIndexPlans, moduleMigrations, MIGRATION_DIGEST_FENCE_DDL, MIGRATION_DIGEST_MARK_LEGACY, assertJournalDumpCoherent, assertMigrationSql, migrationDivergence, migrationFailedError, migrationSetDivergence, migrationSteps, planMigrations, listQuery, cursorOf, searchLimit, searchMatchExpression, searchQuery, ATTACHMENT_TEXT_DDL, ATTACHMENT_BYTES_SQL, ATTACHMENT_CONDEMNED_DDL, ATTACHMENT_SWEEP_LICENCE_DDL, ATTACHMENT_SWEEP_LICENCE_TABLE, WIRE_NONCE_DDL, WIRE_NONCE_FULL, claimWireNonceIn, isWireNonceTable, isWireNonceWrite, clearOrphanSweepLicence, condemnLicensedOrphanAttachments, consumeOrphanSweepLicence, licensedOrphanIds, recordOrphanSweepLicence, refuseUnlicensedOrphanSweep, refuseCondemnedAttachment, refuseCondemnedInDump, rowlessAttachmentIds, attachmentRecordOfRow, enqueueAttachmentText, reconcileAttachmentText, queueAttachmentTextBackfill, startAttachmentTextBackfill, recordAttachmentText, searchAttachments, IDEMPOTENCY_DDL, REFUSALS_TABLE_DDL, REFUSALS_INDEX, refusalInsert, refusalOf, markGuardRefusal, REFUSALS_REBUILD, refusalsAdmitGuards, assertIdempotencyKey, assertPermissionKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, SCHEDULE_STATE_DDL, SCHEDULE_STATE_REBUILD, scheduleStateHasKind, VERTICAL_EVENTS_DDL, EXPORT_HOPS_SQL, emptyImportResult, IMPORT_CURSORS_SQL, IMPORT_CURSOR_OF_SQL, OUTBOX_MARK_SQL, exportedSinceQuery, emittedSinceQuery, emittedReportOf, EMITTED_REPORT_CAP, IMPORT_CURSOR_ADVANCE_SQL, IMPORT_RECORD_SQL, moveImportCursor, CrossVerticalRegistry, exportReadPlan, exportReadQuery, planExportBatch, withheldNote, JOB_RUN_DDL, JOB_RUN_DUE_AT, jobRunListLimit, SYSTEM_DOOR_WAIT, ancestorsWithin, } from '@substrat-run/kernel';
 import { isUpgradeRequest, readSubscription, LIVE_DECIDE_ATTEMPTS, LIVE_FANOUT_LIMIT, LIVE_PRINCIPAL_HEADER, LIVE_SCOPE_HEADER, LIVE_SUBSCRIBE_PATH, LIVE_TENANT_HEADER, LIVE_WITHIN_HEADER, LIVE_EXPIRES_HEADER, LIVE_CLOSE, LIVE_SOCKETS_PER_PRINCIPAL, decodeLiveWithin, liveInstant, liveRefusal, liveRefusalStatus, } from './live-reads.js';
 import { replyOf } from './do-reply.js';
 import { OperationQueue } from './serialization.js';
@@ -44,6 +44,14 @@ const tenantRefusals = new WeakSet();
 /** #1722: a load refused because its copy move's lease ran out (`CopyRestoreFence`), told apart
  *  from a store that moved, since the host must not read it as an applied retry. */
 const fenceRefusals = new WeakSet();
+/** #2531: a role set refused inside the unit writing it (`refuseRoleSetInUnit`), told apart by identity. */
+const roleRefusals = new WeakSet();
+/** `ProjectedRoleRow` as the reserved-key rule reads it. */
+const roleShapeOfRow = (r) => ({
+    key: r.role_key,
+    permissions: JSON.parse(r.permissions),
+    ...(r.holder === 'system' ? { holder: 'system' } : r.holder == null ? {} : { holder: 'person' }),
+});
 /**
  * The scope spine, as this adapter builds it — one of two hand-written copies (#969).
  *
@@ -382,6 +390,10 @@ const KERNEL_DDL = `
   -- #119: the kernel's authorization for one archive/trash move, read by the derived update
   -- trigger. Shared with the other adapter from @substrat-run/kernel; the comments are there.
   ${ENTITY_STATE_MOVES_DDL}
+  -- RFC wire-signing §4: the nonces of signed calls this scope accepted, and their count.
+  -- Store-local: never dumped, written on the bookkeeping path. Shared with the pure adapter
+  -- from @substrat-run/kernel, where the column comments are.
+  ${WIRE_NONCE_DDL}
 `;
 /**
  * Workers RPC carries a plain `Error`'s MESSAGE faithfully and nothing else. A custom
@@ -417,6 +429,8 @@ function kernelEmit(ctx, event) {
         throw new Error('kernelEmit: not an operation context this host built');
     write(event);
 }
+/** #2555: the `_substrat_meta` keys a control-plane-full load keeps from the destination. */
+const PERMISSION_FLAG_KEYS = ['permission_source', 'entitlements_enforced'];
 /** #2450: a commit or a page naming a stage this store no longer holds. */
 const STAGE_GONE = 'the staged load is not here any more (another carry replaced it, or it was already loaded); nothing was loaded';
 /** A competing page zero must leave the stage a live copy owns intact. */
@@ -543,11 +557,11 @@ class WriteRevision {
             if (write)
                 this.written++;
             if (this.keeping && write) {
-                // Bookkeeping takes the copy-marker insert and the lifecycle delivery (#1713) and nothing
-                // else: any other write here would be one the revision never saw, which is the hole this
+                // Bookkeeping takes the copy-marker insert, the lifecycle delivery (#1713) and the wire
+                // nonce claim's own statements (RFC wire-signing §4) and nothing else: any other write here would be one the revision never saw, which is the hole this
                 // class exists to close.
-                if (!isCopyMarkInsert(query) && !isLifecycleWrite(query)) {
-                    throw substratError('internal', `the bookkeeping path takes only the copy-marker insert and the lifecycle delivery (#1722, #1713), not: ${query.slice(0, 80)}`);
+                if (!isCopyMarkInsert(query) && !isLifecycleWrite(query) && !isWireNonceWrite(query)) {
+                    throw substratError('internal', `the bookkeeping path takes only the copy-marker insert, the lifecycle delivery and the wire nonce claim (#1722, #1713), not: ${query.slice(0, 80)}`);
                 }
                 return raw.exec(query, ...bindings);
             }
@@ -574,8 +588,9 @@ class WriteRevision {
      * r10). That only ever restricts what the store may run and changes no data, so it advances no
      * write revision: a backfill that marks a carry's source between its export and its wipe must
      * not read as a write the carry did not copy (that would keep the copy for nothing). Enforced,
-     * not trusted: any write in here but the marker insert (`isCopyMarkInsert`) or the lifecycle
-     * delivery (`isLifecycleWrite`, #1713) throws. Clearing a
+     * not trusted: any write in here but the marker insert (`isCopyMarkInsert`), the lifecycle
+     * delivery (`isLifecycleWrite`, #1713) or a wire nonce claim (`isWireNonceWrite`, RFC
+     * wire-signing §4: a nonce describes a call this store accepted, not its data) throws. Clearing a
      * marker is NOT bookkeeping (r11): it loosens the store, so it is a write a carry fences on.
      */
     bookkeeping(run) {
@@ -3860,6 +3875,10 @@ options = {}) {
          * set defined on this scope, or a role definition fanned out to it, is judged against.
          */
         async roleStateHere(tenantId) {
+            return this.roleStateSync(tenantId);
+        }
+        /** `roleStateHere`, read synchronously, so a unit that writes roles or seats can judge on what it holds (#2531). */
+        roleStateSync(tenantId) {
             // Spine tables only (built in the constructor), so no module migration runs ahead of a provision's.
             const now = new Date().toISOString();
             const rows = this.hasTable('_substrat_roles')
@@ -3875,6 +3894,25 @@ options = {}) {
             const seated = new Set(this.sql.exec(SCOPE_SEATED_ROLES_SQL, now).toArray().map((r) => r.role_key));
             return { roles, seated: [...seated], dropped };
         }
+        /**
+         * #2531: the in-unit judgement. Throws when `roles`, the set the caller's unit is writing for
+         * `tenantId`, is refused by the reserved-key rule (`reservedRoleSetRefusal`, one call) against the
+         * roles, tombstones and seats this scope holds at that moment, with the caller's reservations
+         * joined with this class's. Synchronous, so the unit it runs in cannot interleave with a write
+         * between this read and its own writes; a refusal rolls the whole unit back.
+         *
+         * The answer is a fixed sentence naming the role key only, whoever reads it. The rule's own
+         * wording is the pre-check's, which a caller still asks first for the common case.
+         */
+        refuseRoleSetInUnit(tenantId, roles, { judge, loaded }) {
+            const state = this.roleStateSync(tenantId);
+            const refused = (loaded ? loadedRoleSetRefusedRole : reservedRoleSetRefusedRole)(roles, { reserved: new Set([...judge.reserved, ...this.reservedKeys]), declared: new Set([...judge.declared, ...this.declaredKeys]) }, { roles: state.roles, seated: new Set(state.seated), ...(state.dropped ? { dropped: state.dropped } : {}) });
+            if (refused === null)
+                return;
+            const error = substratError('forbidden', inUnitRoleRefusal(refused.key));
+            roleRefusals.add(error);
+            throw error;
+        }
         /** #2447: what this class's modules reserve and declare — a coordinator judging a role definition joins its own. */
         async reservationHere() {
             return { reserved: [...this.reservedKeys], declared: [...this.declaredKeys] };
@@ -4898,6 +4936,24 @@ options = {}) {
             });
             return marked;
         }
+        /**
+         * RFC wire-signing §4: spend a signed call's nonce in this scope's own store, the claim the
+         * platform's entry makes through the vertical's host (`claimWireNonceLocal`) after every other
+         * check of the envelope has passed. `true` once per nonce; `false` for one already spent, or a
+         * claim after `until`. A store at its cap throws, after its purge committed, which the entry
+         * answers as the store's failure. In storage, so it survives an eviction. Bookkeeping, like the
+         * copy marker: a nonce describes a call this store accepted, not its data, so it advances no
+         * write revision a carry fences on, and no dump carries it.
+         */
+        claimWireNonce(nonce, until) {
+            let answer;
+            this.revision.transactionSync(() => {
+                answer = this.revision.bookkeeping(() => claimWireNonceIn(this.switchSql(), nonce, until, Math.floor(Date.now() / 1000)));
+            });
+            if (answer === 'full')
+                throw new Error(WIRE_NONCE_FULL);
+            return answer;
+        }
         /**
          * Clear a mistaken copy classification (#2005, `clearCopyMarker`); a load's events mark stays,
          * so copied work still never runs here (#2009). A
@@ -5297,7 +5353,8 @@ options = {}) {
          * The tables a dump carries, by name. The derived search index (#827) is excluded: its shadow
          * tables cannot be replayed — this host answers "object name reserved for internal use" — and
          * it is recomputable, so `importDump` rebuilds it from the loaded rows. A dump carries the rows,
-         * never the index over them. A staged load's own tables (#2450) are this store's, not its data.
+         * never the index over them. A staged load's own tables (#2450) are this store's, not its data,
+         * and so is the wire nonce store (RFC wire-signing §4): a load builds it empty.
          */
         dumpTableDefs() {
             return this.sql
@@ -5305,7 +5362,7 @@ options = {}) {
               WHERE type = 'table' AND name NOT GLOB 'sqlite_*' AND name NOT GLOB '_cf_*'
                 AND name NOT GLOB '${STAGE_GLOB}' AND sql IS NOT NULL
               ORDER BY name`)
-                .toArray().filter(({ name }) => !isSearchIndexTable(name));
+                .toArray().filter(({ name }) => !isSearchIndexTable(name) && !isWireNonceTable(name));
         }
         /**
          * One page of `exportDumpStamped` (#2450): the tables in the same order, each table's rows in
@@ -5578,7 +5635,7 @@ options = {}) {
          * in memory at once. `stageId` names the staged load the rows come from: checked inside the
          * load's transaction, and its tables dropped in it once the rows are in.
          */
-        async loadTables(tables, destScopeId, { switchOff, sourceScopeId, exact, loadStamp, expect, resolveKept, markCopy, provisionedFor, fence, } = {}, stageId) {
+        async loadTables(tables, destScopeId, { switchOff, sourceScopeId, exact, loadStamp, expect, resolveKept, markCopy, provisionedFor, fence, roleRepair, onRolesProjected, projection, keepPermissionFlags, } = {}, stageId) {
             // The WHOLE drop-then-replay runs under deferred foreign keys, in one transaction.
             //
             // Two distinct FK hazards, and both need the deferral — the second is why it cannot
@@ -5601,8 +5658,10 @@ options = {}) {
             // rather than failing a restore over data about to be recomputed.
             // Matched without case, as SQLite resolves a table name (#1883 review).
             // #1686: a copy into another scope id loads no capability rows; a same-scope restore keeps them.
+            // The wire nonce store is this store's own (RFC wire-signing §4): never replayed, so a load
+            // starts it empty.
             const replayable = tables
-                .filter((t) => !isSearchIndexTable(t.name.toLowerCase()))
+                .filter((t) => !isSearchIndexTable(t.name.toLowerCase()) && !isWireNonceTable(t.name))
                 .map((t) => (loadDropsRowsOf(t.name, destScopeId, sourceScopeId) ? { ...t, rows: () => [] } : t));
             // The dump is untrusted input (#1143). `SqlStorage.exec` runs every statement
             // in the string it is given, so a `ddl` with anything appended to its CREATE
@@ -5615,6 +5674,13 @@ options = {}) {
             if (exact && !sourceScopeId) {
                 throw substratError('validation_failed', 'restore refused: `exact` needs the scope the dump came from');
             }
+            // #2531: a reaped store takes no role repair, judged or not, as `projectInUnit` drops a
+            // projection there: the load comes back with no roles, no receipt and no enforcement flip,
+            // as it did before the repair rode the load. Read before the unit, as `projectInUnit` reads it.
+            // #2555: the directory's projection is dropped there too, for the same reason.
+            const reaped = roleRepair || projection ? await this.isReaped() : false;
+            const repair = roleRepair && !reaped ? roleRepair : undefined;
+            const directory = projection && !reaped ? projection : undefined;
             const switched = await this.revision.transaction(async () => {
                 // #1722: first, before any read: a store a reap has since emptied must refuse the late load
                 // too, and the check is against this store's clock, inside the load's own transaction.
@@ -5644,6 +5710,8 @@ options = {}) {
                     return { name: t.name, columns: ['id'], rows: at < 0 ? [] : Array.from(t.rows(), (row) => [row[at]]) };
                 }));
                 const receiptBefore = this.provisionedFor();
+                // #2555: this store's own permission flags, read before the drops take them.
+                const flagsBefore = keepPermissionFlags ? PERMISSION_FLAG_KEYS.map((key) => [key, this.metaValue(key)]) : [];
                 if (provisionedFor !== undefined && receiptBefore !== null && receiptBefore !== provisionedFor) {
                     const refused = substratError('conflict', tenantReceiptRefusal(receiptBefore, provisionedFor));
                     tenantRefusals.add(refused);
@@ -5705,7 +5773,8 @@ options = {}) {
                     // `_substrat_tenant_tuples` in its DIRECTORY database, so its per-scope dump omits
                     // them, and without them the very next permission check would raise a bare `no such
                     // table: _substrat_roles`. Roles land empty here and are re-projected by the
-                    // restore's repair leg (host.projectRolesLocal) — the spine's job is only to exist so
+                    // restore's repair leg (`roleRepair` below, or host.projectRolesLocal after the load,
+                    // #2531) — the spine's job is only to exist so
                     // the checker can read it. The column pass follows, for the one outbox index KERNEL_DDL
                     // leaves to it.
                     for (const stmt of executableSqlStatements(KERNEL_DDL))
@@ -5740,6 +5809,15 @@ options = {}) {
                     if (receipt !== null) {
                         this.sql.exec(`INSERT INTO _substrat_meta (key, value) VALUES (?, ?)`, PROVISIONED_FOR_KEY, receipt);
                     }
+                    // #2555: which reader the checker uses, and whether entitlements are enforced, are this
+                    // store's, as its receipt is: the dump's values describe the scope it was captured from,
+                    // when it was. A flag this store did not hold stays unset. The projection below may then
+                    // move them as a fan-out would.
+                    for (const [key, value] of flagsBefore) {
+                        this.sql.exec(`DELETE FROM _substrat_meta WHERE key = ?`, key);
+                        if (value !== null)
+                            this.sql.exec(`INSERT INTO _substrat_meta (key, value) VALUES (?, ?)`, key, value);
+                    }
                     // #1722: whatever stamp an export read here no longer describes this store, so every load
                     // replaces it: with the carry's own, or with none. And the write revision moves on from
                     // where it stood before the drops, so it never goes back.
@@ -5786,9 +5864,38 @@ options = {}) {
                     // #1742: the recorded-off modules go back off INSIDE the replay's transaction, with
                     // the spine and the re-point. A switch that throws rolls the whole restore back, so
                     // the dump's grants never commit live without the switch that should cover them.
-                    return destScopeId && switchOff
+                    const switchedOff = destScopeId && switchOff
                         ? switchRecordedOff(this.switchSql(), { scopeId: destScopeId, ...switchOff })
                         : [];
+                    // #2531: the role repair, last, in this same transaction: judged on the roles, tombstones and
+                    // seats the dump has just brought (`refuseRoleSetInUnit`), then projected exactly as
+                    // `projectRolesLocal` projects it. A refusal rolls the whole load back, so the scope keeps
+                    // its rows and a staged load keeps its stage; an admitted load lands with its repair.
+                    // #2555: a control-plane-full load writes the directory's current state the same way, in the
+                    // same place: the tenant's roles, tuples, entitlements, identity links and the vertical's
+                    // connection keys, each a full replace as a fan-out writes it, so nothing the directory has
+                    // since revoked comes back with the dump. Scope-level tuples (the seats) are not touched.
+                    // The roles are judged only where the loaded state has a part in them (`loaded`).
+                    if (repair || directory) {
+                        try {
+                            if (repair)
+                                this.projectionBody({ judge: repair.judge }, repair.tenantId, repair.roles, []);
+                            else if (directory) {
+                                const { judge, tenantId, roles, tuples, entitlements, identities, connectionKeys } = directory;
+                                this.projectionBody({ judge, loaded: true }, tenantId, roles, tuples, entitlements, undefined, identities, connectionKeys);
+                            }
+                        }
+                        catch (e) {
+                            // The projection's own tenant refusal (its receipt check) is a tenant refusal of the
+                            // load, not the kept-copy `conflict` `checkedLoad` would otherwise read it as.
+                            if (e instanceof Error && !roleRefusals.has(e) && errorCodeOf(e) === 'conflict')
+                                tenantRefusals.add(e);
+                            throw e;
+                        }
+                    }
+                    if (repair)
+                        onRolesProjected?.();
+                    return switchedOff;
                 }
                 finally {
                     this.revisionSuspended = false;
@@ -5849,6 +5956,57 @@ options = {}) {
         async importDumpChecked(tables, destScopeId, opts) {
             return this.checkedLoad(() => this.importDump(tables, destScopeId, opts));
         }
+        /**
+         * #2531: `importDumpChecked` with the role repair judged and projected in the load's own
+         * transaction (`roleRepair`), answered `rolesProjected: true` when it landed there. A reaped
+         * store takes no repair (`loadTables`), so its load answers without it. A method of its
+         * own, so a host meeting a ScopeDO from before it is refused by the runtime, nothing loaded,
+         * rather than loading with the repair silently dropped.
+         */
+        async importDumpJudged(tables, destScopeId, opts, roleRepair) {
+            return this.judgedLoad((onRolesProjected) => this.checkedLoad(() => this.importDump(tables, destScopeId, { ...opts, roleRepair, onRolesProjected })));
+        }
+        /**
+         * #2555: a control-plane-full restore or import. `importDump`, with this store's permission flags
+         * kept through it and, when `projection` is given (a host that projects permissions into its
+         * scopes), the directory's current state judged and projected last in the load's transaction. A
+         * refusal rolls the whole load back. The role judgement's own is answered as `refusedRoles`, so
+         * the host can tell it from any other; every other is answered as data so its code survives the
+         * hop. A method of its own, so a host meeting a ScopeDO from before it is refused by the
+         * runtime, nothing loaded, rather than loading the dump's permission state as is.
+         */
+        importDumpProjected(tables, destScopeId, opts, projection) {
+            return replyOf(async () => {
+                try {
+                    return {
+                        switchedOff: await this.importDump(tables, destScopeId, {
+                            switchOff: opts.switchOff,
+                            sourceScopeId: opts.sourceScopeId,
+                            exact: opts.exact,
+                            keepPermissionFlags: true,
+                            ...(projection ? { projection } : {}),
+                        }),
+                    };
+                }
+                catch (e) {
+                    if (e instanceof Error && roleRefusals.has(e))
+                        return { refusedRoles: e.message };
+                    throw e;
+                }
+            });
+        }
+        /** #2531: `commitStagedDumpChecked` with the role repair in the load's transaction (`importDumpJudged`). */
+        async commitStagedDumpJudged(stageId, destScopeId, opts, roleRepair) {
+            return this.judgedLoad((onRolesProjected) => this.commitStagedDumpChecked(stageId, destScopeId, { ...opts, roleRepair, onRolesProjected }));
+        }
+        /** A judged load, answered `rolesProjected: true` only when its repair was written in it. */
+        async judgedLoad(run) {
+            let projected = false;
+            const out = await run(() => {
+                projected = true;
+            });
+            return out.refused === false && projected ? { ...out, rolesProjected: true } : out;
+        }
         /**
          * Stage one page of a dump for a later `commitStagedDump` (#2450). The rows go into this
          * store's own staging tables, untyped, so every cell is kept as it arrived; nothing of the
@@ -6011,6 +6169,8 @@ options = {}) {
             catch (e) {
                 if (e instanceof Error && fenceRefusals.has(e))
                     return { refused: 'lapsed' };
+                if (e instanceof Error && roleRefusals.has(e))
+                    return { refused: 'roles', message: e.message };
                 const code = errorCodeOf(e);
                 if (code === 'precondition_failed')
                     return { refused: 'changed' };
@@ -7028,6 +7188,17 @@ options = {}) {
         applyProjectionReply(...args) {
             return replyOf(() => this.applyProjection(...args));
         }
+        /**
+         * #2531: `applyProjectionReply` with the role set judged INSIDE the projection's unit, against
+         * the roles, tombstones and seats this scope holds as it writes (`refuseRoleSetInUnit`). A
+         * refusal writes nothing: no role row, tombstone, receipt, seat, switch or enforcement flip.
+         * A method of its own, not an argument, so a host meeting a ScopeDO from before it is refused
+         * by the runtime (no such method) before anything is written, rather than projecting unjudged.
+         * The directory fan-out does not call it (K-55, #2531).
+         */
+        applyJudgedProjectionReply(judge, ...args) {
+            return replyOf(() => this.projectInUnit(judge, ...args));
+        }
         /**
          * Replace this scope's projected view of a tenant's roles + tenant-level tuples
          * with a fresh snapshot, and make it authoritative (source = 'local'). A full
@@ -7072,6 +7243,10 @@ options = {}) {
         switchOff, 
         /** Declared service subjects excluded only from human lockout repair (#1896). */
         serviceSubjects) {
+            return this.projectInUnit(undefined, tenantId, roles, tuples, entitlements, scopeTuples, identities, connectionKeys, switchOff, serviceSubjects);
+        }
+        /** `applyProjection`'s unit, its role set judged in it when `judge` is given (#2531). */
+        async projectInUnit(judge, ...args) {
             if (await this.isReaped())
                 return [];
             // A projection that arrives after this scope was reaped is dropped, not
@@ -7082,123 +7257,131 @@ options = {}) {
             // The whole body is synchronous storage work, so it is ONE transaction (#1738): the queue
             // serializes but does not roll back, and a role insert that throws part-way must not leave
             // the receipt (or a half-replaced role set) behind for `servesTenant` to trust.
-            return this.queue.enqueue(() => this.revision.transactionSync(() => {
-                // #1738: the receipt `servesTenant` reads. First writer wins: absent or equal is written,
-                // a receipt for ANOTHER tenant refuses the whole projection (K-3), before a single row
-                // moves, so a misdirected projection can never re-point a scope or leave its roles behind.
-                // A restore does not trip this: `importDump` keeps the destination's own receipt and
-                // never the dump's (#2016), so the repair projection that follows finds its own tenant.
-                // #2016: a scope with no receipt yet takes its first one only where its role rows agree
-                // (`tenantVerdict`, the same reading the lifecycle back-fill uses), so a projection for
-                // another tenant cannot pin a legacy scope to it.
-                const { verdict, held } = this.tenantVerdict(tenantId);
-                if (verdict === 'foreign') {
-                    throw substratError('conflict', held !== null
-                        ? `applyProjection refused: this scope was provisioned for tenant ${held}, and a projection for tenant ${tenantId} would re-point it`
-                        : `applyProjection ${foreignTenant(held, tenantId)}`);
-                }
-                // Written before any guard below can return early, so every projection leaves it.
-                this.sql.exec(`INSERT OR REPLACE INTO _substrat_meta (key, value) VALUES (?, ?)`, PROVISIONED_FOR_KEY, tenantId);
-                // #2531: a role the new set leaves out is TOMBSTONED, not deleted: it keeps the keys and the
-                // holder it had, and grants nothing (every reader skips a revoked row). Kept for good, as
-                // evidence (K-21): the reserved-key rule reads a system-held tombstone as the stored
-                // definition it was, so a release that drops a role and a later one that adds it back
-                // are judged as one that kept it. A row already tombstoned keeps its first `revoked_at`;
-                // a role the set names is written live again below, which clears it.
-                this.sql.exec(`UPDATE _substrat_roles SET revoked_at = ? WHERE tenant_id = ? AND revoked_at IS NULL`, new Date().toISOString(), tenantId);
-                for (const r of roles) {
-                    this.sql.exec(`INSERT OR REPLACE INTO _substrat_roles (tenant_id, role_key, permissions, source, holder, revoked_at)
-               VALUES (?, ?, ?, ?, ?, NULL)`, tenantId, r.role_key, r.permissions, r.source, r.holder === 'system' ? 'system' : r.holder == null ? null : 'person');
-                }
-                this.sql.exec(`DELETE FROM _substrat_tenant_tuples WHERE tenant_id = ?`, tenantId);
-                for (const t of tuples) {
-                    this.sql.exec(`INSERT OR REPLACE INTO _substrat_tenant_tuples
-                 (tenant_id, subject, relation, object, expires_at, revoked_at)
-               VALUES (?, ?, ?, ?, ?, ?)`, tenantId, t.subject, t.relation, t.object, t.expires_at, t.revoked_at);
-                }
-                if (entitlements !== undefined) {
-                    this.sql.exec(`DELETE FROM _substrat_entitlements WHERE tenant_id = ?`, tenantId);
-                    for (const e of entitlements) {
-                        this.sql.exec(`INSERT OR REPLACE INTO _substrat_entitlements
-                   (tenant_id, entitlement_key, expires_at, quota, plan)
-                 VALUES (?, ?, ?, ?, ?)`, tenantId, e.entitlement_key, e.expires_at, e.quota, e.plan);
-                    }
-                    // #304: once a scope has been projected WITH entitlements even once, its gate
-                    // switches from trust-upstream to strict fail-closed (a missing/expired key
-                    // denies). Left unset, a scope provisioned before #304 keeps trusting upstream
-                    // until a projection (fanOut / reconcile / re-provision) back-fills it — so the
-                    // enforcement flip is per-scope and never strands an un-back-filled scope.
-                    this.sql.exec(`INSERT OR REPLACE INTO _substrat_meta (key, value) VALUES ('entitlements_enforced', '1')`);
+            return this.queue.enqueue(() => this.revision.transactionSync(() => this.projectionBody(judge && { judge }, ...args)));
+        }
+        /**
+         * The projection's writes, synchronous, for a unit the caller holds: `projectInUnit`'s, or a
+         * load's (`loadTables`, #2531), so a restore's role repair lands in the load's transaction.
+         */
+        projectionBody(judgement, ...[tenantId, roles, tuples, entitlements, scopeTuples, identities, connectionKeys, switchOff, serviceSubjects]) {
+            // #1738: the receipt `servesTenant` reads. First writer wins: absent or equal is written,
+            // a receipt for ANOTHER tenant refuses the whole projection (K-3), before a single row
+            // moves, so a misdirected projection can never re-point a scope or leave its roles behind.
+            // A restore does not trip this: `importDump` keeps the destination's own receipt and
+            // never the dump's (#2016), so the repair projection that follows finds its own tenant.
+            // #2016: a scope with no receipt yet takes its first one only where its role rows agree
+            // (`tenantVerdict`, the same reading the lifecycle back-fill uses), so a projection for
+            // another tenant cannot pin a legacy scope to it.
+            const { verdict, held } = this.tenantVerdict(tenantId);
+            if (verdict === 'foreign') {
+                throw substratError('conflict', held !== null
+                    ? `applyProjection refused: this scope was provisioned for tenant ${held}, and a projection for tenant ${tenantId} would re-point it`
+                    : `applyProjection ${foreignTenant(held, tenantId)}`);
+            }
+            // #2531: judged before the first write of the unit, on what the scope holds now.
+            if (judgement)
+                this.refuseRoleSetInUnit(tenantId, roles.map(roleShapeOfRow), judgement);
+            // Written before any guard below can return early, so every projection leaves it.
+            this.sql.exec(`INSERT OR REPLACE INTO _substrat_meta (key, value) VALUES (?, ?)`, PROVISIONED_FOR_KEY, tenantId);
+            // #2531: a role the new set leaves out is TOMBSTONED, not deleted: it keeps the keys and the
+            // holder it had, and grants nothing (every reader skips a revoked row). Kept for good, as
+            // evidence (K-21): the reserved-key rule reads a system-held tombstone as the stored
+            // definition it was, so a release that drops a role and a later one that adds it back
+            // are judged as one that kept it. A row already tombstoned keeps its first `revoked_at`;
+            // a role the set names is written live again below, which clears it.
+            this.sql.exec(`UPDATE _substrat_roles SET revoked_at = ? WHERE tenant_id = ? AND revoked_at IS NULL`, new Date().toISOString(), tenantId);
+            for (const r of roles) {
+                this.sql.exec(`INSERT OR REPLACE INTO _substrat_roles (tenant_id, role_key, permissions, source, holder, revoked_at)
+           VALUES (?, ?, ?, ?, ?, NULL)`, tenantId, r.role_key, r.permissions, r.source, r.holder === 'system' ? 'system' : r.holder == null ? null : 'person');
+            }
+            this.sql.exec(`DELETE FROM _substrat_tenant_tuples WHERE tenant_id = ?`, tenantId);
+            for (const t of tuples) {
+                this.sql.exec(`INSERT OR REPLACE INTO _substrat_tenant_tuples
+             (tenant_id, subject, relation, object, expires_at, revoked_at)
+           VALUES (?, ?, ?, ?, ?, ?)`, tenantId, t.subject, t.relation, t.object, t.expires_at, t.revoked_at);
+            }
+            if (entitlements !== undefined) {
+                this.sql.exec(`DELETE FROM _substrat_entitlements WHERE tenant_id = ?`, tenantId);
+                for (const e of entitlements) {
+                    this.sql.exec(`INSERT OR REPLACE INTO _substrat_entitlements
+               (tenant_id, entitlement_key, expires_at, quota, plan)
+             VALUES (?, ?, ?, ?, ?)`, tenantId, e.entitlement_key, e.expires_at, e.quota, e.plan);
                 }
-                // #406: identity links ride the same snapshot. Full replace, so an unlink is
-                // durable against every later projection — unlike the compiled-in map this
-                // replaces, where a version rollback silently resurrected a removed login.
-                if (identities !== undefined) {
-                    this.sql.exec(`DELETE FROM _substrat_identity_links WHERE tenant_id = ?`, tenantId);
-                    for (const i of identities) {
-                        this.sql.exec(`INSERT OR REPLACE INTO _substrat_identity_links
-                   (tenant_id, provider, external_id, principal_id, scope_id)
-                 VALUES (?, ?, ?, ?, ?)`, tenantId, i.provider, i.external_id, i.principal_id, i.scope_id);
-                    }
+                // #304: once a scope has been projected WITH entitlements even once, its gate
+                // switches from trust-upstream to strict fail-closed (a missing/expired key
+                // denies). Left unset, a scope provisioned before #304 keeps trusting upstream
+                // until a projection (fanOut / reconcile / re-provision) back-fills it — so the
+                // enforcement flip is per-scope and never strands an un-back-filled scope.
+                this.sql.exec(`INSERT OR REPLACE INTO _substrat_meta (key, value) VALUES ('entitlements_enforced', '1')`);
+            }
+            // #406: identity links ride the same snapshot. Full replace, so an unlink is
+            // durable against every later projection — unlike the compiled-in map this
+            // replaces, where a version rollback silently resurrected a removed login.
+            if (identities !== undefined) {
+                this.sql.exec(`DELETE FROM _substrat_identity_links WHERE tenant_id = ?`, tenantId);
+                for (const i of identities) {
+                    this.sql.exec(`INSERT OR REPLACE INTO _substrat_identity_links
+               (tenant_id, provider, external_id, principal_id, scope_id)
+             VALUES (?, ?, ?, ?, ?)`, tenantId, i.provider, i.external_id, i.principal_id, i.scope_id);
                 }
-                // #687: connection sealing keys ride the same snapshot. Full replace, so a
-                // revoked connection's key stops being projected and `sealToConnection` starts
-                // refusing — the same fail-closed direction an unlinked identity takes.
-                if (connectionKeys !== undefined) {
-                    this.sql.exec(`DELETE FROM _substrat_connection_keys WHERE tenant_id = ?`, tenantId);
-                    for (const k of connectionKeys) {
-                        this.sql.exec(`INSERT OR REPLACE INTO _substrat_connection_keys
-                   (tenant_id, connection_id, provider, key_id, public_key)
-                 VALUES (?, ?, ?, ?, ?)`, tenantId, k.connection_id, k.provider, k.key_id, k.public_key);
-                    }
+            }
+            // #687: connection sealing keys ride the same snapshot. Full replace, so a
+            // revoked connection's key stops being projected and `sealToConnection` starts
+            // refusing — the same fail-closed direction an unlinked identity takes.
+            if (connectionKeys !== undefined) {
+                this.sql.exec(`DELETE FROM _substrat_connection_keys WHERE tenant_id = ?`, tenantId);
+                for (const k of connectionKeys) {
+                    this.sql.exec(`INSERT OR REPLACE INTO _substrat_connection_keys
+               (tenant_id, connection_id, provider, key_id, public_key)
+             VALUES (?, ?, ?, ?, ?)`, tenantId, k.connection_id, k.provider, k.key_id, k.public_key);
                 }
-                // #332: scope-level grants (the owner's role tuple at provision) are written in the
-                // SAME enqueued unit as the projection and the enforcement flip below. Additive upsert
-                // — NOT a full replace — so existing scope tuples are preserved. This is what keeps a
-                // scope from ever being left "roles projected, permission_source=local, zero tuples" by
-                // a write that lands the projection but drops before a follow-up owner grant.
-                //
-                // #1659: SEATED, so a reconcile creates what is missing and leaves a revoke alone. It
-                // used to be `INSERT OR REPLACE … revoked_at = NULL`, which undid an operator's revoke
-                // of the owner seat or of a `system:` schedule grant on the next reconcile. And a
-                // module switched off (#1666) gets no `system:` grant seated, new or old.
+            }
+            // #332: scope-level grants (the owner's role tuple at provision) are written in the
+            // SAME enqueued unit as the projection and the enforcement flip below. Additive upsert
+            // — NOT a full replace — so existing scope tuples are preserved. This is what keeps a
+            // scope from ever being left "roles projected, permission_source=local, zero tuples" by
+            // a write that lands the projection but drops before a follow-up owner grant.
+            //
+            // #1659: SEATED, so a reconcile creates what is missing and leaves a revoke alone. It
+            // used to be `INSERT OR REPLACE … revoked_at = NULL`, which undid an operator's revoke
+            // of the owner seat or of a `system:` schedule grant on the next reconcile. And a
+            // module switched off (#1666) gets no `system:` grant seated, new or old.
+            for (const st of scopeTuples ?? []) {
+                const seat = seatScopeTuple(st.subject, st.relation, st.object, st.expires_at);
+                this.sql.exec(seat.sql, ...seat.params);
+            }
+            // #1659's one exception: the owner-of-record's seat comes back over a revoke when
+            // No HUMAN holder remains — declared service subjects cannot prevent lockout repair.
+            // That is the #332 lockout this path exists to repair. The flip guard below still
+            // counts service authority; only the repair excludes the declared service subjects.
+            // With any other effective holder, the revoke stands: a hand-over that seats a
+            // successor before unseating the owner is not undone by the next promote. A holder of
+            // a role the vertical no longer defines is NOT one — it passes no check, so it must
+            // not stand in for the holder this repair exists to restore.
+            if (roles.length > 0 && !this.hasEffectiveRoleGrant(tenantId, serviceSubjects)) {
                 for (const st of scopeTuples ?? []) {
-                    const seat = seatScopeTuple(st.subject, st.relation, st.object, st.expires_at);
-                    this.sql.exec(seat.sql, ...seat.params);
-                }
-                // #1659's one exception: the owner-of-record's seat comes back over a revoke when
-                // No HUMAN holder remains — declared service subjects cannot prevent lockout repair.
-                // That is the #332 lockout this path exists to repair. The flip guard below still
-                // counts service authority; only the repair excludes the declared service subjects.
-                // With any other effective holder, the revoke stands: a hand-over that seats a
-                // successor before unseating the owner is not undone by the next promote. A holder of
-                // a role the vertical no longer defines is NOT one — it passes no check, so it must
-                // not stand in for the holder this repair exists to restore.
-                if (roles.length > 0 && !this.hasEffectiveRoleGrant(tenantId, serviceSubjects)) {
-                    for (const st of scopeTuples ?? []) {
-                        if (!st.lockout_reseat)
-                            continue;
-                        this.sql.exec(`INSERT OR REPLACE INTO _substrat_tuples (subject, relation, object, expires_at, revoked_at)
-                 VALUES (?, ?, ?, ?, NULL)`, st.subject, st.relation, st.object, st.expires_at);
-                    }
+                    if (!st.lockout_reseat)
+                        continue;
+                    this.sql.exec(`INSERT OR REPLACE INTO _substrat_tuples (subject, relation, object, expires_at, revoked_at)
+             VALUES (?, ?, ?, ?, NULL)`, st.subject, st.relation, st.object, st.expires_at);
                 }
-                // #1742: the directory's recorded-off modules go back off HERE, after the seat and in
-                // its unit. A wiped scope's seat has just re-created their `system:` grants (#1659), and
-                // a re-assert arriving later from the control plane left a window in which this
-                // deployment's own sweeper could fire them. Nothing runs between these two lines.
-                const switched = switchOff ? switchRecordedOff(this.switchSql(), switchOff) : [];
-                // #332: only switch on strict local enforcement when SOMEONE actually holds a role.
-                // A projection that leaves role definitions but no effective principal→role grant would
-                // make every check fail closed — a scope serving nothing but denials, unfixable from
-                // inside. Leave `permission_source` as-is instead; a reconcile that restores the owner
-                // grant re-runs this and flips safely. (A CP-less vertical uses the local reader
-                // regardless of this flag, so the owner grant is written above in the same unit — this
-                // guard is the belt to that suspenders, and it protects the CP-backed flip outright.)
-                if (roles.length > 0 && !this.hasEffectiveRoleGrant(tenantId))
-                    return switched;
-                this.sql.exec(`INSERT OR REPLACE INTO _substrat_meta (key, value) VALUES ('permission_source', 'local')`);
+            }
+            // #1742: the directory's recorded-off modules go back off HERE, after the seat and in
+            // its unit. A wiped scope's seat has just re-created their `system:` grants (#1659), and
+            // a re-assert arriving later from the control plane left a window in which this
+            // deployment's own sweeper could fire them. Nothing runs between these two lines.
+            const switched = switchOff ? switchRecordedOff(this.switchSql(), switchOff) : [];
+            // #332: only switch on strict local enforcement when SOMEONE actually holds a role.
+            // A projection that leaves role definitions but no effective principal→role grant would
+            // make every check fail closed — a scope serving nothing but denials, unfixable from
+            // inside. Leave `permission_source` as-is instead; a reconcile that restores the owner
+            // grant re-runs this and flips safely. (A CP-less vertical uses the local reader
+            // regardless of this flag, so the owner grant is written above in the same unit — this
+            // guard is the belt to that suspenders, and it protects the CP-backed flip outright.)
+            if (roles.length > 0 && !this.hasEffectiveRoleGrant(tenantId))
                 return switched;
-            }));
+            this.sql.exec(`INSERT OR REPLACE INTO _substrat_meta (key, value) VALUES ('permission_source', 'local')`);
+            return switched;
         }
         /**
          * Resolve an external identity from this scope's projected links (#406) — the