@substrat-run/control-plane-api 0.13.0 → 0.16.0

package/dist/api.js

@@ -1,9 +1,11 @@
 import { Hono } from 'hono';
-import { adminAction, channelName, createTenantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, registerVerticalInput, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, z, } from '@substrat-run/contracts';
+import { adminAction, channelName, createTenantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, registerVerticalInput, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, z, } from '@substrat-run/contracts';
 import { ulid } from '@substrat-run/kernel';
 import { ControlPlaneError } from './client.js';
 import { mapError } from './errors.js';
+import { maskDump } from './mask.js';
 import { assertSandboxContract, deployManifest, deploymentRefFor } 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
 // CALLER-SUPPLIED rather than minted here, exactly as the contract has them —
@@ -31,6 +33,10 @@ const provisionInstanceBody = z.object({
     owner: z.string().min(1),
     slug: z.string().min(1),
     name: z.string().min(1),
+    config: z.record(z.string(), z.string()).optional(),
+});
+const configureInstanceBody = z.object({
+    entries: z.array(z.object({ key: z.string().min(1), value: z.string() })).min(1),
 });
 const bindHostnameBody = z.object({
     hostname: hostnameSchema,
@@ -67,7 +73,19 @@ const promoteVersionBody = z.object({
     // needs no acknowledgement.
     acknowledge: promotionAcknowledgement.optional(),
 });
-const bindScopeVersionBody = z.object({ versionId: z.string().min(1) });
+const bindScopeVersionBody = z.object({
+    versionId: z.string().min(1),
+    // Fork-before-promote (preview-and-snapshots.md §4): snapshot the pre-migration
+    // data first when this bind crosses a migration-digest boundary. Optional and
+    // ignored on a code-only rebind — the digest compare is the gate, not the flag.
+    snapshot: z.boolean().optional(),
+});
+// A snapshot request (preview-and-snapshots.md §3/§9). `expiresAt` opts into the GC
+// sweep; absent = pinned until deliberately deleted. `kind` defaults to 'archive'.
+const snapshotScopeBody = z.object({
+    kind: z.string().min(1).optional(),
+    expiresAt: z.string().datetime({ offset: true }).optional(),
+});
 const listRolesQuery = z.object({
     tenantId: tenantIdSchema.optional(),
     // Free-form: a module id or 'vertical'. Not narrowed to the source union here
@@ -155,8 +173,12 @@ export function createControlPlaneApi(options) {
         { method: 'GET', re: /\/verticals\/[^/]+\/versions$/ },
         { method: 'POST', re: /\/verticals\/[^/]+\/versions$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/channels$/ },
+        { method: 'GET', re: /\/verticals\/[^/]+\/channels\/[^/]+\/history$/ },
         { method: 'POST', re: /\/verticals\/[^/]+\/channels\/[^/]+\/promote$/ },
         { method: 'POST', re: /\/verticals\/[^/]+\/deploy$/ },
+        // 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$/ },
     ];
     app.use('*', async (c, next) => {
         if (c.get('principal').kind === 'builder') {
@@ -237,6 +259,106 @@ export function createControlPlaneApi(options) {
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
         return c.json(record);
     });
+    // Read-only introspection of a scope's own database (kernel-design §5.4 admin-query
+    // RPC) — the console/dashboard "Data" view.
+    //
+    // The scope's DATA lives in the vertical's own deployment (K-31), NOT in this control
+    // plane's own (empty-module) scope host — so we DELEGATE to the vertical, the mirror
+    // of `/verticals/:slug/instances`. `getScopeRecord` first does the K-3 cross-check +
+    // access-log entry and tells us which vertical (and which VERSION) backs the scope.
+    //
+    // Resolution order matters. A scope's data DO lives in the deployment of its BOUND
+    // version (`verticalVersionId`) — each `substrat push` is a separate WfP script with
+    // its own DO namespace, so the prod-channel deployment is the wrong one the moment an
+    // installed app lags prod. So we prefer bound-version resolution, then fall back to
+    // prod-channel/static (a scope with no bound version), then to reading this host's own
+    // scope DB directly (a co-located host, or the contract tests — data is right here).
+    const verticalForScope = async (c, scope) => {
+        const slug = scope.vertical;
+        if (!slug)
+            return undefined;
+        const actor = c.get('actor');
+        if (scope.verticalVersionId && options.resolveVerticalVersion) {
+            const bound = await options.resolveVerticalVersion(slug, scope.verticalVersionId, actor);
+            if (bound)
+                return bound;
+        }
+        return options.verticals?.[slug] ?? (await options.resolveVertical?.(slug, actor));
+    };
+    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'));
+        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);
+        return c.json(vertical
+            ? await vertical.listScopeTables(scopeId)
+            : await admin.listScopeTables(c.get('actor'), tenantId, scopeId));
+    });
+    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'));
+        const input = readScopeTableInput.parse({
+            table: c.req.param('table'),
+            limit: c.req.query('limit') ? Number(c.req.query('limit')) : undefined,
+            offset: c.req.query('offset') ? Number(c.req.query('offset')) : undefined,
+        });
+        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);
+        return c.json(vertical
+            ? await vertical.readScopeTable(scopeId, input)
+            : await admin.readScopeTable(c.get('actor'), tenantId, scopeId, input));
+    });
+    // The SQL console (#219): one read-only statement, POSTed because SQL does not
+    // belong in a URL. Same delegation as the table reads; the gate's refusal maps to
+    // 400 (errors.ts), and a vertical that cannot answer safely (auth-server, whose
+    // DO redacts secret columns on table reads — arbitrary SQL would walk around the
+    // redaction) refuses via its own 501, relayed verbatim.
+    app.post('/tenants/:tenantId/scopes/:scopeId/query', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const input = queryScopeInput.parse(await c.req.json());
+        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);
+        return c.json(vertical
+            ? await vertical.queryScope(scopeId, input)
+            : await admin.queryScope(c.get('actor'), tenantId, scopeId, input));
+    });
+    // Deliver per-instance CONFIG to the scope's own storage (vertical-auth-detach.md
+    // §2.2) — the missing "delivery" step behind the dashboard's Env tab. Same K-3
+    // addressing + bound-version resolution as introspection: the scope's DO lives in the
+    // deployment of its BOUND version, so that is where its config must land. A scope with
+    // no reachable vertical deployment (co-located/contract-test hosts run no vertical
+    // code) has nowhere to deliver to — 501, so the caller can tell "authored but not
+    // delivered" from "failed". The vertical's own status (e.g. its 501 for no live-config
+    // support) propagates rather than collapsing to a 500.
+    app.post('/tenants/:tenantId/scopes/:scopeId/configure', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const input = configureInstanceBody.parse(await c.req.json());
+        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);
+        if (!vertical) {
+            return c.json({ error: `no deployment is bound for vertical '${scope.vertical ?? '(none)'}'` }, 501);
+        }
+        try {
+            await vertical.configureInstance({ tenantId, scopeId, entries: input.entries });
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError) {
+                return c.json({ error: e.message }, e.status);
+            }
+            throw e;
+        }
+        return c.json({ applied: input.entries.length });
+    });
     // The four lifecycle transitions, one route each — mirroring the four audited
     // actions rather than collapsing into a PATCH that would accept a target
     // status the transition graph forbids. The graph is enforced below the seam;
