@substrat-run/control-plane-api 0.176.0 → 0.177.0

package/dist/api.js

@@ -3,7 +3,7 @@ import { PREVIEW_CONNECTIONS_REFUSAL } from './connection-relay.js';
 import { bindingChangeRefusal, bindingOptionsRefusal, connectionBindingOptions, refusesBindingChange } from './connection-binding-options.js';
 import { resolveObservabilityWindow } from './observability-window.js';
 import { Hono } from 'hono';
-import { permissionKey, parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, lakeEventsInput, ownerTransferInput, memberInviteInput, memberRoleInput, ASSET_PART_PREFIX, assetHash, STORE_DRIVERS, storeCatalogOperation, storeDriverBasisAdmits, channelName, connectLinkId, connectionActivity, connectionActivitySource, connectionCredential, connectionCertificate, connectionFilter, connectionHealthState, connectionProvider, connectorDispatchKind, PROVISION_SIBLING_KIND, ARCHIVE_SCOPE_KIND, PROVISION_TENANT_KIND, SET_ENTITLEMENTS_KIND, MODEL_USAGE_KIND, SWEEP_RUNS_KIND, toConnectionHealthEntry, CONNECTION_EXPIRY_WARNING_DAYS, CONNECTION_STALE_DAYS, connectionProbe, connectionSendTest, connectionSendTestResult, connectionSenders, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, FINDINGS_LIMIT_DEFAULT, FINDINGS_LIMIT_MAX, findingCursorOf, findingKind, findingRuleInput, findingStatus, findingStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, impersonationStamp, promotionAcknowledgement, bindAcknowledgement, rebindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, operationSeriesCount, operationSeriesInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, verticalSlug, scopeText, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, platformScriptCollision, platformScriptRefusal, PLATFORM_SCRIPT_NAMES, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, requestRollupReading, meterDaysReading, verticalOwnersReading, utcDay, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, validationIssuesFrom, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, substratError, errorCodeOf, envVarSpec, capabilityFilterQuery, capabilityId as capabilityIdSchema, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, PLATFORM_FEATURE_SOURCE_BUILDS, SOCIAL_RELAY_VERTICALS, isVerticalConnectorProvider, } from '@substrat-run/contracts';
+import { permissionKey, parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, lakeEventsInput, ownerTransferInput, memberInviteInput, memberRoleInput, ASSET_PART_PREFIX, assetHash, STORE_DRIVERS, storeDriverErasesSubjects, storeDriverServesVertical, storeCatalogOperation, storeDriverBasisAdmits, channelName, connectLinkId, connectionActivity, connectionActivitySource, connectionCredential, connectionCertificate, connectionFilter, connectionHealthState, connectionProvider, connectorDispatchKind, PROVISION_SIBLING_KIND, ARCHIVE_SCOPE_KIND, PROVISION_TENANT_KIND, SET_ENTITLEMENTS_KIND, MODEL_USAGE_KIND, SWEEP_RUNS_KIND, toConnectionHealthEntry, CONNECTION_EXPIRY_WARNING_DAYS, CONNECTION_STALE_DAYS, connectionProbe, connectionSendTest, connectionSendTestResult, connectionSenders, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, FINDINGS_LIMIT_DEFAULT, FINDINGS_LIMIT_MAX, findingCursorOf, findingKind, findingRuleInput, findingStatus, findingStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, impersonationStamp, promotionAcknowledgement, bindAcknowledgement, rebindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, operationSeriesCount, operationSeriesInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, verticalSlug, scopeText, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, platformScriptCollision, platformScriptRefusal, PLATFORM_SCRIPT_NAMES, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, mergeDumpPages, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, requestRollupReading, meterDaysReading, verticalOwnersReading, utcDay, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, validationIssuesFrom, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, substratError, errorCodeOf, envVarSpec, capabilityFilterQuery, capabilityId as capabilityIdSchema, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, PLATFORM_FEATURE_SOURCE_BUILDS, SOCIAL_RELAY_VERTICALS, isVerticalConnectorProvider, } from '@substrat-run/contracts';
 import { upstreamHandleIn, upstreamReferenceOf, withUpstreamReference } from '@substrat-run/contracts';
 import { ENGINE_ENTITLEMENT_KEYS, bareSlug, declarableEntitlementKey, entitlementNamespaceRefusal, grantableEntitlements } from '@substrat-run/contracts';
 import { SCOPE_COPY_LEASE_MS, copyRestoreFence, publishedMigrationDigest, replayStoreErasures } from '@substrat-run/kernel';
