@substrat-run/control-plane-api 0.147.0 → 0.148.0

package/dist/api.js

@@ -1,6 +1,7 @@
+import { PREVIEW_CONNECTIONS_REFUSAL } from './connection-relay.js';
 import { resolveObservabilityWindow } from './observability-window.js';
 import { Hono } from 'hono';
-import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ownerTransferInput, memberInviteInput, memberRoleInput, ASSET_PART_PREFIX, assetHash, 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, 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, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, operationSeriesCount, operationSeriesInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, verticalSlug, 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, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, errorCodeOf, capabilityFilterQuery, capabilityId as capabilityIdSchema, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, } from '@substrat-run/contracts';
+import { permissionKey, parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, lakeEventsInput, ownerTransferInput, memberInviteInput, memberRoleInput, ASSET_PART_PREFIX, assetHash, STORE_KINDS, STORE_RELEASE_MAX_BYTES, 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, 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, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, operationSeriesCount, operationSeriesInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, verticalSlug, 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, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, validationIssuesFrom, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, errorCodeOf, capabilityFilterQuery, capabilityId as capabilityIdSchema, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, } from '@substrat-run/contracts';
 import { SCOPE_COPY_LEASE_MS, copyRestoreFence, replayStoreErasures } from '@substrat-run/kernel';
 import { attributeFailure } from './failure-attribution.js';
 import { auditedChange, withAuditedOutcomes } from './audited-change.js';
