@substrat-run/control-plane-api 0.120.0 → 0.122.0

package/dist/api.js

@@ -1,14 +1,15 @@
 import { resolveObservabilityWindow } from './observability-window.js';
 import { Hono } from 'hono';
-import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, 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, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, redrainEventsInput, REDRAIN_BATCH, } from '@substrat-run/contracts';
+import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, 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, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, bindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, } from '@substrat-run/contracts';
 import { attributeFailure } from './failure-attribution.js';
-import { migrationProgress, ulid } from '@substrat-run/kernel';
+import { BIND_EXPORT_BREAK_REFUSAL, bindExportBreakRefusal, crossVerticalHealth, exportBreakRefusal, isBindExportBreakRefusal, isExportBreakRefusal, migrationProgress, ulid, } from '@substrat-run/kernel';
 import { TENANT_HEADER, confinedTenant } from './auth.js';
 import { mintTenantToken } from './tenant-token.js';
 import { connectionGrantsForScope } from './vertical-client.js';
 import { oidcCallbackUrl, retireClientsOfReapedScope, wirePreviewAuth } from './preview-auth.js';
 import { versionReachedAt } from './scope-deployment.js';
 import { reconcileConnectionGrants } from './connection-grants.js';
+import { reconcileThenReassert } from './reconcile.js';
 import { ConnectionRelayError, relayConnectionUpsert } from './connection-relay.js';
 import { ControlPlaneError } from './client.js';
 import { provisionSiblingScope } from './platform-drain.js';
@@ -56,6 +57,35 @@ function outsideTenant(p, tenantId) {
     const pin = confinedTenant(p);
     return pin !== null && pin !== tenantId;
 }
+/**
+ * #1756: a move refused because it would break apps in the scope's own tenant. Carries the
+ * listing, because every route that moves a scope pins that tenant in its path, so the caller may
+ * read it whole; the counted sentence is the host's (`bindExportBreakRefusal`).
+ */
+class ExportBreakRefused extends ControlPlaneError {
+    breaks;
+    constructor(breaks) {
+        super(409, bindExportBreakRefusal(breaks));
+        this.breaks = breaks;
+    }
+}
+/** The body a route answers an `ExportBreakRefused` with: the sentence and the listing. */
+function exportBreakBody(e) {
+    return { error: e.message, ...(e instanceof ExportBreakRefused ? { exportBreaks: { affected: e.breaks } } : {}) };
+}
+/**
+ * A fleet-wide report, narrowed to what a caller may see: a confined caller gets its own
+ * tenant's rows and a COUNT of the other tenants, never their ids (K-3's forced filter, held on
+ * reports that have to be computed fleet-wide). Staff (`pin === null`) get every row.
+ */
+function narrowToCaller(rows, pin) {
+    if (pin === null)
+        return { visible: [...rows], otherTenants: 0 };
+    return {
+        visible: rows.filter((r) => r.tenantId === pin),
+        otherTenants: new Set(rows.filter((r) => r.tenantId !== pin).map((r) => r.tenantId)).size,
+    };
+}
 // -- request schemas ---------------------------------------------------------
 // Parse, don't trust: every input crosses Zod at the boundary. The ids stay
 // CALLER-SUPPLIED rather than minted here, exactly as the contract has them —