@@ -70,6 +70,7 @@ import { parseTenantRequestQuery, parseTenantWindowQuery, refineTenantWindow, re
 import { namespacesForScript } from './do-namespaces.js';
 import { backupDirectoryIfDue } from './directory-backup.js';
 import { deployedDoClasses, platformSweeperDecision } from './platform-entry.js';
+import { extractedMigrationsDigest, extractedMigrationsProblem, extractedMigrationsRefusal, MigrationExtractionError, MigrationLoaderUnavailable, } from './migration-extract.js';
 import { wireSettingsRefusal, wireUploadFor } from './wire-upload.js';
 import { parseWireWalkCursor, runWireWalk, WIRE_WALK_LIMIT_DEFAULT, WIRE_WALK_LIMIT_MAX, WIRE_WALK_RELEASE_MAX, } from './wire-walk.js';
 import { wireKeyDropSince, wireReadinessReport, WIRE_READINESS_LIMIT_DEFAULT, WIRE_READINESS_LIMIT_MAX } from './wire-readiness.js';
@@ -441,13 +442,62 @@ const restoreDirectoryBody = z.object({
     overwrite: z.boolean().optional(),
 });
 /**
- * How a stored backup is named in the admin log and to callers: the route that fetches
- * it. Store-neutral by construction — the R2 key scheme stays private to the store — and
- * an operator reading a reap entry gets an address they can actually GET, rather than a
- * bucket path they would have to know the platform's internals to use.
+ * How a stored backup is named in the admin log and to callers: the route that restores
+ * it (#2839), which every backup can take, whereas only one stored in a single entry can be
+ * read whole. Store-neutral by construction — the R2 key scheme stays private to the store —
+ * so an operator reading a reap entry gets an address they can use, rather than a bucket
+ * path they would have to know the platform's internals to use.
  */
 function backupRefOf(b) {
-    return `/tenants/${b.tenantId}/scopes/${b.scopeId}/backups/${b.capturedAt}`;
+    return `/tenants/${b.tenantId}/scopes/${b.scopeId}/backups/${b.capturedAt}/restore`;
+}
+/** The tables whose rows a host judges a load's roles by (#2555): the role definitions and their seats. */
+const ROLES_TABLE = '_substrat_roles';
+const TUPLES_TABLE = '_substrat_tuples';
+/**
+ * What a host judges a backup restored from its entries by (#2839): every table's schema, with the
+ * rows of the role definitions and of the role seats only, as the entries leave them in order (a
+ * change batch replaces a row by its rowid, deletes by rowid, or replaces a table read whole). The
+ * scope's data stays at the deployment; this holds no more than the roles a load would apply.
+ */
+function rolesJudgedOf() {
+    const schemas = new Map();
+    const rows = new Map();
+    let unkeyed = 0;
+    const judged = (t, row) => t.name === ROLES_TABLE || (t.name === TUPLES_TABLE && String(row[t.columns.indexOf('relation')]).startsWith('role:'));
+    const take = (t, replace) => {
+        if (t.name !== ROLES_TABLE && t.name !== TUPLES_TABLE)
+            return;
+        const held = replace ? new Map() : (rows.get(t.name) ?? new Map());
+        t.rows.forEach((row, i) => {
+            const key = t.rowids?.[i] ?? `u${unkeyed++}`;
+            if (judged(t, row))
+                held.set(key, row);
+            else
+                held.delete(key);
+        });
+        rows.set(t.name, held);
+    };
+    return {
+        page(tables) {
+            for (const { rows: _, rowids: __, ...schema } of tables) {
+                if (!schemas.has(schema.name))
+                    schemas.set(schema.name, { ...schema, rows: [] });
+            }
+            for (const t of tables)
+                take(t, false);
+        },
+        changes(tables) {
+            for (const { deleted, ...t } of tables) {
+                for (const id of deleted)
+                    rows.get(t.name)?.delete(id);
+                take(t, !t.rowids);
+            }
+        },
+        tables() {
+            return [...schemas.values()].map((t) => ({ ...t, rows: [...(rows.get(t.name)?.values() ?? [])] }));
+        },
+    };
 }
 // A per-PR preview request (preview-and-snapshots.md §2/§9 — the "run a new version
 // against a fork of prod" slice). `tag` is a short DNS-safe label (`pr-123`): it names
@@ -5346,20 +5396,67 @@ export function createControlPlaneApi(options) {
                 `store is global, so a backup would move its data out of that jurisdiction ` +
                 `(K-32); refused until a per-jurisdiction store exists`);
         }
-        const dump = await c.var.admin.exportScope(c.get('actor'), tenantId, scope.id);
+        const { tables: hostTables, ...header } = await c.var.admin.exportScope(c.get('actor'), tenantId, scope.id);
         const vertical = await verticalForScope(c, scope);
-        const tables = vertical ? await vertical.exportScope(scope.id) : dump.tables;
         // Store tables are opaque and stay unsealed. The platform reads them from the store script
         // (#2207); a store it cannot name or reach refuses the backup rather than omitting it.
