@substrat-run/control-plane-api 0.23.0 → 0.25.0

package/dist/api.js

@@ -1,10 +1,10 @@
 import { Hono } from 'hono';
-import { adminAction, channelName, createTenantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, registerVerticalInput, scopeDump, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, z, } from '@substrat-run/contracts';
+import { adminAction, channelName, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, registerVerticalInput, scopeDump, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, z, } from '@substrat-run/contracts';
 import { migrationProgress, ulid } from '@substrat-run/kernel';
 import { ControlPlaneError } from './client.js';
 import { mapError } from './errors.js';
 import { maskDump } from './mask.js';
-import { assertSandboxContract, deployManifest, deploymentRefFor, stableDeploymentRefFor, nextMigrationTag, } from './deploy.js';
+import { assertSandboxContract, deployManifest, deploymentRefFor, stableDeploymentRefFor, nextMigrationTag, upstreamStatusOf, } from './deploy.js';
 import { mintPushToken, pushActorFor } from './push-token.js';
 // -- request schemas ---------------------------------------------------------
 // Parse, don't trust: every input crosses Zod at the boundary. The ids stay
@@ -101,7 +101,13 @@ const auditLogQuery = z.object({
     action: z.array(adminAction).optional(),
     since: z.string().optional(),
     until: z.string().optional(),
-    limit: z.coerce.number().int().positive().max(1000).optional(),
+    // Defaulted, not merely capped: the admin log is append-only and never swept (the
+    // retention decision — it is the compliance witness, control-plane.md §4.4/§4.8), so
+    // it only grows. An unbounded `GET /admin-log` would dump the whole table; a default
+    // page keeps the external read bounded while `nextCursor` still walks the entire log.
+    // The KERNEL call stays deliberately unbounded (an in-process caller that wants
+    // everything asks for everything) — only this HTTP egress vector is bounded by default.
+    limit: z.coerce.number().int().positive().max(1000).default(200),
     cursor: z.string().optional(),
     order: z.enum(['asc', 'desc']).optional(),
 });