@@ -165,6 +195,9 @@ const bindScopeVersionBody = z.object({
     // data first when this bind crosses a migration-digest boundary. Optional and
     // ignored on a code-only rebind — the digest compare is the gate, not the flag.
     snapshot: z.boolean().optional(),
+    // #1756: a bind that drops or re-versions an export an app in this tenant imports is
+    // refused unless acknowledged — the promote gate's `exportBreak`, for one install.
+    acknowledge: bindAcknowledgement.optional(),
 });
 const rebindScopeVerticalBody = z.object({
     // The FULL registry id of the target lineage (e.g. `substrat-9yjbbn/manyfold`) —
@@ -181,7 +214,12 @@ const rebindScopeVerticalBody = z.object({
     // backout copy exactly as in a carried rebind. The scope must be re-provisioned
     // on the target afterwards (`/verticals/:slug/instances` is idempotent, K-31).
     abandonData: z.boolean().optional(),
+    // #1756: within one lineage the rebind is an adopt, refused when it breaks an app in the tenant.
+    acknowledge: bindAcknowledgement.optional(),
 });
+// #1756: an adopt moves the scope onto what its vertical serves, and is refused when that breaks
+// an app in the tenant. The body is optional, as it always was.
+const adoptServingBody = z.object({ acknowledge: bindAcknowledgement.optional() });
 // A snapshot request (preview-and-snapshots.md §3/§9). `expiresAt` opts into the GC
 // sweep; absent = pinned until deliberately deleted. `kind` defaults to 'archive'.
 const snapshotScopeBody = z.object({
@@ -371,6 +409,19 @@ const tenantRoleAssignmentBody = z
  * spells out; `.strict()` so a body that tried to name one is refused, not stripped.
  */
 const systemSwitchBody = systemSwitch.pick({ moduleId: true, reason: true }).strict();
+/**
+ * The fleet read's filter (#1674). `position` defaults to `off` — "what is switched off
+ * across the fleet" is the question the route exists for — and `all` asks for both. Paged
+ * by `operationId`, ascending by default (oldest switch first, as the admin log reads).
+ */
+const systemSwitchesQuery = z.object({
+    position: z.enum(['on', 'off', 'all']).default('off'),
+    tenantId: tenantIdSchema.optional(),
+    scopeId: scopeIdSchema.optional(),
+    moduleId: systemSwitch.shape.moduleId.optional(),
+    vertical: z.string().min(1).optional(),
+    ...listPageQuery.shape,
+});
 /** The peer kill switch's body (#1706) — the tenant and scope come from the path. */
 const peerSwitchBody = peerSwitch.pick({ vertical: true, reason: true }).strict();
 /** A new org under an addressed tenant (#1343) — `tenantId` comes from the path. */
@@ -453,6 +504,7 @@ const TENANT_ROUTES = [
     { method: 'DELETE', re: /\/verticals\/[^/]+$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/registry$/, pin: 'owner' },
+    { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/migrations$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/model$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/flow$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/assets$/, pin: 'owner' },
@@ -460,6 +512,7 @@ const TENANT_ROUTES = [
     { method: 'GET', re: /\/verticals\/[^/]+\/channels$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/channels\/[^/]+\/history$/, pin: 'owner' },
     { method: 'POST', re: /\/verticals\/[^/]+\/channels\/[^/]+\/promote$/, pin: 'owner' },
+    { method: 'GET', re: /\/verticals\/[^/]+\/channels\/[^/]+\/promote-impact$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/previews$/, pin: 'owner' },
     { method: 'POST', re: /\/verticals\/[^/]+\/previews$/, pin: 'owner' },
     { method: 'DELETE', re: /\/verticals\/[^/]+\/previews\/[^/]+$/, pin: 'owner' },
@@ -612,6 +665,9 @@ export function createControlPlaneApi(options) {
         // The declared permission registry of one version (D-39, #336) — owner-narrowed in the
         // handler like the versions list; the builder-facing Permissions tab reads it.
         { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/registry$/ },
+        // The SQL migrations one version adds on top of another (#1677), owner-narrowed the same
+        // way; the promote dialog and `substrat promote` read it.
+        { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/migrations$/ },
         // The emitted entity model of one version (#1214) — owner-narrowed the same way;
         // the dashboard's Model tab reads it.
         { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/model$/ },
@@ -783,6 +839,8 @@ export function createControlPlaneApi(options) {
         if (err instanceof z.ZodError) {
             return problem(c, { status: 400, body: toProblem(err, c.req.path) });
         }
+        if (err instanceof ExportBreakRefused)
+            return c.json(exportBreakBody(err), 409);
         const { status, body } = mapError(err);
         // A 5xx is the PLATFORM failing — an unmapped throw, or a downstream vertical's
         // own 5xx passing through (a DO storage fault during a preview restore is the
@@ -1565,6 +1623,25 @@ export function createControlPlaneApi(options) {
         return (`no deployment is bound for vertical '${slug}': the scope is not on the serving script and its bound ` +
             `version did not resolve. Promote a version to prod, then adopt the scope onto the serving script.`);
     };
+    /**
+     * #1756: refuse, BEFORE any data moves, a move of this scope that would break apps in its
+     * tenant, unless acknowledged. The host refuses the same move whoever calls; this is what keeps
+     * a route that exports, restores or snapshots first from doing so for a move that is refused.
+     * `servingRef` is the route the scope takes in the same act (an adopt).
+     */
+    const refuseOnBreaks = async (actor, tenantId, scopeId, versionId, opts) => {
+        if (opts.acknowledge?.exportBreak)
+            return;
+        const breaks = await admin.bindingImpact(actor, tenantId, scopeId, versionId, opts.servingRef !== undefined ? { servingRef: opts.servingRef } : undefined);
+        if (breaks.length > 0)
+            throw new ExportBreakRefused(breaks);
+    };
+    /** The host's own export-break refusal (the move changed since it was asked), as the same 409. */
+    const relayHostRefusal = (err) => {
+        if (isBindExportBreakRefusal(err))
+            throw new ControlPlaneError(409, err.message);
+        throw err;
+    };
     /**
      * Move ONE legacy scope's data off its per-version dispatch script onto its vertical's
      * stable serving script (#286/#321), then flip routing. The one primitive behind both
@@ -1578,7 +1655,7 @@ export function createControlPlaneApi(options) {
      * installs short-circuit.
      * Throws `ControlPlaneError` so callers surface an actionable status, never a bare 500.
      */
-    const adoptScopeOntoServing = async (c, tenantId, scopeId) => {
+    const adoptScopeOntoServing = async (c, tenantId, scopeId, opts = {}) => {
         const actor = c.get('actor');
         const scope = await admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope) {
@@ -1587,8 +1664,13 @@ export function createControlPlaneApi(options) {
         if (scope.kind === 'preview') {
             throw new ControlPlaneError(409, 'preview scopes cannot adopt the production serving script');
         }
-        if (scope.servingRef)
+        if (scope.servingRef) {
+            // #1674 (Copilot review): an adopt that flipped routing and then failed to re-assert is
+            // retried HERE, so the retry re-asserts too — else a store that lost its OFF marker in
+            // the copy would stay on for good. Cheap and idempotent when nothing is owed.
+            await admin.reassertSystemSwitches(actor, { tenantId, scopeId });
             return { servingRef: scope.servingRef, alreadyAdopted: true };
+        }
         if (!scope.vertical) {
             throw new ControlPlaneError(409, 'scope has no vertical — nothing to adopt onto');
         }
@@ -1596,6 +1678,12 @@ export function createControlPlaneApi(options) {
         if (!serving) {
             throw new ControlPlaneError(409, `vertical '${scope.vertical}' has no serving script yet — promote a version to prod first`);
         }
+        // #1756: onto the serving script, the scope runs the served version from the moment routing
+        // flips — whatever its own version exported. Asked before the export below moves anything.
+        await refuseOnBreaks(actor, tenantId, scopeId, serving.versionId, {
+            servingRef: serving.ref,
+            acknowledge: opts.acknowledge,
+        });
         const source = await verticalForScope(c, scope);
         const dest = await options.resolveVerticalRef?.(serving.ref);
         if (!source || !dest) {
@@ -1604,8 +1692,15 @@ export function createControlPlaneApi(options) {
         const dump = await source.exportScope(scopeId);
         const restored = await retryTransient(() => dest.restoreScope(tenantId, scopeId, dump));
         // Data landed — only now flip routing and move the version pointer.
-        await admin.setScopeServingRef(actor, tenantId, scopeId, serving.ref);
-        await admin.bindScopeVersion(actor, tenantId, scopeId, serving.versionId);
+        await admin
+            .setScopeServingRef(actor, tenantId, scopeId, serving.ref, { acknowledge: opts.acknowledge })
+            .catch(relayHostRefusal);
+        await admin
+            .bindScopeVersion(actor, tenantId, scopeId, serving.versionId, { acknowledge: opts.acknowledge })
+            .catch(relayHostRefusal);
+        // #1674: the scope now routes to a different store, so put the directory's recorded
+        // OFF positions back there — cheap and idempotent when the dump carried them.
+        await admin.reassertSystemSwitches(actor, { tenantId, scopeId });
         return { servingRef: serving.ref, tables: restored.tables };
     };
     /**
@@ -1621,29 +1716,51 @@ export function createControlPlaneApi(options) {
      * Idempotent and retry-safe: the host cascade never rebound these scopes, so their data
      * is still findable on a retry after a failed serve.
      */
-    const adoptAndRebindOwnedScopes = async (c, slug, versionId) => {
+    const adoptAndRebindOwnedScopes = async (c, slug, versionId, 
+    // #1756: the promote's own acknowledgement. An install adopted here goes from ITS version to
+    // the promoted one, which the promote gate judged only from the channel's previous version:
+    // an install lagging behind that is judged again, and passes on the promote's ack or not at all.
+    acknowledge) => {
         const actor = c.get('actor');
+        const none = { refused: [] };
         const serving = await admin.verticalServing(actor, slug);
         if (!serving)
-            return; // embedded / not dispatch-backed — the host cascade handled rebinds
+            return none; // embedded / not dispatch-backed — the host cascade handled rebinds
         const v = await verticalOf(actor, slug);
         if (!v || v.ownerTenant === null || v.listed)
-            return; // private only, like the host cascade
+            return none; // private only, like the host cascade
         const owned = (await admin.listScopes(actor, { tenantId: v.ownerTenant, vertical: slug, status: ['active'] })).filter((s) => !s.forkedFrom && s.kind !== 'preview');
+        // An install refused for what it would break is left where it is, and the rest still move:
+        // one lagging app must not keep every other install's pointer, or the store backfill after
+        // this, from happening. The caller answers with what was refused.
+        const refused = [];
+        let refusal;
         for (const s of owned) {
-            if (!s.servingRef) {
-                // Adopt: export from the scope's current (un-rebound) dispatch → serving script,
-                // then bind to the serving version. Data-first, so a failure here leaves the
-                // scope intact on its old script for the next promote to retry.
-                await adoptScopeOntoServing(c, s.tenantId, s.id);
+            try {
+                if (!s.servingRef) {
+                    // Adopt: export from the scope's current (un-rebound) dispatch → serving script,
+                    // then bind to the serving version. Data-first, so a failure here leaves the
+                    // scope intact on its old script for the next promote to retry.
+                    await adoptScopeOntoServing(c, s.tenantId, s.id, { acknowledge });
+                }
+                else if (s.verticalVersionId !== versionId) {
+                    // Already on the serving script (born there, or adopted earlier): routing is
+                    // pinned to servingRef, so advancing the version pointer only affects Update
+                    // offers. Snapshot on a migration-digest crossing (fork-before-promote, §4).
+                    await admin.bindScopeVersion(actor, s.tenantId, s.id, versionId, { snapshot: true, acknowledge });
+                }
             }
-            else if (s.verticalVersionId !== versionId) {
-                // Already on the serving script (born there, or adopted earlier): routing is
-                // pinned to servingRef, so advancing the version pointer only affects Update
-                // offers. Snapshot on a migration-digest crossing (fork-before-promote, §4).
-                await admin.bindScopeVersion(actor, s.tenantId, s.id, versionId, { snapshot: true });
+            catch (e) {
+                if (e instanceof ExportBreakRefused)
+                    refused.push(...e.breaks);
+                else if (isBindExportBreakRefusal(e) || (e instanceof ControlPlaneError && e.message.startsWith(BIND_EXPORT_BREAK_REFUSAL))) {
+                    refusal ??= e.message; // the host's own refusal (the answer moved under us): counts only
+                }
+                else
+                    throw e;
             }
         }
+        return { refused, ...(refusal ? { refusal } : {}) };
     };
     /**
      * Move ONE scope onto a DIFFERENT vertical lineage's serving script (#389) — the
@@ -1677,15 +1794,24 @@ export function createControlPlaneApi(options) {
             throw new ControlPlaneError(409, `vertical '${target}' has no serving script yet — promote a version to prod first`);
         }
         if (scope.vertical === target && scope.servingRef === serving.ref) {
+            // #1674: a rebind retried after its re-assert failed lands here; re-assert, as adopt does.
+            await admin.reassertSystemSwitches(actor, { tenantId, scopeId });
             return { servingRef: serving.ref, versionId: serving.versionId, alreadyBound: true };
         }
+        // #1756: within one lineage this is an adopt, and judged as one before anything moves. A
+        // crossing is not judged (`bindExportBreaksOf`): the producer's slug itself changes.
+        await refuseOnBreaks(actor, tenantId, scopeId, serving.versionId, {
+            servingRef: serving.ref,
+            acknowledge: opts.acknowledge,
+        });
+        const move = { acknowledge: opts.acknowledge };
         if (opts.abandonData) {
             // Directory-only crossing: no bytes move, so the frontier gate has nothing to
             // protect — the target provisions its own schema from scratch. The source
             // script's copy is untouched and remains the backout, same as a carried rebind.
             // The scope serves nothing until `/verticals/:slug/instances` re-provisions it.
-            await admin.setScopeServingRef(actor, tenantId, scopeId, serving.ref);
-            await admin.bindScopeVersion(actor, tenantId, scopeId, serving.versionId);
+            await admin.setScopeServingRef(actor, tenantId, scopeId, serving.ref, move).catch(relayHostRefusal);
+            await admin.bindScopeVersion(actor, tenantId, scopeId, serving.versionId, move).catch(relayHostRefusal);
             return { servingRef: serving.ref, versionId: serving.versionId, dataAbandoned: true };
         }
         // The frontier gate. Digest equality proves the target's migration set is exactly
@@ -1713,8 +1839,10 @@ export function createControlPlaneApi(options) {
         // `bindScopeVersion` rewrites `scopes.vertical` from the version row, audited. No
         // extra snapshot here (adopt-serving's precedent): the source script's copy is the
         // pre-migration state, and it is never deleted — that copy is the backout.
-        await admin.setScopeServingRef(actor, tenantId, scopeId, serving.ref);
-        await admin.bindScopeVersion(actor, tenantId, scopeId, serving.versionId);
+        await admin.setScopeServingRef(actor, tenantId, scopeId, serving.ref, move).catch(relayHostRefusal);
+        await admin.bindScopeVersion(actor, tenantId, scopeId, serving.versionId, move).catch(relayHostRefusal);
+        // #1674: re-assert the recorded OFF positions in the store the scope now routes to.
+        await admin.reassertSystemSwitches(actor, { tenantId, scopeId });
         return { servingRef: serving.ref, versionId: serving.versionId, tables: restored.tables };
     };
     /**
@@ -2034,7 +2162,8 @@ export function createControlPlaneApi(options) {
             : null;
         const ranAs = versionReachedAt(reached.via, scope, serving);
         try {
-            const result = await vertical.reconcileInstance({
+            // #1674: the recorded OFF positions go back after the reconcile, before the receipt.
+            const result = await reconcileThenReassert(admin, actor, { tenantId, scopeId }, () => vertical.reconcileInstance({
                 tenantId,
                 scopeId,
                 entitlements,
@@ -2045,7 +2174,7 @@ export function createControlPlaneApi(options) {
                 // by the vertical, so the reconcile must carry it into the same ready-gate — a bound
                 // but unmigrated database fails as loudly as an absent one.
                 ...(tenantStores.length ? { tenantStores } : {}),
-            });
+            }));
             // #1172: the reconcile succeeded, so record WHICH version it ran against. Without
             // this the sweep would come back and do it again on the next pass — the console
             // button and the automatic phase have to write the same receipt, or pressing the
@@ -3090,6 +3219,9 @@ export function createControlPlaneApi(options) {
             const vertical = await verticalForScope(c, scope);
             if (vertical)
                 await retryTransient(() => vertical.restoreScope(tenantId, scopeId, tables));
+            // #1674: a backup from before a module was switched off brings it back on; the
+            // directory's record puts it back off now, not at the next reconcile.
+            await admin.reassertSystemSwitches(actor, { tenantId, scopeId });
             return c.json({ restored: scopeId, tables: tables.length });
         }
         catch (e) {
@@ -3158,10 +3290,15 @@ export function createControlPlaneApi(options) {
                 force,
                 localApply: !vertical,
             });
-            if (vertical) {
-                return c.json(await vertical.rewindScope(scopeId, bookmark, { force }));
-            }
-            return c.json(result);
+            const answer = vertical ? await vertical.rewindScope(scopeId, bookmark, { force }) : result;
+            // #1674: a rewind takes the scope's grants back to the bookmark, and with them any
+            // schedule kill switch pulled since — a tenant owner could otherwise undo a staff
+            // switch this way. Clearing the provisioned receipt, only once the rewind has gone
+            // through, makes the next sweep reconcile the scope, and that reconcile re-asserts
+            // what the directory records as off. Left to the sweep rather than done here: the
+            // scope's store restarts to finish the restore, and a re-assert now would race it.
+            await admin.markScopeProvisioned(actor, tenantId, scopeId, null);
+            return c.json(answer);
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
@@ -3178,13 +3315,14 @@ export function createControlPlaneApi(options) {
     app.post('/tenants/:tenantId/scopes/:scopeId/adopt-serving', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const { acknowledge } = adoptServingBody.parse(await c.req.json().catch(() => ({})));
         try {
-            const r = await adoptScopeOntoServing(c, tenantId, scopeId);
+            const r = await adoptScopeOntoServing(c, tenantId, scopeId, { acknowledge });
             return c.json({ adopted: scopeId, ...r });
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, e.status);
+                return c.json(exportBreakBody(e), e.status);
             }
             throw e;
         }
@@ -3211,17 +3349,18 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'adopt-serving is a private-vertical operation' }, 409);
         }
         const owned = (await admin.listScopes(actor, { tenantId: v.ownerTenant, vertical: slug })).filter((s) => !s.forkedFrom && s.kind !== 'preview' && s.status === 'active');
+        const { acknowledge } = adoptServingBody.parse(await c.req.json().catch(() => ({})));
         const adopted = [];
         const alreadyAdopted = [];
         try {
             for (const s of owned) {
-                const r = await adoptScopeOntoServing(c, s.tenantId, s.id);
+                const r = await adoptScopeOntoServing(c, s.tenantId, s.id, { acknowledge });
                 (r.alreadyAdopted ? alreadyAdopted : adopted).push(s.id);
             }
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message, adopted, alreadyAdopted }, e.status);
+                return c.json({ ...exportBreakBody(e), adopted, alreadyAdopted }, e.status);
             }
             throw e;
         }
@@ -3235,21 +3374,34 @@ export function createControlPlaneApi(options) {
     app.post('/tenants/:tenantId/scopes/:scopeId/rebind-vertical', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
-        const { vertical, ackMigrations, abandonData } = rebindScopeVerticalBody.parse(await c.req.json());
+        const { vertical, ackMigrations, abandonData, acknowledge } = rebindScopeVerticalBody.parse(await c.req.json());
         try {
             const r = await rebindScopeOntoVertical(c, tenantId, scopeId, vertical, {
                 ackMigrations,
                 abandonData,
+                acknowledge,
             });
             return c.json({ rebound: scopeId, vertical, ...r });
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, e.status);
+                return c.json(exportBreakBody(e), e.status);
             }
             throw e;
         }
     });
+    // #1756: which apps in this tenant binding `versionId` onto the scope would break — the
+    // question the bind below refuses on, as a read, so a client can ask it before it records
+    // anything of its own (the dashboard's Activity line) and show what an acknowledgement would
+    // break. Refuses what the bind would refuse first (unknown scope or version, not admitted).
+    // Callers: staff, and a tenant's own credential pinned to the tenant in the path; a builder's
+    // push token is not in BUILDER_ROUTES. Every row is in that tenant.
+    app.get('/tenants/:tenantId/scopes/:scopeId/binding-impact', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const versionId = z.string().min(1).parse(c.req.query('versionId'));
+        return c.json({ affected: await admin.bindingImpact(c.get('actor'), tenantId, scopeId, versionId) });
+    });
     // Pin a scope to a vertical version (#31; orchestration.md §4). Refuses a
     // non-admitted version below the seam — that refusal is the registry's reason to
     // exist. A scope operation, so it keeps the scope route shape. `snapshot: true`
@@ -3265,9 +3417,16 @@ export function createControlPlaneApi(options) {
     app.post('/tenants/:tenantId/scopes/:scopeId/version', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
-        const { versionId, snapshot } = bindScopeVersionBody.parse(await c.req.json());
+        const { versionId, snapshot, acknowledge } = bindScopeVersionBody.parse(await c.req.json());
         const actor = c.get('actor');
         const scope = await admin.getScopeRecord(actor, tenantId, scopeId);
+        // #1756: the apps in this tenant the bind would break, asked BEFORE the carry and the
+        // snapshot below, which move data. The host refuses too, whoever calls, but by then a
+        // refusal would land after the bytes had moved. It refuses what the bind would refuse
+        // first (a version not admitted) the same way. An unknown scope has no impact to read, and
+        // the bind below refuses it as it always has.
+        if (scope)
+            await refuseOnBreaks(actor, tenantId, scopeId, versionId, { acknowledge });
         // A refusal throws a ControlPlaneError, which the app's error boundary relays with its
         // status and records as an ops failure. An unknown scope carries nothing, and the bind
         // below refuses it as it always has.
@@ -3275,6 +3434,15 @@ export function createControlPlaneApi(options) {
             if (scope)
                 await carryOntoVersion(c, scope, versionId);
         };
+        // #1674: after the bind, the scope may route to a different store (the carry's
+        // destination); put the directory's recorded OFF positions back there.
+        const reassert = async () => {
+            if (scope)
+                await admin.reassertSystemSwitches(actor, { tenantId, scopeId });
+        };
+        // The host's own refusal, should the impact have changed since it was read above (a
+        // promote landing in between): relayed as the same 409, never as a 500.
+        const bind = (opts) => admin.bindScopeVersion(actor, tenantId, scopeId, versionId, opts).catch(relayHostRefusal);
         if (snapshot) {
             if (!scope) {
                 return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
@@ -3292,18 +3460,24 @@ export function createControlPlaneApi(options) {
                     migrationCrossing = Boolean(current && incoming && current.migrationDigest !== incoming.migrationDigest);
                 }
                 await carry();
-                if (migrationCrossing)
+                if (migrationCrossing) {
+                    // Asked again after the carry: a promote landing since the first question would
+                    // otherwise leave an archive behind for a bind the host then refuses.
+                    await refuseOnBreaks(actor, tenantId, scopeId, versionId, { acknowledge });
                     await orchestratedSnapshot(c, tenantId, scope, {});
-                await admin.bindScopeVersion(actor, tenantId, scopeId, versionId);
+                }
+                await bind({ acknowledge });
             }
             else {
                 await carry();
-                await admin.bindScopeVersion(actor, tenantId, scopeId, versionId, { snapshot: true });
+                await bind({ acknowledge, snapshot: true });
             }
+            await reassert();
             return c.json(await admin.getScopeRecord(actor, tenantId, scopeId));
         }
         await carry();
-        await admin.bindScopeVersion(actor, tenantId, scopeId, versionId);
+        await bind({ acknowledge });
+        await reassert();
         return c.json(await admin.getScopeRecord(actor, tenantId, scopeId));
     });
     // -- instances (K-31) -------------------------------------------------------
@@ -3405,6 +3579,14 @@ export function createControlPlaneApi(options) {
             // one guessed from the serving pointer would claim a hook ran against code this
             // scope was not running.
             const provisioned = await admin.getScopeRecord(c.get('actor'), input.tenantId, input.scopeId);
+            // #1674: this route is idempotent (K-31), so an already-bound scope that was wiped can
+            // come back through it, re-seated live by the deployment — and the receipt below means
+            // no sweep follows. Re-assert the recorded OFF positions before it. Only once the
+            // directory row exists: a brand-new install's is written after this call (see above),
+            // has no record to re-assert, and `reassertSystemSwitches` refuses an unknown scope.
+            if (provisioned) {
+                await admin.reassertSystemSwitches(c.get('actor'), { tenantId: input.tenantId, scopeId: input.scopeId });
+            }
             if (provisioned?.verticalVersionId) {
                 await admin.markScopeProvisioned(c.get('actor'), input.tenantId, input.scopeId, provisioned.verticalVersionId);
             }
@@ -3660,6 +3842,28 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'forbidden' }, 403);
         }
         input.verticalSlug = slug;
+        // `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
+        // and backout run (`serveVersionInPlace`), and `tenant-stores.ts`.
+        // Hold it to that same parser here, at the trust boundary. The STORED
+        // form, not the push-time one: this route keeps accepting what the platform already holds
+        // (no `registry`, pre-#286 nulls), and refuses only what no reader could open. The string
+        // is stored as sent — re-serializing would drop keys a newer publisher carries.
+        if (input.manifestJson != null) {
+            let raw;
+            try {
+                raw = JSON.parse(input.manifestJson);
+            }
+            catch {
+                return c.json({ error: 'manifestJson is not valid JSON' }, 400);
+            }
+            const checked = storedDeployManifest.safeParse(raw);
+            if (!checked.success) {
+                const issue = checked.error.issues[0];
+                return c.json({ error: `manifestJson is not a deploy manifest: ${issue.path.join('.') || '(root)'}: ${issue.message}` }, 400);
+            }
+        }
         await admin.publishVersion(c.get('actor'), input);
         const version = await admin.getVersion(c.get('actor'), input.id, slug);
         return c.json(version, 201);
@@ -3680,6 +3884,29 @@ export function createControlPlaneApi(options) {
         const registry = json ? (storedDeployManifest.parse(JSON.parse(json)).registry ?? null) : null;
         return c.json({ registry });
     });
+    // The SQL migrations one version adds on top of another (#1677): what the promote dialog
+    // and `substrat promote` show before a migration change is acknowledged. `?base=` names the
+    // version to compare against (the one `prod` serves); without it every migration is listed.
+    // Owner-narrowed like `/registry`, and never widened: migration SQL describes a schema.
+    // `migrations` is null for a version that carries none (pushed before the field, or over
+    // the push's cap), which a reader must show as "SQL not available", never as
+    // "no migrations". Bounded in count and bytes (`migrationsOnTop`). The SQL is stored apart
+    // from the manifest (#1764), so this reads it without parsing either manifest.
+    app.get('/verticals/:slug/versions/:id/migrations', async (c) => {
+        const p = c.get('principal');
+        const slug = await resolveVerticalId(c, c.req.param('slug'));
+        if (await notOwned(p, slug)) {
+            return c.json({ error: 'not found' }, 404);
+        }
+        // `versionMigrations` refuses a version of another vertical, so `base` cannot reach one.
+        const migrationsOf = (id) => admin.versionMigrations(c.get('actor'), slug, id);
+        const base = c.req.query('base');
+        const [incoming, baseline] = await Promise.all([
+            migrationsOf(c.req.param('id')),
+            base === undefined ? undefined : migrationsOf(base),
+        ]);
+        return c.json({ migrations: incoming === null ? null : migrationsOnTop(incoming, baseline) });
+    });
     // 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
     // above, and owner-narrowed the same way. `model` is null for a version pushed by a
@@ -4024,6 +4251,58 @@ export function createControlPlaneApi(options) {
             return { minted: [], error: message };
         }
     };
+    /**
+     * Which installed apps promoting `versionId` to `channel` would break: the promote gate's own
+     * answer (`promotionImpact`, judged from the channel's previous version), and — for a PRIVATE,
+     * dispatch-backed vertical's prod — what adopting each owned install still on its own version
+     * would break (#1756). That adopt runs after the serve and carries the promote's acknowledgement,
+     * so the acknowledgement must be asked against both, or it would cover breaks nobody was shown.
+     * Over-approximates for a host that cannot serve in place, where no adopt runs: an extra line
+     * costs a read, a missing one a silent stall.
+     */
+    const promoteImpactOf = async (actor, slug, channel, versionId) => {
+        const gate = await admin.promotionImpact(actor, slug, channel, versionId);
+        if (channel !== 'prod')
+            return gate;
+        const v = await verticalOf(actor, slug);
+        if (!v || v.ownerTenant === null || v.listed)
+            return gate;
+        const incoming = await admin.getVersion(actor, versionId, slug);
+        if (!incoming?.deploymentRef || incoming.admission !== 'admitted')
+            return gate;
+        const lagging = (await admin.listScopes(actor, { tenantId: v.ownerTenant, vertical: slug, status: ['active'] })).filter((s) => !s.forkedFrom && s.kind !== 'preview' && !s.servingRef && s.verticalVersionId !== versionId);
+        const seen = new Set(gate.map((b) => `${b.scopeId}|${b.type}`));
+        const out = [...gate];
+        for (const s of lagging) {
+            // After the adopt it runs the promoted version, served in place: that pointer move, from
+            // what it runs now, is the move to judge.
+            for (const b of await admin.bindingImpact(actor, s.tenantId, s.id, versionId)) {
+                const key = `${b.scopeId}|${b.type}`;
+                if (!seen.has(key))
+                    (seen.add(key), out.push(b));
+            }
+        }
+        return out;
+    };
+    // #1705 PR 3: which installed apps promoting `?versionId=` would break (an export they import,
+    // dropped or re-versioned), BEFORE promoting, so a dialog can show it and ask for the
+    // acknowledgement up front, as it does for the digests. The promote's own 409 carries the same
+    // listing. Narrowed to the caller exactly as that 409 is. Owner-checked like the promote.
+    app.get('/verticals/:slug/channels/:channel/promote-impact', async (c) => {
+        const p = c.get('principal');
+        const slug = await resolveVerticalId(c, c.req.param('slug'));
+        const channel = channelName.parse(c.req.param('channel'));
+        const versionId = z.string().min(1).parse(c.req.query('versionId'));
+        const pin = confinedTenant(p);
+        if (pin) {
+            const v = await verticalOf(p.actor, slug);
+            if (!v || v.ownerTenant !== pin)
+                return c.json({ error: 'forbidden' }, 403);
+        }
+        const breaks = await promoteImpactOf(c.get('actor'), slug, channel, versionId);
+        const { visible, otherTenants } = narrowToCaller(breaks, pin);
+        return c.json({ affected: visible, ...(otherTenants ? { otherTenants } : {}) });
+    });
     app.post('/verticals/:slug/channels/:channel/promote', async (c) => {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
@@ -4060,15 +4339,48 @@ export function createControlPlaneApi(options) {
             }
         }
         const { versionId, acknowledge } = promoteVersionBody.parse(await c.req.json());
+        // #1705 PR 3: the installed consumers a promotion breaks (an export they import, dropped or
+        // re-versioned). The host refuses it without `exportBreak` whoever calls, in counts only,
+        // because it does not know who is asking. This door knows, so it adds the listing, narrowed
+        // the way the store backfill below is: a confined caller sees its own tenant's apps and the
+        // rest as a count, never another tenant's id. Read only when there is something to say: on
+        // the refusal, and before an acknowledged promotion moves the channel it is measured from.
+        // The whole answer is kept beside the narrowed listing, so the refusal's sentence counts the
+        // same breaks the listing lists (in counts, which name no tenant) — the host's own sentence
+        // counts only the gate's half of them.
+        let counted = [];
+        const breaksOf = async () => {
+            const breaks = await promoteImpactOf(c.get('actor'), slug, channel, versionId);
+            counted = breaks;
+            if (breaks.length === 0)
+                return null;
+            const { visible, otherTenants } = narrowToCaller(breaks, confinedTenant(p));
+            return { affected: visible, ...(otherTenants ? { otherTenants } : {}) };
+        };
+        const exportBreaks = acknowledge?.exportBreak ? await breaksOf() : null;
         // 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.
-        await admin.promoteVersion(c.get('actor'), slug, channel, versionId, acknowledge);
+        try {
+            await admin.promoteVersion(c.get('actor'), slug, channel, versionId, acknowledge);
+        }
+        catch (err) {
+            if (!isExportBreakRefusal(err))
+                throw err;
+            // The refusal stands whether or not the listing can be read. A listing that fails turns
+            // into a note, never into a 500 that would hide that the promote was refused.
+            const listing = await breaksOf().then((exportBreaks) => ({ exportBreaks }), (e) => ({
+                exportBreaks: null,
+                exportBreaksUnavailable: `which apps it breaks could not be read: ${e instanceof Error ? e.message : String(e)}`,
+            }));
+            return c.json({ error: listing.exportBreaks ? exportBreakRefusal(counted) : err.message, ...listing }, 409);
+        }
         // The in-place serve (#286), prod only, AFTER every promote gate has passed —
         // uploading first would deploy to live scopes before the acknowledgement check.
         // A failed serve is NOT a failed promote: the channel moved (audited), old code
         // still serves, and promoting again retries the upload.
         let backfill = { minted: [] };
+        let adopted = { refused: [] };
         if (channel === 'prod') {
             try {
                 await serveVersionInPlace(c.get('actor'), slug, versionId);
@@ -4077,7 +4389,9 @@ export function createControlPlaneApi(options) {
                 // dispatch-backed vertical (#321), in the correct order (serve → adopt → rebind),
                 // so a legacy scope's data survives the promote instead of being stranded on a
                 // fresh per-version script. Retry-safe: nothing rebound these scopes yet.
-                await adoptAndRebindOwnedScopes(c, slug, versionId);
+                // Only the export-break acknowledgement is the adopt's to carry: the digest ones are the
+                // promote's own, and a bind's strict acknowledgement refuses them (#1756).
+                adopted = await adoptAndRebindOwnedScopes(c, slug, versionId, acknowledge?.exportBreak ? { exportBreak: true } : undefined);
                 // #825: and mint whatever THIS version newly declares for the tenants already
                 // installed — after the serve, so the declaration being read is the one now live.
                 backfill = await backfillFleetStores(c, slug);
@@ -4091,6 +4405,31 @@ export function createControlPlaneApi(options) {
                 }, 502);
             }
         }
+        // #1756: served, and every install that could move has moved and been backfilled, but one
+        // still on its own version would break apps in its tenant if moved onto the serving script —
+        // a move the promote gate never judged, since that install was not on the channel's previous
+        // version. It is left where it is. Promoting again acknowledged moves it.
+        if (adopted.refused.length > 0 || adopted.refusal) {
+            const sentence = adopted.refused.length > 0 ? bindExportBreakRefusal(adopted.refused) : adopted.refusal;
+            return c.json({
+                error: `promoted and served, but an app still on its own version was not moved onto the serving script: ` +
+                    `${sentence}. Promote again with the export-break acknowledgement to move it`,
+                ...(adopted.refused.length > 0 ? { exportBreaks: { affected: adopted.refused } } : {}),
+                // Narrowed as the success answer's is: a builder never reads another tenant's id here.
+                ...(backfill.minted.length || backfill.error
+                    ? (() => {
+                        const { visible, otherTenants } = narrowToCaller(backfill.minted, confinedTenant(c.get('principal')));
+                        return {
+                            storeBackfill: {
+                                minted: visible,
+                                ...(otherTenants ? { otherTenants } : {}),
+                                ...(backfill.error ? { error: backfill.error } : {}),
+                            },
+                        };
+                    })()
+                    : {}),
+            }, 409);
+        }
         const promoted = (await admin.listChannels(c.get('actor'), slug)).find((ch) => ch.channel === channel);
         // The store backfill rides the response only when it has something to say (#825), so
         // nothing changes for the overwhelming majority of promotes — and when a store WAS
@@ -4103,12 +4442,11 @@ export function createControlPlaneApi(options) {
         // report must not be the one place that hands them the tenant ids of everyone who
         // installed their vertical. The rest is a count, which tells them the fleet was covered
         // without naming who is in it.
-        const p2 = c.get('principal');
-        const reportPin = confinedTenant(p2);
-        const visible = reportPin ? backfill.minted.filter((m) => m.tenantId === reportPin) : backfill.minted;
-        const otherTenants = new Set(backfill.minted.filter((m) => !visible.includes(m)).map((m) => m.tenantId)).size;
+        const { visible, otherTenants } = narrowToCaller(backfill.minted, confinedTenant(c.get('principal')));
         return c.json({
             ...promoted,
+            // What the acknowledged break reached, so a promoter who passed `exportBreak` reads it.
+            ...(exportBreaks ? { exportBreaks } : {}),
             ...(backfill.minted.length || backfill.error
                 ? {
                     storeBackfill: {
@@ -4566,6 +4904,8 @@ export function createControlPlaneApi(options) {
             // than somebody else's, and needs no ownership check of its own to be safe.
             scopeId: z.string().min(1).max(64).optional(),
             vertical: z.string().min(1).max(200).optional(),
+            // A coarser grouping of the same rows (#1767) — never a wider read.
+            grain: z.enum(['surface', 'scope']).optional(),
             hours: z.coerce.number().int().min(1).max(72).default(24),
             since: z.string().datetime({ offset: true }).optional(),
             until: z.string().datetime({ offset: true }).optional(),
@@ -4574,6 +4914,7 @@ export function createControlPlaneApi(options) {
             tenantId,
             scopeId: c.req.query('scopeId') || undefined,
             vertical: c.req.query('vertical') || undefined,
+            grain: c.req.query('grain') || undefined,
             hours: c.req.query('hours'), since: c.req.query('since'), until: c.req.query('until'),
         });
         try {
@@ -5240,6 +5581,8 @@ export function createControlPlaneApi(options) {
             if (existing.servingRef)
                 await admin.setScopeServingRef(actor, tenantId, existing.id, null);
             await admin.bindScopeVersion(actor, tenantId, existing.id, opts.versionId);
+            // #1674: re-assert any recorded OFF in the script the preview now routes to.
+            await admin.reassertSystemSwitches(actor, { tenantId, scopeId: existing.id });
             // Renew (or clear) the preview's GC deadline so a reused preview does not silently die.
             await admin.setScopeExpiresAt(actor, tenantId, existing.id, expiresAt);
             const hostname = await bindPreviewHostname(actor, baseHostname, tenantId, existing.id, opts.tag, surface);
@@ -5599,6 +5942,36 @@ export function createControlPlaneApi(options) {
         }
         return c.json(await admin.systemGrantsStatus(actor, { tenantId, scopeId }));
     });
+    // The fleet read (#1674): every scope with a module switched off, from the directory's
+    // record of the switch, so it needs no walk of every scope's store. The record is not the
+    // gate; the per-scope read above is where a drift between the two shows (`recorded`).
+    //
+    // **Staff and the platform service token ONLY.** Outside `/tenants/:id`, and in neither
+    // BUILDER_ROUTES nor TENANT_ROUTES, so a builder and a tenant credential are both refused
+    // by default-deny before this runs. The `confinedTenant` check is the second lock, not
+    // the first: a fleet-wide read is exactly what a confined credential must never make, and
+    // it must not start answering if this path is ever allowlisted for a narrowed read.
+    app.get('/system-switches', async (c) => {
+        if (confinedTenant(c.get('principal')) !== null) {
+            return c.json({ error: 'forbidden: the schedule switch is staff-only' }, 403);
+        }
+        const q = systemSwitchesQuery.parse({
+            position: c.req.query('position'),
+            tenantId: c.req.query('tenantId'),
+            scopeId: c.req.query('scopeId'),
+            moduleId: c.req.query('moduleId'),
+            vertical: c.req.query('vertical'),
+            limit: c.req.query('limit'),
+            cursor: c.req.query('cursor'),
+            order: c.req.query('order'),
+        });
+        const { position, ...rest } = q;
+        const entries = await admin.listSystemSwitches(c.get('actor'), {
+            ...rest,
+            ...(position === 'all' ? {} : { position }),
+        });
+        return c.json(pageOf(entries, q.limit, (e) => e.operationId));
+    });
     // -- the peer kill switch (#1706) ------------------------------------------
     //
     // One calling vertical's access to ONE scope, off and back on — `revokeFromPeer` and
@@ -5721,6 +6094,51 @@ export function createControlPlaneApi(options) {
         const entries = await admin.listSweepRuns(c.get('actor'), filter);
         return c.json(pageOf(entries, filter.limit, (e) => e.id));
     });
+    // -- the replay lever (#1705 PR 3): move a consumer's watermark on one edge ----
+    // Staff (the console) and a tenant credential (the dashboard, for someone who may manage the
+    // tenant's apps) may pull it: the edge is between two of the tenant's own apps, and what a
+    // replay runs lands in the tenant's own scope. The peer switch's posture, for that reason.
+    // Builders may not: this route is absent from BUILDER_ROUTES, which is default-deny.
+    //
+    // The acknowledgement is refused HERE with the sentence it stands for, rather than left to a
+    // Zod message about a literal. The person pulling the lever has to be told, in words, that a
+    // replay runs handlers again and repeats what they send or call outside the app.
+    app.post('/tenants/:tenantId/scopes/:scopeId/import-cursor', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const pin = confinedTenant(c.get('principal'));
+        if (pin !== null && pin !== tenantId)
+            return c.json({ error: 'forbidden' }, 403);
+        const raw = await c.req.json().catch(() => ({}));
+        const refused = importCursorAcknowledgementMissing(raw);
+        if (refused)
+            return c.json({ error: refused }, 400);
+        const move = importCursorMove.parse(raw);
+        const actor = c.get('actor');
+        // K-3 first, so a scope of another tenant reads as absent before anything is reached.
+        if (!(await admin.getScopeRecord(actor, tenantId, scopeId))) {
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        }
+        return c.json(await admin.moveImportCursor(actor, tenantId, scopeId, move));
+    });
+    // -- edge health (#1705 PR 3): where each cross-vertical edge of one tenant stands -
+    // Read live, through the phase's own reach, so it cannot disagree with the next pass about
+    // which edges exist. Staff and the tenant's own credential, tenant-pinned (the dashboard shows
+    // a tenant its own apps' edges). Builders may not: absent from BUILDER_ROUTES. `?scopeId=`
+    // narrows it to one scope's edges, so a per-app view asks nothing about the rest.
+    app.get('/tenants/:tenantId/cross-vertical/edges', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const pin = confinedTenant(c.get('principal'));
+        if (pin !== null && pin !== tenantId)
+            return c.json({ error: 'forbidden' }, 403);
+        const focus = c.req.query('scopeId');
+        return c.json(await crossVerticalHealth(host, {
+            actor: c.get('actor'),
+            tenantId,
+            ...(focus ? { focus: scopeIdSchema.parse(focus) } : {}),
+            ...(options.crossVertical ? { crossVertical: options.crossVertical } : {}),
+        }));
+    });
     // -- issues (#1233): failures grouped by fingerprint, with a lifecycle --------
     // Staff-only (absent from BUILDER_ROUTES): an issue is a fleet-scoped aggregate
     // with no tenant column, so the forced-filter posture cannot narrow it — a