@@ -8,8 +9,9 @@ import { BIND_EXPORT_BREAK_REFUSAL, CARRIED_AWAY_KEY, bindExportBreakRefusal, ca
 import { TENANT_HEADER, confinedTenant } from './auth.js';
 import { mintTenantToken } from './tenant-token.js';
 import { connectionGrantsForScope } from './vertical-client.js';
-import { scopeStoresOf } from './platform-scope-stores.js';
-import { assertNoUnreachableScopeCopies, listAllScopeScriptCopies, reapScopeScriptCopies, recordStrandedStorage } from './scope-copy-cleanup.js';
+import { runningVersionOf, runningVersionStoresOf, scopeStoreReachOf, scopeStoresOf, unrouteScope } from './platform-scope-stores.js';
+import { PUSH_HOLD_TTL_MS, runStoreKindRollout, storeKindRelease, storedReleaseLoader } from './store-releases.js';
+import { assertNoUnreachableScopeCopies, claimScopeScriptReap, drainScopeScriptCopies, listAllScopeScriptCopies, recordStrandedStorage } from './scope-copy-cleanup.js';
 import { BACKFILL_PAGE_MAX, backfillScopeScriptCopies } from './scope-copy-backfill.js';
 import { oidcCallbackUrl, retireClientsOfReapedScope, wirePreviewAuth } from './preview-auth.js';
 import { scopeDeployment, versionReachedAt } from './scope-deployment.js';
@@ -18,7 +20,7 @@ import { reconcileOutcomeOf, reconcileThenReassert, reviewedEntityGrants, switch
 import { ConnectionRelayError, relayConnectionUpsert } from './connection-relay.js';
 import { ControlPlaneError } from '@substrat-run/control-plane-client';
 import { provisionSiblingScope } from './platform-drain.js';
-import { mapError } from './errors.js';
+import { NON_PROBLEM_REFUSAL, coded, mapError, relayed } from './errors.js';
 import { maskDump, maskRecords } from './mask.js';
 import { createPseudonymizer } from './pseudonymize.js';
 import { openDump, sealDump } from './seal.js';
@@ -30,12 +32,30 @@ import { assertSandboxContract, verticalUploadBindings, deployManifest, storedDe
  * labelled `application/json` is not an RFC 9457 problem however well-shaped its body is,
  * and `/openapi.json` has documented `application/problem+json` on every error response
  * since phase 1 — this is the half that makes the document true.
+ *
+ * `carried` is what a route answered beside `error` before it answered a problem document
+ * (a connector's `probe`, a preview's `operationId`, …), kept verbatim so no client loses a
+ * member. RFC 9457 §3.2 permits extension members; these are not declared per code in
+ * `PROBLEM_EXTENSIONS` yet, which is why they are spelled out at each route rather than
+ * passed through by a mapper. Spread last on purpose: where a route's own `detail` meant the
+ * downstream's reason, it still does.
  */
-function problem(c, answer) {
-    return c.body(JSON.stringify(answer.body), answer.status, {
+function problem(c, answer, carried) {
+    return c.body(JSON.stringify(carried ? { ...answer.body, ...carried } : answer.body), answer.status, {
         'content-type': PROBLEM_CONTENT_TYPE,
     });
 }
+/** A refusal this route decided, by its code (#113): the status follows from the catalog. */
+function refuse(c, code, detail, carried) {
+    return problem(c, coded(code, detail), carried);
+}
+/**
+ * A refusal answered by status alone, as `about:blank`: one relayed from downstream (a
+ * `ControlPlaneError`'s status), or one the closed taxonomy has no code for (501, 422, 502).
+ */
+function refuseStatus(c, status, detail, carried) {
+    return problem(c, relayed(status, detail), carried);
+}
 import { backfillDeclaredStores, blobStoreBindings, collectBlobStoreHandles, collectTenantStoreHandles, missingStoresForTenant, tenantStoreBindings, } from './tenant-stores.js';
 import { mintPushToken, pushActorFor } from './push-token.js';
 import { TENANT_SERIES_SCOPE_CAP, REQUEST_FACET_KEYS } from './observability.js';
@@ -44,6 +64,8 @@ import { namespacesForScript } from './do-namespaces.js';
 import { backupDirectoryIfDue } from './directory-backup.js';
 import { deployedDoClasses, platformSweeperDecision } from './platform-entry.js';
 import { STORAGE_PAGE_DEFAULT, STORAGE_PAGE_MAX, readStoragePage } from './storage-meter.js';
+import { queryLakeEvents } from './lake-gateway.js';
+import { LakeQueryError } from './r2-sql-engine.js';
 import { isCustomHostname, validateBindableHostname, } from './custom-hostnames.js';
 /**
  * Response headers carrying the CLI version advisory (`ControlPlaneApiOptions.cliAdvisory`).
@@ -104,9 +126,9 @@ class CarrySourceChanged extends ControlPlaneError {
         this.attempts = attempts;
     }
 }
-/** 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 } } : {}) };
+/** What a route answers beside the sentence of an `ExportBreakRefused`: the listing. */
+function exportBreaksOf(e) {
+    return e instanceof ExportBreakRefused ? { exportBreaks: { affected: e.breaks } } : {};
 }
 /**
  * A delegated facet answer, normalized — and refused when the vertical that produced it
@@ -782,11 +804,15 @@ function messageOfThrow(err) {
 /** What a 5xx answered with no error object said: the JSON body's `error` (and `detail`), else the status. */
 async function answeredMessage(res) {
     const body = (await res.clone().json().catch(() => null));
-    const error = typeof body?.['error'] === 'string' ? body['error'] : typeof body?.['title'] === 'string' ? body['title'] : null;
-    const detail = typeof body?.['detail'] === 'string' ? body['detail'] : null;
-    if (error && detail)
+    const str = (k) => (typeof body?.[k] === 'string' && body[k] !== '' ? body[k] : null);
+    const error = str('error');
+    const detail = str('detail');
+    // A headline beside a reason (`deploy upload failed` + the upstream's sentence) reads as
+    // both. A problem document's `error` is only the deprecated duplicate of its `detail`
+    // (#113), so it adds nothing, and once it is gone `detail` alone still names the occurrence.
+    if (error && detail && error !== detail)
         return `${error}: ${detail}`;
-    return error ?? detail ?? `HTTP ${res.status}`;
+    return detail ?? error ?? str('title') ?? `HTTP ${res.status}`;
 }
 /**
  * The audited HTTP surface over `HostAdmin` (control-plane.md §4.5).
@@ -819,33 +845,62 @@ export function createControlPlaneApi(options) {
     const { host, authenticate, authenticateBuilder, authenticateTenantService } = options;
     const copyLeaseMs = options.copyLeaseMs ?? SCOPE_COPY_LEASE_MS;
     /** The stores of the version the scope's deployment runs (`scopeStoresOf`, #2207). */
-    const manifestStores = (c, scope) => scopeStoresOf(c.var.admin, c.get('actor'), scope, options.storeKinds);
+    const manifestStores = (c, scope, running) => scopeStoresOf(c.var.admin, c.get('actor'), scope, options.storeKinds, running);
     /**
      * The platform's path to a scope's stores, or nothing: no caller is a co-located host whose
      * own export, restore, wipe and erasure carry its stores, and a scope that declares none has
      * none to reach. A hosted control plane always passes a caller (`unreachablePlatformScopeStores`
      * when it has no route), so a declared store is never skipped there.
      */
-    const platformStoresOf = async (c, scope) => {
+    const platformStoresOf = async (c, scope, running) => {
         const caller = options.platformScopeStores;
         if (!caller || !scope.vertical)
             return undefined;
-        const stores = await manifestStores(c, scope);
+        const stores = await manifestStores(c, scope, running);
         return stores.length > 0 ? { caller, vertical: scope.vertical, stores } : undefined;
     };
-    /** `substrat.wipe` on each declared store, before the scope's own bytes go. */
-    const wipePlatformStores = async (c, scope) => {
+    /**
+     * `substrat.wipe` on each declared store, resolved now and called later: a reap resolves its
+     * stores, which can refuse (503), before it unroutes the scope, and wipes after (#2285).
+     */
+    const platformStoresWipe = async (c, scope) => {
         const reach = await platformStoresOf(c, scope);
-        if (!reach)
-            return;
-        await reach.caller.wipeStores({ tenantId: scope.tenantId, scopeId: scope.id, vertical: reach.vertical, stores: reach.stores });
+        return async () => {
+            if (!reach)
+                return;
+            await reach.caller.wipeStores({ tenantId: scope.tenantId, scopeId: scope.id, vertical: reach.vertical, stores: reach.stores });
+        };
     };
-    /** `substrat.export` on each declared store, for a backup, a full pull or a fork. */
+    /** `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 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
+     * dump when its export is empty, which is what an object that was never written, or one already
+     * wiped, answers. One that still holds rows refuses the export (409), naming the binding and the
+     * way out, rather than produce a dump its own scope could not restore. Wipe, reap and erasure
+     * never export, so they reach such a store regardless.
+     */
     const exportPlatformStores = async (c, scope) => {
-        const reach = await platformStoresOf(c, scope);
-        if (!reach)
+        const caller = options.platformScopeStores;
+        if (!caller || !scope.vertical)
             return undefined;
-        return reach.caller.exportStores({ tenantId: scope.tenantId, scopeId: scope.id, vertical: reach.vertical, stores: reach.stores });
+        const { running, all } = await scopeStoreReachOf(c.var.admin, c.get('actor'), scope, options.storeKinds);
+        if (all.length === 0)
+            return undefined;
+        const exported = await caller.exportStores({ tenantId: scope.tenantId, scopeId: scope.id, vertical: scope.vertical, stores: all });
+        const current = new Set(running.map((store) => store.binding));
+        const dropped = exported.filter((store) => !current.has(store.binding));
+        const held = dropped.find((store) => store.tables.some((table) => table.rows.length > 0));
+        if (held) {
+            throw new ControlPlaneError(409, `scope ${scope.id}'s store '${held.binding}' was declared by an earlier version of '${scope.vertical}' and ` +
+                `still holds data, and the version the scope runs does not declare it, so a dump of it could not be ` +
+                `restored. Declare '${held.binding}' as a '${held.kind}' again in a version the scope runs, then export; ` +
+                `or reap the scope without a backup, which wipes it`);
+        }
+        return exported.filter((store) => current.has(store.binding));
     };
     /**
      * `substrat.erase` on the destination's stores for each subject tombstoned in the destination
@@ -901,7 +956,10 @@ export function createControlPlaneApi(options) {
             return;
         if (!scope.vertical)
             throw new ControlPlaneError(422, 'restore refused: the dump names stores and the scope names no vertical');
-        const declared = new Map((await manifestStores(c, scope)).map((d) => [d.binding, d.kind]));
+        // The destination's running version only (L8): a binding only an earlier version declared
+        // would be imported into an object nothing in the code the scope runs reads.
+        const declared = new Map((await runningVersionStoresOf(c.var.admin, c.get('actor'), scope, options.storeKinds))
+            .map((d) => [d.binding, d.kind]));
         for (const store of stores) {
             const kind = declared.get(store.binding);
             if (kind === undefined) {
@@ -913,6 +971,33 @@ export function createControlPlaneApi(options) {
         }
     };
     const app = new Hono();
+    // Every refusal is a problem document (#113): the tripwire. A route answers a failure
+    // through `refuse`/`refuseStatus`/`problem`, and anything else — a hand-rolled
+    // `c.json({ error }, 4xx)`, a sub-app's text 404 — is logged here as
+    // `control-plane.non-problem-refusal` with the method, the route PATTERN (never the raw
+    // path, which carries tenant and scope ids) and the status. It reads one header and never
+    // the body, so it costs nothing on the success path and discloses nothing on the failure
+    // one. Two mechanisms hold the rule, and they cover different things: this package's test
+    // setup fails any test in which the tripwire fires, which covers every refusal a test
+    // REACHES; `test/problem-source.test.ts` scans this file, reached or not, and refuses any
+    // response it builds with a failure status outside the problem helpers — and any construct
+    // whose status it could not judge (`c.status(`, `c.newResponse(`, `c.html(`, a generic
+    // `c.json<T>(`, a `Response` init it cannot read). In production the tripwire is the line
+    // an operator searches the worker's logs for, should a client report a refusal it could
+    // not parse.
+    //
+    // Registered first, so it sees the answer every other layer settled on, `onError`'s included.
+    app.use('*', async (c, next) => {
+        await next();
+        if (c.res.status >= 400 && !(c.res.headers.get('content-type') ?? '').startsWith(PROBLEM_CONTENT_TYPE)) {
+            console.warn(NON_PROBLEM_REFUSAL, { method: c.req.method, route: c.req.routePath, status: c.res.status });
+        }
+    });
+    // A request no route matches is a refusal too, and Hono's default answers it as text. This
+    // answers only where this app is the top-level one (the node server, a self-host): Hono never
+    // calls a MOUNTED sub-app's `notFound`, so under the hosted worker's `app.route('/api', …)`
+    // the worker's own fallback still answers an unmatched path.
+    app.notFound((c) => refuse(c, 'not_found', 'no such route'));
     // The 5xx backstop: every 5xx this API answers lands an ops-failure row, however it was
     // answered. A 5xx is the PLATFORM failing (an unmapped throw, or a downstream vertical's own
     // 5xx passing through, #559), so the console must be able to list it and a `reference = <id>`
@@ -920,7 +1005,7 @@ export function createControlPlaneApi(options) {
     // that catch a ControlPlaneError and answer it themselves: a preview re-push whose bind failed
     // after a clean carry answered 502 with a reference and left no row behind.
     //
-    // Registered first, so it wraps every other middleware and route. 501 stays out: an honest
+    // Registered ahead of every middleware but the tripwire, so it wraps every route. 501 stays out: an honest
     // not-implemented is a capability statement, not a failure. 4xx stay out too: they are
     // refusals the caller can already read. Actor is unset only when the request failed before
     // authentication, where nothing worth recording refuses. A throw a step already recorded,
@@ -1013,7 +1098,7 @@ export function createControlPlaneApi(options) {
             }
         }
         if (!principal)
-            return c.json({ error: 'unauthenticated' }, 401);
+            return refuse(c, 'unauthenticated', 'unauthenticated');
         c.set('principal', principal);
         c.set('actor', principal.actor);
         // #977: a tenant credential minted for a person writes through a view that names
@@ -1127,7 +1212,7 @@ export function createControlPlaneApi(options) {
         if (c.get('principal').kind === 'builder') {
             const allowed = BUILDER_ROUTES.some((r) => r.method === c.req.method && r.re.test(c.req.path));
             if (!allowed)
-                return c.json({ error: 'forbidden' }, 403);
+                return refuse(c, 'forbidden', 'forbidden');
         }
         await next();
     });
@@ -1137,25 +1222,25 @@ export function createControlPlaneApi(options) {
             return next();
         const pin = tenantCredentialPin(c.req.method, c.req.path);
         if (!pin)
-            return c.json({ error: 'forbidden' }, 403);
+            return refuse(c, 'forbidden', 'forbidden');
         // The sweep: anything naming a tenant must name THIS one. `x-substrat-tenant` is
         // included, which is what stops the pre-#977 shape — a fleet credential plus a
         // caller-asserted tenant header — from surviving as a way to ask for another.
         if (namedTenants(c).some((t) => t !== p.tenantId)) {
-            return c.json({ error: 'forbidden: outside this credential’s tenant' }, 403);
+            return refuse(c, 'forbidden', 'forbidden: outside this credential’s tenant');
         }
         // The route's own pin must be PRESENT, not merely consistent. A missing filter is
         // what makes these routes answer fleet-wide, so absence is the refusal.
         if (pin === 'path' && pathTenant(c.req.path) !== p.tenantId) {
-            return c.json({ error: 'forbidden: outside this credential’s tenant' }, 403);
+            return refuse(c, 'forbidden', 'forbidden: outside this credential’s tenant');
         }
         if (pin === 'query' && c.req.query('tenantId') !== p.tenantId) {
-            return c.json({ error: 'forbidden: this credential must name its own tenant' }, 403);
+            return refuse(c, 'forbidden', 'forbidden: this credential must name its own tenant');
         }
         if (pin === 'catalog') {
             const named = c.req.query('ownerTenant') ?? c.req.query('visibleTo');
             if (named !== p.tenantId) {
-                return c.json({ error: 'forbidden: this credential must name its own tenant' }, 403);
+                return refuse(c, 'forbidden', 'forbidden: this credential must name its own tenant');
             }
         }
         if (pin === 'body') {
@@ -1165,7 +1250,7 @@ export function createControlPlaneApi(options) {
             const body = (await c.req.json().catch(() => null));
             const named = body && typeof body === 'object' ? (body['tenantId'] ?? body['id']) : undefined;
             if (named !== p.tenantId) {
-                return c.json({ error: 'forbidden: this credential must name its own tenant' }, 403);
+                return refuse(c, 'forbidden', 'forbidden: this credential must name its own tenant');
             }
         }
         await next();
@@ -1235,6 +1320,8 @@ export function createControlPlaneApi(options) {
         c.set('failure', e);
         return e.status;
     };
+    /** A caught `ControlPlaneError` answered as itself — its status and sentence, `about:blank` — and marked for the backstop. */
+    const relayRefusal = (c, e, carried) => refuseStatus(c, failedWith(c, e), e.message, carried);
     // Rides out a transient downstream window: the install path's binding-attach →
     // script-settings propagation race (#424 case 2), and a one-shot DO storage blip
     // during an export→restore or snapshot copy (#559 (2)). Retrying is cheap at THESE
@@ -1272,9 +1359,9 @@ export function createControlPlaneApi(options) {
             return problem(c, { status: 400, body: toProblem(err, c.req.path) });
         }
         if (err instanceof ExportBreakRefused)
-            return c.json(exportBreakBody(err), 409);
+            return refuse(c, 'conflict', err.message, exportBreaksOf(err));
         if (err instanceof CarrySourceChanged) {
-            return c.json({ error: err.message, carrySourceChanged: { scopeId: err.scopeId, from: err.from, to: err.to, attempts: err.attempts } }, 409);
+            return refuse(c, 'conflict', err.message, { carrySourceChanged: { scopeId: err.scopeId, from: err.from, to: err.to, attempts: err.attempts } });
         }
         const { status, body } = mapError(err);
         // The 5xx backstop (registered first, above) records it, with this throw as the cause.
@@ -1318,7 +1405,7 @@ export function createControlPlaneApi(options) {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const tenant = await c.var.admin.getTenant(c.get('actor'), tenantId);
         if (!tenant)
-            return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
+            return refuse(c, 'not_found', `unknown tenant: ${tenantId}`);
         return c.json(tenant);
     });
     // Display rename only — the slug stays put (registry ids `<tenantSlug>/<name>` and
@@ -1355,11 +1442,9 @@ export function createControlPlaneApi(options) {
         const { backup: wantsBackup } = await readJsonBody(c, reapScopeBody);
         const tenant = await c.var.admin.getTenant(actor, tenantId);
         if (!tenant)
-            return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
+            return refuse(c, 'not_found', `unknown tenant: ${tenantId}`);
         if (tenant.status !== 'deleting') {
-            return c.json({
-                error: `tenant ${tenantId} is ${tenant.status}, not deleting — only a deleting tenant may be reaped`,
-            }, 409);
+            return refuse(c, 'conflict', `tenant ${tenantId} is ${tenant.status}, not deleting — only a deleting tenant may be reaped`);
         }
         try {
             for (const scope of await c.var.admin.listScopes(actor, { tenantId })) {
@@ -1390,7 +1475,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -1412,10 +1497,10 @@ export function createControlPlaneApi(options) {
             // `builder`, a plan-gated feature, a key no vertical asked for. And never the plan
             // half: an expiry, a quota or a plan name is pricing, which is not the tenant's.
             if (plan.expiresAt != null || plan.quota != null || plan.plan != null) {
-                return c.json({ error: 'a tenant credential grants entitlements without plan fields' }, 403);
+                return refuse(c, 'forbidden', 'a tenant credential grants entitlements without plan fields');
             }
             if (!(await tenantGrantable(p, key))) {
-                return c.json({ error: `entitlement '${key}' is not declared by a vertical this tenant can install` }, 403);
+                return refuse(c, 'forbidden', `entitlement '${key}' is not declared by a vertical this tenant can install`);
             }
         }
         await c.var.admin.grantEntitlement(c.get('actor'), tenantId, key, plan);
@@ -1666,7 +1751,7 @@ export function createControlPlaneApi(options) {
     // worse this week" is the question it exists for.
     app.get('/connections/calls', async (c) => {
         if (!options.observability?.connectorCallsSeries) {
-            return c.json({ error: 'connector-call analytics are not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'connector-call analytics are not configured on this control plane');
         }
         const input = z
             .object({
@@ -1683,7 +1768,7 @@ export function createControlPlaneApi(options) {
     // credential can reach only this path, never the fleet-wide sibling above.
     app.get('/tenants/:tenantId/connections/calls', async (c) => {
         if (!options.observability?.connectorCallsSeries) {
-            return c.json({ error: 'connector-call analytics are not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'connector-call analytics are not configured on this control plane');
         }
         const input = z.object({
             tenantId: tenantIdSchema,
@@ -1780,7 +1865,7 @@ export function createControlPlaneApi(options) {
         const raw = await c.req.json();
         const body = typeof raw === 'object' && raw !== null ? raw : {};
         if (body.tenantId !== undefined && body.tenantId !== tenantId) {
-            return c.json({ error: 'body tenantId disagrees with the route tenant' }, 400);
+            return refuse(c, 'validation_failed', 'body tenantId disagrees with the route tenant');
         }
         try {
             return c.json(await relayConnectionUpsert(c.var.host, c.get('actor'), { ...body, tenantId }, { probeCandidate, prepareCandidate }));
@@ -1789,7 +1874,7 @@ export function createControlPlaneApi(options) {
             if (err instanceof ConnectionRelayError && err.status < 500) {
                 // A refusal carries the provider's own answer, so a console can show WHY rather
                 // than "save failed" — the whole point of checking before writing.
-                return c.json({ error: err.message, ...(err.probe ? { probe: err.probe } : {}) }, err.status);
+                return refuseStatus(c, err.status, err.message, err.probe ? { probe: err.probe } : undefined);
             }
             // A 5xx relay refusal (#603: this deployment holds no seal key) is the PLATFORM
             // failing, not the caller — rethrown so the shared boundary maps it (still a 503
@@ -1808,7 +1893,7 @@ export function createControlPlaneApi(options) {
         const rows = await c.var.admin.listConnections(c.get('actor'), { tenantId, includeRevoked: true });
         const row = rows.find((r) => r.id === id);
         if (!row)
-            return c.json({ error: 'unknown connection' }, 404);
+            return refuse(c, 'not_found', 'unknown connection');
         if (row.status !== 'revoked')
             await c.var.admin.revokeConnection(c.get('actor'), row.id);
         return c.body(null, 204);
@@ -1846,7 +1931,7 @@ export function createControlPlaneApi(options) {
             scopeId,
             id: connectLinkId.parse(c.req.param('linkId')),
         });
-        return link ? c.json(link) : c.json({ error: 'unknown connect link' }, 404);
+        return link ? c.json(link) : refuse(c, 'not_found', 'unknown connect link');
     });
     // The callback's spend. A refusal is a 200 carrying the typed reason, not an error status:
     // "already used" is the answer to the question asked, and the callback renders each one.
@@ -1885,7 +1970,7 @@ export function createControlPlaneApi(options) {
             scopeId,
             id: connectLinkId.parse(c.req.param('linkId')),
         });
-        return link ? c.body(null, 204) : c.json({ error: 'unknown connect link' }, 404);
+        return link ? c.body(null, 204) : refuse(c, 'not_found', 'unknown connect link');
     });
     /**
      * The tenant-scoped connection lookup the two inspection routes share. Same K-3
@@ -1907,6 +1992,79 @@ export function createControlPlaneApi(options) {
         const rows = await c.var.admin.listConnections(c.get('actor'), { tenantId });
         return rows.find((r) => r.id === id);
     };
+    // Staff/service only: deliberately absent from BUILDER_ROUTES and TENANT_ROUTES.
+    // No generic connector-state write and no grant escalation: the connector verifies the
+    // scope's delivered permission again before writing its own binding record.
+    app.get('/tenants/:tenantId/connections/:id/bindings', async (c) => {
+        const row = await inspectableConnection(c);
+        if (!row)
+            return refuse(c, 'not_found', 'unknown connection');
+        const read = options.connectionInspectors?.[row.provider]?.bindings;
+        if (!read)
+            return refuseStatus(c, 501, `no scope binding registered for provider '${row.provider}'`);
+        const bindings = await read(c.var.host, row);
+        return c.json(await Promise.all(bindings.map(async (binding) => {
+            const scope = scopeIdSchema.parse(binding.scopeId);
+            try {
+                const grants = await c.var.host.connectionGrantsInScope(row.tenantId, scope);
+                return { ...binding, permissionHeld: grants.some((g) => g.connectionId === row.id && g.permission === binding.permission), permissionInspectionError: undefined };
+            }
+            catch (error) {
+                // A stored target remains inspectable when its scope is inactive or its
+                // deployment is unavailable. Unknown authority must not read as a missing grant.
+                return { ...binding, permissionHeld: undefined, permissionInspectionError: error instanceof Error ? error.message : String(error) };
+            }
+        })));
+    });
+    app.put('/tenants/:tenantId/connections/:id/bindings/:scopeId', async (c) => {
+        const row = await inspectableConnection(c);
+        if (!row)
+            return refuse(c, 'not_found', 'unknown connection');
+        const bind = options.connectionInspectors?.[row.provider]?.bindScope;
+        if (!bind)
+            return refuseStatus(c, 501, `no scope binding registered for provider '${row.provider}'`);
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const target = await c.var.admin.getScopeRecord(c.get('actor'), row.tenantId, scopeId);
+        if (!target)
+            return refuse(c, 'not_found', 'unknown scope');
+        if (!isPrimaryScope(target))
+            return refuseStatus(c, 403, PREVIEW_CONNECTIONS_REFUSAL);
+        if (target.status !== 'active' || !target.vertical || target.vertical !== row.vertical) {
+            return refuseStatus(c, 409, 'connection and target must share an active vertical scope');
+        }
+        const fields = {
+            operation: z.string().regex(/^[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+$/),
+            permission: permissionKey,
+        };
+        const schema = row.provider === 'planima'
+            ? z.object({ ...fields,
+                organizationId: z.number().int().positive().nullable().optional(),
+                currency: z.string().regex(/^[A-Z]{3}$/).optional(),
+                window: z.object({ fromYear: z.number().int(), toYear: z.number().int() })
+                    .refine((w) => w.toYear >= w.fromYear, 'window ends before it starts').nullable().optional(),
+                horizonYears: z.number().int().min(0).optional(),
+            }).strict()
+            : z.object(fields).strict();
+        const input = schema.parse(await c.req.json());
+        const grants = await c.var.host.connectionGrantsInScope(row.tenantId, scopeId);
+        if (!grants.some((g) => g.connectionId === row.id && g.permission === input.permission)) {
+            return refuseStatus(c, 409, `connection does not hold '${input.permission}' on scope ${scopeId}; grant it through the tenant's authorized connection flow, then bind`);
+        }
+        const operationId = ulid();
+        const done = await auditedChange({
+            flow: 'connection-binding', operationId,
+            run: () => bind(c.var.host, row, { ...input, tenantId: row.tenantId, scopeId, vertical: target.vertical }),
+            refused: () => false,
+            record: (phase) => c.var.admin.recordConnectionBindingChange(c.get('actor'), {
+                tenantId: row.tenantId, scopeId, connectionId: row.id, provider: row.provider,
+                ...input,
+                operationId, ...(phase.phase === 'applied' ? { phase: 'applied' } : phase),
+            }),
+        });
+        if ('error' in done)
+            throw done.error;
+        return c.json({ ...done.result, permissionHeld: true, ...('unrecorded' in done ? { auditWarning: done.unrecorded } : {}) });
+    });
     /**
      * **Verify a credential against the provider** (#605) — the read that turns "stored"
      * into "works, and for this account".
@@ -1924,10 +2082,10 @@ export function createControlPlaneApi(options) {
     app.post('/tenants/:tenantId/connections/:id/verify', async (c) => {
         const row = await inspectableConnection(c);
         if (!row)
-            return c.json({ error: 'unknown connection' }, 404);
+            return refuse(c, 'not_found', 'unknown connection');
         const probe = options.connectionInspectors?.[row.provider]?.probe;
         if (!probe) {
-            return c.json({ error: `no probe registered for provider '${row.provider}'` }, 501);
+            return refuseStatus(c, 501, `no probe registered for provider '${row.provider}'`);
         }
         return c.json(connectionProbe.parse(await probe(c.var.host, row)));
     });
@@ -1946,10 +2104,10 @@ export function createControlPlaneApi(options) {
     app.get('/tenants/:tenantId/connections/:id/activity', async (c) => {
         const row = await inspectableConnection(c);
         if (!row)
-            return c.json({ error: 'unknown connection' }, 404);
+            return refuse(c, 'not_found', 'unknown connection');
         const activity = options.connectionInspectors?.[row.provider]?.activity;
         if (!activity) {
-            return c.json({ error: `no activity view registered for provider '${row.provider}'` }, 501);
+            return refuseStatus(c, 501, `no activity view registered for provider '${row.provider}'`);
         }
         const source = connectionActivitySource.catch('ledger').parse(c.req.query('source'));
         const live = c.req.query('live') === '1';
@@ -1967,10 +2125,10 @@ export function createControlPlaneApi(options) {
     app.get('/tenants/:tenantId/connections/:id/credential', async (c) => {
         const row = await inspectableConnection(c);
         if (!row)
-            return c.json({ error: 'unknown connection' }, 404);
+            return refuse(c, 'not_found', 'unknown connection');
         const credential = options.connectionInspectors?.[row.provider]?.credential;
         if (!credential) {
-            return c.json({ error: `no credential view registered for provider '${row.provider}'` }, 501);
+            return refuseStatus(c, 501, `no credential view registered for provider '${row.provider}'`);
         }
         return c.json(connectionCredential.parse(await credential(c.var.host, row)));
     });
@@ -1982,10 +2140,10 @@ export function createControlPlaneApi(options) {
     app.get('/tenants/:tenantId/connections/:id/certificate', async (c) => {
         const row = await inspectableConnection(c);
         if (!row)
-            return c.json({ error: 'unknown connection' }, 404);
+            return refuse(c, 'not_found', 'unknown connection');
         const certificate = await options.connectionInspectors?.[row.provider]?.certificate?.(c.var.host, row);
         if (!certificate)
-            return c.json({ error: 'this connection signs in with no certificate' }, 404);
+            return refuse(c, 'not_found', 'this connection signs in with no certificate');
         return c.json(connectionCertificate.parse(certificate));
     });
     // -- the scope directory (§3.2/§4.2) ---------------------------------------
@@ -2043,7 +2201,7 @@ export function createControlPlaneApi(options) {
         // A builder acts only within its own tenant; a foreign tenant is hidden as 404 (K-3),
         // never distinguished from "no such scope".
         if (outsideTenant(p, tenantId)) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${input.parentScopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${input.parentScopeId})`);
         }
         // The provisioning sequence lives in one place — `provisionSiblingScope` — shared with the
         // platform-intent drain's `provision-sibling` handler (platform-intents.md B2).
@@ -2057,12 +2215,12 @@ export function createControlPlaneApi(options) {
                 owner: input.owner,
             });
             if (!result.ok)
-                return c.json({ error: result.error }, result.status);
+                return refuseStatus(c, result.status, result.error);
             return c.json(await c.var.admin.getScopeRecord(actor, tenantId, input.scopeId), 201);
         }
         catch (e) {
             if (e instanceof ControlPlaneError)
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             throw e;
         }
     });
@@ -2072,12 +2230,12 @@ export function createControlPlaneApi(options) {
         // A builder reads only its own tenant; a foreign tenant is hidden as 404 (K-3).
         const p = c.get('principal');
         if (outsideTenant(p, tenantId)) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const record = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         // Absent, or present under another tenant — indistinguishable on purpose (K-3).
         if (!record)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(record);
     });
     // Read-only introspection of a scope's own database (kernel-design §5.4 admin-query
@@ -3023,7 +3181,7 @@ export function createControlPlaneApi(options) {
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'listScopeTables', null, {
             viaVertical: (v) => v.listScopeTables(scopeId),
             colocated: () => c.var.admin.listScopeTables(c.get('actor'), tenantId, scopeId),
@@ -3053,11 +3211,11 @@ export function createControlPlaneApi(options) {
         // A builder reads only its own tenant; a foreign tenant is hidden as 404 (K-3).
         const principal = c.get('principal');
         if (outsideTenant(principal, tenantId)) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         // Health reads the scope the same way the Data view does, so it leaves the same
         // row: an auditor should not be able to tell which route reached the tables.
         const tables = await delegatedRead(c, tenantId, scopeId, scope, 'listScopeTables', null, {
@@ -3105,7 +3263,7 @@ export function createControlPlaneApi(options) {
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const principal = c.get('principal');
         if (outsideTenant(principal, tenantId)) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const filter = platformRequestFilter.parse({
             kind: c.req.query('kind'),
@@ -3114,7 +3272,7 @@ export function createControlPlaneApi(options) {
         });
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         // Same delegation ladder as the table reads: the intents live in the DO of the scope's BOUND
         // version, so a hosted scope is asked through its vertical and a co-located one locally.
         const vertical = await verticalForScope(c, scope);
@@ -3135,17 +3293,17 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const p = c.get('principal');
         const scopePin = confinedTenant(p);
         if (scopePin) {
             const v = scope.vertical ? await verticalOf(actor, scope.vertical) : undefined;
             if (!v || v.ownerTenant !== scopePin)
-                return c.json({ error: 'forbidden' }, 403);
+                return refuse(c, 'forbidden', 'forbidden');
         }
         const reached = await deploymentForScope(c, scope);
         if (!reached)
-            return c.json({ error: await diagnoseUnboundScope(c.get('actor'), scope) }, 501);
+            return refuseStatus(c, 501, await diagnoseUnboundScope(c.get('actor'), scope));
         const vertical = reached.client;
         const entitlements = await c.var.admin.listEntitlements(actor, tenantId);
         // #406: re-gathered and re-delivered like entitlements, so a reconcile also repairs a
@@ -3299,7 +3457,7 @@ export function createControlPlaneApi(options) {
                 // unbound store is exactly what makes a vertical refuse its own reconcile), so
                 // it must not be the half that gets dropped.
                 const detail = storeErrors.length ? `${e.message} (stores: ${storeErrors.join('; ')})` : e.message;
-                return c.json({ error: detail }, failedWith(c, e));
+                return refuseStatus(c, failedWith(c, e), detail);
             }
             throw e;
         }
@@ -3321,7 +3479,7 @@ export function createControlPlaneApi(options) {
         });
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'facetEvents', input, {
             // #1762: only the vertical's answer needs the guard. The co-located read runs
             // this platform's own kernel, which withholds by construction.
@@ -3390,7 +3548,7 @@ export function createControlPlaneApi(options) {
         });
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'eventCause', input, {
             viaVertical: (v) => v.eventCause(scopeId, input),
             colocated: () => c.var.admin.eventCause(c.get('actor'), tenantId, scopeId, input),
@@ -3406,7 +3564,7 @@ export function createControlPlaneApi(options) {
         });
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'eventEffects', input, {
             viaVertical: (v) => v.eventEffects(scopeId, input),
             colocated: () => c.var.admin.eventEffects(c.get('actor'), tenantId, scopeId, input),
@@ -3423,7 +3581,7 @@ export function createControlPlaneApi(options) {
         });
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'invocationEvents', input, {
             viaVertical: (v) => v.invocationEvents(scopeId, input),
             colocated: () => c.var.admin.invocationEvents(c.get('actor'), tenantId, scopeId, input),
@@ -3440,7 +3598,7 @@ export function createControlPlaneApi(options) {
         });
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'deadLetters', input, {
             viaVertical: (v) => v.deadLetters(scopeId, input),
             colocated: () => c.var.admin.deadLetters(c.get('actor'), tenantId, scopeId, input),
@@ -3455,7 +3613,7 @@ export function createControlPlaneApi(options) {
         const input = lifecycleFlowInput.parse(await c.req.json());
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'lifecycleFlow', input, {
             viaVertical: (v) => v.lifecycleFlow(scopeId, input),
             colocated: () => c.var.admin.lifecycleFlow(c.get('actor'), tenantId, scopeId, input),
@@ -3470,7 +3628,7 @@ export function createControlPlaneApi(options) {
         const input = operationSeriesInput.parse(await c.req.json());
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'operationSeries', input, {
             viaVertical: (v) => v.operationSeries(scopeId, input),
             colocated: () => c.var.admin.operationSeries(c.get('actor'), tenantId, scopeId, input),
@@ -3490,7 +3648,7 @@ export function createControlPlaneApi(options) {
         });
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'entityHistory', input, {
             viaVertical: (v) => v.entityHistory(scopeId, input),
             colocated: () => c.var.admin.entityHistory(c.get('actor'), tenantId, scopeId, input),
@@ -3506,7 +3664,7 @@ export function createControlPlaneApi(options) {
         });
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'readScopeTable', input, {
             viaVertical: (v) => v.readScopeTable(scopeId, input),
             colocated: () => c.var.admin.readScopeTable(c.get('actor'), tenantId, scopeId, input),
@@ -3523,7 +3681,7 @@ export function createControlPlaneApi(options) {
         const input = queryScopeInput.parse(await c.req.json());
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(
         // The SQL is the argument the co-located branch logs, so it is the argument
         // here — an audit row for the read-only console that did not carry the
@@ -3549,12 +3707,12 @@ export function createControlPlaneApi(options) {
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const principal = c.get('principal');
         if (outsideTenant(principal, tenantId)) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const filter = denialLogQuery.parse(c.req.query());
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'listDenials', filter, {
             viaVertical: (v) => v.listDenials(scopeId, filter),
             colocated: () => c.var.admin.listDenials(c.get('actor'), tenantId, scopeId, filter),
@@ -3565,12 +3723,12 @@ export function createControlPlaneApi(options) {
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const principal = c.get('principal');
         if (outsideTenant(principal, tenantId)) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const filter = denialLogQuery.parse(c.req.query());
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'summarizeDenials', filter, {
             viaVertical: (v) => v.summarizeDenials(scopeId, filter),
             colocated: () => c.var.admin.summarizeDenials(c.get('actor'), tenantId, scopeId, filter),
@@ -3583,14 +3741,14 @@ export function createControlPlaneApi(options) {
     // does not rest on which list the route is absent from. Delegated like the denial log.
     app.get('/tenants/:tenantId/scopes/:scopeId/capabilities', async (c) => {
         if (confinedTenant(c.get('principal')) !== null) {
-            return c.json({ error: 'forbidden: the capability directory is staff-only' }, 403);
+            return refuse(c, 'forbidden', 'forbidden: the capability directory is staff-only');
         }
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const filter = capabilityFilterQuery.parse(c.req.query());
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return c.json(await delegatedRead(c, tenantId, scopeId, scope, 'listCapabilities', filter, {
             viaVertical: (v) => v.listCapabilities(scopeId, filter),
             colocated: () => c.var.admin.listCapabilities(c.get('actor'), tenantId, scopeId, filter),
@@ -3604,7 +3762,7 @@ export function createControlPlaneApi(options) {
     // the scope does not hold is 404; a deployment built before the far end answers 501 "redeploy".
     app.post('/tenants/:tenantId/scopes/:scopeId/capabilities/:capabilityId/revoke', async (c) => {
         if (confinedTenant(c.get('principal')) !== null) {
-            return c.json({ error: 'forbidden: revoking a capability is staff-only' }, 403);
+            return refuse(c, 'forbidden', 'forbidden: revoking a capability is staff-only');
         }
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -3625,20 +3783,20 @@ export function createControlPlaneApi(options) {
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const principal = c.get('principal');
         if (outsideTenant(principal, tenantId)) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const vertical = await verticalForScope(c, scope);
         if (!vertical)
-            return c.json({ error: await diagnoseUnboundScope(c.get('actor'), scope) }, 501);
+            return refuseStatus(c, 501, await diagnoseUnboundScope(c.get('actor'), scope));
         try {
             return c.json(await vertical.ownerSeat(tenantId, scopeId));
         }
         catch (e) {
             if (e instanceof ControlPlaneError)
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             throw e;
         }
     });
@@ -3660,25 +3818,25 @@ export function createControlPlaneApi(options) {
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const principal = c.get('principal');
         if (outsideTenant(principal, tenantId)) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const vertical = await verticalForScope(c, scope);
         if (!vertical)
-            return c.json({ error: await diagnoseUnboundScope(actor, scope) }, 501);
+            return refuseStatus(c, 501, await diagnoseUnboundScope(actor, scope));
         const origin = await instanceOrigin(c.var.admin, actor, scopeId);
         if (!origin) {
-            return c.json({ error: `scope ${scopeId} has no hostname bound — a claim link needs an address to open on` }, 409);
+            return refuse(c, 'conflict', `scope ${scopeId} has no hostname bound — a claim link needs an address to open on`);
         }
         try {
             return c.json(await vertical.mintOwnerClaim({ tenantId, scopeId, origin, actor }), 201);
         }
         catch (e) {
             if (e instanceof ControlPlaneError)
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             throw e;
         }
     });
@@ -3706,10 +3864,10 @@ export function createControlPlaneApi(options) {
         // K-3: another tenant's pair, or no such scope, reads the same — absent.
         const scope = outsideTenant(principal, tenantId) ? null : await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return { refusal: c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404) };
+            return { refusal: refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`) };
         const vertical = await verticalForScope(c, scope);
         if (!vertical)
-            return { refusal: c.json({ error: await diagnoseUnboundScope(actor, scope) }, 501) };
+            return { refusal: refuseStatus(c, 501, await diagnoseUnboundScope(actor, scope)) };
         return { tenantId, scopeId, actor, vertical, person: memberPerson(principal) };
     };
     /**
@@ -3724,7 +3882,7 @@ export function createControlPlaneApi(options) {
         const { operationId } = done;
         if ('error' in done) {
             if (done.error instanceof ControlPlaneError) {
-                return c.json({ error: done.error.message, operationId }, failedWith(c, done.error));
+                return relayRefusal(c, done.error, { operationId });
             }
             throw done.error;
         }
@@ -3763,7 +3921,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError)
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             throw e;
         }
     });
@@ -3772,11 +3930,11 @@ export function createControlPlaneApi(options) {
         if ('refusal' in target)
             return target.refusal;
         if (!target.person)
-            return c.json({ error: NO_PERSON }, 403);
+            return refuse(c, 'forbidden', NO_PERSON);
         const body = memberInviteInput.parse(await c.req.json());
         const origin = await instanceOrigin(c.var.admin, target.actor, target.scopeId);
         if (!origin) {
-            return c.json({ error: `scope ${target.scopeId} has no hostname bound — an invite link needs an address to open on` }, 409);
+            return refuse(c, 'conflict', `scope ${target.scopeId} has no hostname bound — an invite link needs an address to open on`);
         }
         const { tenantId, scopeId, person } = target;
         const done = await auditedMemberChange(c, { tenantId, scopeId, change: 'invite', caller: person, roleKey: body.roleKey }, () => target.vertical.inviteMember({ tenantId, scopeId, caller: person, origin, roleKey: body.roleKey, email: body.email ?? null }), (link) => ({ principal: link.principal }));
@@ -3787,7 +3945,7 @@ export function createControlPlaneApi(options) {
         if ('refusal' in target)
             return target.refusal;
         if (!target.person)
-            return c.json({ error: NO_PERSON }, 403);
+            return refuse(c, 'forbidden', NO_PERSON);
         const member = principalIdSchema.parse(c.req.param('principal'));
         const body = memberRoleInput.parse(await c.req.json());
         const { tenantId, scopeId, person } = target;
@@ -3799,7 +3957,7 @@ export function createControlPlaneApi(options) {
         if ('refusal' in target)
             return target.refusal;
         if (!target.person)
-            return c.json({ error: NO_PERSON }, 403);
+            return refuse(c, 'forbidden', NO_PERSON);
         const member = principalIdSchema.parse(c.req.param('principal'));
         const { tenantId, scopeId, person } = target;
         const done = await auditedMemberChange(c, { tenantId, scopeId, change: 'remove', caller: person, principal: member }, () => target.vertical.removeMember({ tenantId, scopeId, caller: person, principal: member }), (removal) => ({ revoked: removal.revoked }));
@@ -3817,7 +3975,7 @@ export function createControlPlaneApi(options) {
     // and a team credential cannot show it is that person asking.
     app.post('/tenants/:tenantId/scopes/:scopeId/owner-transfer', async (c) => {
         if (confinedTenant(c.get('principal')) !== null) {
-            return c.json({ error: 'forbidden: an owner hand-over is staff-only' }, 403);
+            return refuse(c, 'forbidden', 'forbidden: an owner hand-over is staff-only');
         }
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -3826,10 +3984,10 @@ export function createControlPlaneApi(options) {
         // K-3 first, so a scope of another tenant reads as absent before anything is reached.
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const vertical = await verticalForScope(c, scope);
         if (!vertical)
-            return c.json({ error: await diagnoseUnboundScope(actor, scope) }, 501);
+            return refuseStatus(c, 501, await diagnoseUnboundScope(actor, scope));
         const operationId = ulid();
         // An abandon (`abandon: true`) is audited the same way, every row marked, so the log tells
         // a hand-over closed without finishing from one that finished.
@@ -3862,17 +4020,17 @@ export function createControlPlaneApi(options) {
         const input = configureInstanceBody.parse(await c.req.json());
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const vertical = await verticalForScope(c, scope);
         if (!vertical) {
-            return c.json({ error: await diagnoseUnboundScope(c.get('actor'), scope) }, 501);
+            return refuseStatus(c, 501, await diagnoseUnboundScope(c.get('actor'), scope));
         }
         try {
             await vertical.configureInstance({ tenantId, scopeId, entries: input.entries });
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -3929,7 +4087,7 @@ export function createControlPlaneApi(options) {
                             message: error,
                         }, failure.cause);
                         c.set('failureRecorded', true);
-                        return c.json({ error }, 503);
+                        return refuse(c, 'unavailable', error);
                     }
                 }
             }
@@ -4065,7 +4223,7 @@ export function createControlPlaneApi(options) {
         const body = snapshotScopeBody.parse(await c.req.json().catch(() => ({})));
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         try {
             const { snapId, replay } = await orchestratedSnapshot(c, tenantId, scope, body);
             const record = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, snapId);
@@ -4074,7 +4232,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -4120,9 +4278,20 @@ export function createControlPlaneApi(options) {
      */
     const reapScopeStorage = async (c, scope) => {
         const actor = c.get('actor');
+        const dispatch = options.resolveVerticalRef;
+        // #2285: every refusal that can be decided up front comes before anything is destroyed, the
+        // unroute included: a refused reap leaves the scope routed and whole. Then unroute, wipe, delete.
+        if (dispatch)
+            await claimScopeScriptReap({ admin: c.var.admin, actor }, scope.tenantId, scope.id);
+        else
+            await assertNoUnreachableScopeCopies(c.var.admin, actor, scope.tenantId, scope.id);
+        const wipeStores = await platformStoresWipe(c, scope);
+        // Stop routing before the wipe: a call that lands between the wipe and the delete would
+        // recreate the store object, and nothing left could reach it.
+        await unrouteScope(c.var.admin, actor, scope);
         // #2207: the stores first, on every path below: a routed scope's copies are reaped through
         // their scripts, and a store is per scope, not per script.
-        await wipePlatformStores(c, scope);
+        await wipeStores();
         // The deployment the scope's vertical resolves to, deleted through; a 501 there is recorded
         // as stranded storage, as `reapScopeScriptCopies` records its own.
         const viaDeployment = async () => {
@@ -4132,13 +4301,11 @@ export function createControlPlaneApi(options) {
             }
             return stranded;
         };
-        if (!options.resolveVerticalRef) {
-            await assertNoUnreachableScopeCopies(c.var.admin, actor, scope.tenantId, scope.id);
+        if (!dispatch)
             return viaDeployment();
-        }
-        const unrouted = (await routeOf(c, scope)) === null;
-        const { storageStranded } = await reapScopeScriptCopies({ admin: c.var.admin, actor, resolveRef: options.resolveVerticalRef }, scope.tenantId, scope.id);
-        const bySlug = unrouted ? await viaDeployment() : false;
+        const noScript = (await routeOf(c, scope)) === null;
+        const { storageStranded } = await drainScopeScriptCopies({ admin: c.var.admin, actor, resolveRef: dispatch }, scope.tenantId, scope.id);
+        const bySlug = noScript ? await viaDeployment() : false;
         return storageStranded || bySlug;
     };
     app.delete('/tenants/:tenantId/scopes/:scopeId', async (c) => {
@@ -4147,9 +4314,9 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         if (!scope.forkedFrom) {
-            return c.json({ error: `scope ${scopeId} is not a fork — only snapshots may be deleted` }, 409);
+            return refuse(c, 'conflict', `scope ${scopeId} is not a fork — only snapshots may be deleted`);
         }
         try {
             // Vertical's storage first, then the in-process delete (refusal re-check,
@@ -4162,7 +4329,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -4211,12 +4378,12 @@ export function createControlPlaneApi(options) {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         if (!options.scopeBackups)
-            return c.json({ error: 'no backup target configured' }, 501);
+            return refuseStatus(c, 501, 'no backup target configured');
         // Reads the directory, not the store, for the tenant cross-check: the store is keyed
         // by (tenant, scope) but nothing there proves the caller's tenant owns the scope.
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            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
@@ -4227,13 +4394,13 @@ export function createControlPlaneApi(options) {
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const capturedAt = c.req.param('capturedAt');
         if (!options.scopeBackups)
-            return c.json({ error: 'no backup target configured' }, 501);
+            return refuseStatus(c, 501, 'no backup target configured');
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const dump = await options.scopeBackups.get({ tenantId, scopeId, capturedAt });
         if (!dump)
-            return c.json({ error: `no backup for scope ${scopeId} at ${capturedAt}` }, 404);
+            return refuse(c, 'not_found', `no backup for scope ${scopeId} at ${capturedAt}`);
         // 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
@@ -4250,13 +4417,13 @@ export function createControlPlaneApi(options) {
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         try {
             return c.json(await backupScope(c, tenantId, scope), 201);
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -4284,7 +4451,7 @@ export function createControlPlaneApi(options) {
         const subjectId = dataSubjectIdSchema.parse(c.req.param('subjectId'));
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const copies = await listAllScopeScriptCopies(c.var.admin, c.get('actor'), tenantId, scopeId);
         // A move in flight can still restore a copy no inventory read now would name. Its entries
         // settle when it confirms or fails, or, if it died, when the sweep finds its lease run out.
@@ -4293,17 +4460,33 @@ export function createControlPlaneApi(options) {
         }
         const erasureEpoch = await c.var.admin.scopeErasureEpoch(c.get('actor'), tenantId, scopeId);
         const currentRef = await routeOf(c, scope);
+        // The version the deployment runs, read once (#2285): the stores below are judged against it,
+        // and the claim before the key goes requires it, and the serving pointer as read, to still hold.
+        const running = await runningVersionOf(c.var.admin, c.get('actor'), scope);
         // #2207: the stores of the version the deployment runs, resolved before anything is erased. A
         // version that declares none is not asked. One that cannot be resolved while a kind is
         // registered refuses (503): the key must not be destroyed while a store may hold the subject.
-        const reach = await platformStoresOf(c, scope);
+        const reach = await platformStoresOf(c, scope, running);
+        /**
+         * 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
+         * on this fence before the key goes, and the claim moves the erasure epoch every bind compares,
+         * so the bind either lands first and the claim refuses (412, the key kept), or it is refused.
+         */
+        const fence = {
+            versionId: scope.verticalVersionId,
+            servingRef: scope.servingRef ?? null,
+            epoch: erasureEpoch,
+            copyCount: copies.length,
+            ...(running.servingPointer !== undefined ? { servingPointer: running.servingPointer } : {}),
+        };
         // Not asked is `undefined`, not `[]` (#2242): with no platform path the host's own stores
         // (the pure adapter's co-located runners) are erased in its shred or its finalize.
         const eraseStores = async () => reach ? reach.caller.eraseSubject({ tenantId, scopeId, vertical: reach.vertical, subjectId, stores: reach.stores }) : undefined;
         /** The host's own shred, with the platform's store erasure first: a store that errors keeps the key. */
         const shredHere = async () => {
             const storeErasures = await eraseStores();
-            const receipt = await c.var.admin.shredSubject(c.get('actor'), tenantId, scopeId, subjectId);
+            const receipt = await c.var.admin.shredSubject(c.get('actor'), tenantId, scopeId, subjectId, fence).catch(relayHostRefusal);
             return { ...receipt, storeErasures: [...receipt.storeErasures, ...(storeErasures ?? [])] };
         };
         if (!options.resolveVerticalRef) {
@@ -4332,10 +4515,7 @@ export function createControlPlaneApi(options) {
         if (bySlug)
             redactions.push(await bySlug.redactSubject(scopeId, subjectId));
         const storeErasures = await eraseStores();
-        return c.json(await c.var.admin.finalizeSubjectShred(c.get('actor'), tenantId, scopeId, subjectId, redactions, {
-            versionId: scope.verticalVersionId, servingRef: scope.servingRef ?? null, epoch: erasureEpoch,
-            copyCount: copies.length,
-        }, storeErasures).catch(relayHostRefusal));
+        return c.json(await c.var.admin.finalizeSubjectShred(c.get('actor'), tenantId, scopeId, subjectId, redactions, fence, storeErasures).catch(relayHostRefusal));
     });
     // -- directory backups (#40) -----------------------------------------------
     // The platform's own disaster recovery, on the same store posture as the scope
@@ -4350,7 +4530,7 @@ export function createControlPlaneApi(options) {
     // question an unrehearsed backup story never has a way to ask.
     app.get('/directory/backups', async (c) => {
         if (!options.directoryBackups)
-            return c.json({ error: 'no directory backup target configured' }, 501);
+            return refuseStatus(c, 501, 'no directory backup target configured');
         return c.json(await options.directoryBackups.list());
     });
     // Take one NOW, cadence ignored — the pre-migration checkpoint an operator takes by
@@ -4358,7 +4538,7 @@ export function createControlPlaneApi(options) {
     // copy without waiting a day for the cron.
     app.post('/directory/backups', async (c) => {
         if (!options.directoryBackups)
-            return c.json({ error: 'no directory backup target configured' }, 501);
+            return refuseStatus(c, 501, 'no directory backup target configured');
         const result = await backupDirectoryIfDue({
             admin: c.var.admin,
             store: options.directoryBackups,
@@ -4373,11 +4553,11 @@ export function createControlPlaneApi(options) {
     // and audited by `exportDirectory` underneath.
     app.get('/directory/backups/:capturedAt', async (c) => {
         if (!options.directoryBackups)
-            return c.json({ error: 'no directory backup target configured' }, 501);
+            return refuseStatus(c, 501, 'no directory backup target configured');
         const capturedAt = c.req.param('capturedAt');
         const dump = await options.directoryBackups.get({ capturedAt });
         if (!dump)
-            return c.json({ error: `no directory backup at ${capturedAt}` }, 404);
+            return refuse(c, 'not_found', `no directory backup at ${capturedAt}`);
         return c.json(dump);
     });
     // Break-glass: REPLACE the directory with a stored copy.
@@ -4391,18 +4571,16 @@ export function createControlPlaneApi(options) {
     // with nothing in it — needs no such ceremony.
     app.post('/directory/restore', async (c) => {
         if (!options.directoryBackups)
-            return c.json({ error: 'no directory backup target configured' }, 501);
+            return refuseStatus(c, 501, 'no directory backup target configured');
         const body = restoreDirectoryBody.parse(await c.req.json().catch(() => ({})));
         const dump = await options.directoryBackups.get({ capturedAt: body.capturedAt });
         if (!dump)
-            return c.json({ error: `no directory backup at ${body.capturedAt}` }, 404);
+            return refuse(c, 'not_found', `no directory backup at ${body.capturedAt}`);
         const actor = c.get('actor');
         const live = await c.var.admin.listTenants(actor, { limit: 1 });
         if (live.length > 0 && !body.overwrite) {
-            return c.json({
-                error: 'the directory is not empty — a restore REPLACES it, so anything created ' +
-                    'since this copy was taken would be lost; pass overwrite=true to confirm',
-            }, 409);
+            return refuse(c, 'conflict', 'the directory is not empty — a restore REPLACES it, so anything created ' +
+                'since this copy was taken would be lost; pass overwrite=true to confirm');
         }
         await c.var.admin.restoreDirectory(actor, dump);
         return c.json({ capturedAt: dump.capturedAt, tables: dump.tables.length });
@@ -4454,7 +4632,7 @@ export function createControlPlaneApi(options) {
     };
     app.post('/previews/repair-serving-pins', async (c) => {
         if (!options.resolveVerticalVersion || !options.resolveVerticalRef) {
-            return c.json({ error: 'repairing serving pins needs dispatch resolution for both ends' }, 501);
+            return refuseStatus(c, 501, 'repairing serving pins needs dispatch resolution for both ends');
         }
         const { cursor, limit, dryRun } = await readJsonBody(c, repairServingPinsBody);
         const actor = c.get('actor');
@@ -4625,13 +4803,13 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         if (!isPrimaryScope(scope)) {
-            return c.json({ error: 'clear-copy-mark refused: the directory says this scope is a copy (a preview or a fork)' }, 409);
+            return refuse(c, 'conflict', 'clear-copy-mark refused: the directory says this scope is a copy (a preview or a fork)');
         }
         const vertical = await verticalForScope(c, scope);
         if (!vertical)
-            return c.json({ error: await diagnoseUnboundScope(actor, scope) }, 501);
+            return refuseStatus(c, 501, await diagnoseUnboundScope(actor, scope));
         const { cleared } = await vertical.clearCopyMark(scopeId, { kind: scope.kind, forkedFrom: scope.forkedFrom });
         await c.var.admin.recordCopyMark(actor, { action: 'clear', tenantId, scopeId, outcome: cleared ? 'cleared' : 'absent' });
         return c.json({ cleared });
@@ -4657,16 +4835,14 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const parsed = redrainEventsInput.safeParse(await c.req.json().catch(() => ({})));
         if (!parsed.success) {
-            return c.json({ error: 'body must be { drainedBefore: <ISO 8601 instant> } — the end of the window to reopen' }, 400);
+            return refuse(c, 'validation_failed', 'body must be { drainedBefore: <ISO 8601 instant> } — the end of the window to reopen');
         }
         // Refused at the door rather than left to the adapters: an instant in the future
         // reopens rows the drain shipped AFTER the rebuild, which is exactly the double-write
         // the required instant exists to prevent. Host code, so it may read the real clock.
         if (Date.parse(parsed.data.drainedBefore) > Date.now()) {
-            return c.json({
-                error: `drainedBefore ${parsed.data.drainedBefore} is in the future — it would reopen rows ` +
-                    'already shipped to the rebuilt table. Pass the instant the old table stopped receiving.',
-            }, 400);
+            return refuse(c, 'validation_failed', `drainedBefore ${parsed.data.drainedBefore} is in the future — it would reopen rows ` +
+                'already shipped to the rebuilt table. Pass the instant the old table stopped receiving.');
         }
         // The input schema also carries `countOnly` (#1545), and this route does not honour it:
         // its answer (`redrained`, `more`) is a statement that rows moved. Ignoring the field
@@ -4675,11 +4851,11 @@ export function createControlPlaneApi(options) {
         // caller is told where counting lives. Refused whatever its value: on this route the
         // field has no meaning at all, and "accepted when false" is a rule nobody can rely on.
         if (parsed.data.countOnly !== undefined) {
-            return c.json({ error: 'countOnly is not honoured here — POST the same body to …/redrain-count for a read-only count' }, 400);
+            return refuse(c, 'validation_failed', 'countOnly is not honoured here — POST the same body to …/redrain-count for a read-only count');
         }
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         // The instant alone, never `parsed.data`, so the field cannot reach the adapter from
         // this door even if the refusal above is ever relaxed.
         const redrained = await c.var.admin.redrainEvents(actor, tenantId, scopeId, {
@@ -4710,26 +4886,72 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const parsed = redrainEventsInput.safeParse(await c.req.json().catch(() => ({})));
         if (!parsed.success) {
-            return c.json({ error: 'body must be { drainedBefore: <ISO 8601 instant> } — the window to count' }, 400);
+            return refuse(c, 'validation_failed', 'body must be { drainedBefore: <ISO 8601 instant> } — the window to count');
         }
         // The same future refusal as the reopen. A count of a window that has not closed yet
         // is not dangerous, it is meaningless — and a dry run whose instant this door accepts
         // and the real run rejects would be the worst kind of rehearsal.
         if (Date.parse(parsed.data.drainedBefore) > Date.now()) {
-            return c.json({
-                error: `drainedBefore ${parsed.data.drainedBefore} is in the future — it would count rows ` +
-                    'already shipped to the rebuilt table. Pass the instant the old table stopped receiving.',
-            }, 400);
+            return refuse(c, 'validation_failed', `drainedBefore ${parsed.data.drainedBefore} is in the future — it would count rows ` +
+                'already shipped to the rebuilt table. Pass the instant the old table stopped receiving.');
         }
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const redrainable = await c.var.admin.redrainEvents(actor, tenantId, scopeId, {
             drainedBefore: parsed.data.drainedBefore,
             countOnly: true,
         });
         return c.json({ redrainable, drainedBefore: parsed.data.drainedBefore });
     });
+    // #1334 — one tenant's events from the Tier-2 lake, through the gateway that scopes them
+    // (`lake-gateway.ts`): the tenant is this path segment and nothing else, the filters are a
+    // 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.
+    //
+    // 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
+    // are what the access log exists to prevent. A refused or failed query discloses nothing
+    // and leaves no row.
+    app.get('/tenants/:tenantId/lake/events', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        if (!options.lakeQuery) {
+            return refuseStatus(c, 501, 'the Tier-2 lake is not queryable on this control plane');
+        }
+        const parsed = lakeEventsInput.safeParse(c.req.query());
+        if (!parsed.success) {
+            // `errors` is the declared member (#113); `issues`, zod's own shape, is what this route
+            // answered before it and stays for the clients that read it. Carried rather than built by
+            // `coded`, which would answer a field list with its canonical sentence instead of this one.
+            return refuse(c, 'validation_failed', 'invalid lake query', {
+                errors: validationIssuesFrom(parsed.error),
+                issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+            });
+        }
+        let page;
+        try {
+            page = await queryLakeEvents(options.lakeQuery, tenantId, parsed.data);
+        }
+        catch (err) {
+            if (err instanceof LakeQueryError)
+                return refuseStatus(c, 502, err.message);
+            throw err;
+        }
+        // The filters, not the page: the same projection every other read logs.
+        const { cursor: _cursor, limit: _limit, ...filters } = parsed.data;
+        await c.var.admin.recordDelegatedRead(c.get('actor'), {
+            method: 'lakeEvents',
+            tenantId,
+            scopeId: parsed.data.scopeId ?? null,
+            params: filters,
+            resultCount: page.events.length,
+        });
+        return c.json(page);
+    });
     app.post('/tenants/:tenantId/scopes/:scopeId/reap', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -4739,9 +4961,9 @@ export function createControlPlaneApi(options) {
         const { backup: wantsBackup } = await readJsonBody(c, reapScopeBody);
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         if (scope.status !== 'archived') {
-            return c.json({ error: `scope ${scopeId} is ${scope.status}, not archived — only an archived scope may be reaped` }, 409);
+            return refuse(c, 'conflict', `scope ${scopeId} is ${scope.status}, not archived — only an archived scope may be reaped`);
         }
         // Refuse a scope that still resolves a hostname BEFORE any delegation — the vertical's
         // `deleteScope` below wipes the hosted DO's bytes, so this must gate ahead of it, not
@@ -4750,10 +4972,8 @@ export function createControlPlaneApi(options) {
         // the same guard because releasing every name is the point there.)
         const boundNames = await c.var.admin.listHostnames(actor, { scopeId, limit: 1 });
         if (boundNames.length > 0) {
-            return c.json({
-                error: `scope ${scopeId} still resolves hostname '${boundNames[0].hostname}' — ` +
-                    `unbind it before reaping (reap wipes storage and cannot be undone)`,
-            }, 409);
+            return refuse(c, 'conflict', `scope ${scopeId} still resolves hostname '${boundNames[0].hostname}' — ` +
+                `unbind it before reaping (reap wipes storage and cannot be undone)`);
         }
         // The recoverable copy, BEFORE any byte is wiped (#493). Ordering is the whole
         // guarantee: `backupScope` has to have resolved — durably stored — before
@@ -4772,13 +4992,10 @@ export function createControlPlaneApi(options) {
             }
             catch (e) {
                 if (e instanceof ControlPlaneError) {
-                    return c.json({ error: e.message }, failedWith(c, e));
+                    return relayRefusal(c, e);
                 }
-                return c.json({
-                    error: 'backup failed — the scope was NOT reaped and its data is intact; ' +
-                        'retry, or reap with backup=false to accept an unrecoverable wipe',
-                    detail: e instanceof Error ? e.message : String(e),
-                }, 502);
+                return refuseStatus(c, 502, 'backup failed — the scope was NOT reaped and its data is intact; ' +
+                    'retry, or reap with backup=false to accept an unrecoverable wipe', { detail: e instanceof Error ? e.message : String(e) });
             }
         }
         try {
@@ -4793,7 +5010,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -4810,15 +5027,13 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         // Residency (K-7/K-32): jurisdiction pins EXECUTION, not just storage. A pull
         // lands the data on a machine outside the platform's control, so anything
         // pinned tighter than `global` is refused until a compliant path exists.
         if (scope.jurisdiction !== 'global') {
-            return c.json({
-                error: `scope ${scopeId} is pinned to '${scope.jurisdiction}' — a local pull would ` +
-                    `move its data outside that jurisdiction; refused (K-32, preview-and-snapshots.md §6)`,
-            }, 403);
+            return refuse(c, 'forbidden', `scope ${scopeId} is pinned to '${scope.jurisdiction}' — a local pull would ` +
+                `move its data outside that jurisdiction; refused (K-32, preview-and-snapshots.md §6)`);
         }
         const full = c.req.query('full') === 'true';
         try {
@@ -4846,7 +5061,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -4873,7 +5088,7 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const tenant = await c.var.admin.getTenant(actor, tenantId);
         if (!tenant)
-            return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
+            return refuse(c, 'not_found', `unknown tenant: ${tenantId}`);
         // Every scope, tombstones included: an archived or reaped scope is part of the
         // tenant's history, and an export that quietly dropped them would misrepresent what
         // the tenant was. Their DATA is a different question, handled below.
@@ -4885,12 +5100,10 @@ export function createControlPlaneApi(options) {
         // partial is the failure mode worth avoiding.
         const pinned = scopes.filter((s) => s.jurisdiction !== 'global');
         if (pinned.length > 0) {
-            return c.json({
-                error: `tenant ${tenantId} has ${pinned.length} scope(s) pinned to a jurisdiction ` +
-                    `(${[...new Set(pinned.map((s) => s.jurisdiction))].join(', ')}) — an export would ` +
-                    `move that data out of the region it was promised; refused (K-32). Export the ` +
-                    `global scopes individually, or wait for a per-jurisdiction path.`,
-            }, 403);
+            return refuse(c, 'forbidden', `tenant ${tenantId} has ${pinned.length} scope(s) pinned to a jurisdiction ` +
+                `(${[...new Set(pinned.map((s) => s.jurisdiction))].join(', ')}) — an export would ` +
+                `move that data out of the region it was promised; refused (K-32). Export the ` +
+                `global scopes individually, or wait for a per-jurisdiction path.`);
         }
         const full = c.req.query('full') === 'true';
         try {
@@ -4969,7 +5182,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -4991,7 +5204,7 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const raw = await c.req.json();
         const dump = scopeDump.parse(raw);
         // #1869: where the uploaded file says it came from, when the caller had to set the dump's
@@ -5001,7 +5214,7 @@ export function createControlPlaneApi(options) {
         // A backup with no tables is not a scope dump — name that plainly rather than letting
         // the empty replay reach the checker and surface as a bare `internal error` (#321).
         if (dump.tables.length === 0) {
-            return c.json({ error: 'restore refused: the backup has no tables — not a scope dump' }, 422);
+            return refuseStatus(c, 422, 'restore refused: the backup has no tables — not a scope dump');
         }
         // #2207: the dump's stores against the destination's declaration, before anything is written.
         if (options.platformScopeStores) {
@@ -5010,7 +5223,7 @@ export function createControlPlaneApi(options) {
             }
             catch (e) {
                 if (e instanceof ControlPlaneError)
-                    return c.json({ error: e.message }, failedWith(c, e));
+                    return relayRefusal(c, e);
                 throw e;
             }
         }
@@ -5076,7 +5289,7 @@ export function createControlPlaneApi(options) {
             // 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 c.json({ error: e.message }, failedWith(c, e));
+                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
@@ -5084,7 +5297,7 @@ export function createControlPlaneApi(options) {
             // secondary obs #2). The route is staff/owner-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 c.json({ error: 'restore failed — the backup could not be loaded', detail }, 422);
+            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
@@ -5097,7 +5310,7 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const vertical = await verticalForScope(c, scope);
         return c.json(vertical
             ? await vertical.appliedMigrations(scopeId)
@@ -5113,7 +5326,7 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const vertical = await verticalForScope(c, scope);
         return c.json(vertical
             ? await vertical.migrationBookmarks(scopeId)
@@ -5133,7 +5346,7 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         try {
             const vertical = await verticalForScope(c, scope);
             const result = await c.var.admin.rewindScope(actor, tenantId, scopeId, bookmark, {
@@ -5156,7 +5369,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -5176,7 +5389,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json(exportBreakBody(e), failedWith(c, e));
+                return relayRefusal(c, e, exportBreaksOf(e));
             }
             throw e;
         }
@@ -5194,13 +5407,13 @@ export function createControlPlaneApi(options) {
         if (adoptPin) {
             const v = await verticalOf(actor, slug);
             if (!v || v.ownerTenant !== adoptPin)
-                return c.json({ error: 'forbidden' }, 403);
+                return refuse(c, 'forbidden', 'forbidden');
         }
         const v = await verticalOf(actor, slug);
         if (!v)
-            return c.json({ error: `unknown vertical '${slug}'` }, 404);
+            return refuse(c, 'not_found', `unknown vertical '${slug}'`);
         if (v.ownerTenant === null) {
-            return c.json({ error: 'adopt-serving is a private-vertical operation' }, 409);
+            return refuse(c, 'conflict', 'adopt-serving is a private-vertical operation');
         }
         const owned = (await c.var.admin.listScopes(actor, { tenantId: v.ownerTenant, vertical: slug })).filter((s) => !s.forkedFrom && s.kind !== 'preview' && s.status === 'active');
         const { acknowledge } = await readJsonBody(c, adoptVerticalServingBody);
@@ -5214,7 +5427,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ ...exportBreakBody(e), adopted, alreadyAdopted }, failedWith(c, e));
+                return relayRefusal(c, e, { ...exportBreaksOf(e), adopted, alreadyAdopted });
             }
             throw e;
         }
@@ -5234,7 +5447,7 @@ export function createControlPlaneApi(options) {
         // another tenant's private vertical, which a confined caller must not even learn exists
         // (404, as `GET /verticals/:slug` answers it).
         if (await notReadable(c.get('principal'), vertical)) {
-            return c.json({ error: `unknown vertical: ${vertical}` }, 404);
+            return refuse(c, 'not_found', `unknown vertical: ${vertical}`);
         }
         try {
             const r = await rebindScopeOntoVertical(c, tenantId, scopeId, vertical, {
@@ -5246,7 +5459,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json(exportBreakBody(e), failedWith(c, e));
+                return relayRefusal(c, e, exportBreaksOf(e));
             }
             throw e;
         }
@@ -5317,7 +5530,7 @@ export function createControlPlaneApi(options) {
         const { script } = keptScriptQuery.parse(c.req.query());
         const scope = await c.var.admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const kept = await (await keptHolder(script)).keptCopy(scopeId);
         return c.json({ scopeId, script, kept, routesTo: await routeOf(c, scope) });
     });
@@ -5336,17 +5549,15 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         if (scope.jurisdiction !== 'global') {
-            return c.json({
-                error: `scope ${scopeId} is pinned to '${scope.jurisdiction}' — a local pull would ` +
-                    `move its data outside that jurisdiction; refused (K-32, preview-and-snapshots.md §6)`,
-            }, 403);
+            return refuse(c, 'forbidden', `scope ${scopeId} is pinned to '${scope.jurisdiction}' — a local pull would ` +
+                `move its data outside that jurisdiction; refused (K-32, preview-and-snapshots.md §6)`);
         }
         const holder = await keptHolder(script);
         const kept = await holder.keptCopy(scopeId);
         if (!kept)
-            return c.json({ error: `scope ${scopeId} has no kept copy in '${script}'` }, 409);
+            return refuse(c, 'conflict', `scope ${scopeId} has no kept copy in '${script}'`);
         const dump = await c.var.admin.exportScope(actor, tenantId, scopeId);
         const tables = await holder.exportScope(scopeId);
         if (full === 'true')
@@ -5361,20 +5572,18 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         const scope = await c.var.admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         const holder = await keptHolder(body.script);
         const kept = await holder.keptCopy(scopeId);
         if (!kept)
-            return c.json({ error: `scope ${scopeId} has no kept copy in '${body.script}'` }, 409);
+            return refuse(c, 'conflict', `scope ${scopeId} has no kept copy in '${body.script}'`);
         const route = await routeOf(c, scope);
         // `release` is for a kept copy the scope routes to (a rollback bound it after a carry kept
         // it); the other two act on a kept copy the scope has left, against the store it runs on.
         if (body.action === 'release' ? route !== body.script : !route || route === body.script) {
-            return c.json({
-                error: body.action === 'release'
-                    ? `scope ${scopeId} routes to '${route ?? '(nothing)'}', not to the kept copy in '${body.script}'; release is for a kept copy that is live`
-                    : `scope ${scopeId} routes to '${route ?? '(nothing)'}', so there is no live copy to resolve against`,
-            }, 409);
+            return refuse(c, 'conflict', body.action === 'release'
+                ? `scope ${scopeId} routes to '${route ?? '(nothing)'}', not to the kept copy in '${body.script}'; release is for a kept copy that is live`
+                : `scope ${scopeId} routes to '${route ?? '(nothing)'}', so there is no live copy to resolve against`);
         }
         const at = new Date().toISOString();
         const revisionOf = async (client) => {
@@ -5405,7 +5614,7 @@ export function createControlPlaneApi(options) {
         if (body.action === 'release') {
             const out = await holder.releaseKeptCopy({ scopeId, revision: revisionBefore, ...markCopy, ...stampFence });
             if ('refused' in out) {
-                return c.json({ error: `the kept copy of scope ${scopeId} ${out.refused === 'changed' ? 'changed since it was read' : 'is no longer kept'}; nothing was released` }, 412);
+                return refuse(c, 'precondition_failed', `the kept copy of scope ${scopeId} ${out.refused === 'changed' ? 'changed since it was read' : 'is no longer kept'}; nothing was released`);
             }
             await record('release', revisionBefore);
             return c.json({ scopeId, script: body.script, action: 'release', revisionBefore });
@@ -5413,7 +5622,7 @@ export function createControlPlaneApi(options) {
         if (body.action === 'discard') {
             const out = await holder.discardKeptCopy({ scopeId, revision: revisionBefore, carriedTo: route, at, ...markCopy, ...stampFence });
             if ('refused' in out) {
-                return c.json({ error: `the kept copy of scope ${scopeId} ${out.refused === 'changed' ? 'changed since it was read' : 'is no longer kept'}; nothing was discarded` }, 412);
+                return refuse(c, 'precondition_failed', `the kept copy of scope ${scopeId} ${out.refused === 'changed' ? 'changed since it was read' : 'is no longer kept'}; nothing was discarded`);
             }
             const revisionAfter = await revisionOf(holder);
             await record('discard', revisionAfter);
@@ -5421,10 +5630,8 @@ export function createControlPlaneApi(options) {
         }
         // restore-forward: the acknowledgement names what is replaced, as the marker says it.
         if (body.acknowledge.replacesLiveWritesSince !== kept.keptAt) {
-            return c.json({
-                error: `a restore forward replaces what the live store took since ${kept.keptAt}; acknowledge exactly that ` +
-                    `(acknowledge.replacesLiveWritesSince: '${kept.keptAt}')`,
-            }, 409);
+            return refuse(c, 'conflict', `a restore forward replaces what the live store took since ${kept.keptAt}; acknowledge exactly that ` +
+                `(acknowledge.replacesLiveWritesSince: '${kept.keptAt}')`);
         }
         // Fenced on the binding through the whole resolution (Codex #2008 r8): the kept copy goes only
         // once its data is in the store the scope still routes to. Every refusal below leaves it kept.
@@ -5436,21 +5643,19 @@ export function createControlPlaneApi(options) {
                 (now.verticalVersionId ?? null) === (scope.verticalVersionId ?? null) &&
                 (now.servingRef ?? null) === (scope.servingRef ?? null));
         };
-        const moved = () => c.json({
-            error: `scope ${scopeId} was re-pointed while the kept copy was being restored forward, so nothing was resolved ` +
-                `and the kept copy in '${body.script}' stays kept; read it again and resolve it again`,
-        }, 409);
+        const moved = () => refuse(c, 'conflict', `scope ${scopeId} was re-pointed while the kept copy was being restored forward, so nothing was resolved ` +
+            `and the kept copy in '${body.script}' stays kept; read it again and resolve it again`);
         // The live store as read now, and nothing else, is what gets replaced. The binding read again
         // after the marker ties the marker to the live store: a move that landed before this read
         // (its wipe minting a tombstone here) changed the binding, and is refused.
         const liveMarker = await live.loadMarker(scopeId);
         if (liveMarker === 'unfenced') {
-            return c.json({ error: `the deployment serving scope ${scopeId} ('${liveScript}') predates the fence (#1722); re-push it, then resolve` }, 409);
+            return refuse(c, 'conflict', `the deployment serving scope ${scopeId} ('${liveScript}') predates the fence (#1722); re-push it, then resolve`);
         }
         if (!(await bindingHeld()))
             return moved();
         if ((await isCarriedAway(live, scope)) || (await live.keptCopy(scopeId))) {
-            return c.json({ error: `the store scope ${scopeId} routes to in '${liveScript}' is not a live store (wiped or kept); nothing was resolved` }, 409);
+            return refuse(c, 'conflict', `the store scope ${scopeId} routes to in '${liveScript}' is not a live store (wiped or kept); nothing was resolved`);
         }
         const dump = await retryTransient(() => holder.exportScope(scopeId));
         // #2185: before the load as well as after it, so a throw once the kept copy has landed (the
@@ -5489,10 +5694,8 @@ export function createControlPlaneApi(options) {
             ...stampFence,
         });
         if ('refused' in wiped) {
-            return c.json({
-                error: `restored forward into '${route}', but the kept copy in '${body.script}' changed since it was read, so it ` +
-                    `stays kept: read it again and resolve it again`,
-            }, 409);
+            return refuse(c, 'conflict', `restored forward into '${route}', but the kept copy in '${body.script}' changed since it was read, so it ` +
+                `stays kept: read it again and resolve it again`);
         }
         return c.json({ scopeId, script: body.script, action: 'restore-forward', liveScript, revisionBefore, revisionAfter });
     });
@@ -5550,7 +5753,7 @@ export function createControlPlaneApi(options) {
         };
         if (snapshot) {
             if (!scope) {
-                return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+                return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
             }
             const vertical = await verticalForScope(c, scope);
             if (vertical) {
@@ -5625,13 +5828,13 @@ export function createControlPlaneApi(options) {
         // uniform whether or not anything is deployed. Existing scopes keep serving.
         const registered = (await c.var.admin.listVerticals(c.get('actor'))).find((v) => v.slug === slug);
         if (registered?.installsBlocked) {
-            return c.json({ error: `new installs of vertical '${slug}' are blocked` }, 403);
+            return refuse(c, 'forbidden', `new installs of vertical '${slug}' are blocked`);
         }
         // Static binding first (milestone-one shape), then the dispatch resolver for a
         // pushed vertical — the provisioning mirror of the router's verticalFor.
         const vertical = options.verticals?.[slug] ?? (await options.resolveVertical?.(slug, c.get('actor')));
         if (!vertical) {
-            return c.json({ error: `no deployment is bound for vertical '${slug}'` }, 501);
+            return refuseStatus(c, 501, `no deployment is bound for vertical '${slug}'`);
         }
         const input = provisionInstanceBody.parse(await c.req.json());
         // #310: the platform is the authoritative source of the tenant's entitlements — it
@@ -5750,7 +5953,7 @@ export function createControlPlaneApi(options) {
                         message: e.message,
                     }, e);
                 }
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             }
             throw e;
         }
@@ -5979,7 +6182,7 @@ export function createControlPlaneApi(options) {
             input.slug = effectiveSlug(p, input.slug);
             const owner = await ownerOf(p.actor, input.slug);
             if (owner !== undefined && owner !== p.tenantId)
-                return c.json({ error: 'forbidden' }, 403);
+                return refuse(c, 'forbidden', 'forbidden');
             input.ownerTenant = p.tenantId;
         }
         await c.var.admin.registerVertical(c.get('actor'), input);
@@ -5994,7 +6197,7 @@ export function createControlPlaneApi(options) {
         // A builder reading a vertical it does not own gets 404 — indistinguishable from
         // absent, the same fail-closed reflex K-3 uses for a cross-tenant scope.
         if (await notReadable(p, slug)) {
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         }
         const page = pageParams(c);
         const entries = await c.var.admin.listVersions(c.get('actor'), slug, page);
@@ -6006,12 +6209,12 @@ export function createControlPlaneApi(options) {
         // the same fail-closed cross-check `(tenantId, scopeId)` makes (K-3) — a mismatch is
         // a client bug, not a silent publish under the wrong vertical.
         if (input.verticalSlug !== c.req.param('slug')) {
-            return c.json({ error: 'verticalSlug does not match the path' }, 400);
+            return refuse(c, 'validation_failed', 'verticalSlug does not match the path');
         }
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, input.verticalSlug);
         if (await notOwned(p, slug)) {
-            return c.json({ error: 'forbidden' }, 403);
+            return refuse(c, 'forbidden', 'forbidden');
         }
         input.verticalSlug = slug;
         // `manifestJson` is a string the schema cannot look inside, and every reader parses it
@@ -6028,19 +6231,19 @@ export function createControlPlaneApi(options) {
                 raw = JSON.parse(input.manifestJson);
             }
             catch {
-                return c.json({ error: 'manifestJson is not valid JSON' }, 400);
+                return refuse(c, 'validation_failed', 'manifestJson is not valid JSON');
             }
-            const refuse = (issue, under = []) => c.json({ error: `manifestJson is not a deploy manifest: ${[...under, ...issue.path].join('.') || '(root)'}: ${issue.message}` }, 400);
+            const refuseManifest = (issue, under = []) => refuse(c, 'validation_failed', `manifestJson is not a deploy manifest: ${[...under, ...issue.path].join('.') || '(root)'}: ${issue.message}`);
             const checked = storedDeployManifest.safeParse(raw);
             if (!checked.success)
-                return refuse(checked.error.issues[0]);
+                return refuseManifest(checked.error.issues[0]);
             // #1869: a registry handed to this route now is NEW, so it answers to the push-time rule on
             // entity-grant shapes (no kernel namespace as an entity type), as `deployManifest` does.
             // An absent registry stays accepted, as above.
             if (checked.data.registry) {
                 const registry = pushedPermissionRegistry.safeParse(checked.data.registry);
                 if (!registry.success)
-                    return refuse(registry.error.issues[0], ['registry']);
+                    return refuseManifest(registry.error.issues[0], ['registry']);
             }
         }
         await c.var.admin.publishVersion(c.get('actor'), input);
@@ -6057,7 +6260,7 @@ export function createControlPlaneApi(options) {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         if (await notReadable(p, slug)) {
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         }
         const json = await c.var.admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
         const registry = json ? (storedDeployManifest.parse(JSON.parse(json)).registry ?? null) : null;
@@ -6075,7 +6278,7 @@ export function createControlPlaneApi(options) {
         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);
+            return refuse(c, 'not_found', 'not found');
         }
         // `versionMigrations` refuses a version of another vertical, so `base` cannot reach one.
         const migrationsOf = (id) => c.var.admin.versionMigrations(c.get('actor'), slug, id);
@@ -6097,7 +6300,7 @@ export function createControlPlaneApi(options) {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         if (await notReadable(p, slug)) {
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         }
         const json = await c.var.admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
         const parsed = json ? storedDeployManifest.parse(JSON.parse(json)) : null;
@@ -6120,7 +6323,7 @@ export function createControlPlaneApi(options) {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         if (await notReadable(p, slug)) {
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         }
         const json = await c.var.admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
         const parsed = json ? storedDeployManifest.parse(JSON.parse(json)) : null;
@@ -6148,7 +6351,7 @@ export function createControlPlaneApi(options) {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         if (await notReadable(p, slug)) {
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         }
         const json = await c.var.admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
         const parsed = json ? storedDeployManifest.parse(JSON.parse(json)) : null;
@@ -6167,7 +6370,7 @@ export function createControlPlaneApi(options) {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         if (await notReadable(p, slug)) {
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         }
         const json = await c.var.admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
         const assets = json ? (storedDeployManifest.parse(JSON.parse(json)).assets ?? null) : null;
@@ -6192,7 +6395,7 @@ export function createControlPlaneApi(options) {
         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);
+            return refuse(c, 'not_found', 'not found');
         }
         await c.var.admin.requestPublish(c.get('actor'), slug);
         return c.json({ slug, requested: true });
@@ -6248,7 +6451,7 @@ export function createControlPlaneApi(options) {
         // 404, not 403: a slug this tenant does not own reads as absent, the same
         // existence-hiding reflex the registry's other per-slug reads use (K-3).
         if (await notOwned(c.get('principal'), slug))
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         await c.var.admin.deleteVertical(c.get('actor'), slug);
         return c.json({ slug, deleted: true });
     });
@@ -6256,7 +6459,7 @@ export function createControlPlaneApi(options) {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         if (await notReadable(p, slug)) {
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         }
         const page = pageParams(c);
         const entries = await c.var.admin.listChannels(c.get('actor'), slug, page);
@@ -6270,16 +6473,74 @@ export function createControlPlaneApi(options) {
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         const rawChannel = c.req.param('channel');
         if (rawChannel !== 'prod') {
-            return c.json({ error: `channel '${rawChannel}' is retired — only 'prod' has history` }, 400);
+            return refuse(c, 'validation_failed', `channel '${rawChannel}' is retired — only 'prod' has history`);
         }
         const channel = channelName.parse(rawChannel);
         if (await notOwned(p, slug)) {
-            return c.json({ error: 'not found' }, 404);
+            return refuse(c, 'not_found', 'not found');
         }
         const page = pageParams(c);
         const entries = await c.var.admin.listChannelHistory(c.get('actor'), slug, channel, page);
         return c.json(pageOf(entries, page.limit, (e) => e.id));
     });
+    /**
+     * Puts the store scripts a version's declared stores need in place, before its vertical is
+     * uploaded (#2210). A declaration with no uploader configured is refused (501) rather than
+     * served without its store. A failure is recorded as an ops failure at stage `store-upload`
+     * (#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.
+     */
+    const ensureScopeStoresOf = async (actor, operation, slug, stores, owner) => {
+        if (stores.length === 0)
+            return;
+        const holder = ulid();
+        const kinds = [...new Set(stores.map((store) => store.kind))].sort();
+        const held = [];
+        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 kind (#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 kind of kinds) {
+                if (!(await host.admin.holdStoreKind(actor, { kind, holder, mode: 'shared', ttlMs: PUSH_HOLD_TTL_MS }))) {
+                    throw new ControlPlaneError(409, `${operation} refused: scope store kind '${kind}' is being rolled out; try again in a few minutes`);
+                }
+                held.push(kind);
+            }
+            const loadRelease = options.storeReleases
+                ? storedReleaseLoader({ admin: host.admin, actor, bytes: options.storeReleases.bytes })
+                : async () => undefined;
+            // One kind 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 kind.
+            for (const kind of kinds) {
+                for (const each of held) {
+                    if (!(await host.admin.holdStoreKind(actor, { kind: each, holder, mode: 'shared', ttlMs: PUSH_HOLD_TTL_MS, renew: true }))) {
+                        throw new ControlPlaneError(409, `${operation} refused: the hold on scope store kind '${each}' lapsed during the upload; try again`);
+                    }
+                }
+                await options.ensureScopeStores({ vertical: slug, stores: stores.filter((store) => store.kind === kind), loadRelease });
+            }
+        }
+        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;
+        }
+        finally {
+            for (const kind of held)
+                await host.admin.releaseStoreKindHold(actor, { kind, holder }).catch(() => undefined);
+        }
+    };
     /**
      * 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
@@ -6332,6 +6593,8 @@ export function createControlPlaneApi(options) {
         ].map((b) => b.type === 'd1'
             ? { type: 'd1', name: b.name, id: b.id }
             : { type: 'r2_bucket', name: b.name, bucket_name: b.bucketName });
+        // #2210: the store scripts first, so the vertical is never served before what it reaches.
+        await ensureScopeStoresOf(actor, 'serve', slug, manifest.scopeStores, async () => (await ownerOf(actor, slug)) ?? null);
         await options.deployVertical(ref, {
             entry: manifest.entry,
             compatibilityDate: manifest.compatibilityDate,
@@ -6487,7 +6750,7 @@ export function createControlPlaneApi(options) {
         if (pin) {
             const v = await verticalOf(p.actor, slug);
             if (!v || v.ownerTenant !== pin)
-                return c.json({ error: 'forbidden' }, 403);
+                return refuse(c, 'forbidden', 'forbidden');
         }
         const breaks = await promoteImpactOf(c.get('actor'), slug, channel, versionId);
         const { visible, otherTenants } = narrowToCaller(breaks, pin);
@@ -6500,10 +6763,8 @@ export function createControlPlaneApi(options) {
         // with the honest alternative — a non-prod environment is a scope with data, a preview.
         const rawChannel = c.req.param('channel');
         if (rawChannel !== 'prod') {
-            return c.json({
-                error: `channel '${rawChannel}' is retired — 'prod' is the only channel. To run a version ` +
-                    `against non-prod data, create a preview: 'substrat preview create --tag <tag>'.`,
-            }, 400);
+            return refuse(c, 'validation_failed', `channel '${rawChannel}' is retired — 'prod' is the only channel. To run a version ` +
+                `against non-prod data, create a preview: 'substrat preview create --tag <tag>'.`);
         }
         const channel = channelName.parse(rawChannel);
         const promotePin = confinedTenant(p);
@@ -6511,7 +6772,7 @@ export function createControlPlaneApi(options) {
             // A confined principal promotes only verticals its tenant owns.
             const v = await verticalOf(p.actor, slug);
             if (!v || v.ownerTenant !== promotePin)
-                return c.json({ error: 'forbidden' }, 403);
+                return refuse(c, 'forbidden', 'forbidden');
             // …and a BUILDER promotes prod only while the vertical is PRIVATE (not listed).
             // A private vertical's blast radius is the owning tenant itself, and dev/staging
             // already run the same bundle in the same sandbox, so a staff prod gate there
@@ -6525,7 +6786,7 @@ export function createControlPlaneApi(options) {
             // a tenant may do inside its own. Taking the gate away from them here would be a
             // capability change hidden in a security fix.
             if (p.kind === 'builder' && channel === 'prod' && v.listed) {
-                return c.json({ error: 'promotion to prod is staff-only for a listed vertical' }, 403);
+                return refuse(c, 'forbidden', 'promotion to prod is staff-only for a listed vertical');
             }
         }
         const { versionId, acknowledge } = promoteVersionBody.parse(await c.req.json());
@@ -6563,7 +6824,7 @@ export function createControlPlaneApi(options) {
                 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);
+            return refuse(c, 'conflict', listing.exportBreaks ? exportBreakRefusal(counted) : err.message, listing);
         }
         // The in-place serve (#286), prod only, AFTER every promote gate has passed —
         // uploading first would deploy to live scopes before the acknowledgement check.
@@ -6589,10 +6850,7 @@ export function createControlPlaneApi(options) {
             catch (e) {
                 const detail = e instanceof Error ? e.message : String(e);
                 console.error('serve.inplace.failed', { slug, versionId, detail });
-                return c.json({
-                    error: 'promoted, but the in-place serve failed — scopes still run the previous code; promote again to retry',
-                    detail,
-                }, 502);
+                return refuseStatus(c, 502, 'promoted, but the in-place serve failed — scopes still run the previous code; promote again to retry', { detail });
             }
         }
         // #1756: served, and every install that could move has moved and been backfilled, but one
@@ -6601,9 +6859,8 @@ export function createControlPlaneApi(options) {
         // 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`,
+            return refuse(c, 'conflict', `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
@@ -6618,7 +6875,7 @@ export function createControlPlaneApi(options) {
                         };
                     })()
                     : {}),
-            }, 409);
+            });
         }
         const promoted = (await c.var.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
@@ -6656,13 +6913,13 @@ export function createControlPlaneApi(options) {
     // tenant); for everything else admission still gates serving.
     app.post('/verticals/:slug/deploy', async (c) => {
         if (!options.deployVertical) {
-            return c.json({ error: 'deploy is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'deploy is not configured on this control plane');
         }
         const p = c.get('principal');
         const form = await c.req.formData();
         const raw = form.get('manifest');
         if (typeof raw !== 'string')
-            return c.json({ error: 'missing manifest part' }, 400);
+            return refuse(c, 'validation_failed', 'missing manifest part');
         const manifest = deployManifest.parse(JSON.parse(raw));
         // §4 sandbox contract, before anything reaches the namespace.
         assertSandboxContract(manifest);
@@ -6699,20 +6956,20 @@ export function createControlPlaneApi(options) {
         let ownerTenant;
         if (p.kind === 'builder') {
             if (pin && pin !== p.tenantSlug && pin !== p.tenantId) {
-                return c.json({ error: `push is pinned to workspace '${pin}' but this session acts for '${p.tenantSlug}'` }, 403);
+                return refuse(c, 'forbidden', `push is pinned to workspace '${pin}' but this session acts for '${p.tenantSlug}'`);
             }
             slug = effectiveSlug(p, bare);
             // A builder pushes to a slug it owns, or claims an unregistered one (§3).
             const existingOwner = await ownerOf(c.get('actor'), slug);
             if (existingOwner !== undefined && existingOwner !== p.tenantId) {
-                return c.json({ error: 'forbidden' }, 403);
+                return refuse(c, 'forbidden', 'forbidden');
             }
             ownerTenant = p.tenantId;
         }
         else if (pin) {
             const workspace = (await c.var.admin.listTenants(c.get('actor'))).find((t) => t.slug === pin || t.id === pin);
             if (!workspace)
-                return c.json({ error: `unknown workspace '${pin}'` }, 404);
+                return refuse(c, 'not_found', `unknown workspace '${pin}'`);
             // Back-compat: a BARE slug already registered as the pinned tenant's (a staff
             // hand-registration predating prefixed claims) stays addressable as itself.
             // Otherwise the claim lands under the tenant prefix, exactly like a builder push —
@@ -6721,7 +6978,7 @@ export function createControlPlaneApi(options) {
             slug = bareOwner === workspace.id ? bare : `${workspace.slug}/${bare}`;
             const existingOwner = slug === bare ? bareOwner : await ownerOf(c.get('actor'), slug);
             if (existingOwner !== undefined && existingOwner !== workspace.id) {
-                return c.json({ error: `vertical '${slug}' is not owned by workspace '${pin}'` }, 403);
+                return refuse(c, 'forbidden', `vertical '${slug}' is not owned by workspace '${pin}'`);
             }
             ownerTenant = workspace.id;
         }
@@ -6736,7 +6993,7 @@ export function createControlPlaneApi(options) {
         // registry id that predates the rule, so it can never put a script under a platform name.
         const collision = platformScriptCollision(slug);
         if (collision)
-            return c.json({ error: platformScriptRefusal(slug, collision) }, 422);
+            return refuseStatus(c, 422, platformScriptRefusal(slug, collision));
         // #388: refuse the SILENT lineage fork. A first push of a registry id that does not
         // exist yet, whose product name (the slug's tail) matches an existing lineage this
         // push could CONFUSE ITSELF WITH, is almost always a mis-identified project — a
@@ -6771,13 +7028,11 @@ export function createControlPlaneApi(options) {
                         ? 'owned by this same workspace'
                         : `owned by tenant ${v.ownerTenant}`;
                 const named = siblings.map((v) => `'${v.slug}' (${owner(v)}${v.listed ? ', listed' : ''})`).join(', ');
-                return c.json({
-                    error: `this push would CREATE a new vertical '${slug}' — a separate lineage beside ${named}. ` +
-                        `Installs of the existing lineage never update from pushes to '${slug}'. If you meant to ` +
-                        `update it, fix the project's identity first: package.json \`substrat.slug\` and ` +
-                        `\`substrat.tenant\` (or --tenant) decide where a push lands. To deliberately run a ` +
-                        `separate same-named lineage, re-run with --allow-fork.`,
-                }, 409);
+                return refuse(c, 'conflict', `this push would CREATE a new vertical '${slug}' — a separate lineage beside ${named}. ` +
+                    `Installs of the existing lineage never update from pushes to '${slug}'. If you meant to ` +
+                    `update it, fix the project's identity first: package.json \`substrat.slug\` and ` +
+                    `\`substrat.tenant\` (or --tenant) decide where a push lands. To deliberately run a ` +
+                    `separate same-named lineage, re-run with --allow-fork.`);
             }
         }
         // Two kinds of part in one body (#340): worker MODULES (unprefixed) and static ASSETS
@@ -6802,7 +7057,7 @@ export function createControlPlaneApi(options) {
             });
         }
         if (!modules.some((m) => m.name === manifest.entry)) {
-            return c.json({ error: `entry module '${manifest.entry}' is not among the uploaded files` }, 400);
+            return refuse(c, 'validation_failed', `entry module '${manifest.entry}' is not among the uploaded files`);
         }
         // The static-asset half of the §4 sandbox contract (self-serve-deploy.md §4.1). The
         // bytes are inert — no code, no authority — so they are ACCEPTED; the content-address
@@ -6815,19 +7070,17 @@ export function createControlPlaneApi(options) {
         for (const file of manifest.assets?.files ?? []) {
             const part = assetParts.get(file.path);
             if (!part) {
-                return c.json({ error: `asset '${file.path}' is named in the manifest but was not uploaded` }, 400);
+                return refuse(c, 'validation_failed', `asset '${file.path}' is named in the manifest but was not uploaded`);
             }
             const content = new Uint8Array(await part.arrayBuffer());
             if (content.byteLength !== file.size) {
-                return c.json({ error: `asset '${file.path}' declares ${file.size} bytes but ${content.byteLength} arrived` }, 400);
+                return refuse(c, 'validation_failed', `asset '${file.path}' declares ${file.size} bytes but ${content.byteLength} arrived`);
             }
             const actual = await assetHash(content, file.path);
             if (actual !== file.hash) {
-                return c.json({
-                    error: `asset '${file.path}' does not match its declared content hash ` +
-                        `(declared ${file.hash}, computed ${actual}) — the hash is the runtime's shared dedup key, ` +
-                        `so a mismatch is refused rather than stored`,
-                }, 400);
+                return refuse(c, 'validation_failed', `asset '${file.path}' does not match its declared content hash ` +
+                    `(declared ${file.hash}, computed ${actual}) — the hash is the runtime's shared dedup key, ` +
+                    `so a mismatch is refused rather than stored`);
             }
             assets.push({
                 path: file.path,
@@ -6842,9 +7095,7 @@ export function createControlPlaneApi(options) {
             // An unlisted asset part would be uploaded by nothing and served by nothing; saying so
             // beats silently dropping it, because the builder's page would 404 with no explanation.
             const extra = [...assetParts.keys()].slice(0, 5).join(', ');
-            return c.json({
-                error: `${assetParts.size} uploaded asset part(s) are absent from the manifest (${extra}${assetParts.size > 5 ? ', …' : ''})`,
-            }, 400);
+            return refuse(c, 'validation_failed', `${assetParts.size} uploaded asset part(s) are absent from the manifest (${extra}${assetParts.size > 5 ? ', …' : ''})`);
         }
         // #1902: whether this version's uploads carry the platform's scope sweeper — decided here,
         // ONCE, before anything is uploaded, and recorded with the version below so every later
@@ -6852,11 +7103,14 @@ export function createControlPlaneApi(options) {
         // while it is still a push; it can never become a promote or a backout that refuses.
         const sweeper = platformSweeperDecision(manifest, { entry: manifest.entry, modules });
         if ('refuse' in sweeper)
-            return c.json({ error: sweeper.refuse }, 422);
+            return refuseStatus(c, 422, sweeper.refuse);
         // 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);
         try {
             await options.deployVertical(deploymentRef, {
                 entry: manifest.entry,
@@ -6905,8 +7159,8 @@ export function createControlPlaneApi(options) {
             }, e);
             c.set('failureRecorded', true);
             return rejected
-                ? c.json({ error: 'deploy rejected', detail }, 422)
-                : c.json({ error: 'deploy upload failed', detail }, 502);
+                ? 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
@@ -6993,7 +7247,7 @@ export function createControlPlaneApi(options) {
     // because "no namespaces in that script" and "I cannot look" are different answers.
     app.get('/platform/do-namespaces', async (c) => {
         if (!options.doNamespaces) {
-            return c.json({ error: 'durable-object namespace lookup is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'durable-object namespace lookup is not configured on this control plane');
         }
         const { script } = z.object({ script: z.string().min(1).max(200) }).parse({ script: c.req.query('script') });
         return c.json(namespacesForScript(await options.doNamespaces.list(), script));
@@ -7013,7 +7267,7 @@ export function createControlPlaneApi(options) {
     // on the route where a mistake is least visible.
     app.get('/observability/metrics', async (c) => {
         if (!options.observability) {
-            return c.json({ error: 'observability is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'observability is not configured on this control plane');
         }
         const { hours } = z
             .object({ hours: z.coerce.number().int().min(1).max(72).default(24) })
@@ -7030,7 +7284,7 @@ export function createControlPlaneApi(options) {
     // 501 when the reader cannot bucket — an empty series would render as "quiet".
     app.get('/observability/metrics-series', async (c) => {
         if (!options.observability?.serviceMetricsSeries) {
-            return c.json({ error: 'bucketed observability is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'bucketed observability is not configured on this control plane');
         }
         const { hours } = z
             .object({ hours: z.coerce.number().int().min(1).max(72).default(24) })
@@ -7054,7 +7308,7 @@ export function createControlPlaneApi(options) {
     });
     app.get('/observability/logs', async (c) => {
         if (!options.observability) {
-            return c.json({ error: 'observability is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'observability is not configured on this control plane');
         }
         // `service` repeats: one deployed unit per param, so a caller can ask for a
         // vertical's whole set (the dashboard's "all versions") in one query and get one
@@ -7100,7 +7354,7 @@ export function createControlPlaneApi(options) {
     // a forgotten parameter is the exact leak being closed here.
     app.get('/observability/tenant-metrics', async (c) => {
         if (!options.observability?.tenantMetrics) {
-            return c.json({ error: 'tenant-grain observability is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'tenant-grain observability is not configured on this control plane');
         }
         const p = c.get('principal');
         const tenantId = confinedTenant(p) ?? c.req.query('tenantId');
@@ -7145,7 +7399,7 @@ export function createControlPlaneApi(options) {
     // buckets, and at least one is required because an unnarrowed ask is not on offer.
     app.get('/observability/tenant-metrics-series', async (c) => {
         if (!options.observability?.tenantMetricsSeries) {
-            return c.json({ error: 'bucketed tenant-grain observability is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'bucketed tenant-grain observability is not configured on this control plane');
         }
         const p = c.get('principal');
         const tenantId = confinedTenant(p) ?? c.req.query('tenantId');
@@ -7176,7 +7430,7 @@ export function createControlPlaneApi(options) {
     });
     app.get('/observability/tenant-logs', async (c) => {
         if (!options.observability?.tenantLogs) {
-            return c.json({ error: 'tenant-grain observability is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'tenant-grain observability is not configured on this control plane');
         }
         const p = c.get('principal');
         const tenantId = confinedTenant(p) ?? c.req.query('tenantId');
@@ -7234,7 +7488,7 @@ export function createControlPlaneApi(options) {
     // #1331: one app's sampled field reports, joined to the router's own request lines.
     app.get('/observability/tenant-field-coverage', async (c) => {
         if (!options.observability?.fieldCoverage) {
-            return c.json({ error: 'field coverage is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'field coverage is not configured on this control plane');
         }
         const tenantId = confinedTenant(c.get('principal')) ?? c.req.query('tenantId');
         if (!tenantId)
@@ -7257,11 +7511,11 @@ export function createControlPlaneApi(options) {
         const scopes = await host.admin.listScopes(c.get('actor'), { tenantId: input.tenantId });
         const installed = scopes.find((s) => s.id === input.scopeId);
         if (!installed?.vertical)
-            return c.json({ error: 'app not found' }, 404);
+            return refuse(c, 'not_found', 'app not found');
         const services = scriptFamiliesOfScopes(scopes, { scopeId: input.scopeId });
         const json = await c.var.admin.versionManifest(c.get('actor'), installed.vertical, input.versionId);
         if (!json)
-            return c.json({ error: 'version not found' }, 404);
+            return refuse(c, 'not_found', 'version not found');
         const outputSurface = storedDeployManifest.parse(JSON.parse(json)).outputSurface ?? [];
         const declared = Object.fromEntries(outputSurface.map((op) => [op.operationId, op.fields]));
         return c.json(await options.observability.fieldCoverage({
@@ -7297,7 +7551,7 @@ export function createControlPlaneApi(options) {
     const appServices = async (actor, tenantId, scopeId, vertical) => scriptFamiliesOfScopes(await host.admin.listScopes(actor, { tenantId: tenantIdSchema.parse(tenantId) }), { scopeId, vertical });
     app.get('/observability/tenant-request-volume', async (c) => {
         if (!options.observability?.tenantRequestVolume) {
-            return c.json({ error: 'request aggregation is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'request aggregation is not configured on this control plane');
         }
         const scope = parseTenantRequestQuery(requestTenantOf(c), requestQueryOf(c));
         // A bucket COUNT: zooming in keeps it and narrows the window, so the bucket shrinks.
@@ -7308,7 +7562,7 @@ export function createControlPlaneApi(options) {
     });
     app.get('/observability/tenant-request-facets', async (c) => {
         if (!options.observability?.tenantRequestFacets) {
-            return c.json({ error: 'request aggregation is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'request aggregation is not configured on this control plane');
         }
         const scope = parseTenantRequestQuery(requestTenantOf(c), requestQueryOf(c));
         // `facet` repeats; absent means every facet. Each one is a backend query, so a panel
@@ -7321,7 +7575,7 @@ export function createControlPlaneApi(options) {
     // #1747: the tenant's `ctx.log` lines grouped by the template they were written from.
     app.get('/observability/tenant-log-patterns', async (c) => {
         if (!options.observability?.tenantLogPatterns) {
-            return c.json({ error: 'log patterns are not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'log patterns are not configured on this control plane');
         }
         const scope = parseTenantWindowQuery(requestTenantOf(c), requestQueryOf(c));
         const narrow = z
@@ -7349,7 +7603,7 @@ export function createControlPlaneApi(options) {
     });
     app.get('/observability/tenant-requests', async (c) => {
         if (!options.observability?.tenantRequests) {
-            return c.json({ error: 'request aggregation is not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'request aggregation is not configured on this control plane');
         }
         const scope = parseTenantRequestQuery(requestTenantOf(c), requestQueryOf(c));
         const limit = z.coerce.number().int().min(1).max(200).default(50).parse(c.req.query('limit'));
@@ -7384,7 +7638,7 @@ export function createControlPlaneApi(options) {
      */
     app.get('/verticals/:slug/egress', async (c) => {
         if (!options.observability?.observedEgress) {
-            return c.json({ error: 'observed egress is not available on this control plane' }, 501);
+            return refuseStatus(c, 501, 'observed egress is not available on this control plane');
         }
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         const { hours, limit } = z
@@ -7455,12 +7709,12 @@ export function createControlPlaneApi(options) {
     // can NOT do (prod promote, admit, other tenants' slugs) holds for it identically.
     app.post('/push-tokens', async (c) => {
         if (!options.pushTokenSecret) {
-            return c.json({ error: 'push tokens are not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'push tokens are not configured on this control plane');
         }
         const { tenantId } = z.object({ tenantId: tenantIdSchema }).parse(await c.req.json());
         const tenant = await c.var.admin.getTenant(c.get('actor'), tenantId);
         if (!tenant)
-            return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
+            return refuse(c, 'not_found', `unknown tenant: ${tenantId}`);
         const token = await mintPushToken(options.pushTokenSecret, {
             actor: await pushActorFor(tenantId),
             tenantId,
@@ -7477,7 +7731,7 @@ export function createControlPlaneApi(options) {
     // ONLY fleet-wide thing it does. Everything else it does is spent per tenant.
     app.post('/tenant-tokens', async (c) => {
         if (!options.tenantTokenSecret) {
-            return c.json({ error: 'tenant tokens are not configured on this control plane' }, 501);
+            return refuseStatus(c, 501, 'tenant tokens are not configured on this control plane');
         }
         const { tenantId, principal, impersonation } = z
             .object({
@@ -7604,7 +7858,7 @@ export function createControlPlaneApi(options) {
             // The body names the tenant the binding lands under; a confined principal may
             // only name its own (the adapter then verifies the scope belongs to it, K-3).
             if (input.tenantId !== bindPin)
-                return c.json({ error: 'forbidden' }, 403);
+                return refuse(c, 'forbidden', 'forbidden');
         }
         if (p.kind === 'builder') {
             // The region column is an EU-residency claim (K-30) — never builder-suppliable.
@@ -7613,7 +7867,7 @@ export function createControlPlaneApi(options) {
             // the binding sits, so widening this to #977's credential would be a behaviour
             // change wearing a security fix's clothes.
             if (input.region !== null) {
-                return c.json({ error: 'region is derived from the scope, not chosen on a binding' }, 403);
+                return refuse(c, 'forbidden', 'region is derived from the scope, not chosen on a binding');
             }
         }
         // Registrable-suffix guard (#305, D-35): a custom domain must be a real registrable
@@ -7622,7 +7876,7 @@ export function createControlPlaneApi(options) {
         if (custom(input.hostname)) {
             const bad = validateBindableHostname(input.hostname);
             if (bad)
-                return c.json({ error: bad }, 422);
+                return refuseStatus(c, 422, bad);
         }
         await c.var.admin.bindHostname(c.get('actor'), input);
         const bound = (await c.var.admin.listHostnames(c.get('actor'), { scopeId: input.scopeId })).find((h) => h.hostname === input.hostname);
@@ -7639,11 +7893,11 @@ export function createControlPlaneApi(options) {
     app.post('/hostnames/:hostname/verify', async (c) => {
         const name = c.req.param('hostname');
         if (confinedTenant(c.get('principal')) !== null && !(await tenantHostname(c, name))) {
-            return c.json({ error: `unknown hostname: ${name.toLowerCase()}` }, 404);
+            return refuse(c, 'not_found', `unknown hostname: ${name.toLowerCase()}`);
         }
         const row = await hostnameRow(c, name);
         if (!row)
-            return c.json({ error: `unknown hostname: ${name.toLowerCase()}` }, 404);
+            return refuse(c, 'not_found', `unknown hostname: ${name.toLowerCase()}`);
         await runIssuance(c.var.admin, c.get('actor'), row);
         return c.json(await hostnameRow(c, name));
     });
@@ -7653,7 +7907,7 @@ export function createControlPlaneApi(options) {
         // `setHostnameStatus` normalizes and 404s an unknown one below the seam.
         const name = c.req.param('hostname');
         if (confinedTenant(c.get('principal')) !== null && !(await tenantHostname(c, name))) {
-            return c.json({ error: `unknown hostname: ${name.toLowerCase()}` }, 404);
+            return refuse(c, 'not_found', `unknown hostname: ${name.toLowerCase()}`);
         }
         await c.var.admin.setHostnameStatus(c.get('actor'), name, status, note);
         const row = (await c.var.admin.listHostnames(c.get('actor'), {})).find((h) => h.hostname === name.toLowerCase());
@@ -7667,7 +7921,7 @@ export function createControlPlaneApi(options) {
     app.delete('/hostnames/:hostname', async (c) => {
         const name = c.req.param('hostname');
         if (confinedTenant(c.get('principal')) !== null && !(await tenantHostname(c, name))) {
-            return c.json({ error: `unknown hostname: ${name.toLowerCase()}` }, 404);
+            return refuse(c, 'not_found', `unknown hostname: ${name.toLowerCase()}`);
         }
         // Release the Cloudflare custom hostname before dropping the row, or the CF object
         // leaks (billable, and it would block a future rebind of the same name). Best-effort:
@@ -7717,27 +7971,35 @@ export function createControlPlaneApi(options) {
      *  reaps a HALF-BUILT leftover before re-forking (see `orchestratedPreview`). */
     /** Answers whether some of the preview's storage was stranded (and recorded as such). */
     const reapPreview = async (c, preview) => {
-        // A fork's own sign-in clients go FIRST (#1704): a failure here leaves the preview in
+        const actor = c.get('actor');
+        const dispatch = options.resolveVerticalRef;
+        // #2285: every refusal that can be decided up front comes before anything is destroyed, so a
+        // refused reap (a copy move in flight, a copy nothing can reach, stores that cannot be named)
+        // leaves the preview routed, signing in, and whole.
+        if (dispatch)
+            await claimScopeScriptReap({ admin: c.var.admin, actor }, preview.tenantId, preview.id);
+        else
+            await assertNoUnreachableScopeCopies(c.var.admin, actor, preview.tenantId, preview.id);
+        const wipeStores = await platformStoresWipe(c, preview);
+        // A preview is still routed until its row goes: unroute before the wipe.
+        await unrouteScope(c.var.admin, actor, preview);
+        // A fork's own sign-in clients go once nothing routes to it, and before the row (#1704): an
+        // unroute that fails leaves the preview signing in, and a failure here leaves the preview in
         // place, so the retry a PR-close job makes still finds it — after the row is gone, nothing
         // would name those clients again. A clean room never had one.
         await retireClientsOfReapedScope(previewAuthDeps(c), preview);
-        await wipePlatformStores(c, preview);
+        await wipeStores();
         let storageStranded = false;
-        if (options.resolveVerticalRef) {
-            ({ storageStranded } = await reapScopeScriptCopies({
-                admin: c.var.admin,
-                actor: c.get('actor'),
-                resolveRef: options.resolveVerticalRef,
-            }, preview.tenantId, preview.id));
+        if (dispatch) {
+            ({ storageStranded } = await drainScopeScriptCopies({ admin: c.var.admin, actor, resolveRef: dispatch }, preview.tenantId, preview.id));
         }
         else {
-            await assertNoUnreachableScopeCopies(c.var.admin, c.get('actor'), preview.tenantId, preview.id);
             const vertical = await verticalForScope(c, preview);
             if (vertical)
                 await vertical.deleteScope({ tenantId: preview.tenantId, scopeId: preview.id });
         }
         // Co-located hosts have no script ref; their storage is wiped by deleteSnapshot.
-        await c.var.host.deleteSnapshot(c.get('actor'), preview.tenantId, preview.id);
+        await c.var.host.deleteSnapshot(actor, preview.tenantId, preview.id);
         return { storageStranded };
     };
     /** The preview-login seam (#1704, `preview-auth.ts`): the directory, and each issuer's deployment. */
@@ -8171,23 +8433,23 @@ export function createControlPlaneApi(options) {
         const slug = await resolveVerticalId(c, c.req.param('slug'));
         const v = await verticalOf(c.get('actor'), slug);
         if (!v)
-            return { error: `unknown vertical '${slug}'`, status: 404 };
+            return { refused: 'not_found', error: `unknown vertical '${slug}'` };
         if (confinedTenant(p) !== null && v.ownerTenant !== confinedTenant(p)) {
-            return { error: 'forbidden', status: 403 };
+            return { refused: 'forbidden', error: 'forbidden' };
         }
         if (v.ownerTenant === null)
-            return { error: `vertical '${slug}' has no owner tenant`, status: 409 };
+            return { refused: 'conflict', error: `vertical '${slug}' has no owner tenant` };
         return { tenantId: v.ownerTenant, slug };
     };
     app.post('/verticals/:slug/previews', async (c) => {
         const gate = await previewVertical(c);
         if ('error' in gate)
-            return c.json({ error: gate.error }, gate.status);
+            return refuse(c, gate.refused, gate.error);
         const { tenantId, slug } = gate;
         const body = createPreviewBody.parse(await c.req.json());
         const actor = c.get('actor');
         if (body.empty && body.sourceScopeId) {
-            return c.json({ error: `pass either --empty (clean-room) or a sourceScopeId, not both` }, 400);
+            return refuse(c, 'validation_failed', `pass either --empty (clean-room) or a sourceScopeId, not both`);
         }
         // Clean-room (#509 (b)): a null source provisions an EMPTY scope — no prod scope needed.
         // Everything else forks the tenant's own active, non-fork scope for this vertical.
@@ -8201,12 +8463,12 @@ export function createControlPlaneApi(options) {
                     : null;
             if (!source) {
                 if (body.sourceScopeId) {
-                    return c.json({ error: `no active prod scope ${body.sourceScopeId} for '${slug}'` }, 404);
+                    return refuse(c, 'not_found', `no active prod scope ${body.sourceScopeId} for '${slug}'`);
                 }
                 if (owned.length === 0) {
-                    return c.json({ error: `no prod scope to fork for '${slug}' — provision one first, or pass empty:true for a clean-room preview` }, 409);
+                    return refuse(c, 'conflict', `no prod scope to fork for '${slug}' — provision one first, or pass empty:true for a clean-room preview`);
                 }
-                return c.json({ error: `'${slug}' has several prod scopes — pass sourceScopeId`, scopes: owned.map((s) => s.id) }, 409);
+                return refuse(c, 'conflict', `'${slug}' has several prod scopes — pass sourceScopeId`, { scopes: owned.map((s) => s.id) });
             }
         }
         try {
@@ -8215,14 +8477,14 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError)
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             throw e;
         }
     });
     app.get('/verticals/:slug/previews', async (c) => {
         const gate = await previewVertical(c);
         if ('error' in gate)
-            return c.json({ error: gate.error }, gate.status);
+            return refuse(c, gate.refused, gate.error);
         const { tenantId, slug } = gate;
         const actor = c.get('actor');
         const previews = (await c.var.admin.listScopes(actor, { tenantId, vertical: slug }))
@@ -8248,7 +8510,7 @@ export function createControlPlaneApi(options) {
     app.delete('/verticals/:slug/previews/:tag', async (c) => {
         const gate = await previewVertical(c);
         if ('error' in gate)
-            return c.json({ error: gate.error }, gate.status);
+            return refuse(c, gate.refused, gate.error);
         const { tenantId, slug } = gate;
         const tag = c.req.param('tag');
         const actor = c.get('actor');
@@ -8266,7 +8528,7 @@ export function createControlPlaneApi(options) {
         }
         catch (e) {
             if (e instanceof ControlPlaneError)
-                return c.json({ error: e.message }, failedWith(c, e));
+                return relayRefusal(c, e);
             throw e;
         }
     });
@@ -8353,7 +8615,7 @@ export function createControlPlaneApi(options) {
     // not be able to switch itself back on, and the dashboard has no flow that pulls it.
     const switchScheduleRoute = (to) => async (c) => {
         if (confinedTenant(c.get('principal')) !== null) {
-            return c.json({ error: 'forbidden: the schedule switch is staff-only' }, 403);
+            return refuse(c, 'forbidden', 'forbidden: the schedule switch is staff-only');
         }
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -8361,7 +8623,7 @@ export function createControlPlaneApi(options) {
         const actor = c.get('actor');
         // K-3 first, so a scope of another tenant reads as absent before anything is reached.
         if (!(await c.var.admin.getScopeRecord(actor, tenantId, scopeId))) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const input = { moduleId: body.moduleId, node: { tenantId, scopeId }, reason: body.reason };
         return c.json(to === 'off' ? await c.var.admin.revokeFromSystem(actor, input) : await c.var.admin.restoreToSystem(actor, input));
@@ -8375,14 +8637,14 @@ export function createControlPlaneApi(options) {
     // `confinedTenant` check, not a kind test.
     app.get('/tenants/:tenantId/scopes/:scopeId/system-grants', async (c) => {
         if (confinedTenant(c.get('principal')) !== null) {
-            return c.json({ error: 'forbidden: the schedule switch is staff-only' }, 403);
+            return refuse(c, 'forbidden', 'forbidden: the schedule switch is staff-only');
         }
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const actor = c.get('actor');
         // K-3 first, so a scope of another tenant reads as absent before anything is reached.
         if (!(await c.var.admin.getScopeRecord(actor, tenantId, scopeId))) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         return c.json(await c.var.admin.systemGrantsStatus(actor, { tenantId, scopeId }));
     });
@@ -8397,7 +8659,7 @@ export function createControlPlaneApi(options) {
     // 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);
+            return refuse(c, 'forbidden', 'forbidden: the schedule switch is staff-only');
         }
         const q = systemSwitchesQuery.parse({
             position: c.req.query('position'),
@@ -8435,12 +8697,12 @@ export function createControlPlaneApi(options) {
         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);
+            return refuse(c, 'forbidden', 'forbidden');
         const body = peerSwitchBody.parse(await c.req.json());
         const actor = c.get('actor');
         // K-3 first, so a scope of another tenant reads as absent before anything is reached.
         if (!(await c.var.admin.getScopeRecord(actor, tenantId, scopeId))) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         const input = { vertical: body.vertical, node: { tenantId, scopeId }, reason: body.reason };
         return c.json(to === 'off' ? await c.var.admin.revokeFromPeer(actor, input) : await c.var.admin.restoreToPeer(actor, input));
@@ -8455,10 +8717,10 @@ export function createControlPlaneApi(options) {
         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);
+            return refuse(c, 'forbidden', 'forbidden');
         const actor = c.get('actor');
         if (!(await c.var.admin.getScopeRecord(actor, tenantId, scopeId))) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         return c.json(await c.var.admin.peerGrantsStatus(actor, { tenantId, scopeId }));
     });
@@ -8471,10 +8733,10 @@ export function createControlPlaneApi(options) {
         const vertical = c.req.query('vertical');
         const pin = confinedTenant(c.get('principal'));
         if (pin !== null && pin !== tenantId)
-            return c.json({ error: 'forbidden' }, 403);
+            return refuse(c, 'forbidden', 'forbidden');
         const actor = c.get('actor');
         if (!(await c.var.admin.getScopeRecord(actor, tenantId, scopeId)))
-            return c.json({ error: 'app not found' }, 404);
+            return refuse(c, 'not_found', 'app not found');
         return c.json(vertical === undefined
             ? await c.var.admin.peerBindings(actor, tenantId, scopeId)
             : await c.var.admin.peerBinding(actor, tenantId, scopeId, verticalSlug.parse(vertical)) ?? null);
@@ -8486,11 +8748,11 @@ export function createControlPlaneApi(options) {
         // The target choice is the tenant's alone. Staff may inspect it through GET, but cannot
         // choose a tenant's site on its behalf.
         if (pin !== tenantId)
-            return c.json({ error: 'forbidden' }, 403);
+            return refuse(c, 'forbidden', 'forbidden');
         const body = peerBindingBody.parse(await c.req.json());
         const actor = c.get('actor');
         if (!(await c.var.admin.getScopeRecord(actor, tenantId, scopeId)))
-            return c.json({ error: 'app not found' }, 404);
+            return refuse(c, 'not_found', 'app not found');
         const operationId = ulid();
         const base = { tenantId, scopeId, operationId, vertical: body.vertical, targetScopeId: body.targetScopeId };
         const done = await auditedChange({
@@ -8605,16 +8867,16 @@ export function createControlPlaneApi(options) {
         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);
+            return refuse(c, 'forbidden', 'forbidden');
         const raw = await c.req.json().catch(() => ({}));
         const refused = importCursorAcknowledgementMissing(raw);
         if (refused)
-            return c.json({ error: refused }, 400);
+            return refuse(c, 'validation_failed', refused);
         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 c.var.admin.getScopeRecord(actor, tenantId, scopeId))) {
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            return refuse(c, 'not_found', `unknown scope for tenant: (${tenantId}, ${scopeId})`);
         }
         return c.json(await c.var.admin.moveImportCursor(actor, tenantId, scopeId, move));
     });
@@ -8627,7 +8889,7 @@ export function createControlPlaneApi(options) {
         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);
+            return refuse(c, 'forbidden', 'forbidden');
         const focus = c.req.query('scopeId');
         return c.json(await crossVerticalHealth(c.var.host, {
             actor: c.get('actor'),
@@ -8659,7 +8921,7 @@ export function createControlPlaneApi(options) {
         const input = issueStatusUpdate.parse(await c.req.json());
         const updated = await c.var.admin.setIssueStatus(c.get('actor'), input.fingerprint, input.status);
         if (!updated)
-            return c.json({ error: 'unknown issue fingerprint' }, 404);
+            return refuse(c, 'not_found', 'unknown issue fingerprint');
         return c.json(updated);
     });
     // -- findings (#1748): the tenant inbox, with a lifecycle and suppress rules ----
@@ -8682,17 +8944,17 @@ export function createControlPlaneApi(options) {
     app.put('/tenants/:tenantId/findings/:id/status', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         if (outsideTenant(c.get('principal'), tenantId))
-            return c.json({ error: 'forbidden' }, 403);
+            return refuse(c, 'forbidden', 'forbidden');
         const { status } = findingStatusUpdate.parse(await c.req.json());
         const updated = await c.var.admin.setFindingStatus(c.get('actor'), tenantId, c.req.param('id'), status);
         if (!updated)
-            return c.json({ error: 'unknown finding' }, 404);
+            return refuse(c, 'not_found', 'unknown finding');
         return c.json(updated);
     });
     app.get('/tenants/:tenantId/finding-rules', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         if (outsideTenant(c.get('principal'), tenantId))
-            return c.json({ error: 'forbidden' }, 403);
+            return refuse(c, 'forbidden', 'forbidden');
         const filter = findingRulesQuery.parse({ active: c.req.query('active'), limit: c.req.query('limit') });
         const entries = await c.var.admin.listFindingRules(c.get('actor'), tenantId, filter);
         return c.json({ entries });
@@ -8702,17 +8964,17 @@ export function createControlPlaneApi(options) {
     app.post('/tenants/:tenantId/finding-rules', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         if (outsideTenant(c.get('principal'), tenantId))
-            return c.json({ error: 'forbidden' }, 403);
+            return refuse(c, 'forbidden', 'forbidden');
         const input = findingRuleInput.parse(await c.req.json());
         return c.json(await c.var.admin.createFindingRule(c.get('actor'), tenantId, input), 201);
     });
     app.delete('/tenants/:tenantId/finding-rules/:ruleId', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         if (outsideTenant(c.get('principal'), tenantId))
-            return c.json({ error: 'forbidden' }, 403);
+            return refuse(c, 'forbidden', 'forbidden');
         const revoked = await c.var.admin.revokeFindingRule(c.get('actor'), tenantId, c.req.param('ruleId'));
         if (!revoked)
-            return c.json({ error: 'unknown finding rule' }, 404);
+            return refuse(c, 'not_found', 'unknown finding rule');
         return c.json(revoked);
     });
     // -- model usage (#1054): meter 3, the one D-30 could not compute -------------
@@ -8748,6 +9010,166 @@ export function createControlPlaneApi(options) {
         const summary = await c.var.admin.summarizeModelUsage(c.get('actor'), { ...(q.tenantId ? { tenantId: q.tenantId } : {}), since, until }, options.modelMarginPercent ?? DEFAULT_MODEL_MARGIN_PERCENT);
         return c.json(summary);
     });
+    // -- store-kind releases (D-63, #2300) ----------------------------------------
+    // Staff only: none of these is on the builder or the tenant allowlist. A write is also made by a
+    // person: `humanStaffActor` must name the same actor from a human staff sign-in, so the
+    // automation token, which resolves to a staff actor as well, publishes nothing.
+    const registeredKind = (kind) => {
+        const registration = (options.storeKinds ?? STORE_KINDS).find((k) => k.kind === kind);
+        if (!registration)
+            throw new ControlPlaneError(403, `scope store kind '${kind}' is not registered`);
+        return registration;
+    };
+    const releaseFlow = () => {
+        if (!options.storeReleases || !options.ensureScopeStores) {
+            throw new ControlPlaneError(501, 'this control plane keeps no store kind releases');
+        }
+        return { flow: options.storeReleases, ensureScopeStores: options.ensureScopeStores };
+    };
+    /**
+     * A write made by a person, on purpose. The staff session also rides a cookie, which a browser
+     * sends on a same-site request a page fires, so these writes take JSON only (a form or a
+     * `text/plain` beacon cannot set it without a CORS preflight, 415) and refuse a request a
+     * browser marks as from another origin (403). A request with neither header is the CLI's.
+     */
+    const byAPerson = async (c) => {
+        if (!/^application\/json\s*(;|$)/i.test(c.req.header('content-type') ?? '')) {
+            throw new ControlPlaneError(415, 'a store kind release write takes application/json');
+        }
+        const origin = c.req.header('origin');
+        const site = c.req.header('sec-fetch-site');
+        if ((origin && origin !== new URL(c.req.url).origin) || (site && site !== 'same-origin' && site !== 'none')) {
+            throw new ControlPlaneError(403, 'a store kind release write is not taken from another origin');
+        }
+        const actor = c.get('actor');
+        const person = options.humanStaffActor ? await options.humanStaffActor(c.req.raw) : null;
+        if (!person || person !== actor) {
+            throw new ControlPlaneError(403, 'a store kind release is published by a person: this takes a staff sign-in, not a service token');
+        }
+        return actor;
+    };
+    /** The pin a release is run under, or a refusal: the platform runs only what this repo pins. */
+    const pinOf = async (c, registration, sha256) => {
+        const stored = await c.var.admin.getStoreKindRelease(c.get('actor'), registration.kind, sha256);
+        if (!stored)
+            throw new ControlPlaneError(404, `release ${sha256} of '${registration.kind}' is not stored`);
+        const pin = registration.releases.find((p) => p.sha256 === sha256);
+        if (!pin) {
+            throw new ControlPlaneError(422, `release ${sha256} of '${registration.kind}' is not pinned in its registration; it runs once a reviewed change pins it and the control plane is deployed`);
+        }
+        if (pin.sourceCommit !== stored.sourceCommit) {
+            throw new ControlPlaneError(422, `release ${sha256} is pinned at ${pin.sourceCommit} and was stored as built from ${stored.sourceCommit}`);
+        }
+        return pin;
+    };
+    const rollOut = async (c, registration, sha256, action) => {
+        const { flow, ensureScopeStores } = releaseFlow();
+        const actor = c.get('actor');
+        const loadRelease = storedReleaseLoader({ admin: c.var.admin, actor, bytes: flow.bytes });
+        const result = await runStoreKindRollout({
+            admin: c.var.admin,
+            actor,
+            registration,
+            sha256,
+            action,
+            ensure: async (input) => {
+                const result = await ensureScopeStores({ ...input, loadRelease });
+                return result ? result.uploaded > 0 : true;
+            },
+            ensureCanary: (to) => flow.ensureCanary({ kind: registration.kind, to, loadRelease }),
+            callCanary: flow.callCanary,
+        });
+        return c.json(result, result.complete ? 200 : 202);
+    };
+    /** Neither a rollout nor a rollback lowers the stored schema: a kind migrates forward only. */
+    const assertSchemaKept = (registration, from, to) => {
+        if (from === null || from === to.sha256)
+            return;
+        const leaving = registration.releases.find((p) => p.sha256 === from);
+        if (!leaving)
+            throw new ControlPlaneError(409, `the current release ${from} of '${registration.kind}' is not pinned, so its schema cannot be judged`);
+        if (to.schema < leaving.schema) {
+            throw new ControlPlaneError(409, `release ${to.sha256} has schema ${to.schema}, below the current release's ${leaving.schema}: objects may already have migrated`);
+        }
+    };
+    app.get('/store-kinds/:kind', async (c) => {
+        const registration = registeredKind(c.req.param('kind'));
+        const state = await c.var.admin.storeKindState(c.get('actor'), registration.kind);
+        return c.json({ kind: registration.kind, pins: registration.releases, ...state });
+    });
+    // Store a release's bytes, before or after its pin lands (D-63). Idempotent per bundle.
+    app.put('/store-kinds/:kind/releases', async (c) => {
+        const registration = registeredKind(c.req.param('kind'));
+        const actor = await byAPerson(c);
+        const { flow } = releaseFlow();
+        const body = await readCappedJson(c.req.raw, STORE_RELEASE_REQUEST_MAX_BYTES);
+        const release = await storeKindRelease({ admin: c.var.admin, actor, bytes: flow.bytes, kind: registration.kind, body });
+        return c.json({ release, pinned: registration.releases.some((p) => p.sha256 === release.sha256 && p.sourceCommit === release.sourceCommit) }, 201);
+    });
+    // Roll a stored, pinned release out: the canary, then every vertical that ever declared the
+    // kind. Posting the same release again converges a rollout that stopped.
+    app.post('/store-kinds/:kind/rollouts', async (c) => {
+        const registration = registeredKind(c.req.param('kind'));
+        await byAPerson(c);
+        const { sha256 } = z.object({ sha256: z.string().regex(/^[0-9a-f]{64}$/) }).strict().parse(await c.req.json());
+        const pin = await pinOf(c, registration, sha256);
+        const { current } = await c.var.admin.storeKindState(c.get('actor'), registration.kind);
+        assertSchemaKept(registration, current?.sha256 ?? null, pin);
+        return rollOut(c, registration, sha256, 'rollout');
+    });
+    // Return to the immediately previous good release (D-63), never further and never a guess. After
+    // a rollout that ended diverged, that is the current good release itself: undoing the bad
+    // rollout converges every script back on the release the fleet was healthy on (kernel
+    // `storeKindStateIn`, `rollbackTarget`).
+    app.post('/store-kinds/:kind/rollback', async (c) => {
+        const registration = registeredKind(c.req.param('kind'));
+        await byAPerson(c);
+        const { current, rollbackTarget } = await c.var.admin.storeKindState(c.get('actor'), registration.kind);
+        if (!current || !rollbackTarget)
+            throw new ControlPlaneError(409, `kind '${registration.kind}' has no previous good release to roll back to`);
+        const pin = await pinOf(c, registration, rollbackTarget);
+        assertSchemaKept(registration, current.sha256, pin);
+        return rollOut(c, registration, rollbackTarget, 'rollback');
+    });
     return app;
 }
+/**
+ * The most a release upload's body may be: the decoded cap, as base64 (4 bytes per 3), plus room
+ * for the JSON around it. A bigger body is refused (413) before it is read whole.
+ */
+const STORE_RELEASE_REQUEST_MAX_BYTES = Math.ceil((STORE_RELEASE_MAX_BYTES * 4) / 3) + 1024 * 1024;
+/** A JSON body read to at most `max` bytes: a declared length over it, or a stream past it, is 413. */
+async function readCappedJson(request, max) {
+    const declared = Number(request.headers.get('content-length') ?? NaN);
+    if (Number.isFinite(declared) && declared > max)
+        throw new ControlPlaneError(413, `the body is over ${max} bytes`);
+    if (!request.body)
+        throw new ControlPlaneError(422, 'the body is empty');
+    const reader = request.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > max) {
+            await reader.cancel().catch(() => undefined);
+            throw new ControlPlaneError(413, `the body is over ${max} bytes`);
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new ControlPlaneError(422, 'the body is not JSON');
+    }
+}
 //# sourceMappingURL=api.js.map