@@ -184,6 +190,14 @@ export function createControlPlaneApi(options) {
         // A builder REQUESTS publication of a vertical it owns (marketplace-publish.md §5); the
         // `listing` flip stays staff-only. Ownership is checked in the handler.
         { method: 'POST', re: /\/verticals\/[^/]+\/publish-request$/ },
+        // The hostname map, tenant-narrowed (K-26 multi-surface exposure): a builder manages
+        // bindings for ITS OWN scopes — the same power the dashboard already exercises for it
+        // over the service token. Each handler narrows to the principal's tenant; an unknown
+        // or foreign hostname reads as 404 (existence hiding, like the registry filter).
+        { method: 'GET', re: /\/hostnames$/ },
+        { method: 'POST', re: /\/hostnames$/ },
+        { method: 'PATCH', re: /\/hostnames\/[^/]+\/status$/ },
+        { method: 'DELETE', re: /\/hostnames\/[^/]+$/ },
     ];
     app.use('*', async (c, next) => {
         if (c.get('principal').kind === 'builder') {
@@ -238,11 +252,56 @@ export function createControlPlaneApi(options) {
         await admin.setTenantStatus(c.get('actor'), tenantId, status);
         return c.json(await admin.getTenant(c.get('actor'), tenantId));
     });
+    // Reap a DELETING tenant now (control-plane.md §4.8) — the staff "reap now" that skips
+    // the grace window, the tenant analogue of the scope reap route below. Refuses a tenant
+    // that is not `deleting` (409): a reap only ever follows the reversible delete state, and
+    // starting/reversing it is the ordinary `PATCH …/status` transition above. Every scope is
+    // reaped FIRST (archive-if-needed → the vertical wipes its co-located DO → `reapScope`,
+    // the same storage-before-row ordering the scope route keeps) so no scope's bytes outlive
+    // the tenant, then `reapTenant` clears the directory. Staff/service only (not in
+    // BUILDER_ROUTES). Idempotent: a crash mid-reap leaves the tenant `deleting`, and a retry
+    // (or the grace-window sweep) converges — reaped scopes are skipped, reapTenant re-checks.
+    app.post('/tenants/:tenantId/reap', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const actor = c.get('actor');
+        const tenant = await admin.getTenant(actor, tenantId);
+        if (!tenant)
+            return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
+        if (tenant.status !== 'deleting') {
+            return c.json({
+                error: `tenant ${tenantId} is ${tenant.status}, not deleting — only a deleting tenant may be reaped`,
+            }, 409);
+        }
+        try {
+            for (const scope of await admin.listScopes(actor, { tenantId })) {
+                if (scope.status === 'reaped')
+                    continue;
+                if (scope.status !== 'archived')
+                    await admin.archiveScope(actor, tenantId, scope.id);
+                const vertical = await verticalForScope(c, scope);
+                if (vertical)
+                    await vertical.deleteScope({ scopeId: scope.id });
+                await admin.reapScope(actor, tenantId, scope.id);
+            }
+            await admin.reapTenant(actor, tenantId);
+            return c.json(await admin.getTenant(actor, tenantId));
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError) {
+                return c.json({ error: e.message }, e.status);
+            }
+            throw e;
+        }
+    });
     // -- entitlements (§4.3) ---------------------------------------------------
     app.get('/tenants/:tenantId/entitlements', async (c) => c.json(await admin.listEntitlements(c.get('actor'), tenantIdSchema.parse(c.req.param('tenantId')))));
     app.put('/tenants/:tenantId/entitlements/:key', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
-        await admin.grantEntitlement(c.get('actor'), tenantId, c.req.param('key'));
+        // The body is the plan half (#33) and optional — a bodyless PUT is the
+        // pre-widening bare flag grant, and PATCH semantics in the store mean it
+        // preserves whatever plan fields the grant already carries.
+        const plan = entitlementGrantInput.parse(await c.req.json().catch(() => ({})));
+        await admin.grantEntitlement(c.get('actor'), tenantId, c.req.param('key'), plan);
         return c.json(await admin.listEntitlements(c.get('actor'), tenantId));
     });
     app.delete('/tenants/:tenantId/entitlements/:key', async (c) => {
@@ -344,6 +403,82 @@ export function createControlPlaneApi(options) {
         }
         return options.verticals?.[slug] ?? (await options.resolveVertical?.(slug, actor));
     };
+    /**
+     * Move ONE legacy scope's data off its per-version dispatch script onto its vertical's
+     * stable serving script (#286/#321), then flip routing. The one primitive behind both
+     * the explicit `adopt-serving` endpoint and the automatic adoption a prod promote runs.
+     *
+     * Ordering is data-first: export from the script that holds the data TODAY (the scope's
+     * current dispatch — resolved BEFORE any version rebind), restore into the serving
+     * script (which re-projects the vertical's roles), and only then `setScopeServingRef` +
+     * advance the version pointer. A crash before the flip leaves the scope serving its old
+     * script intact, and the adopt retries idempotently. Already-adopted scopes short-circuit.
+     * Throws `ControlPlaneError` so callers surface an actionable status, never a bare 500.
+     */
+    const adoptScopeOntoServing = async (c, tenantId, scopeId) => {
+        const actor = c.get('actor');
+        const scope = await admin.getScopeRecord(actor, tenantId, scopeId);
+        if (!scope) {
+            throw new ControlPlaneError(404, `unknown scope for tenant: (${tenantId}, ${scopeId})`);
+        }
+        if (scope.servingRef)
+            return { servingRef: scope.servingRef, alreadyAdopted: true };
+        if (!scope.vertical) {
+            throw new ControlPlaneError(409, 'scope has no vertical — nothing to adopt onto');
+        }
+        const serving = await admin.verticalServing(actor, scope.vertical);
+        if (!serving) {
+            throw new ControlPlaneError(409, `vertical '${scope.vertical}' has no serving script yet — promote a version to prod first`);
+        }
+        const source = await verticalForScope(c, scope);
+        const dest = await options.resolveVerticalRef?.(serving.ref);
+        if (!source || !dest) {
+            throw new ControlPlaneError(501, 'adopt-serving needs dispatch resolution for both ends');
+        }
+        const dump = await source.exportScope(scopeId);
+        const restored = await dest.restoreScope(tenantId, scopeId, dump);
+        // Data landed — only now flip routing and move the version pointer.
+        await admin.setScopeServingRef(actor, tenantId, scopeId, serving.ref);
+        await admin.bindScopeVersion(actor, tenantId, scopeId, serving.versionId);
+        return { servingRef: serving.ref, tables: restored.tables };
+    };
+    /**
+     * After a prod in-place serve, own the owned-scope adopt+rebind the host cascade
+     * delegated to us for a dispatch-backed vertical (#321): adopt any still-legacy scope
+     * onto the serving script (data survives), and advance every owned scope's version
+     * pointer to the promoted version so Update stops offering a crossing already made.
+     *
+     * Gated exactly where the host cascade would have run: PRIVATE (owned, unlisted) only,
+     * active non-fork scopes only. Runs only when a serving script exists — i.e. the serve
+     * actually happened (dispatch-backed + deploy configured); for an embedded vertical the
+     * host cascade already rebound, and `verticalServing` is null, so this is a no-op.
+     * Idempotent and retry-safe: the host cascade never rebound these scopes, so their data
+     * is still findable on a retry after a failed serve.
+     */
+    const adoptAndRebindOwnedScopes = async (c, slug, versionId) => {
+        const actor = c.get('actor');
+        const serving = await admin.verticalServing(actor, slug);
+        if (!serving)
+            return; // embedded / not dispatch-backed — the host cascade handled rebinds
+        const v = await verticalOf(actor, slug);
+        if (!v || v.ownerTenant === null || v.listed)
+            return; // private only, like the host cascade
+        const owned = (await admin.listScopes(actor, { tenantId: v.ownerTenant, vertical: slug, status: ['active'] })).filter((s) => !s.forkedFrom);
+        for (const s of owned) {
+            if (!s.servingRef) {
+                // Adopt: export from the scope's current (un-rebound) dispatch → serving script,
+                // then bind to the serving version. Data-first, so a failure here leaves the
+                // scope intact on its old script for the next promote to retry.
+                await adoptScopeOntoServing(c, s.tenantId, s.id);
+            }
+            else if (s.verticalVersionId !== versionId) {
+                // Already on the serving script (born there, or adopted earlier): routing is
+                // pinned to servingRef, so advancing the version pointer only affects Update
+                // offers. Snapshot on a migration-digest crossing (fork-before-promote, §4).
+                await admin.bindScopeVersion(actor, s.tenantId, s.id, versionId, { snapshot: true });
+            }
+        }
+    };
     app.get('/tenants/:tenantId/scopes/:scopeId/tables', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -355,6 +490,36 @@ export function createControlPlaneApi(options) {
             ? await vertical.listScopeTables(scopeId)
             : await admin.listScopeTables(c.get('actor'), tenantId, scopeId));
     });
