@substrat-run/control-plane-api 0.14.0 → 0.17.0

package/README.md

@@ -0,0 +1,58 @@
+# @substrat-run/control-plane-api
+
+The HTTP surface over `HostAdmin` for [Substrat](https://github.com/substrat-run/substrat) —
+the **audited control-plane transport**. It is the seam between the platform's admin
+operations (provision a scope, bind a hostname, grant a role, deploy a vertical) and
+whatever runs them: the console, the CLI, or another service.
+
+It is a transport, not a source of truth. Every call lands on `HostAdmin`, every mutation
+is audited, and the same contract runs over any scope host (the pure-SQLite adapter in
+CI, Durable Objects in production).
+
+## What's in the box
+
+- **`createControlPlaneApi`** — a [Hono](https://hono.dev) app exposing `HostAdmin` over
+  HTTP, with authentication and the audit log wired in.
+- **`ControlPlaneClient`** — the typed client for that surface (what the console and CLI
+  call), plus `ControlPlaneError` for structured failures.
+- **`VerticalClient`** — the narrowed, tenant-scoped seam an app uses to provision itself.
+- **`deployManifest` / `createWfpUploader`** — the deploy path: validate a vertical
+  bundle against the sandbox contract and upload it to Workers-for-Platforms.
+
+## Install
+
+```sh
+pnpm add @substrat-run/control-plane-api
+```
+
+```ts
+import { createControlPlaneApi } from '@substrat-run/control-plane-api';
+
+const app = createControlPlaneApi({ admin /* HostAdmin */, /* auth, audit, … */ });
+export default app; // a Hono app — serve it on Node, Workers, or in tests
+```
+
+```ts
+import { ControlPlaneClient } from '@substrat-run/control-plane-api';
+
+const cp = new ControlPlaneClient({ baseUrl, token });
+await cp.provisionScope({ tenant, slug });
+```
+
+## Documentation
+
+**https://substrat.net/platform/control-plane** — the admin surface, the audit model,
+authentication, and how the console/CLI/router sit on top of it.
+
+## Related packages
+
+- [`@substrat-run/kernel`](https://npmjs.com/package/@substrat-run/kernel) — the
+  scope-host + `HostAdmin` contract this exposes
+- [`@substrat-run/adapter-sqlite`](https://npmjs.com/package/@substrat-run/adapter-sqlite) —
+  the pure-SQLite host it runs against in CI and self-host
+- [`@substrat-run/cli`](https://npmjs.com/package/@substrat-run/cli) — the deploy tooling
+  that drives this surface
+
+## Status
+
+Pre-release (0.x): the surface changes without notice until the platform GAs.

package/dist/api.d.ts

@@ -4,6 +4,7 @@ import type { ScopeHost } from '@substrat-run/kernel';
 import type { PlatformActorAuth, BuilderAuth, Principal } from './auth.js';
 import type { VerticalClient } from './vertical-client.js';
 import type { DeployVerticalFn } from './deploy.js';
+import type { ObservabilityReader } from './observability.js';
 export interface ControlPlaneApiOptions {
     host: ScopeHost;
     /**
@@ -55,6 +56,23 @@ export interface ControlPlaneApiOptions {
      * the vertical-management routes and to the verticals their tenant owns.
      */
     authenticateBuilder?: BuilderAuth;
+    /**
+     * Signs tenant-scoped push tokens (push-token.ts) — the CI credential the dashboard
+     * mints into a customer repo. Absent ⇒ the mint route 501s. A dedicated secret,
+     * never PLATFORM_SECRET (injected into pushed verticals) and never the service
+     * token; set once, out of routine rotation (rotating it revokes every issued token).
+     */
+    pushTokenSecret?: string;
+    /**
+     * Cloudflare-native observability reads (design/observability.md §4.1) —
+     * host-injected like `deployVertical`, so this package holds no credential and the
+     * Cloudflare token never leaves the platform (D-34). Absent ⇒ the observability
+     * routes 501. Staff-only for now: the routes are deliberately NOT in
+     * `BUILDER_ROUTES` — the builder view needs owner-narrowing (only scripts whose
+     * registry `ownerTenant` is the caller's) before it can be opened, and default-deny
+     * means forgetting that costs a feature, never a leak.
+     */
+    observability?: ObservabilityReader;
 }
 type Vars = {
     actor: PlatformActorId;
@@ -78,9 +96,13 @@ type Vars = {
  *    retrofitted (K-20). Note there is no route here that accepts an `actor`
  *    field at all — it is unrepresentable, not merely ignored.
  * 2. **Reads are exposed; enforcement writes are not.** defineRole / assignRole /
- *    grant / grantToOrg / addMember / linkIdentity are on `HostAdmin` but get no
- *    route: the console's v1 job is the tenant registry, lifecycle, entitlements
- *    and history. `resolveIdentity` especially stays off — it is the auth
+ *    grant / grantToOrg / addMember are on `HostAdmin` but get no route: the
+ *    console's v1 job is the tenant registry, lifecycle, entitlements and
+ *    history. The ONE exception is the identity-mirror pair under
+ *    `/tenants/:tenantId/identities` (service/staff only): builder auth resolves
+ *    a CLI session against THIS deployment's directory, but identity links are
+ *    born in the Dashboard's own deployment — a different DO — so the dashboard
+ *    mirrors them here. `resolveIdentity` especially stays off — it is the auth
  *    adapter's read path, not an admin surface.
  */
 export declare function createControlPlaneApi(options: ControlPlaneApiOptions): Hono<{

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;AAqB5B,OAAO,KAAK,EAAE,eAAe,EAAqB,MAAM,yBAAyB,CAAC;AAClF,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;AAK3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,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;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC;CACnC;AAKD,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AAkG7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAglBhG"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAwB5B,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;AAM3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,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;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;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;AAoH7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CA87BhG"}

package/dist/api.js

@@ -1,9 +1,11 @@
 import { Hono } from 'hono';
-import { adminAction, channelName, createTenantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, readScopeTableInput, 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, identityLink, principalId as principalIdSchema, 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
@@ -104,9 +122,13 @@ const auditLogQuery = z.object({
  *    retrofitted (K-20). Note there is no route here that accepts an `actor`
  *    field at all — it is unrepresentable, not merely ignored.
  * 2. **Reads are exposed; enforcement writes are not.** defineRole / assignRole /
- *    grant / grantToOrg / addMember / linkIdentity are on `HostAdmin` but get no
- *    route: the console's v1 job is the tenant registry, lifecycle, entitlements
- *    and history. `resolveIdentity` especially stays off — it is the auth
+ *    grant / grantToOrg / addMember are on `HostAdmin` but get no route: the
+ *    console's v1 job is the tenant registry, lifecycle, entitlements and
+ *    history. The ONE exception is the identity-mirror pair under
+ *    `/tenants/:tenantId/identities` (service/staff only): builder auth resolves
+ *    a CLI session against THIS deployment's directory, but identity links are
+ *    born in the Dashboard's own deployment — a different DO — so the dashboard
+ *    mirrors them here. `resolveIdentity` especially stays off — it is the auth
  *    adapter's read path, not an admin surface.
  */
 export function createControlPlaneApi(options) {
@@ -155,6 +177,7 @@ 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
@@ -216,6 +239,28 @@ export function createControlPlaneApi(options) {
         await admin.revokeEntitlement(c.get('actor'), tenantId, c.req.param('key'));
         return c.json(await admin.listEntitlements(c.get('actor'), tenantId));
     });
+    // -- identity mirror (builder-plane.md §4) ---------------------------------
+    // Builder auth (`whoami`, the CLI session reader) resolves `userId → tenants`
+    // against THIS deployment's identity directory, but the links are created at
+    // dashboard sign-up in the Dashboard's OWN deployment — a different DO. This
+    // pair is the mirror seam the dashboard writes through (idempotent, keyed the
+    // same as its local links). Not in BUILDER_ROUTES: a builder cannot write the
+    // directory that authenticates builders — service/staff only, fail-closed.
+    const mirrorIdentityBody = identityLink.omit({ tenantId: true });
+    app.put('/tenants/:tenantId/identities', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const link = mirrorIdentityBody.parse(await c.req.json());
+        // The pool must exist before a link can land in it (central topology, K-23);
+        // registering an existing pool is a no-op.
+        await admin.registerIdentityPool(c.get('actor'), { provider: link.provider, topology: 'central', tenantId: null });
+        await admin.linkIdentity(c.get('actor'), { ...link, tenantId });
+        return c.body(null, 204);
+    });
+    app.delete('/tenants/:tenantId/identities/:principal', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        await admin.unlinkIdentity(c.get('actor'), tenantId, principalIdSchema.parse(c.req.param('principal')));
+        return c.body(null, 204);
+    });
     // -- the scope directory (§3.2/§4.2) ---------------------------------------
     app.get('/scopes', async (c) => {
         const filter = listScopesQuery.parse({
@@ -293,6 +338,53 @@ export function createControlPlaneApi(options) {
             ? 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;
@@ -312,15 +404,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
@@ -334,6 +589,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')));
@@ -370,6 +632,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
@@ -465,6 +731,23 @@ export function createControlPlaneApi(options) {
         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'));
@@ -473,18 +756,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,
@@ -496,8 +796,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);
@@ -588,6 +889,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
@@ -616,6 +972,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