@substrat-run/control-plane-api 0.24.0 → 0.26.0

package/dist/api.d.ts

@@ -5,6 +5,7 @@ import type { PlatformActorAuth, BuilderAuth, Principal } from './auth.js';
 import type { VerticalClient } from './vertical-client.js';
 import type { DeployVerticalFn, FetchVerticalModulesFn } from './deploy.js';
 import type { ObservabilityReader } from './observability.js';
+import { type CustomHostnameProvisioner } from './custom-hostnames.js';
 export interface ControlPlaneApiOptions {
     host: ScopeHost;
     /**
@@ -89,6 +90,23 @@ export interface ControlPlaneApiOptions {
      * means forgetting that costs a feature, never a leak.
      */
     observability?: ObservabilityReader;
+    /**
+     * Issues + polls Cloudflare-for-SaaS custom hostnames (#305, §4.7) — host-injected
+     * like `deployVertical`, so this package holds no Cloudflare credential (D-34). When
+     * present, binding a CUSTOM domain kicks off issuance (create → `verifying` + DNS
+     * records) instead of leaving a bare `pending` row that only a manual status flip
+     * could clear. Absent ⇒ a custom bind records `pending` and issuance never runs (the
+     * self-host / dev shape, where there is no CF-for-SaaS zone).
+     */
+    provisionHostname?: CustomHostnameProvisioner;
+    /**
+     * The platform's base domains — the wildcard-covered zones a PLATFORM hostname is
+     * minted under (`substrat.run`, `global.substrat.run`, …). A bind AT or UNDER one of
+     * these rides the wildcard cert and goes straight to `active`; anything else is a
+     * custom domain and walks issuance. Empty/absent ⇒ every bind is treated as custom
+     * (correct for a deployment that mints no platform hostnames).
+     */
+    platformBaseDomains?: string[];
 }
 type Vars = {
     actor: PlatformActorId;

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AA2B5B,OAAO,KAAK,EAAE,eAAe,EAA4B,MAAM,yBAAyB,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAY3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAChG;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,KACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACpF;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,sBAAsB,CAAC;IAC9C;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC;IAClC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAKD,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AAsH7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAkzChG"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AA2B5B,OAAO,KAAK,EAAE,eAAe,EAA4B,MAAM,yBAAyB,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAa3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAChG;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,KACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACpF;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,sBAAsB,CAAC;IAC9C;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC;IAClC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;IAC9C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAKD,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AA4H7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CA0nDhG"}

package/dist/api.js

@@ -4,8 +4,9 @@ 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';
+import { isCustomHostname, validateBindableHostname, } from './custom-hostnames.js';
 // -- request schemas ---------------------------------------------------------
 // Parse, don't trust: every input crosses Zod at the boundary. The ids stay
 // CALLER-SUPPLIED rather than minted here, exactly as the contract has them —
@@ -101,7 +102,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(),
 });
@@ -191,6 +198,8 @@ export function createControlPlaneApi(options) {
         { method: 'GET', re: /\/hostnames$/ },
         { method: 'POST', re: /\/hostnames$/ },
         { method: 'PATCH', re: /\/hostnames\/[^/]+\/status$/ },
+        // Re-poll issuance ("check again") — self-serve for the scope's own tenant (#305).
+        { method: 'POST', re: /\/hostnames\/[^/]+\/verify$/ },
         { method: 'DELETE', re: /\/hostnames\/[^/]+$/ },
     ];
     app.use('*', async (c, next) => {
@@ -209,6 +218,20 @@ export function createControlPlaneApi(options) {
             return c.json({ error: 'invalid request', issues: err.issues }, 400);
         }
         const { status, body } = mapError(err);
+        // A 500 is, by definition, a throw whose message `mapError` did not recognise — so the
+        // client gets a GENERIC body that discloses nothing, and until now nothing recorded WHAT
+        // threw either. That left every unmapped failure (e.g. a raw SQLite constraint from a
+        // registry write, or a deploy that 500s with no detail) undiagnosable without reproducing
+        // it. Log the real error + the request that provoked it, server-side only, so the worker
+        // tail names the cause. Mapped 4xx are honest refusals — no log needed.
+        if (status >= 500) {
+            console.error('control-plane.unhandled', {
+                method: c.req.method,
+                path: c.req.path,
+                detail: err instanceof Error ? err.message : String(err),
+                stack: err instanceof Error ? err.stack : undefined,
+            });
+        }
         return c.json(body, status);
     });
     // -- tenant registry (§4.1) ------------------------------------------------
@@ -246,6 +269,47 @@ 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) => {
@@ -356,6 +420,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'));
@@ -367,6 +507,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'));
@@ -544,6 +714,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
@@ -601,6 +804,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);
@@ -612,7 +820,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
@@ -664,50 +878,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
@@ -1037,6 +1262,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);
@@ -1147,13 +1378,22 @@ 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
@@ -1291,6 +1531,53 @@ export function createControlPlaneApi(options) {
             filter.tenantId = p.tenantId;
         return c.json(await admin.listHostnames(c.get('actor'), filter));
     });