@@ -256,15 +378,178 @@ export function createControlPlaneApi(options) {
             return c.json(await admin.getScopeRecord(c.get('actor'), tenantId, scopeId));
         });
     }
+    // -- snapshots (preview-and-snapshots.md §3/§9) -----------------------------
+    // The DATA half of a snapshot runs inside the vertical's own deployment (the
+    // scope's bytes never cross the boundary — the §9 property the trust line rests
+    // on); the DIRECTORY half — provenance row, activation, version bind — runs here.
+    // With no vertical client resolved (co-located host, tests, self-host) the host's
+    // in-process snapshotScope does both halves against its own SCOPE namespace.
+    const orchestratedSnapshot = async (c, tenantId, scope, opts) => {
+        const actor = c.get('actor');
+        const vertical = await verticalForScope(c, scope);
+        if (!vertical)
+            return options.host.snapshotScope(actor, tenantId, scope.id, opts);
+        const snapId = scopeIdSchema.parse(ulid());
+        // Directory row FIRST, as `provisioning` (K-31's two-phase shape, used as
+        // intended): a crash between the row and the data copy leaves an inert
+        // provisioning row — which, carrying provenance and an expiry, the GC sweep
+        // eventually reaps — never copied data with no record.
+        await options.host.provisionScope(actor, {
+            tenantId,
+            scopeId: snapId,
+            kind: opts.kind ?? 'archive',
+            vertical: scope.vertical,
+            jurisdiction: scope.jurisdiction,
+            forkedFrom: scope.id,
+            forkedAt: new Date().toISOString(),
+            expiresAt: opts.expiresAt,
+        });
+        await vertical.snapshotScope({ sourceScopeId: scope.id, newScopeId: snapId });
+        await admin.activateScope(actor, tenantId, snapId);
+        // Bound to the SOURCE's current version: source and fork share a deployment, so
+        // the fork resolves to the DO namespace its bytes actually live in.
+        if (scope.verticalVersionId) {
+            await admin.bindScopeVersion(actor, tenantId, snapId, scope.verticalVersionId);
+        }
+        return snapId;
+    };
+    // The forks OF one scope — what a Snapshots UI lists. A directory read (kind,
+    // provenance, expiry all live on the scope row); newest first.
+    app.get('/tenants/:tenantId/scopes/:scopeId/snapshots', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const scopes = await admin.listScopes(c.get('actor'), { tenantId });
+        return c.json(scopes
+            .filter((s) => s.forkedFrom === scopeId)
+            .sort((a, b) => (a.forkedAt < b.forkedAt ? 1 : -1)));
+    });
+    app.post('/tenants/:tenantId/scopes/:scopeId/snapshots', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const body = snapshotScopeBody.parse(await c.req.json().catch(() => ({})));
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        try {
+            const snapId = await orchestratedSnapshot(c, tenantId, scope, body);
+            return c.json(await admin.getScopeRecord(c.get('actor'), tenantId, snapId), 201);
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError) {
+                return c.json({ error: e.message }, e.status);
+            }
+            throw e;
+        }
+    });
+    // Reap a fork. The fork-only refusal is surfaced HERE, before any delegation —
+    // the vertical must never even be asked to wipe a primary scope — and re-checked
+    // below the seam by deleteSnapshot, which also wipes the co-located storage,
+    // removes hostnames + the directory row, and writes the audit entry.
+    app.delete('/tenants/:tenantId/scopes/:scopeId', 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.forkedFrom) {
+            return c.json({ error: `scope ${scopeId} is not a fork — only snapshots may be deleted` }, 409);
+        }
+        try {
+            // Vertical's storage first, then the in-process delete (refusal re-check,
+            // local/placeholder wipe, hostnames + directory row, audit) — the same
+            // storage-before-row ordering deleteSnapshot itself keeps, so a crash
+            // between the two converges on retry.
+            const vertical = await verticalForScope(c, scope);
+            if (vertical)
+                await vertical.deleteScope({ scopeId });
+            await options.host.deleteSnapshot(actor, tenantId, scopeId);
+            return c.json({ deleted: 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
+    // exportScope access-log entry), jurisdiction-gated, and MASKED by default —
+    // `?full=true` is the explicit break-glass. Dumps are JSON-safe today (no BLOB
+    // columns exist in any schema); a vertical that adds one needs an encoding here.
+    app.get('/tenants/:tenantId/scopes/:scopeId/export', 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);
+        // 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);
+        }
+        const full = c.req.query('full') === 'true';
+        try {
+            // The canonical export first: it writes the K-24 access-log entry and is the
+            // bytes when the host is co-located. When the scope's data lives in a vertical
+            // deployment, its dump OVERLAYS the (placeholder) tables — audit stays on the
+            // one canonical path either way.
+            const dump = await admin.exportScope(actor, tenantId, scopeId);
+            const vertical = await verticalForScope(c, scope);
+            const tables = vertical ? await vertical.exportScope(scopeId) : dump.tables;
+            return c.json({ ...dump, tables: full ? tables : maskDump(tables), masked: !full });
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError) {
+                return c.json({ error: e.message }, e.status);
+            }
+            throw e;
+        }
+    });
     // Pin a scope to a vertical version (#31; orchestration.md §4). Refuses a
     // non-admitted version below the seam — that refusal is the registry's reason to
