@substrat-run/contract-tests 0.13.0 → 0.16.0

package/dist/scope-host-suite.js

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { connectorCalls, connectorTestFetch, resetConnectorCalls } from './connector-fixture.js';
-import { connectionId, moduleManifest, orgId, platformActorId, principalId, scopeId, tenantId, } from '@substrat-run/contracts';
-import { ulid } from '@substrat-run/kernel';
+import { connectionId, moduleManifest, orgId, AUTO_ADMISSION_NOTE, platformActorId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, } from '@substrat-run/contracts';
+import { runPlatformSweep, ulid } from '@substrat-run/kernel';
 import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, testModManifest, victimModManifest, } from './modules.js';
 /**
  * The scope-host contract suite (design doc §11). Every adapter — pure SQLite,
@@ -285,6 +285,365 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const after = await host.executorDeadLetters(t1, s1);
             expect(after).toHaveLength(before.length);
         });
+        // -- scope data introspection: the §5.4 admin-query RPC --------------------
+        //
+        // A read-only window into a scope's OWN database (the console/dashboard Data
+        // view). The properties that matter: it sees the vertical's tables AND the
+        // spine (flagged apart), pages, refuses an unknown table, and fails closed on
+        // a mismatched (tenantId, scopeId) pair exactly as getScope does (K-3).
+        describe('scope data introspection (§5.4)', () => {
+            it('lists the scope tables, flagging the spine as system', async () => {
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/write-marker', { v: 'introspect-me' });
+                const tables = await host.admin.listScopeTables(staff, t1, s1);
+                const byName = new Map(tables.map((t) => [t.name, t]));
+                // The vertical's own table: present, not flagged system, with rows.
+                expect(byName.get('marker')?.system).toBe(false);
+                expect(byName.get('marker').rowCount).toBeGreaterThan(0);
+                // The spine: present and flagged system, so the UI can group it apart.
+                expect(byName.get('_substrat_outbox')?.system).toBe(true);
+            });
+            it('reads a bounded page of a table', async () => {
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/write-marker', { v: 'page-row' });
+                const page = await host.admin.readScopeTable(staff, t1, s1, { table: 'marker', limit: 50, offset: 0 });
+                expect(page.columns).toContain('v');
+                const vCol = page.columns.indexOf('v');
+                expect(page.rows.map((r) => r[vCol])).toContain('page-row');
+                expect(page.rowCount).toBeGreaterThanOrEqual(page.rows.length);
+            });
+            it('respects limit (paging)', async () => {
+                const page = await host.admin.readScopeTable(staff, t1, s1, { table: 'marker', limit: 1, offset: 0 });
+                expect(page.rows.length).toBeLessThanOrEqual(1);
+                expect(page.limit).toBe(1);
+            });
+            it('rejects an unknown table', async () => {
+                await expect(host.admin.readScopeTable(staff, t1, s1, { table: 'no_such_table', limit: 50, offset: 0 })).rejects.toThrow(/unknown table/);
+            });
+            it('fails closed on a mismatched (tenantId, scopeId) pair (K-3)', async () => {
+                await expect(host.admin.listScopeTables(staff, t2, s1)).rejects.toThrow();
+                await expect(host.admin.readScopeTable(staff, t2, s1, { table: 'marker', limit: 50, offset: 0 })).rejects.toThrow();
+            });
+        });
+        // -- the SQL console: queryScope (#219) -----------------------------------
+        //
+        // The table reads above are safe by construction; here user SQL DOES reach the
+        // scope's DB, so what the contract pins is the enforcement: any write shape is
+        // refused AND leaves no trace, results are row-capped, and the K-3 cross-check
+        // fails closed exactly as the table reads do.
+        describe('scope SQL console: queryScope (#219)', () => {
+            it('runs a read-only SELECT, joins included', async () => {
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/write-marker', { v: 'console-row' });
+                const result = await host.admin.queryScope(staff, t1, s1, {
+                    sql: `SELECT m.v, count(*) AS n FROM marker m WHERE m.v = 'console-row' GROUP BY m.v`,
+                });
+                expect(result.columns).toEqual(['v', 'n']);
+                expect(result.rows.length).toBe(1);
+                expect(result.rows[0][0]).toBe('console-row');
+                expect(result.truncated).toBe(false);
+            });
+            it('reads the spine (projections read it; only writes forge it)', async () => {
+                const result = await host.admin.queryScope(staff, t1, s1, {
+                    sql: 'SELECT type FROM _substrat_outbox ORDER BY id LIMIT 5',
+                });
+                expect(result.columns).toEqual(['type']);
+                expect(result.rows.length).toBeGreaterThan(0);
+            });
+            it("a ';' or a write verb inside a string literal does not trip the gate", async () => {
+                const result = await host.admin.queryScope(staff, t1, s1, {
+                    sql: `SELECT 'update t; drop table x' AS s -- comment with; semicolon`,
+                });
+                expect(result.rows[0][0]).toBe('update t; drop table x');
+            });
+            it('caps the result and reports truncation, never an error', async () => {
+                const result = await host.admin.queryScope(staff, t1, s1, {
+                    sql: `WITH RECURSIVE n(x) AS (SELECT 1 UNION ALL SELECT x + 1 FROM n WHERE x < 1000)
+                SELECT x FROM n`,
+                });
+                expect(result.rows.length).toBe(SCOPE_QUERY_ROW_MAX);
+                expect(result.truncated).toBe(true);
+            });
+            it('rejects every write shape — and the refusal leaves no trace', async () => {
+                const writes = [
+                    `INSERT INTO marker (v) VALUES ('forged')`,
+                    `UPDATE marker SET v = 'forged'`,
+                    `DELETE FROM marker`,
+                    `REPLACE INTO marker (v) VALUES ('forged')`,
+                    `DROP TABLE marker`,
+                    `CREATE TABLE forged (id TEXT)`,
+                    `PRAGMA journal_mode = OFF`,
+                    `SELECT 1; DELETE FROM marker`,
+                    // The first-keyword check alone would pass this one — SQLite allows a
+                    // write behind a CTE, which is exactly why write verbs are refused anywhere.
+                    `WITH x AS (SELECT v FROM marker) INSERT INTO marker (v) SELECT v FROM x`,
+                ];
+                for (const sql of writes) {
+                    // The message prefix is CONTRACT: the transport maps /read-only console/
+                    // to a 400, so both adapters must refuse with it (errors.ts).
+                    await expect(host.admin.queryScope(staff, t1, s1, { sql })).rejects.toThrow(/read-only console/);
+                }
+                // No write happened and nothing was forged: the marker rows are intact.
+                const after = await host.admin.queryScope(staff, t1, s1, {
+                    sql: `SELECT count(*) FROM marker WHERE v = 'forged'`,
+                });
+                expect(after.rows[0][0]).toBe(0);
+            });
+            it('fails closed on a mismatched (tenantId, scopeId) pair (K-3)', async () => {
+                await expect(host.admin.queryScope(staff, t2, s1, { sql: 'SELECT 1' })).rejects.toThrow();
+            });
+        });
+        // -- scope export (preview-and-snapshots.md §3) ---------------------------
+        //
+        // The privileged sibling of introspection: not a bounded page but the WHOLE
+        // scope — every table, its DDL, every row — the source a fork/pull reads. What
+        // matters: it is complete (the vertical's tables AND the spine), it is faithful
+        // (rows + schema, not blob-as-null), it drops only the un-recreatable sqlite_*
+        // internals, and it fails closed on a mismatched pair exactly as the reads do.
+        describe('scope export (§3)', () => {
+            it('dumps every table — the vertical\'s own AND the spine — with DDL and rows', async () => {
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/write-marker', { v: 'export-me' });
+                const dump = await host.admin.exportScope(staff, t1, s1);
+                expect(dump.tenantId).toBe(t1);
+                expect(dump.scopeId).toBe(s1);
+                expect(dump.capturedAt).toBeTruthy();
+                const byName = new Map(dump.tables.map((t) => [t.name, t]));
+                // The vertical's own table: dumped, with its CREATE statement and its rows.
+                const marker = byName.get('marker');
+                expect(marker).toBeDefined();
+                expect(marker.ddl.toLowerCase()).toContain('create table');
+                const vCol = marker.columns.indexOf('v');
+                expect(vCol).toBeGreaterThanOrEqual(0);
+                expect(marker.rows.map((r) => r[vCol])).toContain('export-me');
+                // The `_substrat_*` spine is INCLUDED — a fork must carry event/migration state.
+                expect(byName.has('_substrat_outbox')).toBe(true);
+                expect(byName.has('_substrat_migrations')).toBe(true);
+                // SQLite's own internals are NOT dumped (auto-managed, un-recreatable).
+                expect(dump.tables.some((t) => t.name.startsWith('sqlite_'))).toBe(false);
+            });
+            it('is complete — every introspected table (minus sqlite internals) is present', async () => {
+                const tables = await host.admin.listScopeTables(staff, t1, s1);
+                const dump = await host.admin.exportScope(staff, t1, s1);
+                const dumped = new Set(dump.tables.map((t) => t.name));
+                for (const t of tables) {
+                    if (t.name.startsWith('sqlite_'))
+                        continue;
+                    expect(dumped.has(t.name)).toBe(true);
+                }
+                // The vertical table's rows are dumped in full (count matches introspection).
+                const marker = dump.tables.find((t) => t.name === 'marker');
+                const introMarker = tables.find((t) => t.name === 'marker');
+                expect(marker.rows.length).toBe(introMarker.rowCount);
+            });
+            it('fails closed on a mismatched (tenantId, scopeId) pair (K-3)', async () => {
+                await expect(host.admin.exportScope(staff, t2, s1)).rejects.toThrow();
+            });
+        });
+        // -- scope import: the fork round-trip (preview-and-snapshots.md §3) -------
+        //
+        // The write side of exportScope. `importScope` provisions a NEW scope and loads
+        // a dump into it — a faithful, INDEPENDENT copy at the source's frontier. What
+        // matters: the copy has the source's tables + rows (fidelity), and the two do not
+        // share storage (a later write to one is invisible to the other).
+        describe('scope import — fork (§3)', () => {
+            it('round-trips: import a dump into a new scope, identical to the source', async () => {
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/write-marker', { v: 'fork-me' });
+                const dump = await host.admin.exportScope(staff, t1, s1);
+                const copy = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: copy, jurisdiction: 'eu', vertical: 'connector-vertical' }, dump);
+                // Same tables and row counts as the source (the spine came across too).
+                const src = (await host.admin.listScopeTables(staff, t1, s1))
+                    .map((t) => `${t.name}:${t.rowCount}`)
+                    .sort();
+                const dst = (await host.admin.listScopeTables(staff, t1, copy))
+                    .map((t) => `${t.name}:${t.rowCount}`)
+                    .sort();
+                expect(dst).toEqual(src);
+                // The vertical's data is present in the copy.
+                const page = await host.admin.readScopeTable(staff, t1, copy, {
+                    table: 'marker',
+                    limit: 200,
+                    offset: 0,
+                });
+                const vCol = page.columns.indexOf('v');
+                expect(page.rows.map((r) => r[vCol])).toContain('fork-me');
+            });
+            it('is an independent copy — a later write to the source does not reach it', async () => {
+                const dump = await host.admin.exportScope(staff, t1, s1);
+                const copy = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: copy, jurisdiction: 'eu', vertical: 'connector-vertical' }, dump);
+                const countMarker = async (sc) => (await host.admin.listScopeTables(staff, t1, sc)).find((t) => t.name === 'marker')
+                    ?.rowCount ?? 0;
+                const before = await countMarker(copy);
+                // Write to the SOURCE after the fork; the copy is frozen at capture time.
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/write-marker', { v: 'after-fork' });
+                expect(await countMarker(copy)).toBe(before);
+            });
+            it('records fork provenance (forked_from/at + kind) on the new scope', async () => {
+                const dump = await host.admin.exportScope(staff, t1, s1);
+                const copy = scopeId.parse(ulid());
+                await host.importScope(staff, {
+                    tenantId: t1,
+                    scopeId: copy,
+                    jurisdiction: 'eu',
+                    vertical: 'connector-vertical',
+                    kind: 'preview',
+                }, dump);
+                const rec = await host.admin.getScopeRecord(staff, t1, copy);
+                expect(rec?.kind).toBe('preview');
+                expect(rec?.forkedFrom).toBe(s1); // stamped from the dump's source scope
+                expect(rec?.forkedAt).toBe(dump.capturedAt);
+                // A normally-provisioned scope carries no provenance — the fields are what
+                // set a fork apart.
+                const src = await host.admin.getScopeRecord(staff, t1, s1);
+                expect(src?.forkedFrom).toBeNull();
+                expect(src?.forkedAt).toBeNull();
+            });
+        });
+        // -- snapshot & auto-snapshot on bind (preview-and-snapshots.md §3/§4) -----
+        //
+        // snapshotScope forks an `archive` copy at the source's frontier. bindScopeVersion,
+        // opted in, does it automatically before a MIGRATION-changing rebind — and only
+        // then: a code-only rebind (same migration digest) snapshots nothing, and opting
+        // out never snapshots.
+        describe('scope snapshot (§3/§4)', () => {
+            const countForks = async (of) => (await host.admin.listScopes(staff, { tenantId: t1 })).filter((sc) => sc.forkedFrom === of)
+                .length;
+            it('snapshotScope forks an archive copy at the source frontier', async () => {
+                const stub = await host.getScope(alice, t1, s1);
+                await stub.invoke('test/write-marker', { v: 'snap-me' });
+                const snapId = await host.snapshotScope(staff, t1, s1);
+                const rec = await host.admin.getScopeRecord(staff, t1, snapId);
+                expect(rec?.kind).toBe('archive');
+                expect(rec?.forkedFrom).toBe(s1);
+                const page = await host.admin.readScopeTable(staff, t1, snapId, {
+                    table: 'marker',
+                    limit: 200,
+                    offset: 0,
+                });
+                const vCol = page.columns.indexOf('v');
+                expect(page.rows.map((r) => r[vCol])).toContain('snap-me');
+            });
+            it('bindScopeVersion snapshots a migration-changing rebind, and only that', async () => {
+                // A fresh scope + a vertical with two admitted versions of differing migration
+                // digest, plus a third that is a code-only change (same migration digest).
+                const sb = scopeId.parse(ulid());
+                await host.provisionScope(staff, {
+                    tenantId: t1,
+                    scopeId: sb,
+                    jurisdiction: 'eu',
+                    vertical: 'snaptest',
+                });
+                await host.admin.activateScope(staff, t1, sb);
+                await host.admin.registerVertical(staff, {
+                    slug: 'snaptest',
+                    name: 'Snap Test',
+                    source: 'builtin',
+                });
+                const publish = async (version, mig) => {
+                    const id = ulid();
+                    await host.admin.publishVersion(staff, {
+                        id,
+                        verticalSlug: 'snaptest',
+                        version,
+                        manifestDigest: `man-${version}`,
+                        permissionDigest: 'p',
+                        migrationDigest: mig,
+                        deploymentRef: null,
+                    });
+                    await host.admin.admitVersion(staff, id);
+                    return id;
+                };
+                const vA = await publish('1.0.0', 'gA');
+                const vB = await publish('2.0.0', 'gB'); // migration change vs vA
+                const vBcode = await publish('2.0.1', 'gB'); // code-only vs vB
+                const before = await countForks(sb);
+                await host.admin.bindScopeVersion(staff, t1, sb, vA); // first bind — no prior version
+                await host.admin.bindScopeVersion(staff, t1, sb, vB, { snapshot: true }); // gA→gB — snapshot
+                expect(await countForks(sb)).toBe(before + 1);
+                // The snapshot is an archive bound to the OUTGOING version (vA) — the frontier
+                // it froze at.
+                const forks = (await host.admin.listScopes(staff, { tenantId: t1 })).filter((sc) => sc.forkedFrom === sb);
+                expect(forks.every((f) => f.kind === 'archive')).toBe(true);
+                expect(forks.some((f) => f.verticalVersionId === vA)).toBe(true);
+                // A code-only rebind (same migration digest), even opted in, snapshots nothing.
+                await host.admin.bindScopeVersion(staff, t1, sb, vBcode, { snapshot: true });
+                expect(await countForks(sb)).toBe(before + 1);
+                // Opting out never snapshots, even across a migration boundary.
+                await host.admin.bindScopeVersion(staff, t1, sb, vA); // gB→gA, no opts
+                expect(await countForks(sb)).toBe(before + 1);
+            });
+        });
+        // -- snapshot retention: deleteSnapshot + the GC sweep (§3/§9) -------------
+        //
+        // The one sanctioned hard delete, kept narrow: only a FORK may be reaped, and the
+        // sweep only reaps forks whose creator asked for an expiry. What matters: the
+        // delete removes record + hostnames + storage; a primary scope is refused; the
+        // sweep takes exactly the expired and leaves the unexpired and the pinned.
+        describe('snapshot retention (§3/§9)', () => {
+            it('deleteSnapshot removes the fork — record, hostnames, and reachability', async () => {
+                const snapId = await host.snapshotScope(staff, t1, s1);
+                await host.admin.bindHostname(staff, {
+                    hostname: `snap-${snapId.toLowerCase()}.test.example`,
+                    tenantId: t1,
+                    scopeId: snapId,
+                    surface: 'app',
+                    region: null,
+                    canonical: true,
+                });
+                expect(await host.admin.listHostnames(staff, { scopeId: snapId })).toHaveLength(1);
+                await host.deleteSnapshot(staff, t1, snapId);
+                expect(await host.admin.getScopeRecord(staff, t1, snapId)).toBeUndefined();
+                expect(await host.admin.listHostnames(staff, { scopeId: snapId })).toHaveLength(0);
+                // The storage is unreachable through every read: the directory row is gone,
+                // so the K-3 cross-check fails closed.
+                await expect(host.admin.exportScope(staff, t1, snapId)).rejects.toThrow();
+            });
+            it('refuses to delete a primary scope (forkedFrom is null)', async () => {
+                await expect(host.deleteSnapshot(staff, t1, s1)).rejects.toThrow(/not a fork/);
+                // Still there, still readable.
+                expect((await host.admin.getScopeRecord(staff, t1, s1))?.id).toBe(s1);
+            });
+            it('the GC sweep reaps exactly the expired forks', async () => {
+                const past = new Date(Date.now() - 60_000).toISOString();
+                const future = new Date(Date.now() + 3_600_000).toISOString();
+                const expired = await host.snapshotScope(staff, t1, s1, { expiresAt: past });
+                const unexpired = await host.snapshotScope(staff, t1, s1, { expiresAt: future });
+                const pinned = await host.snapshotScope(staff, t1, s1); // no expiry — retained
+                const report = await runPlatformSweep(host, {
+                    actor: staff,
+                    fetch: connectorTestFetch,
+                    sweepers: {},
+                    drainRetries: false,
+                });
+                expect(report.snapshotsReaped).toBeGreaterThanOrEqual(1);
+                expect(await host.admin.getScopeRecord(staff, t1, expired)).toBeUndefined();
+                expect((await host.admin.getScopeRecord(staff, t1, unexpired))?.id).toBe(unexpired);
+                expect((await host.admin.getScopeRecord(staff, t1, pinned))?.id).toBe(pinned);
+                // The primary scope was never in danger.
+                expect((await host.admin.getScopeRecord(staff, t1, s1))?.id).toBe(s1);
+                // Clean up the survivors so later suite state stays predictable.
+                await host.deleteSnapshot(staff, t1, unexpired);
+                await host.deleteSnapshot(staff, t1, pinned);
+            });
+            it('gcSnapshots: false skips the phase', async () => {
+                const past = new Date(Date.now() - 60_000).toISOString();
+                const snapId = await host.snapshotScope(staff, t1, s1, { expiresAt: past });
+                const report = await runPlatformSweep(host, {
+                    actor: staff,
+                    fetch: connectorTestFetch,
+                    sweepers: {},
+                    drainRetries: false,
+                    gcSnapshots: false,
+                });
+                expect(report.snapshotsReaped).toBe(0);
+                expect((await host.admin.getScopeRecord(staff, t1, snapId))?.id).toBe(snapId);
+                await host.deleteSnapshot(staff, t1, snapId);
+            });
+        });
         // -- the integrations hub: connections (#101) -----------------------------
         //
         // The store exists so a vertical's connector can reach a tenant's provider
@@ -611,6 +970,115 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 ownerTenant: t2,
             })).rejects.toThrow(/owned by the platform/);
         });
+        it('carries registry-driven install metadata (marketplace-publish.md §3) and refreshes it', async () => {
+            // ownerGrants/entitlements/provides/requires ride the registry (one install_spec JSON
+            // column) so the dashboard installs a vertical without a hardcoded catalog entry.
+            await host.admin.registerVertical(staff, {
+                slug: 'authy',
+                name: 'Authy',
+                source: 'cli',
+                ownerTenant: t2,
+                entitlements: ['authy'],
+                ownerGrants: ['content:admin'],
+                provides: ['oidc-issuer'],
+            });
+            const first = (await host.admin.listVerticals(staff)).find((v) => v.slug === 'authy');
+            expect(first?.entitlements).toEqual(['authy']);
+            expect(first?.ownerGrants).toEqual(['content:admin']);
+            expect(first?.provides).toEqual(['oidc-issuer']);
+            expect(first?.requires).toBeUndefined();
+            // Like envSpec, install metadata evolves with the manifest: an otherwise-identical
+            // re-registration refreshes it rather than conflicting.
+            await host.admin.registerVertical(staff, {
+                slug: 'authy',
+                name: 'Authy',
+                source: 'cli',
+                ownerTenant: t2,
+                entitlements: ['authy'],
+                ownerGrants: ['content:admin', 'content:publish'],
+                requires: ['oidc-issuer'],
+            });
+            const second = (await host.admin.listVerticals(staff)).find((v) => v.slug === 'authy');
+            expect(second?.ownerGrants).toEqual(['content:admin', 'content:publish']);
+            expect(second?.requires).toEqual(['oidc-issuer']);
+            expect(second?.provides).toBeUndefined(); // dropped on refresh — the blob is replaced whole
+        });
+        it('publishes/unpublishes a vertical to the marketplace (setVerticalListed), preserved across re-push', async () => {
+            const at = (slug) => host.admin.listVerticals(staff).then((vs) => vs.find((v) => v.slug === slug));
+            await host.admin.registerVertical(staff, { slug: 'listtest', name: 'ListTest', source: 'cli', ownerTenant: t2 });
+            expect((await at('listtest'))?.listed).toBe(false); // private on push
+            await host.admin.setVerticalListed(staff, 'listtest', true);
+            expect((await at('listtest'))?.listed).toBe(true); // published
+            // The invariant: a re-push does NOT unpublish it — `listed` is its own column, untouched
+            // by the register refresh (publish is a distinct action from push).
+            await host.admin.registerVertical(staff, { slug: 'listtest', name: 'ListTest', source: 'cli', ownerTenant: t2 });
+            expect((await at('listtest'))?.listed).toBe(true);
+            await host.admin.setVerticalListed(staff, 'listtest', true); // idempotent
+            await host.admin.setVerticalListed(staff, 'listtest', false);
+            expect((await at('listtest'))?.listed).toBe(false); // unpublished
+            // A builder's publish REQUEST is recorded, and RESOLVED (cleared) by the staff listing.
+            await host.admin.requestPublish(staff, 'listtest');
+            expect((await at('listtest'))?.publishRequestedAt).toBeTruthy();
+            await host.admin.setVerticalListed(staff, 'listtest', true);
+            expect((await at('listtest'))?.publishRequestedAt).toBeUndefined(); // cleared on review
+            await expect(host.admin.setVerticalListed(staff, 'no-such-vertical', true)).rejects.toThrow(/unknown vertical/);
+            await expect(host.admin.requestPublish(staff, 'no-such-vertical')).rejects.toThrow(/unknown vertical/);
+        });
+        it('blocks new installs (setVerticalInstallsBlocked) — a provisioning gate, not a delete', async () => {
+            const at = (slug) => host.admin.listVerticals(staff).then((vs) => vs.find((v) => v.slug === slug));
+            await host.admin.registerVertical(staff, { slug: 'blocktest', name: 'BlockTest', source: 'cli', ownerTenant: t2 });
+            expect((await at('blocktest'))?.installsBlocked).toBe(false); // installable on push
+            await host.admin.setVerticalInstallsBlocked(staff, 'blocktest', true);
+            expect((await at('blocktest'))?.installsBlocked).toBe(true);
+            await host.admin.setVerticalInstallsBlocked(staff, 'blocktest', true); // idempotent
+            // Orthogonal to `listed` — blocking is not unpublishing.
+            expect((await at('blocktest'))?.listed).toBe(false);
+            await host.admin.setVerticalInstallsBlocked(staff, 'blocktest', false);
+            expect((await at('blocktest'))?.installsBlocked).toBe(false);
+            await expect(host.admin.setVerticalInstallsBlocked(staff, 'no-such-vertical', true)).rejects.toThrow(/unknown vertical/);
+        });
+        it('deletes a vertical — refused while a scope is bound, total once nothing is', async () => {
+            // 'callout' still backs s1 (bound above): the refusal that stops a delete from
+            // stranding a live scope's version pin and routing.
+            await expect(host.admin.deleteVertical(staff, 'callout')).rejects.toThrow(/still backs/);
+            expect((await host.admin.listVerticals(staff)).some((v) => v.slug === 'callout')).toBe(true);
+            // A vertical nothing is bound to deletes totally: row, versions, channels.
+            const versionId = ulid();
+            await host.admin.registerVertical(staff, { slug: 'deletable', name: 'Deletable', source: 'cli', ownerTenant: t2 });
+            await host.admin.publishVersion(staff, {
+                id: versionId,
+                verticalSlug: 'deletable',
+                version: '0.0.1',
+                manifestDigest: 'm',
+                permissionDigest: 'p',
+                migrationDigest: 'g',
+                deploymentRef: null,
+            });
+            await host.admin.admitVersion(staff, versionId);
+            await host.admin.promoteVersion(staff, 'deletable', 'dev', versionId);
+            await host.admin.deleteVertical(staff, 'deletable');
+            expect((await host.admin.listVerticals(staff)).some((v) => v.slug === 'deletable')).toBe(false);
+            expect(await host.admin.listVersions(staff, 'deletable')).toEqual([]);
+            expect(await host.admin.listChannels(staff, 'deletable')).toEqual([]);
+            // The slug is claimable again — a delete is a real removal, not a tombstone.
+            await host.admin.registerVertical(staff, { slug: 'deletable', name: 'Deletable', source: 'cli', ownerTenant: t2 });
+            expect(await host.admin.listVersions(staff, 'deletable')).toEqual([]); // no resurrected versions
+            await host.admin.deleteVertical(staff, 'deletable');
+            await expect(host.admin.deleteVertical(staff, 'no-such-vertical')).rejects.toThrow(/unknown vertical/);
+        });
+        it('refreshes `listed` on builtin re-registration (the catalog re-seed can list a row)', async () => {
+            const at = (slug) => host.admin.listVerticals(staff).then((vs) => vs.find((v) => v.slug === slug));
+            // A builtin first registered UNLISTED (bundled but not yet deployable, or a row
+            // predating the `listed` column) must become listed when the seed says so —
+            // `ensureCatalog` re-registers each boot, and for builtins `listed` is seed metadata.
+            await host.admin.registerVertical(staff, { slug: 'seeded', name: 'Seeded', source: 'builtin' });
+            expect((await at('seeded'))?.listed).toBe(false);
+            await host.admin.registerVertical(staff, { slug: 'seeded', name: 'Seeded', source: 'builtin', listed: true });
+            expect((await at('seeded'))?.listed).toBe(true);
+            // And back: flipping the seed to `connected: false` delists on the next re-seed.
+            await host.admin.registerVertical(staff, { slug: 'seeded', name: 'Seeded', source: 'builtin' });
+            expect((await at('seeded'))?.listed).toBe(false);
+        });
         it('refuses to bind a rejected version, and rejection is terminal', async () => {
             const versionId = ulid();
             await host.admin.publishVersion(staff, {
@@ -727,6 +1195,102 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             });
             await expect(host.admin.promoteVersion(staff, 'callout', 'dev', pending)).rejects.toThrow(/pending, not admitted/);
         });
+        // -- private verticals: self-serve prod (builder-plane.md §4-revised) ----
+        // A private vertical's blast radius is its own tenant — dev/staging already
+        // run the same bundle in the same sandbox — so its versions self-admit on
+        // push and prod is the owner's to move. The staff seam moves to publish,
+        // where the audience actually widens.
+        const publishPrivate = async (slug, version, digests) => {
+            const id = ulid();
+            await host.admin.publishVersion(staff, {
+                id,
+                verticalSlug: slug,
+                version,
+                manifestDigest: `man-${version}`,
+                permissionDigest: digests?.perm ?? 'pp',
+                migrationDigest: digests?.mig ?? 'gg',
+                deploymentRef: null,
+            });
+            return id;
+        };
+        it('a private vertical version lands ADMITTED on push, noted as auto-admission', async () => {
+            await host.admin.registerVertical(staff, {
+                slug: 'egeryds/crm',
+                name: 'Egeryds CRM',
+                source: 'cli',
+                ownerTenant: t2,
+            });
+            const vid = await publishPrivate('egeryds/crm', '0.1.0');
+            const [v] = await host.admin.listVersions(staff, 'egeryds/crm');
+            expect(v?.admission).toBe('admitted');
+            expect(v?.admissionNote).toBe(AUTO_ADMISSION_NOTE);
+            // Promotable immediately — for a private vertical, push + promote IS the deploy.
+            await host.admin.promoteVersion(staff, 'egeryds/crm', 'prod', vid);
+            expect((await host.admin.listChannels(staff, 'egeryds/crm')).find((c) => c.channel === 'prod')?.versionId).toBe(vid);
+        });
+        it('a platform vertical still lands pending — auto-admission is scoped to private ownership', async () => {
+            // 'callout' is platform-owned (ownerTenant null): the 9.9.9 push in the test
+            // above landed pending. The distinction is the whole design: self-admission
+            // exists only where the author and the audience are the same tenant.
+            const versions = await host.admin.listVersions(staff, 'callout');
+            expect(versions.find((v) => v.version === '9.9.9')?.admission).toBe('pending');
+        });
+        it('promotion appends to the channel history — the go-live timeline rollback picks from', async () => {
+            const first = (await host.admin.listChannelHistory(staff, 'egeryds/crm', 'prod'));
+            expect(first).toHaveLength(1);
+            expect(first[0].fromVersionId).toBeNull(); // nothing before the first go-live
+            const v2 = await publishPrivate('egeryds/crm', '0.2.0');
+            await host.admin.promoteVersion(staff, 'egeryds/crm', 'prod', v2);
+            // Rollback is a NEW promotion of the older version — the timeline only grows.
+            const v1 = first[0].versionId;
+            await host.admin.promoteVersion(staff, 'egeryds/crm', 'prod', v1);
+            const timeline = await host.admin.listChannelHistory(staff, 'egeryds/crm', 'prod');
+            expect(timeline.map((h) => h.versionId)).toEqual([v1, v2, v1]); // newest first
+            expect(timeline[0].fromVersionId).toBe(v2);
+            expect(timeline[1].fromVersionId).toBe(v1);
+            // Each entry records who and exactly when — `at` is the PITR anchor a data
+            // rollback would rewind to (preview-and-snapshots.md §7).
+            expect(timeline[0].actor).toBe(staff);
+            expect(new Date(timeline[0].at).getTime()).toBeGreaterThan(0);
+            // Narrowing by channel works: dev never moved, so its timeline is empty.
+            expect(await host.admin.listChannelHistory(staff, 'egeryds/crm', 'dev')).toHaveLength(0);
+        });
+        it("prod promote of a private vertical re-points the owner's live scopes (merge IS the deploy)", async () => {
+            // A fresh app scope in the owning tenant, bound to the current prod version.
+            // Promoting a new one re-points it without a separate update step — that is
+            // what makes merge-to-main a complete deploy, and a rollback promote reach
+            // the running app.
+            const appScope = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t2, scopeId: appScope });
+            await host.admin.activateScope(staff, t2, appScope);
+            const prodNow = (await host.admin.listChannels(staff, 'egeryds/crm')).find((c) => c.channel === 'prod')
+                .versionId;
+            await host.admin.bindScopeVersion(staff, t2, appScope, prodNow);
+            const v3 = await publishPrivate('egeryds/crm', '0.3.0');
+            await host.admin.promoteVersion(staff, 'egeryds/crm', 'prod', v3);
+            expect((await host.admin.getScopeRecord(staff, t2, appScope))?.verticalVersionId).toBe(v3);
+        });
+        it('publish refuses an auto-admitted prod version until a staff admit vouches for it', async () => {
+            // Listing is the moment OTHER tenants start trusting this code, so the version
+            // they would install needs a recorded human decision — the auto-admission note
+            // is exactly what marks its absence.
+            await expect(host.admin.setVerticalListed(staff, 'egeryds/crm', true)).rejects.toThrow(/auto-admitted.*staff admit/);
+            // A staff admit of the already-admitted version upgrades it to a manual vouch
+            // (clears the note, audited) — then listing passes.
+            const prodNow = (await host.admin.listChannels(staff, 'egeryds/crm')).find((c) => c.channel === 'prod')
+                .versionId;
+            await host.admin.admitVersion(staff, prodNow);
+            const upgraded = (await host.admin.listVersions(staff, 'egeryds/crm')).find((v) => v.id === prodNow);
+            expect(upgraded?.admission).toBe('admitted');
+            expect(upgraded?.admissionNote).toBeNull();
+            await host.admin.setVerticalListed(staff, 'egeryds/crm', true);
+            // Listed now: the next push lands PENDING — staff admission is back in the
+            // path exactly when the audience widened.
+            const v4 = await publishPrivate('egeryds/crm', '0.4.0');
+            expect((await host.admin.listVersions(staff, 'egeryds/crm')).find((v) => v.id === v4)?.admission).toBe('pending');
+            // Unlist again so later suites see the vertical private (and pushes self-admit).
+            await host.admin.setVerticalListed(staff, 'egeryds/crm', false);
+        });
         // -- the provisioning state (K-31) ---------------------------------------
         it('provisions a scope as `provisioning`, not `active`', async () => {
             // The directory row exists before the vertical has created the scope DO. Born
@@ -883,6 +1447,30 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // but neither of them routes traffic.
             expect(await host.admin.resolveHostname('eu.example.com')).toBeUndefined();
         });
+        it('unbinds a hostname: the row is gone, it stops resolving, and the unbind is audited', async () => {
+            // The inverse of bindHostname — what a cleanup pass uses on orphaned rows.
+            // A hard delete, not a tombstone: the row is routing config, and its history
+            // lives in the admin log.
+            await host.admin.unbindHostname(staff, 'EU.example.com'); // case-insensitive, like DNS
+            expect((await host.admin.listHostnames(staff, { scopeId: s1 })).map((h) => h.hostname)).not.toContain('eu.example.com');
+            expect(await host.admin.resolveHostname('eu.example.com')).toBeUndefined();
+            const entries = await host.admin.auditLog(staff, { scopeId: s1 });
+            expect(entries.map((e) => e.action)).toContain('unbindHostname');
+            // Idempotent: unbinding an unknown hostname is a no-op, not an error — a
+            // cleanup pass can re-run over a partial failure.
+            await expect(host.admin.unbindHostname(staff, 'eu.example.com')).resolves.toBeUndefined();
+            // The released name is immediately reclaimable by another scope.
+            await host.admin.bindHostname(staff, {
+                hostname: 'eu.example.com',
+                tenantId: t2,
+                scopeId: s2,
+                surface: 'app',
+                region: null,
+                canonical: false,
+            });
+            const reclaimed = (await host.admin.listHostnames(staff, { scopeId: s2 })).find((h) => h.hostname === 'eu.example.com');
+            expect(reclaimed?.scopeId).toBe(s2);
+        });
         it('rejects duplicate module registration', () => {
             expect(() => host.registerModule({ manifest: testModManifest })).toThrow(/already registered/);
         });