+    // Scope health (#321, criterion #3). The silent failure the field report chased was an
+    // ACTIVE scope serving traffic from a DO whose `_substrat_roles` projection is EMPTY:
+    // identity resolves, every permission check denies, and it reads as a per-app 403 rather
+    // than a platform condition. Surface it as one. The role count comes from the SAME
+    // introspection the Data view uses (the serving script the router actually dispatches to),
+    // so it reflects the DO in front of live traffic — reusing existing plumbing rather than
+    // a new scope-DO route. `roleProjectionEmpty` on an active scope is the flag a console
+    // fleet view raises; a scope whose roles live off-DO (adapter-sqlite's directory) reports
+    // a null count and is not flagged.
+    app.get('/tenants/:tenantId/scopes/:scopeId/health', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        const vertical = await verticalForScope(c, scope);
+        const tables = vertical
+            ? await vertical.listScopeTables(scopeId)
+            : await admin.listScopeTables(c.get('actor'), tenantId, scopeId);
+        const roles = tables.find((t) => t.name === '_substrat_roles');
+        const roleCount = roles ? roles.rowCount : null;
+        const roleProjectionEmpty = scope.status === 'active' && roleCount === 0;
+        return c.json({
+            scopeId,
+            status: scope.status,
+            servingRef: scope.servingRef ?? null,
+            roleCount,
+            roleProjectionEmpty,
+        });
+    });
     app.get('/tenants/:tenantId/scopes/:scopeId/tables/:table', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
@@ -532,6 +697,39 @@ export function createControlPlaneApi(options) {
             throw e;
         }
     });