-    // exist. A scope operation, so it keeps the scope route shape.
+    // exist. A scope operation, so it keeps the scope route shape. `snapshot: true`
+    // opts into fork-before-promote (§4): on a migration-digest-crossing bind the
+    // pre-migration data is snapshotted first — orchestrated through the vertical
+    // when one resolves, in-process otherwise.
     app.post('/tenants/:tenantId/scopes/:scopeId/version', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
-        const { versionId } = bindScopeVersionBody.parse(await c.req.json());
-        await admin.bindScopeVersion(c.get('actor'), tenantId, scopeId, versionId);
-        return c.json(await admin.getScopeRecord(c.get('actor'), tenantId, scopeId));
+        const { versionId, snapshot } = bindScopeVersionBody.parse(await c.req.json());
+        const actor = c.get('actor');
+        if (snapshot) {
+            const scope = await admin.getScopeRecord(actor, tenantId, scopeId);
+            if (!scope) {
+                return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+            }
+            const vertical = await verticalForScope(c, scope);
+            if (vertical) {
+                // Delegated path: the digest compare lives here (the in-process path does
+                // it below the seam). Snapshot only a migration-crossing bind.
+                if (scope.vertical && scope.verticalVersionId) {
+                    const versions = await admin.listVersions(actor, scope.vertical);
+                    const current = versions.find((v) => v.id === scope.verticalVersionId);
+                    const incoming = versions.find((v) => v.id === versionId);
+                    if (current && incoming && current.migrationDigest !== incoming.migrationDigest) {
+                        await orchestratedSnapshot(c, tenantId, scope, {});
+                    }
+                }
+                await admin.bindScopeVersion(actor, tenantId, scopeId, versionId);
+            }
+            else {
+                await admin.bindScopeVersion(actor, tenantId, scopeId, versionId, { snapshot: true });
+            }
+            return c.json(await admin.getScopeRecord(actor, tenantId, scopeId));
+        }
+        await admin.bindScopeVersion(actor, tenantId, scopeId, versionId);
+        return c.json(await admin.getScopeRecord(actor, tenantId, scopeId));
     });
     // -- instances (K-31) -------------------------------------------------------
     // The one place this surface calls OUT rather than sitting over `HostAdmin`, and