-        const stores = (await exportPlatformStores(c, scope)) ?? dump.stores;
-        // Seal classified payloads per subject on the way in (#37). This copy is full-fidelity
-        // and the platform keeps it, which is precisely why an erasure could never reach it: a
-        // redaction fixes the live scope and does nothing to the object already in R2. Sealed
-        // here, destroying one subject's key reaches backwards into every copy already taken.
-        // Restores open it again (`restoreFromBackup`) — except for subjects shredded in the
-        // meantime, which is the mechanism working rather than the copy being damaged.
-        const sealed = await sealDump(tables, sealerFor(c, tenantId, scope.id));
-        return store.put({ vertical: scope.vertical, dump: { ...dump, tables: sealed, stores } });
+        const stores = (await exportPlatformStores(c, scope)) ?? header.stores;
+        const backup = backupStage(store.begin({ vertical: scope.vertical, header: { ...header, stores } }), sealerFor(c, tenantId, scope.id));
+        // #2839: from a vertical, the data moves into the store a page at a time, as a paged copy
+        // moves it into another scope (#2450): captured, so a scope taking writes meanwhile is still
+        // copied as it was at one moment, and never held whole here. A deployment that predates
+        // paging answers whole, and that is stored as one entry, as the co-located host's tables are.
+        const moved = vertical
+            ? (await transferScope(vertical, backup.dest, { from: scope.id }, { retry: retryTransient, stamp: false, alwaysStage: true })).dump
+            : hostTables;
+        if (Array.isArray(moved))
+            await backup.dest.stageScopePage(scope.id, ulid(), 0, moved);
+        try {
+            return await backup.commit();
+        }
+        catch (e) {
+            await backup.discard();
+            throw e;
+        }
+    };
+    /**
+     * A backup being written, as the destination of a paged copy (#2839): each page and each batch of
+     * captured changes the copy stages becomes one entry, sealed per subject on the way in (#37).
+     * This copy is full-fidelity and the platform keeps it, which is precisely why an erasure could
+     * never reach it: a redaction fixes the live scope and does nothing to the object already in R2.
+     * Sealed here, destroying one subject's key reaches backwards into every copy already taken.
+     * Restores open it again, except for subjects shredded in the meantime, which is the mechanism
+     * working rather than the copy being damaged.
+     *
+     * A copy that starts again discards its stage and stages anew, so the backup is the stage written
+     * last.
+     */
+    const backupStage = (writer, sealer) => {
+        let last = { stageId: '', entries: 0, tables: new Set() };
+        const took = (stageId, seq, tables) => {
+            if (stageId !== last.stageId)
+                last = { stageId, entries: 0, tables: new Set() };
+            last.entries = Math.max(last.entries, seq + 1);
+            for (const t of tables)
+                last.tables.add(t.name);
+        };
+        return {
+            dest: {
+                stageScopePage: async (_, stageId, seq, tables) => {
+                    await writer.put(stageId, seq, { kind: 'page', tables: await sealDump(tables, sealer) });
+                    took(stageId, seq, tables);
+                    return { staged: true };
+                },
+                stageScopeChanges: async (_, stageId, seq, tables) => {
+                    await writer.put(stageId, seq, { kind: 'changes', tables: await sealDump(tables, sealer) });
+                    took(stageId, seq, tables);
+                    return { staged: true };
+                },
+                discardStagedScope: (_, stageId) => writer.discard(stageId),
+            },
+            commit: () => writer.commit({ stageId: last.stageId, entries: last.entries, tables: last.tables.size }),
+            discard: () => writer.discard(last.stageId),
+        };
     };
     // The copies held for one scope — metadata only, so listing a reaped scope's backups
     // is cheap and hands out no bytes. Readable AFTER the reap (that is the point): the
@@ -5377,9 +5474,11 @@ export function createControlPlaneApi(options) {
             return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await options.scopeBackups.list({ tenantId, scopeId }));
     });
-    // One backup's DUMP — the restore source. Staff-only like the export it came from
-    // (not in BUILDER_ROUTES), and full-fidelity, so it is the same governed-pull posture:
-    // K-3 cross-checked above, and `POST …/restore` is where it goes back.
+    // One backup's DUMP. Staff-only like the export it came from (not in BUILDER_ROUTES), and
+    // full-fidelity, so it is the same governed-pull posture: K-3 cross-checked above. Only a
+    // backup stored in one entry is served whole (#2839). One stored in several (more pages, or
+    // writes caught while it was taken) is not a dump until a deployment applies them in order,
+    // so it is answered 413 and `POST …/backups/:capturedAt/restore` loads it back.
     app.get('/tenants/:tenantId/scopes/:scopeId/backups/:capturedAt', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -5389,16 +5488,20 @@ export function createControlPlaneApi(options) {
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
             return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
-        const dump = await options.scopeBackups.get({ tenantId, scopeId, capturedAt });
-        if (!dump)
+        const held = await options.scopeBackups.get({ tenantId, scopeId, capturedAt });
+        if (!held)
             return refuse(c, 'not_found', `no backup for scope ${scopeId} at ${capturedAt}`);
+        if (held.entries > 1) {
+            return refuseStatus(c, 413, `backup ${capturedAt} of scope ${scopeId} is stored in ${held.entries} entries (its pages, and any writes caught while it was taken), which only a restore applies; restore it with POST /tenants/${tenantId}/scopes/${scopeId}/backups/${capturedAt}/restore`);
+        }
+        const { tables } = await held.entry(0);
         // Unseal on the way out (#37). The bytes in the store stay sealed — this is the
         // authorized read opening them with the keys the platform holds. A subject shredded
         // since the copy was taken opens to a null payload, which is exactly the erasure
         // working: the ciphertext never left the object, and nothing turns it back into a
         // person. A dump taken before sealing existed passes through untouched.
-        const opened = await openDump(dump.tables, sealerFor(c, tenantId, scopeId));
-        return c.json({ ...dump, tables: opened });
+        const opened = await openDump(mergeDumpPages([tables]), sealerFor(c, tenantId, scopeId));
+        return c.json({ ...held.header, tables: opened });
     });
     // Take a backup WITHOUT reaping — the standalone copy (a pre-migration checkpoint, an
     // export-to-keep). The reap route below takes its own; this is the same act made