+    // Reap an ARCHIVED primary scope (control-plane.md §4.4): free its DO storage —
+    // Cloudflare never garbage-collects a Durable Object, so a deleted app's bytes persist
+    // forever otherwise — while keeping the directory row as a tombstone. A POST verb, not
+    // DELETE: DELETE means "remove the record" (and is already the fork hard-delete above),
+    // whereas reap KEEPS the row and just moves it to `reaped`. Staff/service only — not in
+    // BUILDER_ROUTES. The archived-only refusal is surfaced HERE before any delegation (the
+    // vertical must never be asked to wipe a live scope) and re-checked below the seam by
+    // reapScope. Same storage-before-row ordering as deleteSnapshot: the vertical wipes its
+    // co-located DO first, then the in-process reapScope flips the status and audits.
+    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'));
+        const actor = c.get('actor');
+        const scope = await admin.getScopeRecord(actor, tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        if (scope.status !== 'archived') {
+            return c.json({ error: `scope ${scopeId} is ${scope.status}, not archived — only an archived scope may be reaped` }, 409);
+        }
+        try {
+            const vertical = await verticalForScope(c, scope);
+            if (vertical)
+                await vertical.deleteScope({ scopeId });
+            await admin.reapScope(actor, tenantId, scopeId);
+            return c.json(await admin.getScopeRecord(actor, tenantId, scopeId));
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError) {
+                return c.json({ error: e.message }, e.status);
+            }
+            throw e;
+        }
+    });
     // The governed pull (preview-and-snapshots.md §6/§8) — the ONE route that
     // deliberately hands scope BYTES to the caller, which is why every §6 layer sits
     // on it: staff-only (not in BUILDER_ROUTES), K-3 cross-checked, K-24 audited (the
@@ -589,6 +787,11 @@ export function createControlPlaneApi(options) {
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
         const dump = scopeDump.parse(await c.req.json());
+        // 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);
+        }
         try {
             await host.restoreScope(actor, tenantId, scopeId, dump);
             const vertical = await verticalForScope(c, scope);
@@ -600,7 +803,13 @@ export function createControlPlaneApi(options) {
             if (e instanceof ControlPlaneError) {
                 return c.json({ error: e.message }, e.status);
             }
-            throw e;
+            // A restore throw is driven by the caller-supplied dump (a shape the target cannot
+            // load, a DDL the engine rejects), so DISCLOSE it as an actionable 422 rather than
+            // collapsing to the generic 500 `internal error` mapError would produce (#321,
+            // secondary obs #2). The route is staff/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);
         }
     });
     // #286: the PITR bookmarks a scope recorded before its migration passes — the
@@ -652,50 +861,61 @@ export function createControlPlaneApi(options) {
             throw e;
         }
     });