@@ -278,6 +563,13 @@ export function createControlPlaneApi(options) {
     // in-between properly, and it is still unused — see the PR.
     app.post('/verticals/:slug/instances', async (c) => {
         const slug = c.req.param('slug');
+        // The install kill-switch: a blocked vertical takes no NEW instances, for anyone
+        // including its owner. Refused before deployment resolution so the answer is
+        // uniform whether or not anything is deployed. Existing scopes keep serving.
+        const registered = (await 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);
+        }
         // 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')));
@@ -314,6 +606,10 @@ export function createControlPlaneApi(options) {
         const v = (await admin.listVerticals(actor)).find((x) => x.slug === slug);
         return v ? v.ownerTenant : undefined;
     };
+    // The full registry row, for the checks that need more than the owner — whether the
+    // vertical is PRIVATE (owned + not listed), which is what scopes a builder's prod
+    // self-serve below.
+    const verticalOf = async (actor, slug) => (await admin.listVerticals(actor)).find((x) => x.slug === slug);
     // The vertical id a request actually addresses. For a BUILDER it is `<tenantSlug>/<name>`
     // (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
@@ -389,6 +685,43 @@ export function createControlPlaneApi(options) {
         await admin.rejectVersion(c.get('actor'), id, note);
         return c.json((await admin.listVersions(c.get('actor'), slug)).find((v) => v.id === id));
     });
+    // A builder REQUESTS publication of a vertical it owns (marketplace-publish.md §5) — any owner
+    // may ask; the staff `listing` flip below is the review gate. Owner-checked (like promote).
+    app.post('/verticals/:slug/publish-request', async (c) => {
+        const p = c.get('principal');
+        const slug = effectiveSlug(p, c.req.param('slug'));
+        if (p.kind === 'builder' && (await ownerOf(p.actor, slug)) !== p.tenantId) {
+            return c.json({ error: 'not found' }, 404);
+        }
+        await admin.requestPublish(c.get('actor'), slug);
+        return c.json({ slug, requested: true });
+    });
+    // Publish/unpublish a vertical to the PUBLIC marketplace (marketplace-publish.md §5). Staff
+    // admission of a publish request — NOT in BUILDER_ROUTES, so a builder is refused (the review
+    // gate). `listed` then makes `availableCatalog` offer it to every tenant + resolves the request.
+    app.post('/verticals/:slug/listing', async (c) => {
+        const slug = c.req.param('slug');
+        const { listed } = z.object({ listed: z.boolean() }).parse(await c.req.json());
+        await admin.setVerticalListed(c.get('actor'), slug, listed);
+        return c.json({ slug, listed });
+    });
+    // The install kill-switch (staff-only — not in BUILDER_ROUTES, so a builder is
+    // refused by the confinement middleware). Blocks NEW installs; existing scopes
+    // keep serving. Orthogonal to /listing (visibility).
+    app.post('/verticals/:slug/install-block', async (c) => {
+        const slug = c.req.param('slug');
+        const { blocked } = z.object({ blocked: z.boolean() }).parse(await c.req.json());
+        await admin.setVerticalInstallsBlocked(c.get('actor'), slug, blocked);
+        return c.json({ slug, installsBlocked: blocked });
+    });
+    // Delete a vertical + its versions and channels (staff-only, same confinement).
+    // Refused below the seam while any scope is still bound — surfaces as a 4xx via
+    // mapError, naming the count. Dispatch scripts become orphans for cleanup (#248).
+    app.delete('/verticals/:slug', async (c) => {
+        const slug = c.req.param('slug');
+        await admin.deleteVertical(c.get('actor'), slug);
+        return c.json({ slug, deleted: true });
+    });
     app.get('/verticals/:slug/channels', async (c) => {
         const p = c.get('principal');
         const slug = effectiveSlug(p, c.req.param('slug'));
@@ -397,18 +730,35 @@ export function createControlPlaneApi(options) {
         }
         return c.json(await admin.listChannels(c.get('actor'), slug));
     });
+    // The promotion timeline (newest first) — what a rollback UI picks a target from.
+    // Owner-narrowed like the channel read above: a builder sees only its own verticals'
+    // history, and a foreign slug 404s indistinguishably from an absent one.
+    app.get('/verticals/:slug/channels/:channel/history', async (c) => {
+        const p = c.get('principal');
+        const slug = effectiveSlug(p, c.req.param('slug'));
+        const channel = channelName.parse(c.req.param('channel'));
+        if (p.kind === 'builder' && (await ownerOf(p.actor, slug)) !== p.tenantId) {
+            return c.json({ error: 'not found' }, 404);
+        }
+        return c.json(await admin.listChannelHistory(c.get('actor'), slug, channel));
+    });
     app.post('/verticals/:slug/channels/:channel/promote', async (c) => {
         const p = c.get('principal');
         const slug = effectiveSlug(p, c.req.param('slug'));
         const channel = channelName.parse(c.req.param('channel'));
         if (p.kind === 'builder') {
-            // Staff keep the prod gate (model B, §2/§4): a builder self-serves dev/staging;
-            // admission and prod promotion stay a human staff decision (the trust boundary
-            // self-serve-deploy.md §3 is explicit about). And only on verticals it owns.
-            if (channel === 'prod')
-                return c.json({ error: 'promotion to prod is staff-only' }, 403);
-            if ((await ownerOf(p.actor, slug)) !== p.tenantId)
+            // A builder promotes only verticals it owns — and 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 protected nothing; it returns the moment
+            // the audience widens (publish flips `listed`, and prod becomes staff-only
+            // again — the trust boundary marketplace-publish.md §2 draws).
+            const v = await verticalOf(p.actor, slug);
+            if (!v || v.ownerTenant !== p.tenantId)
                 return c.json({ error: 'forbidden' }, 403);
+            if (channel === 'prod' && v.listed) {
+                return c.json({ error: 'promotion to prod is staff-only for a listed vertical' }, 403);
+            }
         }
         const { versionId, acknowledge } = promoteVersionBody.parse(await c.req.json());
         // The blast-radius moment: refuses a changed digest without the acknowledgement,
@@ -420,8 +770,9 @@ export function createControlPlaneApi(options) {
     // The deploy seam (self-serve-deploy.md): a `substrat push` uploads a built bundle
     // here. The order is upload → record, deliberately: a failed record leaves an
     // orphaned namespace script (invisible, GC'able) rather than a directory row
-    // pointing at a deployment that is not there. The version lands PENDING — a push
-    // is not a deploy; admission still gates serving.
+    // pointing at a deployment that is not there. The version lands PENDING — except a
+    // PRIVATE vertical's, which self-admits below the seam (its blast radius is its own
+    // 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);
@@ -490,6 +841,15 @@ export function createControlPlaneApi(options) {
             name: manifest.name ?? slug,
             source: 'cli',
             ownerTenant: p.kind === 'builder' ? p.tenantId : (existingOwner ?? null),
+            // The vertical's declared config surface rides to the registry, so the dashboard
+            // renders a settings form for a pushed vertical exactly like a builtin.
+            ...(manifest.envSpec ? { envSpec: manifest.envSpec } : {}),
+            // Registry-driven install metadata (marketplace-publish.md §3) — so the dashboard
+            // installs a pushed vertical without a hardcoded catalog entry.
+            ...(manifest.ownerGrants ? { ownerGrants: manifest.ownerGrants } : {}),
+            ...(manifest.entitlements ? { entitlements: manifest.entitlements } : {}),
+            ...(manifest.provides ? { provides: manifest.provides } : {}),
+            ...(manifest.requires ? { requires: manifest.requires } : {}),
         });
         await admin.publishVersion(c.get('actor'), {
             id,
@@ -503,6 +863,61 @@ export function createControlPlaneApi(options) {
         const version = (await admin.listVersions(c.get('actor'), slug)).find((v) => v.id === id);
         return c.json(version, 201);
     });
+    // -- observability (design/observability.md §4.1) --------------------------
+    // Proxied Cloudflare-native reads: the console's fleet view and (later, owner-
+    // narrowed) the dashboard's builder view. STAFF-ONLY — not in BUILDER_ROUTES; see
+    // the option's doc for why. Tier-3 numbers (master-plan §5.3): sampled, approximate,
+    // never money.
+    app.get('/observability/metrics', async (c) => {
+        if (!options.observability) {
+            return c.json({ error: 'observability is not configured on this control plane' }, 501);
+        }
+        const { hours } = z
+            .object({ hours: z.coerce.number().int().min(1).max(72).default(24) })
+            .parse({ hours: c.req.query('hours') });
+        return c.json(await options.observability.serviceMetrics({ hours }));
+    });
+    app.get('/observability/logs', async (c) => {
+        if (!options.observability) {
+            return c.json({ error: 'observability is not configured on this control plane' }, 501);
+        }
+        const input = z
+            .object({
+            service: z.string().min(1).max(200).optional(),
+            level: z.enum(['log', 'info', 'warn', 'error', 'debug']).optional(),
+            hours: z.coerce.number().int().min(1).max(72).default(1),
+            limit: z.coerce.number().int().min(1).max(500).default(100),
+        })
+            .parse({
+            service: c.req.query('service') || undefined,
+            level: c.req.query('level') || undefined,
+            hours: c.req.query('hours'),
+            limit: c.req.query('limit'),
+        });
+        return c.json(await options.observability.recentLogs(input));
+    });
+    // -- push tokens (push-token.ts) -------------------------------------------
+    // Mint a tenant-scoped CI credential. STAFF-ONLY by the builder allowlist (not in
+    // BUILDER_ROUTES): the dashboard mints over its service token during git-import
+    // setup; a builder session cannot mint (their own session already authenticates
+    // them, and a self-serve mint surface deserves its own decision, not a side door).
+    // The token authenticates as a BUILDER for the named tenant — everything a builder
+    // 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);
+        }
+        const { tenantId } = z.object({ tenantId: tenantIdSchema }).parse(await c.req.json());
+        const tenant = await admin.getTenant(c.get('actor'), tenantId);
+        if (!tenant)
+            return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
+        const token = await mintPushToken(options.pushTokenSecret, {
+            actor: await pushActorFor(tenantId),
+            tenantId,
+            tenantSlug: tenant.slug,
+        });
+        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
@@ -531,6 +946,14 @@ export function createControlPlaneApi(options) {
         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.
+    app.delete('/hostnames/:hostname', async (c) => {
+        const name = c.req.param('hostname');
+        await admin.unbindHostname(c.get('actor'), name);
+        return c.json({ deleted: name.toLowerCase() });
+    });
     // -- roles, read only (§4.5 console item 4) --------------------------------
     // The READ lands; `defineRole` deliberately does not. Creating a role over
     // HTTP is a permission change, and the permission diff is a human checkpoint