@substrat-run/control-plane-api 0.176.0 → 0.178.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,11 +70,12 @@ 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';
 import { STORAGE_PAGE_DEFAULT, STORAGE_PAGE_MAX, readStoragePage } from './storage-meter.js';
-import { queryLakeEvents } from './lake-gateway.js';
+import { queryLakeEvents, teamWindowRefusal } from './lake-gateway.js';
 import { LakeQueryError } from './r2-sql-engine.js';
 import { isCustomHostname, validateBindableHostname, } from './custom-hostnames.js';
 import { isSocialRelayVertical, reconcileScopeSocialRelay, relayHostnames, } from './social-relay.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
@@ -730,6 +780,8 @@ const TENANT_ROUTES = [
     // grant (`tenantGrantableEntitlement`): the pin alone would let it grant itself any.
     { method: 'PUT', re: /\/tenants\/[^/]+\/entitlements\/[^/]+$/, pin: 'path' },
     { method: 'GET', re: /\/tenants\/[^/]+\/cross-vertical\/edges$/, pin: 'path' },
+    // #1334: the team's own lake events. The handler adds the window rule for this credential.
+    { method: 'GET', re: /\/tenants\/[^/]+\/lake\/events$/, pin: 'path' },
     // Findings (#1748): the tenant's inbox, its verdicts and its suppress rules. The dashboard
     // checks WHO inside the tenant may read or act (its findings permissions) before calling.
     { method: 'PUT', re: /\/tenants\/[^/]+\/findings\/[^/]+\/status$/, pin: 'path' },
@@ -964,7 +1016,7 @@ export function createControlPlaneApi(options) {
     /** `substrat.wipe` on each declared store, before the scope's own bytes go. */
     const wipePlatformStores = async (c, scope) => (await platformStoresWipe(c, scope))();
     /**
-     * `substrat.export` on each store the lifecycle reaches, for a backup, a full pull or a fork.
+     * A dump in pages (`substrat.export-page`) of each store the lifecycle reaches, for a backup, a full pull or a fork.
      *
      * A dump is only worth taking if it restores, and a restore imports only what the destination's
      * version declares (L8). So a binding only an earlier version declared (#2286) is left out of the
@@ -1249,6 +1301,9 @@ export function createControlPlaneApi(options) {
         { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/model$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/concept$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/schedules$/ },
+        // The scope-store drivers one vertical may use (#2813), so a push judges its stores as the
+        // upload will. `?vertical=` required; the answer names no other vertical.
+        { method: 'GET', re: /\/store-drivers$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/channels$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/channels\/[^/]+\/history$/ },
         { method: 'POST', re: /\/verticals\/[^/]+\/channels\/[^/]+\/promote$/ },
@@ -5346,20 +5401,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 +5479,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 +5493,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 +5566,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
@@ -5900,9 +6017,10 @@ export function createControlPlaneApi(options) {
     // closed `.strict()` list with no tenant in it, and a row of any other tenant fails the
     // read whole. Envelope only — no payload until erasure reaches the lake.
     //
-    // Staff only, by default-deny: on neither BUILDER_ROUTES nor TENANT_ROUTES. A tenant's
-    // own credential reaching this is a separate decision, with a dashboard call site and a
-    // member permission in front of it.
+    // Staff, and a team's own credential (TENANT_ROUTES, path-pinned). The dashboard checks
+    // `dashboard:read-event-lake` before it calls. A team's read must name a window of at most
+    // `LAKE_TEAM_WINDOW_DAYS` (`teamWindowRefusal`): nothing below the gateway prunes by tenant,
+    // so the window is what bounds the scan. Builders stay refused (not in BUILDER_ROUTES).
     //
     // K-24: the access row is written AFTER the engine answers and BEFORE anything is
     // returned, and a failed write fails the request — rows whose disclosure went unrecorded
@@ -5923,6 +6041,11 @@ export function createControlPlaneApi(options) {
                 issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
             });
         }
+        if (c.get('principal').kind === 'tenant') {
+            const refusal = teamWindowRefusal(parsed.data, Date.now());
+            if (refusal)
+                return refuse(c, 'validation_failed', refusal);
+        }
         let page;
         try {
             page = await queryLakeEvents(options.lakeQuery, tenantId, parsed.data);
@@ -6232,32 +6355,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 +6497,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 +7554,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,8 +7600,16 @@ export function createControlPlaneApi(options) {
             const connectorProblems = pushedConnectorProblems(checked.data);
             if (connectorProblems.length > 0)
                 return refuseManifest({ path: ['connectors'], message: connectorProblems.join('; ') });
-        }
-        await c.var.admin.publishVersion(c.get('actor'), input);
+            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. The publish is
+        // made under the push's shared hold (#2816), so a rollout walks this vertical or waits for it.
+        await ensureScopeStoresOf(c.get('actor'), 'deploy', slug, scopeStores, async () => (await ownerOf(c.get('actor'), slug)) ?? null, async (renew) => {
+            await renew();
+            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 +7666,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
@@ -7661,57 +7906,78 @@ export function createControlPlaneApi(options) {
      * (#559), then rethrown, so the push or serve answers it and the vertical upload never runs.
      * The row carries the vertical's owner, so it shows in that tenant's failure view; the serve
      * path reads the owner only once something has failed.
+     *
+     * `then` runs after the uploads, still under the shared holds (#2816): a push or a publish passes
+     * the step that records the version's store declarations, so a rollout either finds the vertical
+     * in what it walks or is refused until that step is done. `renew` renews every hold, and refuses
+     * (409) once one has lapsed; `then` calls it right before it records. A failure in `then` is not
+     * recorded here: it is the caller's to answer.
      */
-    const ensureScopeStoresOf = async (actor, operation, slug, stores, owner) => {
+    const ensureScopeStoresOf = async (actor, operation, slug, stores, owner, then = async () => undefined) => {
         if (stores.length === 0)
-            return;
+            return then(async () => undefined);
+        // 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 = [];
+        const renewHolds = async (when) => {
+            for (const each of held) {
+                if (!(await host.admin.holdStoreDriver(actor, { driver: each, holder, mode: 'shared', ttlMs: PUSH_HOLD_TTL_MS, renew: true }))) {
+                    throw new ControlPlaneError(409, `${operation} refused: the hold on scope store driver '${each}' lapsed ${when}; try again`);
+                }
+            }
+        };
+        const renew = () => renewHolds('during the upload');
         try {
-            if (!options.ensureScopeStores) {
-                throw new ControlPlaneError(501, `${operation} refused: '${slug}' declares a scope store and this control plane uploads no store script`);
-            }
-            // A shared hold on each driver (#2300): a rollout holds it exclusively, and a rebuild that read
-            // a script's release before a rollout moved it would upload the old release back over it.
-            // Neither the refusal nor anything else here names another vertical: a push answers its own.
-            for (const driver of drivers) {
-                if (!(await host.admin.holdStoreDriver(actor, { driver, holder, mode: 'shared', ttlMs: PUSH_HOLD_TTL_MS }))) {
-                    throw new ControlPlaneError(409, `${operation} refused: scope store driver '${driver}' is being rolled out; try again in a few minutes`);
+            try {
+                if (!options.ensureScopeStores) {
+                    throw new ControlPlaneError(501, `${operation} refused: '${slug}' declares a scope store and this control plane uploads no store script`);
                 }
-                held.push(driver);
-            }
-            const loadRelease = options.storeReleases
-                ? storedReleaseLoader({ admin: host.admin, actor, bytes: options.storeReleases.bytes })
-                : async () => undefined;
-            // One driver at a time, each renewing every hold first: a push whose uploads outlast a hold
-            // stops (409) rather than upload after a rollout could have taken the driver.
-            for (const driver of drivers) {
-                for (const each of held) {
-                    if (!(await host.admin.holdStoreDriver(actor, { driver: each, holder, mode: 'shared', ttlMs: PUSH_HOLD_TTL_MS, renew: true }))) {
-                        throw new ControlPlaneError(409, `${operation} refused: the hold on scope store driver '${each}' lapsed during the upload; try again`);
+                // A shared hold on each driver (#2300): a rollout holds it exclusively, and a rebuild that read
+                // a script's release before a rollout moved it would upload the old release back over it.
+                // Neither the refusal nor anything else here names another vertical: a push answers its own.
+                for (const driver of drivers) {
+                    if (!(await host.admin.holdStoreDriver(actor, { driver, holder, mode: 'shared', ttlMs: PUSH_HOLD_TTL_MS }))) {
+                        throw new ControlPlaneError(409, `${operation} refused: scope store driver '${driver}' is being rolled out; try again in a few minutes`);
                     }
+                    held.push(driver);
+                }
+                const loadRelease = options.storeReleases
+                    ? storedReleaseLoader({ admin: host.admin, actor, bytes: options.storeReleases.bytes })
+                    : async () => undefined;
+                // One driver at a time, each renewing every hold first: a push whose uploads outlast a hold
+                // stops (409) rather than upload after a rollout could have taken the driver.
+                for (const driver of drivers) {
+                    await renew();
+                    const registration = (options.storeDrivers ?? STORE_DRIVERS).find((k) => k.driver === driver);
+                    if (!registration)
+                        throw new ControlPlaneError(403, `scope store driver '${driver}' is not registered`);
+                    // Read under the shared hold (D-65): a revoke takes the driver exclusively, so one written
+                    // before this read is seen, and none is written until this upload is done.
+                    const approvals = await readStoreDriverApprovals(host.admin, actor, registration);
+                    await options.ensureScopeStores({ vertical: slug, stores: stores.filter((store) => store.driver === driver), loadRelease, approvals });
                 }
-                const registration = (options.storeDrivers ?? STORE_DRIVERS).find((k) => k.driver === driver);
-                if (!registration)
-                    throw new ControlPlaneError(403, `scope store driver '${driver}' is not registered`);
-                // Read under the shared hold (D-65): a revoke takes the driver exclusively, so one written
-                // before this read is seen, and none is written until this upload is done.
-                const approvals = await readStoreDriverApprovals(host.admin, actor, registration);
-                await options.ensureScopeStores({ vertical: slug, stores: stores.filter((store) => store.driver === driver), loadRelease, approvals });
             }
-        }
-        catch (e) {
-            recordFailure({
-                actor,
-                operation: `${operation}.store-upload`,
-                stage: 'store-upload',
-                vertical: slug,
-                tenantId: await owner().catch(() => null),
-                status: e instanceof ControlPlaneError ? e.status : 502,
-                message: e instanceof Error ? e.message : String(e),
-            }, e);
-            throw e;
+            catch (e) {
+                recordFailure({
+                    actor,
+                    operation: `${operation}.store-upload`,
+                    stage: 'store-upload',
+                    vertical: slug,
+                    tenantId: await owner().catch(() => null),
+                    status: e instanceof ControlPlaneError ? e.status : 502,
+                    message: e instanceof Error ? e.message : String(e),
+                }, e);
+                throw e;
+            }
+            return await then(() => renewHolds('before the version was recorded'));
         }
         finally {
             for (const driver of held)
@@ -7752,6 +8018,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 +8463,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,123 +8915,150 @@ 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();
         const deploymentRef = deploymentRefFor(slug, id);
         // #2210: the store scripts first, outside the vertical upload's try, so a store failure
-        // answers as itself and the vertical is not uploaded at all.
-        await ensureScopeStoresOf(c.get('actor'), 'deploy', slug, manifest.scopeStores, async () => ownerTenant ?? null);
-        let wire;
-        try {
-            wire = await deployVerticalScript(options.deployVertical, c.get('actor'), slug, deploymentRef, {
-                entry: manifest.entry,
-                compatibilityDate: manifest.compatibilityDate,
-                compatibilityFlags: manifest.compatibilityFlags,
-                modules,
-                doClasses: manifest.doClasses,
-                bindings: verticalUploadBindings({
+        // answers as itself and the vertical is not uploaded at all. The upload, the registration and
+        // the publish run under the store push's shared hold (#2816): a rollout that starts before the
+        // version records its stores is refused, and one after walks this vertical.
+        const deployVertical = options.deployVertical;
+        const pushed = await ensureScopeStoresOf(c.get('actor'), 'deploy', slug, manifest.scopeStores, async () => ownerTenant ?? null, async (renew) => {
+            let wire;
+            try {
+                wire = await deployVerticalScript(deployVertical, c.get('actor'), slug, deploymentRef, {
+                    entry: manifest.entry,
+                    compatibilityDate: manifest.compatibilityDate,
+                    compatibilityFlags: manifest.compatibilityFlags,
+                    modules,
+                    doClasses: manifest.doClasses,
+                    bindings: verticalUploadBindings({
+                        vertical: slug,
+                        manifest,
+                        drivers: options.storeDrivers,
+                        // #2349: the migrations this push declares, which are the ones the version stores.
+                        platformBindings: await migrationsDigestBindings(manifest.migrations ?? null),
+                    }),
+                    // #1242: the freshly minted version id — this archive script IS that version,
+                    // and a preview routed at it stamps the signals `version` dimension honestly.
+                    versionId: id,
+                    // #1902: the platform's scope sweeper, as decided above and recorded with the version.
+                    ...(sweeper.supply ? { supplySweeper: true } : {}),
+                    // #340: the verified bytes go up with the bundle. The manifest's routing config
+                    // rides along untouched — it decides what the RUNTIME does with paths, and carries
+                    // no reach, so there is nothing in it for the sandbox contract to refuse.
+                    ...(manifest.assets ? { assets: { ...manifest.assets, files: assets } } : {}),
+                });
+            }
+            catch (e) {
+                // The upload to the runtime failed. Surface the detail (the builder is
+                // authenticated) rather than the anonymous 500 the generic handler would give, so a
+                // push failure is diagnosable without reading worker logs. The version label is NOT
+                // consumed here: registration/publish happen only AFTER a successful upload (below),
+                // so a failed push leaves the same --version reusable (#307).
+                //
+                // Answer the upstream status honestly: a runtime 4xx is a bad-bundle rejection — the
+                // builder's own script (e.g. a module-top-level throw → CF 10021), well-formed HTTP
+                // but refused — so a 422, not a 502 that reads as a platform outage. A 5xx (or any
+                // throw with no upstream status) is a platform failure and stays a 502.
+                const detail = e instanceof Error ? e.message : String(e);
+                const upstream = upstreamStatusOf(e);
+                console.error('deploy.upload.failed', { slug, deploymentRef, detail, upstream });
+                const rejected = upstream !== undefined && upstream >= 400 && upstream < 500;
+                // Both outcomes land an ops-failure row (#559): the 502 is the platform's to
+                // explain, and the 422 is what the builder-facing failure view (step 5) will
+                // list — a red push should be explainable from a durable record either way.
+                recordFailure({
+                    actor: c.get('actor'),
+                    operation: 'deploy.upload',
+                    stage: 'wfp-upload',
                     vertical: slug,
-                    manifest,
-                    drivers: options.storeDrivers,
-                    // #2349: the migrations this push declares, which are the ones the version stores.
-                    platformBindings: await migrationsDigestBindings(manifest.migrations ?? null),
-                }),
-                // #1242: the freshly minted version id — this archive script IS that version,
-                // and a preview routed at it stamps the signals `version` dimension honestly.
-                versionId: id,
-                // #1902: the platform's scope sweeper, as decided above and recorded with the version.
-                ...(sweeper.supply ? { supplySweeper: true } : {}),
-                // #340: the verified bytes go up with the bundle. The manifest's routing config
-                // rides along untouched — it decides what the RUNTIME does with paths, and carries
-                // no reach, so there is nothing in it for the sandbox contract to refuse.
-                ...(manifest.assets ? { assets: { ...manifest.assets, files: assets } } : {}),
+                    tenantId: ownerTenant ?? null,
+                    status: rejected ? 422 : 502,
+                    message: detail,
+                }, e);
+                c.set('failureRecorded', true);
+                return rejected
+                    ? refuseStatus(c, 422, 'deploy rejected', { detail })
+                    : refuseStatus(c, 502, 'deploy upload failed', { detail });
+            }
+            // Register-then-publish, both idempotent-ish below the seam: a first push of a
+            // slug registers it; publishVersion lands the version pending with deploymentRef
+            // (or admitted, for a PRIVATE vertical — the registry's self-admit rule). The owner
+            // was resolved with the slug above: the builder's tenant, the pinned workspace, or
+            // the preserved existing owner for an unpinned staff push. An upload that outlasted the
+            // store hold refuses here (409) before the vertical or its version is registered, so the
+            // label stays reusable; unlike a failed upload, it lands no ops-failure row.
+            await renew();
+            await c.var.admin.registerVertical(c.get('actor'), {
+                slug,
+                name: manifest.name ?? slug,
+                source: 'cli',
+                ownerTenant,
+                // The vertical's declared config surface rides to the registry, so the dashboard
+                // renders a settings form for a pushed vertical exactly like a builtin.
+                ...(manifest.envSpec ? { envSpec: manifest.envSpec } : {}),
+                // Registry-driven install metadata (marketplace-publish.md §3) — so the dashboard
+                // installs a pushed vertical without a hardcoded catalog entry.
+                ...(manifest.ownerGrants ? { ownerGrants: manifest.ownerGrants } : {}),
+                ...(manifest.entitlements ? { entitlements: manifest.entitlements } : {}),
+                ...(manifest.provides ? { provides: manifest.provides } : {}),
+                ...(manifest.requires ? { requires: manifest.requires } : {}),
+                // The declared vertical-defined connectors (vertical-connectors.md §7.2): what the dashboard's
+                // door renders. The proxy never reads this copy; it reads the running version's manifest.
+                ...(manifest.connectors ? { connectors: manifest.connectors } : {}),
+                // The declared provisioner intent (#455) — a REQUEST the console reviews; the
+                // tenant-provisioner grant itself is never touched by a push. Refreshes on every
+                // re-push like the rest of the install spec, exactly because it grants nothing.
+                ...(manifest.provisions ? { provisions: manifest.provisions } : {}),
+                // The declared email-sender intent (#303) — a REQUEST the console reviews; the
+                // `emailSender` grant itself is never touched by a push. Refreshes on every re-push
+                // like the rest of the install spec, exactly because it grants nothing.
+                ...(manifest.sendsEmail ? { sendsEmail: true } : {}),
+                // Where the scope lifecycle is held (#1713): `'router'` keeps the vertical's scopes out of
+                // the lifecycle delivery. Refreshes on every re-push like the rest of the install spec.
+                ...(manifest.lifecycle ? { lifecycle: manifest.lifecycle } : {}),
+                // The declared surfaces (K-26) ride like envSpec: registry metadata for the
+                // hostname-binding picker, never behavior. Not part of any admission digest.
+                ...(manifest.surfaces ? { surfaces: manifest.surfaces } : {}),
             });
-        }
-        catch (e) {
-            // The upload to the runtime failed. Surface the detail (the builder is
-            // authenticated) rather than the anonymous 500 the generic handler would give, so a
-            // push failure is diagnosable without reading worker logs. The version label is NOT
-            // consumed here: registration/publish happen only AFTER a successful upload (below),
-            // so a failed push leaves the same --version reusable (#307).
-            //
-            // Answer the upstream status honestly: a runtime 4xx is a bad-bundle rejection — the
-            // builder's own script (e.g. a module-top-level throw → CF 10021), well-formed HTTP
-            // but refused — so a 422, not a 502 that reads as a platform outage. A 5xx (or any
-            // throw with no upstream status) is a platform failure and stays a 502.
-            const detail = e instanceof Error ? e.message : String(e);
-            const upstream = upstreamStatusOf(e);
-            console.error('deploy.upload.failed', { slug, deploymentRef, detail, upstream });
-            const rejected = upstream !== undefined && upstream >= 400 && upstream < 500;
-            // Both outcomes land an ops-failure row (#559): the 502 is the platform's to
-            // explain, and the 422 is what the builder-facing failure view (step 5) will
-            // list — a red push should be explainable from a durable record either way.
-            recordFailure({
-                actor: c.get('actor'),
-                operation: 'deploy.upload',
-                stage: 'wfp-upload',
-                vertical: slug,
-                tenantId: ownerTenant ?? null,
-                status: rejected ? 422 : 502,
-                message: detail,
-            }, e);
-            c.set('failureRecorded', true);
-            return rejected
-                ? refuseStatus(c, 422, 'deploy rejected', { detail })
-                : refuseStatus(c, 502, 'deploy upload failed', { detail });
-        }
-        // Register-then-publish, both idempotent-ish below the seam: a first push of a
-        // slug registers it; publishVersion lands the version pending with deploymentRef
-        // (or admitted, for a PRIVATE vertical — the registry's self-admit rule). The owner
-        // was resolved with the slug above: the builder's tenant, the pinned workspace, or
-        // the preserved existing owner for an unpinned staff push.
-        await c.var.admin.registerVertical(c.get('actor'), {
-            slug,
-            name: manifest.name ?? slug,
-            source: 'cli',
-            ownerTenant,
-            // The vertical's declared config surface rides to the registry, so the dashboard
-            // renders a settings form for a pushed vertical exactly like a builtin.
-            ...(manifest.envSpec ? { envSpec: manifest.envSpec } : {}),
-            // Registry-driven install metadata (marketplace-publish.md §3) — so the dashboard
-            // installs a pushed vertical without a hardcoded catalog entry.
-            ...(manifest.ownerGrants ? { ownerGrants: manifest.ownerGrants } : {}),
-            ...(manifest.entitlements ? { entitlements: manifest.entitlements } : {}),
-            ...(manifest.provides ? { provides: manifest.provides } : {}),
-            ...(manifest.requires ? { requires: manifest.requires } : {}),
-            // The declared vertical-defined connectors (vertical-connectors.md §7.2): what the dashboard's
-            // door renders. The proxy never reads this copy; it reads the running version's manifest.
-            ...(manifest.connectors ? { connectors: manifest.connectors } : {}),
-            // The declared provisioner intent (#455) — a REQUEST the console reviews; the
-            // tenant-provisioner grant itself is never touched by a push. Refreshes on every
-            // re-push like the rest of the install spec, exactly because it grants nothing.
-            ...(manifest.provisions ? { provisions: manifest.provisions } : {}),
-            // The declared email-sender intent (#303) — a REQUEST the console reviews; the
-            // `emailSender` grant itself is never touched by a push. Refreshes on every re-push
-            // like the rest of the install spec, exactly because it grants nothing.
-            ...(manifest.sendsEmail ? { sendsEmail: true } : {}),
-            // Where the scope lifecycle is held (#1713): `'router'` keeps the vertical's scopes out of
-            // the lifecycle delivery. Refreshes on every re-push like the rest of the install spec.
-            ...(manifest.lifecycle ? { lifecycle: manifest.lifecycle } : {}),
-            // The declared surfaces (K-26) ride like envSpec: registry metadata for the
-            // hostname-binding picker, never behavior. Not part of any admission digest.
-            ...(manifest.surfaces ? { surfaces: manifest.surfaces } : {}),
-        });
-        await c.var.admin.publishVersion(c.get('actor'), {
-            id,
-            verticalSlug: slug,
-            version: manifest.version,
-            manifestDigest: manifest.digests.manifest,
-            permissionDigest: manifest.digests.permission,
-            migrationDigest: manifest.digests.migration,
-            deploymentRef,
-            ...(origin ? { origin } : {}),
-            // Retained for the serving upload (#286): the archive script keeps the module
-            // bytes, this keeps their shape (entry, compat, doClasses, bindings).
-            // #1902: with the sweeper decision the push made, which no later upload re-makes.
-            manifestJson: JSON.stringify({ ...manifest, platformSweeper: sweeper.supply }),
+            await c.var.admin.publishVersion(c.get('actor'), {
+                id,
+                verticalSlug: slug,
+                version: manifest.version,
+                manifestDigest: manifest.digests.manifest,
+                permissionDigest: manifest.digests.permission,
+                migrationDigest: manifest.digests.migration,
+                deploymentRef,
+                ...(origin ? { origin } : {}),
+                // Retained for the serving upload (#286): the archive script keeps the module
+                // bytes, this keeps their shape (entry, compat, doClasses, bindings).
+                // #1902: with the sweeper decision the push made, which no later upload re-makes.
+                manifestJson: JSON.stringify({ ...manifest, platformSweeper: sweeper.supply }),
+            });
+            return { wire };
         });
+        if (pushed instanceof Response)
+            return pushed;
+        const { wire } = pushed;
         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 +11219,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.
@@ -11192,6 +11568,32 @@ export function createControlPlaneApi(options) {
         const verticals = [...new Set([...declared.verticals.map((v) => v.vertical), ...declared.unreadable])].sort();
         return { fingerprint, ...storeRebuildStatus(walk, fingerprint, verticals, options.storeReleases?.settleMs), walk: walk ?? null };
     };
+    // The scope-store registry a push is judged by, for ONE vertical (#2813): `?vertical=` is the slug the
+    // push deploys as, required (bare, or already prefixed with the caller's own workspace). Every registration comes back, with `verticals` reduced to
+    // `[vertical]` when it serves that vertical and `[]` when it does not (omitted when it serves
+    // every one), so the CLI's own check can say "does not serve" and no other vertical's slug is
+    // read. "Serves" is judged for the registry id the deploy forms (`<tenant>/<name>` for a builder
+    // or a pinned staff push), the same one `ensureScopeStoresOf` judges. The staff-only
+    // `/store-drivers/:driver` below is the driver's release state and stays as it was.
+    app.get('/store-drivers', async (c) => {
+        const parsed = verticalSlug.safeParse(c.req.query('vertical'));
+        if (!parsed.success)
+            return refuse(c, 'validation_failed', 'vertical is required: the slug the push deploys as');
+        const vertical = parsed.data;
+        const p = c.get('principal');
+        const pin = c.req.header(TENANT_HEADER)?.trim();
+        let id = effectiveSlug(p, vertical);
+        if (p.kind !== 'builder' && pin) {
+            // The pinned-staff branch of the deploy's own slug derivation (`POST /verticals/:slug/deploy`).
+            const workspace = (await c.var.admin.listTenants(c.get('actor'))).find((t) => t.slug === pin || t.id === pin);
+            if (!workspace)
+                return refuse(c, 'not_found', `unknown workspace '${pin}'`);
+            const bareOwner = await ownerOf(c.get('actor'), vertical);
+            id = vertical.startsWith(`${workspace.slug}/`) || bareOwner === workspace.id ? vertical : `${workspace.slug}/${vertical}`;
+        }
+        const drivers = (options.storeDrivers ?? STORE_DRIVERS).map((d) => d.verticals ? { ...d, verticals: storeDriverServesVertical(d, id) ? [vertical] : [] } : d);
+        return c.json({ drivers });
+    });
     app.get('/store-drivers/:driver', async (c) => {
         await staffPerson(c, statusWords);
         const registration = registeredDriver(c.req.param('driver'));