-    // #286: adopt a LEGACY scope onto its vertical's stable serving script — the
-    // one-time data hop off per-version dispatch. Export from the script that holds
-    // the data today (the bound version's), restore into the serving script (which
-    // re-projects the vertical's roles), then flip routing. Ordering is data-first:
-    // a crash before the flip leaves the scope serving from its old script, intact,
-    // and the adopt retries idempotently. The scope's version pointer moves to the
-    // serving version in the same act, so Update stops offering a crossing it
-    // already made.
+    // #286/#321: adopt a LEGACY scope onto its vertical's stable serving script — the
+    // one-time data hop off per-version dispatch, and the builder-triggerable backfill for
+    // installs that predate the in-place serve. The whole body lives in
+    // `adoptScopeOntoServing` (shared with the automatic adoption a prod promote runs);
+    // here it is just mapped to a JSON response.
     app.post('/tenants/:tenantId/scopes/:scopeId/adopt-serving', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
-        const actor = c.get('actor');
-        const scope = await admin.getScopeRecord(actor, tenantId, scopeId);
-        if (!scope)
-            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
-        if (scope.servingRef) {
-            return c.json({ adopted: scopeId, servingRef: scope.servingRef, alreadyAdopted: true });
+        try {
+            const r = await adoptScopeOntoServing(c, tenantId, scopeId);
+            return c.json({ adopted: scopeId, ...r });
         }
-        if (!scope.vertical) {
-            return c.json({ error: 'scope has no vertical — nothing to adopt onto' }, 409);
+        catch (e) {
+            if (e instanceof ControlPlaneError) {
+                return c.json({ error: e.message }, e.status);
+            }
+            throw e;
         }
-        const serving = await admin.verticalServing(actor, scope.vertical);
-        if (!serving) {
-            return c.json({ error: `vertical '${scope.vertical}' has no serving script yet — promote a version to prod first` }, 409);
+    });
+    // Backfill EVERY still-legacy active scope of a vertical in one call — the vertical-wide
+    // trigger for an install that predates the in-place serve. Owner or staff (owned-slug
+    // checked by the confinement middleware). Idempotent: already-adopted scopes are skipped
+    // and reported. A per-scope failure stops the run and surfaces which scope failed, so a
+    // re-run resumes from there (each adopt is data-first and retry-safe).
+    app.post('/verticals/:slug/adopt-serving', async (c) => {
+        const p = c.get('principal');
+        const slug = effectiveSlug(p, c.req.param('slug'));
+        const actor = c.get('actor');
+        if (p.kind === 'builder') {
+            const v = await verticalOf(actor, slug);
+            if (!v || v.ownerTenant !== p.tenantId)
+                return c.json({ error: 'forbidden' }, 403);
         }
-        const source = await verticalForScope(c, scope);
-        const dest = await options.resolveVerticalRef?.(serving.ref);
-        if (!source || !dest) {
-            return c.json({ error: 'adopt-serving needs dispatch resolution for both ends' }, 501);
+        const v = await verticalOf(actor, slug);
+        if (!v)
+            return c.json({ error: `unknown vertical '${slug}'` }, 404);
+        if (v.ownerTenant === null) {
+            return c.json({ error: 'adopt-serving is a private-vertical operation' }, 409);
         }
+        const owned = (await admin.listScopes(actor, { tenantId: v.ownerTenant, vertical: slug })).filter((s) => !s.forkedFrom && s.status === 'active');
+        const adopted = [];
+        const alreadyAdopted = [];
         try {
-            const dump = await source.exportScope(scopeId);
-            const restored = await dest.restoreScope(tenantId, scopeId, dump);
-            // Data landed — only now flip routing and move the version pointer.
-            await admin.setScopeServingRef(actor, tenantId, scopeId, serving.ref);
-            await admin.bindScopeVersion(actor, tenantId, scopeId, serving.versionId);
-            return c.json({ adopted: scopeId, servingRef: serving.ref, tables: restored.tables });
+            for (const s of owned) {
+                const r = await adoptScopeOntoServing(c, s.tenantId, s.id);
+                (r.alreadyAdopted ? alreadyAdopted : adopted).push(s.id);
+            }
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
-                return c.json({ error: e.message }, e.status);
+                return c.json({ error: e.message, adopted, alreadyAdopted }, e.status);
             }
             throw e;
         }
+        return c.json({ vertical: slug, adopted, alreadyAdopted });
     });
     // Pin a scope to a vertical version (#31; orchestration.md §4). Refuses a
     // non-admitted version below the seam — that refusal is the registry's reason to
@@ -761,8 +981,18 @@ export function createControlPlaneApi(options) {
             return c.json({ error: `no deployment is bound for vertical '${slug}'` }, 501);
         }
         const input = provisionInstanceBody.parse(await c.req.json());
+        // #310: the platform is the authoritative source of the tenant's entitlements — it
+        // gathers them HERE (not from the caller's body) and delivers them WITH provisioning so
+        // the CP-less vertical projects them and enforces plan/quota/expiry at request time
+        // (#304). A vertical predating the field ignores it; grant/revoke AFTER provision ride
+        // a re-provision (this endpoint is idempotent, K-31), meanwhile expiry still enforces
+        // locally because the projected row carries it.
+        const entitlements = await admin.listEntitlements(c.get('actor'), input.tenantId);
         try {
-            const instance = await vertical.provisionInstance(input);
+            const instance = await vertical.provisionInstance({
+                ...input,
+                entitlements,
+            });
             return c.json(instance, 201);
         }
         catch (e) {
@@ -798,10 +1028,13 @@ export function createControlPlaneApi(options) {
     // (builder-plane.md §5): they send a bare `--slug`, the control plane forms the prefix
     // from their authenticated tenant — so two builders can each own a `helpdesk` with no
     // global claim race, and a builder can never name another tenant's namespace (their
-    // prefix is fixed by auth). Staff address a vertical by its full id, so for them the raw
-    // slug is the identity. A builder slug that already contains `/` yields a two-slash id
-    // that fails `verticalSlug` validation / the ownership check downstream — fail-closed.
-    const effectiveSlug = (p, raw) => p.kind === 'builder' ? `${p.tenantSlug}/${raw}` : raw;
+    // prefix is fixed by auth). Idempotent: a builder addressing its own FULL id (e.g. the
+    // `verticalSlug` a deploy response returned) is not double-prefixed — the prefix is
+    // auth-derived either way, so this can never reach another tenant's namespace. Staff
+    // address a vertical by its full id, so for them the raw slug is the identity. A builder
+    // slug carrying any OTHER tenant's prefix yields a two-slash id that fails
+    // `verticalSlug` validation / the ownership check downstream — fail-closed.
+    const effectiveSlug = (p, raw) => p.kind === 'builder' ? (raw.startsWith(`${p.tenantSlug}/`) ? raw : `${p.tenantSlug}/${raw}`) : raw;
     app.get('/verticals', async (c) => {
         const all = await admin.listVerticals(c.get('actor'));
         const p = c.get('principal');
@@ -1012,6 +1245,12 @@ export function createControlPlaneApi(options) {
         if (channel === 'prod') {
             try {
                 await serveVersionInPlace(c.get('actor'), slug, versionId);
+                // Adopt any still-legacy owned scope onto the serving script and advance every
+                // owned scope's version — the rebind the host cascade delegated to us for a
+                // dispatch-backed vertical (#321), in the correct order (serve → adopt → rebind),
+                // so a legacy scope's data survives the promote instead of being stranded on a
+                // fresh per-version script. Retry-safe: nothing rebound these scopes yet.
+                await adoptAndRebindOwnedScopes(c, slug, versionId);
             }
             catch (e) {
                 const detail = e instanceof Error ? e.message : String(e);
@@ -1035,15 +1274,6 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'deploy is not configured on this control plane' }, 501);
         }
         const p = c.get('principal');
-        // A builder pushes a bare `--slug`; the registry id is `<tenantSlug>/<name>` (§5).
-        const slug = effectiveSlug(p, c.req.param('slug'));
-        // A builder pushes to a slug it owns, or claims an unregistered one (§3). Checked
-        // BEFORE the upload so a refused push never leaves an orphaned namespace script.
-        // `existingOwner` also lets a staff push stay ownership-idempotent (below).
-        const existingOwner = await ownerOf(c.get('actor'), slug);
-        if (p.kind === 'builder' && existingOwner !== undefined && existingOwner !== p.tenantId) {
-            return c.json({ error: 'forbidden' }, 403);
-        }
         const form = await c.req.formData();
         const raw = form.get('manifest');
         if (typeof raw !== 'string')
@@ -1051,6 +1281,56 @@ export function createControlPlaneApi(options) {
         const manifest = deployManifest.parse(JSON.parse(raw));
         // §4 sandbox contract, before anything reaches the namespace.
         assertSandboxContract(manifest);
+        // The workspace this push is FOR — the project's pin (package.json `substrat.tenant`),
+        // sent by the CLI alongside the bundle. The pin is intent, and intent is honored or
+        // refused, never silently reinterpreted: a BUILDER's workspace is already fixed by
+        // auth, so a pin naming a different one is a 403 rather than a push that lands
+        // somewhere the project didn't say; STAFF have no workspace of their own, so the pin
+        // is what makes their push land as the tenant's — prefixed and owned exactly as the
+        // equivalent builder push — instead of claiming the slug platform-owned (unowned ⇒
+        // invisible in every workspace dashboard, and never self-admitting) with the pin
+        // silently dropped. An old CLI that sends no pin keeps today's behavior on all paths.
+        const pinField = form.get('tenant');
+        const pin = typeof pinField === 'string' && pinField.length > 0 ? pinField : null;
+        // Resolve the registry id + owner this push acts on. Checked BEFORE the upload so a
+        // refused push never leaves an orphaned namespace script.
+        const bare = c.req.param('slug');
+        let slug;
+        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);
+            }
+            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);
+            }
+            ownerTenant = p.tenantId;
+        }
+        else if (pin) {
+            const workspace = (await admin.listTenants(c.get('actor'))).find((t) => t.slug === pin || t.id === pin);
+            if (!workspace)
+                return c.json({ error: `unknown workspace '${pin}'` }, 404);
+            // 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 —
+            // same namespace, no claim race with other workspaces' bare names.
+            const bareOwner = await ownerOf(c.get('actor'), bare);
+            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);
+            }
+            ownerTenant = workspace.id;
+        }
+        else {
+            // No pin: the raw slug is the identity and an existing owner is preserved
+            // (null ⇒ platform-owned for a first-party vertical) — unchanged staff behavior.
+            slug = bare;
+            ownerTenant = (await ownerOf(c.get('actor'), slug)) ?? null;
+        }
         const modules = [];
         for (const [name, value] of form.entries()) {
             if (name === 'manifest')
@@ -1081,23 +1361,33 @@ export function createControlPlaneApi(options) {
             });
         }
         catch (e) {
-            // The upload to the runtime failed (e.g. Cloudflare rejected the script). This is
-            // a platform/runtime error, not a bad request — surface the detail (the builder is
+            // The upload to the runtime failed. Surface the detail (the builder is
             // authenticated) rather than the anonymous 500 the generic handler would give, so a
-            // push failure is diagnosable without reading worker logs.
+            // push failure is diagnosable without reading worker logs. The version label is NOT
+            // consumed here: registration/publish happen only AFTER a successful upload (below),
+            // so a failed push leaves the same --version reusable (#307).
+            //
+            // Answer the upstream status honestly: a runtime 4xx is a bad-bundle rejection — the
+            // builder's own script (e.g. a module-top-level throw → CF 10021), well-formed HTTP
+            // but refused — so a 422, not a 502 that reads as a platform outage. A 5xx (or any
+            // throw with no upstream status) is a platform failure and stays a 502.
             const detail = e instanceof Error ? e.message : String(e);
-            console.error('deploy.upload.failed', { slug, deploymentRef, detail });
-            return c.json({ error: 'deploy upload failed', detail }, 502);
+            const upstream = upstreamStatusOf(e);
+            console.error('deploy.upload.failed', { slug, deploymentRef, detail, upstream });
+            return upstream !== undefined && upstream >= 400 && upstream < 500
+                ? c.json({ error: 'deploy rejected', detail }, 422)
+                : c.json({ error: 'deploy upload failed', detail }, 502);
         }
         // Register-then-publish, both idempotent-ish below the seam: a first push of a