@@ -5458,6 +5561,15 @@ export function createControlPlaneApi(options) {
         // version that declares none is not asked. One that cannot be resolved while a driver is
         // registered refuses (503): the key must not be destroyed while a store may hold the subject.
         const reach = await platformStoresOf(c, scope, running);
+        // A store whose driver cannot erase a subject yet would answer `{ erased: 0 }` while it still
+        // holds them. Refused before anything is erased, so the key is kept and a retry can converge.
+        const unerasable = reach?.stores.find((store) => {
+            const registration = (options.storeDrivers ?? STORE_DRIVERS).find((k) => k.driver === store.driver);
+            return registration !== undefined && !storeDriverErasesSubjects(registration);
+        });
+        if (unerasable) {
+            throw new ControlPlaneError(501, `scope ${scopeId}'s store '${unerasable.binding}' runs driver '${unerasable.driver}', which cannot erase a subject yet; nothing was erased`);
+        }
         /**
          * L19: a bind, promote, rollback or serving re-upload that lands while the stores are erased
          * would run a version whose stores this erasure did not reach. Both arms take one atomic claim
@@ -6232,32 +6344,135 @@ export function createControlPlaneApi(options) {
             // keyed by (scope, subject), so a copy of scope A landing in scope B — a backout onto
             // a different scope, a world loaded sideways — must be opened with A's keys. Using
             // the destination's would find no key, null every payload, and call it a restore.
-            const origin = { tenantId: tenantIdSchema.parse(dump.tenantId), scopeId: scopeIdSchema.parse(dump.scopeId) };
-            const tables = await openDump(dump.tables, sealerFor(c, origin.tenantId, origin.scopeId));
-            const vertical = await verticalForScope(c, scope);
+            const tables = await openDump(dump.tables, sealerFor(c, tenantIdSchema.parse(dump.tenantId), scopeIdSchema.parse(dump.scopeId)));
+            return c.json(await loadIntoScope(c, scope, { header: dump, tables, sourceHint }));
+        }
+        catch (e) {
+            return restoreFailed(c, scope, e);
+        }
+    });
+    // Restore a held backup into its scope, read from the store here rather than handed in (#2839):
+    // a backup stored in parts is staged at the deployment one entry at a time, opened with the
+    // backup's own provenance, and loaded from the stage, so no call holds the whole backup. One
+    // stored whole loads as `POST …/restore` loads a dump, through the same path. Staff-only, as the
+    // backup routes are (not in TENANT_ROUTES or BUILDER_ROUTES).
+    app.post('/tenants/:tenantId/scopes/:scopeId/backups/:capturedAt/restore', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const capturedAt = c.req.param('capturedAt');
+        const store = options.scopeBackups;
+        if (!store)
+            return refuseStatus(c, 501, 'no backup target configured');
+        const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
+        const held = await store.get({ tenantId, scopeId, capturedAt });
+        if (!held)
+            return refuse(c, 'not_found', `no backup for scope ${scopeId} at ${capturedAt}`);
+        const { header } = held;
+        if (options.platformScopeStores) {
+            try {
+                await refuseUndeclaredDumpStores(c, scope, header.stores);
+            }
+            catch (e) {
+                if (e instanceof ControlPlaneError)
+                    return relayRefusal(c, e);
+                throw e;
+            }
+        }
+        const sealer = sealerFor(c, tenantIdSchema.parse(header.tenantId), scopeIdSchema.parse(header.scopeId));
+        try {
+            if (held.entries === 1) {
+                const { tables } = await held.entry(0);
+                if (tables.length === 0) {
+                    return refuseStatus(c, 422, 'restore refused: the backup has no tables — not a scope dump');
+                }
+                return c.json(await loadIntoScope(c, scope, { header, tables: await openDump(mergeDumpPages([tables]), sealer) }));
+            }
+            // The host judges the roles the backup seats or defines before anything is replaced (#2555), and
+            // records the tables it restores. So it is handed every table's schema and the role tables' rows,
+            // gathered while the entries are staged: its whole part of a load into a deployment, whose
+            // placeholder is not the scope's store.
+            const stage = async (vertical) => {
+                const stageId = ulid();
+                const judged = rolesJudgedOf();
+                try {
+                    for (let index = 0; index < held.entries; index++) {
+                        const entry = await held.entry(index);
+                        let staged;
+                        if (entry.kind === 'page') {
+                            const tables = await openDump(entry.tables, sealer);
+                            judged.page(tables);
+                            staged = await retryTransient(() => vertical.stageScopePage(scopeId, stageId, index, tables));
+                        }
+                        else {
+                            const tables = await openDump(entry.tables, sealer);
+                            judged.changes(tables);
+                            staged = await retryTransient(() => vertical.stageScopeChanges(scopeId, stageId, index, tables));
+                        }
+                        if (staged === 'predates') {
+                            throw new ControlPlaneError(409, `backup ${capturedAt} is stored in ${held.entries} parts, and the deployment scope ${scopeId} runs cannot load one in parts; push a newer version of the vertical and restore again`);
+                        }
+                    }
+                }
+                catch (e) {
+                    await abandonCopy({ dest: vertical }, { from: scopeId, into: scopeId, stageId });
+                    throw e;
+                }
+                return { dump: { stageId }, tables: judged.tables() };
+            };
+            return c.json(await loadIntoScope(c, scope, { header, tables: [], stage }));
+        }
+        catch (e) {
+            return restoreFailed(c, scope, e);
+        }
+    });
+    /**
+     * Load a dump into an existing scope: the one path `POST …/restore` and a backup's restore share,
+     * so both write the same audit row, judge the same roles and stores, replay the same erasures and
+     * clear the same receipt. `tables` are opened (#37). `stage`, for a backup stored in several
+     * entries (#2839), stages it at the scope's deployment, which then loads the stage, and answers
+     * the tables the host's audited restore judges and records in place of `tables`. Those are every
+     * table's schema with the role rows only, so after a staged restore the host's placeholder holds
+     * no data, and its `_substrat_migrations` and `_substrat_meta` journals are empty, where a whole
+     * dump's restore leaves them full. The scope's own journals are the deployment's.
+     */
+    const loadIntoScope = async (c, scope, input) => {
+        const actor = c.get('actor');
+        const tenantId = tenantIdSchema.parse(scope.tenantId);
+        const scopeId = scopeIdSchema.parse(scope.id);
+        const { header, sourceHint } = input;
+        const origin = scopeIdSchema.parse(header.scopeId);
+        const vertical = await verticalForScope(c, scope);
+        if (input.stage && !vertical) {
+            throw new ControlPlaneError(409, `scope ${scopeId} has no deployment to load a backup stored in parts into`);
+        }
+        // #2185: cleared before the load as well as after it (below): a step after the load can still
+        // throw (the deployment's half, the re-assert), and the data that landed may predate a reconcile.
+        await c.var.admin.markScopeProvisioned(actor, tenantId, scopeId, null);
+        const staged = input.stage && vertical ? await input.stage(vertical) : undefined;
+        const tables = staged?.tables ?? input.tables;
+        try {
             const storesCaller = options.platformScopeStores;
-            const landing = { ...dump, tables, stores: storesCaller && vertical ? [] : dump.stores };
-            // #2185: cleared before the load as well as after it (below): a step after the load can still
-            // throw (the deployment's half, the re-assert), and the data that landed may predate a reconcile.
-            await c.var.admin.markScopeProvisioned(actor, tenantId, scopeId, null);
+            const landing = { ...header, tables, stores: storesCaller && vertical ? [] : header.stores };
             const hostReplay = await c.var.host.restoreScope(actor, tenantId, scopeId, landing, sourceHint ? { sourceScopeId: sourceHint } : undefined);
-            if (storesCaller && vertical && scope.vertical && dump.stores.length > 0) {
+            if (storesCaller && vertical && scope.vertical && header.stores.length > 0) {
                 await storesCaller.importStores({
                     tenantId,
                     scopeId,
                     vertical: scope.vertical,
-                    stores: dump.stores,
+                    stores: header.stores,
                 });
             }
             const platformReplay = storesCaller && scope.vertical
-                ? await replayPlatformStoreErasures(c, scope, sourceHint ?? origin.scopeId)
+                ? await replayPlatformStoreErasures(c, scope, sourceHint ?? origin)
                 : undefined;
             const replays = [hostReplay, platformReplay].filter((r) => !!r);
             // #1742: the recorded OFF positions ride the restore, so the deployment switches them
             // off in the replay's own event — its own sweeper cannot land in between.
             const restored = vertical
-                ? await restoreCarryingSwitches(actor, vertical, tenantId, scopeId, tables, {
-                    scopeId: sourceHint ?? origin.scopeId,
+                ? await restoreCarryingSwitches(actor, vertical, tenantId, scopeId, staged?.dump ?? tables, {
+                    scopeId: sourceHint ?? origin,
                     exact: false,
                 })
                 : undefined;
@@ -6271,31 +6486,37 @@ export function createControlPlaneApi(options) {
             // finished: the install reads as not reconciled, and the sweep's next pass reconciles it.
             // Again here, after the load, for a sweep reconcile that wrote the receipt while it ran.
             await c.var.admin.markScopeProvisioned(actor, tenantId, scopeId, null);
-            return c.json({
+            return {
                 restored: scopeId,
                 tables: tables.length,
                 // #2820: what the deployment serving the scope did with the dump's own indexes and triggers.
                 ...(restored ? { moduleObjects: restored.moduleObjects } : {}),
                 ...storeReplayFields(replays),
-            });
+            };
         }
         catch (e) {
-            // #2185: and once more on the way out of a failure, for a sweep reconcile that wrote the
-            // receipt between the clear above and the throw. Clearing is always safe (at worst one more
-            // reconcile); a clear that fails here must not hide the restore's own error.
-            await c.var.admin.markScopeProvisioned(actor, tenantId, scopeId, null).catch(() => undefined);
-            if (e instanceof ControlPlaneError) {
-                return relayRefusal(c, e);
-            }
-            // A restore throw is driven by the caller-supplied dump (a shape the target cannot
-            // load, a DDL the engine rejects), so DISCLOSE it as an actionable 422 rather than
-            // collapsing to the generic 500 `internal error` mapError would produce (#321,
-            // secondary obs #2). The route is staff- or own-tenant-gated and the detail is about the
-            // dump the caller sent, not another tenant's state.
-            const detail = e instanceof Error ? e.message : String(e);
-            return refuseStatus(c, 422, 'restore failed — the backup could not be loaded', { detail });
+            // A stage the refused load left at the deployment goes now rather than waiting for a wipe.
+            if (staged && vertical)
+                await abandonCopy({ dest: vertical }, { from: scopeId, into: scopeId, stageId: staged.dump.stageId });
+            throw e;
         }
-    });
+    };
+    /** How a refused or failed restore answers, on either route. */
+    const restoreFailed = async (c, scope, e) => {
+        // #2185: and once more on the way out of a failure, for a sweep reconcile that wrote the
+        // receipt between the clear before the load and the throw. Clearing is always safe (at worst
+        // one more reconcile); a clear that fails here must not hide the restore's own error.
+        await c.var.admin.markScopeProvisioned(c.get('actor'), tenantIdSchema.parse(scope.tenantId), scopeIdSchema.parse(scope.id), null).catch(() => undefined);
+        if (e instanceof ControlPlaneError) {
+            return relayRefusal(c, e);
+        }
+        // A restore throw is driven by the dump (a shape the target cannot load, a DDL the engine
+        // rejects), so DISCLOSE it as an actionable 422 rather than collapsing to the generic 500
+        // `internal error` mapError would produce (#321, secondary obs #2). The routes are staff- or
+        // own-tenant-gated and the detail is about the dump, not another tenant's state.
+        const detail = e instanceof Error ? e.message : String(e);
+        return refuseStatus(c, 422, 'restore failed — the backup could not be loaded', { detail });
+    };
     // #1236: when this scope's migrations actually ran — the schema-change history
     // whose instants `_substrat_migrations.applied_at` has held all along with no
     // reader. Read through the vertical that holds the scope's data when one
@@ -7322,6 +7543,7 @@ export function createControlPlaneApi(options) {
             return refuse(c, 'forbidden', 'forbidden');
         }
         input.verticalSlug = slug;
+        let scopeStores = [];
         // `manifestJson` is a string the schema cannot look inside, and every reader parses it
         // with `storedDeployManifest` and 500s on a row it refuses: the per-version reads below
         // (registry, schedules, flow, model, assets), the serving-upload rebuild that promote
@@ -7367,7 +7589,12 @@ export function createControlPlaneApi(options) {
             const connectorProblems = pushedConnectorProblems(checked.data);
             if (connectorProblems.length > 0)
                 return refuseManifest({ path: ['connectors'], message: connectorProblems.join('; ') });
+            scopeStores = checked.data.scopeStores;
         }
+        // #2210: publishing records the version's store bindings for the whole vertical's lifecycle
+        // (backup, wipe, erasure, the meter), so its store scripts are put in place first, as a push
+        // does: a driver with no approved release refuses here, and nothing is published.
+        await ensureScopeStoresOf(c.get('actor'), 'deploy', slug, scopeStores, async () => (await ownerOf(c.get('actor'), slug)) ?? null);
         await c.var.admin.publishVersion(c.get('actor'), input);
         const version = await c.var.admin.getVersion(c.get('actor'), input.id, slug);
         return c.json(version, 201);
@@ -7425,7 +7652,11 @@ export function createControlPlaneApi(options) {
             base: base ?? null,
             digest: await promoteReviewDigest(baseVersion && { ...baseVersion, migrations: baseline ?? null }, { ...incomingVersion, migrations: incoming }),
         };
-        return c.json({ migrations: incoming === null ? null : migrationsOnTop(incoming, baseline), review });
+        // #2351: whether the incoming set was read from the version's bundle, or only declared by its
+        // push (pushed before the read, or a bundle that exposes no registrations). A version storing none was
+        // compared with nothing, whatever it recorded.
+        const readFromBundle = incoming !== null && !!(await c.var.admin.versionMigrationsExtracted?.(c.get('actor'), slug, incomingId));
+        return c.json({ migrations: incoming === null ? null : migrationsOnTop(incoming, baseline), review, readFromBundle });
     });
     // The emitted entity model (#1214) one version ships: entities, field schemas, parent
     // edges, declared lifecycles — read out of the same retained manifest as the registry
@@ -7665,6 +7896,14 @@ export function createControlPlaneApi(options) {
     const ensureScopeStoresOf = async (actor, operation, slug, stores, owner) => {
         if (stores.length === 0)
             return;
+        // D-67: a driver whose registration names its verticals serves those only, refused before any
+        // hold is taken or anything is uploaded.
+        for (const store of stores) {
+            const registration = (options.storeDrivers ?? STORE_DRIVERS).find((k) => k.driver === store.driver);
+            if (registration && !storeDriverServesVertical(registration, slug)) {
+                throw new ControlPlaneError(403, `${operation} refused: scope store driver '${store.driver}' does not serve vertical '${slug}'`);
+            }
+        }
         const holder = ulid();
         const drivers = [...new Set(stores.map((store) => store.driver))].sort();
         const held = [];
@@ -7752,6 +7991,59 @@ export function createControlPlaneApi(options) {
             recordFailure({ actor, operation: 'deploy.wire-record', vertical, version: versionId, message: `the capability record of ${deploymentRef} was not written` }, error);
         }
     };
+    const readBundleMigrations = async (bundle, declared) => {
+        if (!options.extractMigrations)
+            return { kind: 'unmarked' };
+        let registered;
+        try {
+            registered = await options.extractMigrations(bundle);
+        }
+        catch (e) {
+            if (e instanceof MigrationLoaderUnavailable)
+                return { kind: 'unavailable', message: e.message };
+            if (!(e instanceof MigrationExtractionError))
+                throw e;
+            return { kind: 'failed', message: e.message };
+        }
+        if (!registered)
+            return { kind: 'unmarked' };
+        const problem = declared && extractedMigrationsProblem(declared, registered);
+        if (problem)
+            return { kind: 'differs', message: extractedMigrationsRefusal(problem) };
+        return { kind: 'read', digest: await extractedMigrationsDigest(registered) };
+    };
+    /**
+     * #2351: a version pushed before its bundle was read is read once, at its first promote, from
+     * its archive script. Same set: recorded, and the promote goes on. Another set: the refusal,
+     * before anything moves. No registrations, or a bundle that cannot be read here (it was
+     * accepted at push, before this read existed): the promote goes on as it did, unrecorded, so such
+     * a version is read again at every promote. A version storing no migrations has nothing to
+     * compare, and one that is not admitted is refused by the promote without a read.
+     */
+    const bundleMigrationsRefusal = async (admin, actor, slug, versionId) => {
+        if (!options.extractMigrations || !options.fetchVerticalModules || !admin.versionMigrationsExtracted || !admin.recordMigrationsExtracted) {
+            return null;
+        }
+        const [extracted, declared, version, manifestJson] = await Promise.all([
+            admin.versionMigrationsExtracted(actor, slug, versionId),
+            admin.versionMigrations(actor, slug, versionId),
+            admin.getVersion(actor, versionId, slug),
+            admin.versionManifest(actor, slug, versionId),
+        ]);
+        if (extracted !== null || declared === null || version?.admission !== 'admitted' || !version.deploymentRef || !manifestJson)
+            return null;
+        const manifest = storedDeployManifest.parse(JSON.parse(manifestJson));
+        // An archive that cannot be read back is the serve's to report, after the promote, as it is today.
+        const modules = await options.fetchVerticalModules(version.deploymentRef).catch(() => null);
+        if (!modules)
+            return null;
+        const read = await readBundleMigrations({ entry: manifest.entry, compatibilityDate: manifest.compatibilityDate, compatibilityFlags: manifest.compatibilityFlags, modules }, declared);
+        if (read.kind === 'differs')
+            return read.message;
+        if (read.kind === 'read')
+            await admin.recordMigrationsExtracted(actor, slug, versionId, read.digest);
+        return null;
+    };
     /**
      * Serve a version IN PLACE (#286): upload its bundle onto the vertical's ONE stable
      * serving script, where every scope's data DO lives — this is the step that makes a
@@ -8144,6 +8436,10 @@ export function createControlPlaneApi(options) {
         const answer = roleStateAnswer(roles, confinedTenant(p));
         if (answer)
             return refuseStatus(c, answer.status, answer.message, answer.extra);
+        // #2351: a version whose bundle was never read is read now, before anything moves.
+        const bundleRefusal = await bundleMigrationsRefusal(c.var.admin, c.get('actor'), slug, versionId);
+        if (bundleRefusal)
+            return refuseStatus(c, 422, bundleRefusal);
         // The blast-radius moment: refuses a changed digest without the acknowledgement,
         // and refuses a non-admitted version. Both are enforced below the seam and
         // surface as a 4xx through mapError, not a 500.
@@ -8592,6 +8888,20 @@ export function createControlPlaneApi(options) {
         const sweeper = platformSweeperDecision(manifest, { entry: manifest.entry, modules });
         if ('refuse' in sweeper)
             return refuseStatus(c, 422, sweeper.refuse);
+        // #2351: the migrations the bundle registers, read before anything is uploaded. Where the
+        // manifest carries migrations they must be the registered ones, or the push is refused, and
+        // so is a bundle that cannot be evaluated or does not settle: the stored set is then provably
+        // what the version runs. A declared `[]` is a set like any other: the bundle must register
+        // none. A loader that fails is the platform's, so that push answers 503 and may be retried. A
+        // manifest that leaves the field off (over the caps a manifest carries) stores none, so nothing
+        // is gated: its push is accepted however the read went, and records the digest of what was
+        // read, if anything was.
+        const read = await readBundleMigrations({ entry: manifest.entry, compatibilityDate: manifest.compatibilityDate, compatibilityFlags: manifest.compatibilityFlags, modules }, manifest.migrations ?? null);
+        if (read.kind === 'differs' || (read.kind === 'failed' && manifest.migrations))
+            return refuseStatus(c, 422, read.message);
+        if (read.kind === 'unavailable' && manifest.migrations)
+            return refuseStatus(c, 503, read.message);
+        const migrationsExtracted = read.kind === 'read' ? read.digest : null;
         // Mint the version id first: the deploymentRef (the dispatch script name) is keyed
         // on it, so it is CF-valid and unique per version.
         const id = ulid();
@@ -8709,6 +9019,8 @@ export function createControlPlaneApi(options) {
             manifestJson: JSON.stringify({ ...manifest, platformSweeper: sweeper.supply }),
         });
         await recordWireUpload(c.var.admin, c.get('actor'), id, wire);
+        if (migrationsExtracted)
+            await c.var.admin.recordMigrationsExtracted?.(c.get('actor'), slug, id, migrationsExtracted);
         // Same spirit as the permission-surface gate, advisory tier: when the push DECLARES
         // surfaces, name any surface that hostnames are still bound to but the declaration
         // dropped — the URL keeps resolving (routing never keys on the declaration), it just
@@ -10869,6 +11181,32 @@ export function createControlPlaneApi(options) {
         });
         return c.json(pageOf(entries, filter.limit, (e) => e.id));
     });
+    // -- builder turns: one summary per builder-studio turn, every team -------------
+    // Staff only, and stated here rather than left to the allowlists' default-deny: a
+    // summary names a team and a project, and the turn behind it carries what someone
+    // typed into the studio. The builder answers both; this relays and re-parses.
+    app.get('/builder-turns', async (c) => {
+        if (!staffCaller(c))
+            return refuse(c, 'forbidden', 'forbidden');
+        if (!options.builderTurns)
+            return refuseStatus(c, 501, 'the builder studio is not configured');
+        const url = new URL(c.req.url);
+        const forwarded = new URLSearchParams();
+        for (const key of ['tenantId', 'projectId', 'outcome', 'redGate', 'troubled', 'since', 'limit', 'cursor']) {
+            const value = url.searchParams.get(key);
+            if (value)
+                forwarded.set(key, value);
+        }
+        return c.json(await options.builderTurns.list(forwarded));
+    });
+    app.get('/builder-turns/:turnId', async (c) => {
+        if (!staffCaller(c))
+            return refuse(c, 'forbidden', 'forbidden');
+        if (!options.builderTurns)
+            return refuseStatus(c, 501, 'the builder studio is not configured');
+        const turn = await options.builderTurns.get(c.req.param('turnId'));
+        return turn ? c.json(turn) : refuse(c, 'not_found', 'no such turn');
+    });
     // -- sweep runs (#1232): the durable record of what a sweep pass touched -------
     // Staff read fleet-wide (the console's later view); a builder's tenant is forced
     // from the principal, the /ops-failures posture exactly.