+    // Which base domains ride the platform wildcard cert (go straight to `active`);
+    // everything else is a custom domain that walks Cloudflare-for-SaaS issuance (§4.7).
+    const platformBaseDomains = options.platformBaseDomains ?? [];
+    const custom = (hostname) => isCustomHostname(hostname, platformBaseDomains);
+    /**
+     * Drive a freshly-bound (or re-checked) hostname through issuance (§4.7):
+     *
+     *   - a PLATFORM mint rides the wildcard cert → flip straight to `active`;
+     *   - a CUSTOM domain, when a provisioner is configured → `create` (on first bind) or
+     *     `check` (a re-verify), persisting status + DNS records + the CF id;
+     *   - a custom domain with NO provisioner (self-host/dev) → left `pending`.
+     *
+     * Failures are swallowed to a `failed`/`pending` note rather than thrown: a bind that
+     * recorded the row must still return 201, and the reconcile sweep retries.
+     */
+    const runIssuance = async (actor, row) => {
+        if (!custom(row.hostname)) {
+            // Platform mint: rides *.<base> — no per-hostname CF object, immediately servable.
+            if (row.status !== 'active')
+                await admin.setHostnameStatus(actor, row.hostname, 'active');
+            return;
+        }
+        if (!options.provisionHostname)
+            return; // no CF-for-SaaS zone here; stays pending
+        try {
+            const issuance = row.customHostnameId
+                ? await options.provisionHostname.check(row.customHostnameId)
+                : await options.provisionHostname.create(row.hostname);
+            await admin.setHostnameIssuance(actor, row.hostname, {
+                status: issuance.status,
+                note: issuance.note,
+                // Only write the id on create; a re-check leaves it untouched (undefined).
+                customHostnameId: row.customHostnameId ? undefined : issuance.customHostnameId,
+                validationRecords: issuance.records,
+            });
+        }
+        catch (err) {
+            // Record the failure as a note but keep the row — the sweep re-attempts. Never
+            // turn a transient CF error into a lost binding.
+            await admin.setHostnameIssuance(actor, row.hostname, {
+                status: 'failed',
+                note: err instanceof Error ? err.message : String(err),
+                validationRecords: row.validationRecords,
+            });
+        }
+    };
+    const hostnameRow = async (c, name) => (await admin.listHostnames(c.get('actor'), {})).find((h) => h.hostname === name.toLowerCase());
     app.post('/hostnames', async (c) => {
         const p = c.get('principal');
         const input = bindHostnameBody.parse(await c.req.json());
@@ -1304,9 +1591,36 @@ export function createControlPlaneApi(options) {
                 return c.json({ error: 'region is derived from the scope, not chosen on a binding' }, 403);
             }
         }
+        // Registrable-suffix guard (#305, D-35): a custom domain must be a real registrable
+        // name, never a bare public suffix whose cookie would span tenants. Platform mints
+        // skip it — they are the platform's own registrable domain by construction.
+        if (custom(input.hostname)) {
+            const bad = validateBindableHostname(input.hostname);
+            if (bad)
+                return c.json({ error: bad }, 422);
+        }
         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);
+        if (bound)
+            await runIssuance(c.get('actor'), bound);
+        // Re-read so the response carries the post-issuance status + DNS records the caller
+        // (dashboard / CLI) renders — a custom bind comes back `verifying` with records.
+        const out = (await admin.listHostnames(c.get('actor'), { scopeId: input.scopeId })).find((h) => h.hostname === input.hostname);
+        return c.json(out ?? bound, 201);
+    });
+    // Re-poll a custom hostname's issuance ("check again" in the dashboard). Tenant-narrowed
+    // like the other hostname routes; a platform mint or an already-active row is a no-op
+    // re-affirm. Idempotent and safe to hammer — it just reflects Cloudflare's current state.
+    app.post('/hostnames/:hostname/verify', 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);
+        }
+        const row = await hostnameRow(c, name);
+        if (!row)
+            return c.json({ error: `unknown hostname: ${name.toLowerCase()}` }, 404);
+        await runIssuance(c.get('actor'), row);
+        return c.json(await hostnameRow(c, name));
     });
     app.patch('/hostnames/:hostname/status', async (c) => {
         const { status, note } = setHostnameStatusBody.parse(await c.req.json());
@@ -1330,6 +1644,14 @@ export function createControlPlaneApi(options) {
         if (c.get('principal').kind === 'builder' && !(await tenantHostname(c, name))) {
             return c.json({ error: `unknown hostname: ${name.toLowerCase()}` }, 404);
         }
+        // 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:
+        // a CF failure must not strand the unbind — the row still goes, and a leaked CF
+        // hostname is a cleanup nuisance, not a routing hazard. `remove` already tolerates 404.
+        const row = await hostnameRow(c, name);
+        if (row?.customHostnameId && options.provisionHostname) {
+            await options.provisionHostname.remove(row.customHostnameId).catch(() => { });
+        }
         await admin.unbindHostname(c.get('actor'), name);
         return c.json({ deleted: name.toLowerCase() });
     });