-        // slug registers it; publishVersion lands the version pending with deploymentRef.
-        // A builder push claims the slug for its tenant; a staff push preserves the existing
-        // owner (null ⇒ platform-owned for a first-party vertical) rather than clobbering it.
+        // slug registers it; publishVersion lands the version pending with deploymentRef
+        // (or admitted, for a PRIVATE vertical — the registry's self-admit rule). The owner
+        // was resolved with the slug above: the builder's tenant, the pinned workspace, or
+        // the preserved existing owner for an unpinned staff push.
         await admin.registerVertical(c.get('actor'), {
             slug,
             name: manifest.name ?? slug,
             source: 'cli',
-            ownerTenant: p.kind === 'builder' ? p.tenantId : (existingOwner ?? null),
+            ownerTenant,
             // The vertical's declared config surface rides to the registry, so the dashboard
             // renders a settings form for a pushed vertical exactly like a builtin.
             ...(manifest.envSpec ? { envSpec: manifest.envSpec } : {}),
@@ -1107,6 +1397,9 @@ export function createControlPlaneApi(options) {
             ...(manifest.entitlements ? { entitlements: manifest.entitlements } : {}),
             ...(manifest.provides ? { provides: manifest.provides } : {}),
             ...(manifest.requires ? { requires: manifest.requires } : {}),
+            // The declared surfaces (K-26) ride like envSpec: registry metadata for the
+            // hostname-binding picker, never behavior. Not part of any admission digest.
+            ...(manifest.surfaces ? { surfaces: manifest.surfaces } : {}),
         });
         await admin.publishVersion(c.get('actor'), {
             id,
@@ -1120,8 +1413,23 @@ export function createControlPlaneApi(options) {
             // bytes, this keeps their shape (entry, compat, doClasses, bindings).
             manifestJson: JSON.stringify(manifest),
         });
+        // Same spirit as the permission-surface gate, advisory tier: when the push DECLARES
+        // surfaces, name any surface that hostnames are still bound to but the declaration
+        // dropped — the URL keeps resolving (routing never keys on the declaration), it just
+        // serves whatever the vertical does for an unknown surface. A push declaring nothing
+        // opts out of the check entirely.
+        const warnings = [];
+        if (manifest.surfaces?.length) {
+            const declared = new Set(manifest.surfaces.map((s) => s.name));
+            const bound = await admin.listHostnames(c.get('actor'), {});
+            for (const h of bound) {
+                if (h.verticalSlug === slug && !declared.has(h.surface)) {
+                    warnings.push(`hostname '${h.hostname}' is bound to surface '${h.surface}', which this version no longer declares`);
+                }
+            }
+        }
         const version = (await admin.listVersions(c.get('actor'), slug)).find((v) => v.id === id);
-        return c.json(version, 201);
+        return c.json({ ...version, ...(warnings.length ? { warnings } : {}) }, 201);
     });
     // -- observability (design/observability.md §4.1) --------------------------
     // Proxied Cloudflare-native reads: the console's fleet view and (later, owner-
@@ -1179,20 +1487,46 @@ export function createControlPlaneApi(options) {
         return c.json({ token, tenantSlug: tenant.slug }, 201);
     });
     // -- the hostname map (§4.7, K-26) -----------------------------------------
-    // The three STAFF actions land here. `resolveHostname` deliberately does NOT:
-    // it is the router's per-request machine path, unaudited by design (K-24), and
-    // putting it on the audited staff surface would either flood the log or quietly
-    // create an unaudited route on a surface whose whole claim is that it is audited.
-    // The router reads the directory directly; it does not come through here.
+    // Staff actions, PLUS a tenant-narrowed builder view (multi-surface exposure —
+    // binding an EKA-style second surface is self-serve for the scope's own tenant).
+    // `resolveHostname` deliberately does NOT land here: it is the router's per-request
+    // machine path, unaudited by design (K-24), and putting it on the audited staff
+    // surface would either flood the log or quietly create an unaudited route on a
+    // surface whose whole claim is that it is audited. The router reads the directory
+    // directly; it does not come through here.
+    // A builder's view of one hostname: the row when it belongs to their tenant,
+    // undefined otherwise — a foreign hostname must read as nonexistent, never as 403
+    // (which would confirm the name is taken by someone).
+    const tenantHostname = async (c, name) => {
+        const p = c.get('principal');
+        const filter = p.kind === 'builder' ? { tenantId: p.tenantId } : {};
+        return (await admin.listHostnames(c.get('actor'), filter)).find((h) => h.hostname === name.toLowerCase());
+    };
     app.get('/hostnames', async (c) => {
+        const p = c.get('principal');
         const filter = listHostnamesQuery.parse({
             tenantId: c.req.query('tenantId'),
             scopeId: c.req.query('scopeId'),
         });
+        // A builder's list is ALWAYS its own tenant's — the query may narrow further
+        // (scopeId) but never widen; a foreign tenantId in the query loses silently.
+        if (p.kind === 'builder')
+            filter.tenantId = p.tenantId;
         return c.json(await admin.listHostnames(c.get('actor'), filter));
     });
     app.post('/hostnames', async (c) => {
+        const p = c.get('principal');
         const input = bindHostnameBody.parse(await c.req.json());
+        if (p.kind === 'builder') {
+            // The body names the tenant the binding lands under; a builder may only name
+            // its own (the adapter then verifies the scope belongs to it, K-3).
+            if (input.tenantId !== p.tenantId)
+                return c.json({ error: 'forbidden' }, 403);
+            // The region column is an EU-residency claim (K-30) — never builder-suppliable.
+            if (input.region !== null) {
+                return c.json({ error: 'region is derived from the scope, not chosen on a binding' }, 403);
+            }
+        }
         await admin.bindHostname(c.get('actor'), input);
         const bound = (await admin.listHostnames(c.get('actor'), { scopeId: input.scopeId })).find((h) => h.hostname === input.hostname);
         return c.json(bound, 201);
@@ -1202,15 +1536,23 @@ export function createControlPlaneApi(options) {
         // Not path-parsed through the schema: a hostname is the path segment here, and
         // `setHostnameStatus` normalizes and 404s an unknown one below the seam.
         const name = c.req.param('hostname');
+        if (c.get('principal').kind === 'builder' && !(await tenantHostname(c, name))) {
+            return c.json({ error: `unknown hostname: ${name.toLowerCase()}` }, 404);
+        }
         await admin.setHostnameStatus(c.get('actor'), name, status, note);
         const row = (await admin.listHostnames(c.get('actor'), {})).find((h) => h.hostname === name.toLowerCase());
         return c.json(row);
     });
     // Unbind (hard-delete) a hostname row — what the orphan cleanup uses on rows
-    // whose scope is archived or gone. Staff-only (not in BUILDER_ROUTES), audited
-    // below the seam, idempotent: an unknown hostname deletes nothing and still 200s.
+    // whose scope is archived or gone, and what an operator uses to retire a surface
+    // URL. Audited below the seam, idempotent for staff: an unknown hostname deletes
+    // nothing and still 200s. For a builder a hostname outside their tenant is a 404 —
+    // idempotency yields to existence hiding at the tenant boundary.
     app.delete('/hostnames/:hostname', async (c) => {
         const name = c.req.param('hostname');
+        if (c.get('principal').kind === 'builder' && !(await tenantHostname(c, name))) {
+            return c.json({ error: `unknown hostname: ${name.toLowerCase()}` }, 404);
+        }
         await admin.unbindHostname(c.get('actor'), name);
         return c.json({ deleted: name.toLowerCase() });
     });