@substrat-run/control-plane-api 0.164.0 → 0.166.0

package/dist/api.js

@@ -1,21 +1,22 @@
+import { sourceBuildRequest } from '@substrat-run/contracts';
 import { PREVIEW_CONNECTIONS_REFUSAL } from './connection-relay.js';
 import { connectionBindingOptions } from './connection-binding-options.js';
 import { resolveObservabilityWindow } from './observability-window.js';
 import { Hono } from 'hono';
-import { permissionKey, parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, lakeEventsInput, ownerTransferInput, memberInviteInput, memberRoleInput, ASSET_PART_PREFIX, assetHash, STORE_DRIVERS, STORE_RELEASE_MAX_BYTES, channelName, connectLinkId, connectionActivity, connectionActivitySource, connectionCredential, connectionCertificate, connectionFilter, connectionHealthState, connectionProvider, connectorDispatchKind, PROVISION_SIBLING_KIND, ARCHIVE_SCOPE_KIND, PROVISION_TENANT_KIND, SET_ENTITLEMENTS_KIND, MODEL_USAGE_KIND, SWEEP_RUNS_KIND, toConnectionHealthEntry, CONNECTION_EXPIRY_WARNING_DAYS, CONNECTION_STALE_DAYS, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, FINDINGS_LIMIT_DEFAULT, FINDINGS_LIMIT_MAX, findingCursorOf, findingKind, findingRuleInput, findingStatus, findingStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, impersonationStamp, promotionAcknowledgement, bindAcknowledgement, rebindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, operationSeriesCount, operationSeriesInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, verticalSlug, scopeText, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, platformScriptCollision, platformScriptRefusal, PLATFORM_SCRIPT_NAMES, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, requestRollupReading, meterDaysReading, verticalOwnersReading, utcDay, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, validationIssuesFrom, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, substratError, errorCodeOf, capabilityFilterQuery, capabilityId as capabilityIdSchema, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, SOCIAL_RELAY_VERTICALS, isVerticalConnectorProvider, } from '@substrat-run/contracts';
+import { permissionKey, parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, lakeEventsInput, ownerTransferInput, memberInviteInput, memberRoleInput, ASSET_PART_PREFIX, assetHash, STORE_DRIVERS, storeCatalogOperation, channelName, connectLinkId, connectionActivity, connectionActivitySource, connectionCredential, connectionCertificate, connectionFilter, connectionHealthState, connectionProvider, connectorDispatchKind, PROVISION_SIBLING_KIND, ARCHIVE_SCOPE_KIND, PROVISION_TENANT_KIND, SET_ENTITLEMENTS_KIND, MODEL_USAGE_KIND, SWEEP_RUNS_KIND, toConnectionHealthEntry, CONNECTION_EXPIRY_WARNING_DAYS, CONNECTION_STALE_DAYS, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, FINDINGS_LIMIT_DEFAULT, FINDINGS_LIMIT_MAX, findingCursorOf, findingKind, findingRuleInput, findingStatus, findingStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, impersonationStamp, promotionAcknowledgement, bindAcknowledgement, rebindAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, entityHistoryInput, eventFacetInput, eventCauseInput, eventEffectsInput, invocationEventsInput, deadLettersInput, lifecycleFlowInput, operationSeriesCount, operationSeriesInput, delegatedReadParams, createOrgInput, roleKey as roleKeySchema, peerSwitch, verticalSlug, scopeText, systemSwitch, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, denialGroupBy, registerVerticalInput, platformScriptCollision, platformScriptRefusal, PLATFORM_SCRIPT_NAMES, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, requestRollupReading, meterDaysReading, verticalOwnersReading, utcDay, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, validationIssuesFrom, redrainEventsInput, importCursorMove, importCursorAcknowledgementMissing, REDRAIN_BATCH, migrationsOnTop, substratError, errorCodeOf, envVarSpec, capabilityFilterQuery, capabilityId as capabilityIdSchema, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, PLATFORM_FEATURE_SOURCE_BUILDS, SOCIAL_RELAY_VERTICALS, isVerticalConnectorProvider, } from '@substrat-run/contracts';
 import { upstreamHandleIn, upstreamReferenceOf, withUpstreamReference } from '@substrat-run/contracts';
 import { ENGINE_ENTITLEMENT_KEYS, bareSlug, declarableEntitlementKey, entitlementNamespaceRefusal, grantableEntitlements } from '@substrat-run/contracts';
 import { SCOPE_COPY_LEASE_MS, copyRestoreFence, publishedMigrationDigest, replayStoreErasures } from '@substrat-run/kernel';
 import { attributeFailure } from './failure-attribution.js';
 import { auditedChange, withAuditedOutcomes } from './audited-change.js';
-import { BIND_EXPORT_BREAK_REFUSAL, CARRIED_AWAY_KEY, bindExportBreakRefusal, carriedAwayDump, dumpMetaValue, metaValueIn, crossVerticalHealth, exportBreakRefusal, isBindExportBreakRefusal, isExportBreakRefusal, listedPromoteRefusal, isExportBreakUnjudged, isPrimaryScope, promoteReviewDigest, rebindReviewDigest, assertRebindReviewCurrent, migrationProgress, ulid, auditWarningOf, REQUEST_ROLLUP_LIMIT_DEFAULT, REQUEST_ROLLUP_LIMIT_MAX, METER_DAYS_LIMIT_DEFAULT, METER_DAYS_LIMIT_MAX, releaseRolesAskScopes, releaseRoleSetRefusal, withheldOpsFailure, } from '@substrat-run/kernel';
+import { BIND_EXPORT_BREAK_REFUSAL, CARRIED_AWAY_KEY, bindExportBreakRefusal, carriedAwayDump, dumpMetaValue, metaValueIn, crossVerticalHealth, exportBreakRefusal, isBindExportBreakRefusal, isExportBreakRefusal, listedPromoteRefusal, isExportBreakUnjudged, isPrimaryScope, promoteReviewDigest, rebindReviewDigest, assertRebindReviewCurrent, migrationProgress, ulid, auditWarningOf, REQUEST_ROLLUP_LIMIT_DEFAULT, REQUEST_ROLLUP_LIMIT_MAX, STORAGE_GAUGE_RETENTION_MONTHS, MODEL_USAGE_RETENTION_DAYS, BILLING_ROLLUP_RETENTION_MONTHS, METER_DAYS_LIMIT_DEFAULT, METER_DAYS_LIMIT_MAX, releaseRolesAskScopes, releaseRoleSetRefusal, withheldOpsFailure, } from '@substrat-run/kernel';
 import { TENANT_HEADER, confinedTenant } from './auth.js';
 import { mintTenantToken } from './tenant-token.js';
 import { beginTransfer, connectionGrantsForScope, transferScope, isScopeNotHeld, notHeldIsBenign } from './vertical-client.js';
 import { COPY_JOB_MAX_MS, copyJobAt, copyJobHeld, copyJobId, copyJobLive, copyTagId, versionIdOfOrder, versionOrderOf, } from './copy-job.js';
 import { runningVersionOf, runningVersionStoresOf, scopeStoreReachOf, scopeStoresOf, unrouteScope } from './platform-scope-stores.js';
 import { STORE_REBUILD_REQUEST_SUBREQUESTS, runStoreFleetRebuild, storeRebuildBudget, storeRebuildStatus } from './store-rebuild.js';
-import { PUSH_HOLD_TTL_MS, runStoreDriverRollout, storeDriverRelease, storedReleaseLoader } from './store-releases.js';
+import { PUSH_HOLD_TTL_MS, STORE_RELEASE_STORED_MAX_BYTES, approveStoredDriverRelease, runStoreDriverRevoke, runStoreDriverRollout, storeDriverRelease, storedReleaseLoader } from './store-releases.js';
 import { assertNoUnreachableScopeCopies, claimScopeScriptReap, drainScopeScriptCopies, listAllScopeScriptCopies, recordStrandedStorage } from './scope-copy-cleanup.js';
 import { BACKFILL_PAGE_MAX, backfillScopeScriptCopies } from './scope-copy-backfill.js';
 import { oidcCallbackUrl, retireClientsOfReapedScope, wirePreviewAuth } from './preview-auth.js';
@@ -715,6 +716,8 @@ const TENANT_ROUTES = [
     { method: 'POST', re: /\/tenants\/[^/]+\/orgs$/, pin: 'path' },
     { method: 'POST', re: /\/tenants\/[^/]+\/role-assignments$/, pin: 'path' },
     { method: 'DELETE', re: /\/tenants\/[^/]+\/role-assignments$/, pin: 'path' },
+    { method: 'GET', re: /\/tenants\/[^/]+\/entitlements$/, pin: 'path' },
+    { method: 'GET', re: /\/tenants\/[^/]+\/metered-usage$/, pin: 'path' },
     // An install's entitlement. The handler narrows WHICH key a tenant credential may
     // grant (`tenantGrantableEntitlement`): the pin alone would let it grant itself any.
     { method: 'PUT', re: /\/tenants\/[^/]+\/entitlements\/[^/]+$/, pin: 'path' },
@@ -820,6 +823,7 @@ const TENANT_ROUTES = [
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/registry$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/migrations$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/model$/, pin: 'owner' },
+    { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/concept$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/flow$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/assets$/, pin: 'owner' },
     { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/schedules$/, pin: 'owner' },
@@ -1146,7 +1150,7 @@ export function createControlPlaneApi(options) {
     const advisory = options.cliAdvisory;
     app.use('*', async (c, next) => {
         await next();
-        c.header(PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER);
+        c.header(PLATFORM_FEATURES_HEADER, [PLATFORM_FEATURE_SCOPE_SWEEPER, ...(options.sourceBuilds ? [PLATFORM_FEATURE_SOURCE_BUILDS] : [])].join(','));
         if (advisory?.minVersion)
             c.header(CLI_MIN_VERSION_HEADER, advisory.minVersion);
         if (advisory?.latestVersion)
@@ -1232,10 +1236,13 @@ export function createControlPlaneApi(options) {
         // The emitted entity model of one version (#1214) — owner-narrowed the same way;
         // the dashboard's Model tab reads it.
         { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/model$/ },
+        { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/concept$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/schedules$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/channels$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/channels\/[^/]+\/history$/ },
         { method: 'POST', re: /\/verticals\/[^/]+\/channels\/[^/]+\/promote$/ },
+        { method: 'GET', re: /\/projects$/ },
+        { method: 'POST', re: /\/projects$/ },
         { 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.
@@ -1677,6 +1684,168 @@ export function createControlPlaneApi(options) {
     });
     // -- entitlements (§4.3) ---------------------------------------------------
     app.get('/tenants/:tenantId/entitlements', async (c) => c.json(await c.var.admin.listEntitlements(c.get('actor'), tenantIdSchema.parse(c.req.param('tenantId')))));
+    // One tenant's persisted usage, with no price-bearing fields (#2689). This read never
+    // wakes a scope or writes a row. A gauge projection is capped at 501 narrow scope rows;
+    // request rows at 10,000 plus 30 status rows; model pages at 25 x 501: at most 28
+    // directory calls and 23,056 projected rows. Labels are capped at the read source,
+    // and no staff ledger row crosses the RPC. The 5-second cooperative budget stops new
+    // reads, though it cannot interrupt one in flight. Every cap marks a lower bound.
+    // The dashboard credential reaches this path only when its signed tenant pin matches.
+    app.get('/tenants/:tenantId/metered-usage', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        if (outsideTenant(c.get('principal'), tenantId))
+            return refuse(c, 'forbidden', 'forbidden');
+        const admin = c.var.admin;
+        const actor = c.get('actor');
+        const usageNow = options.meteredUsageNow ?? (() => performance.now());
+        const deadline = usageNow() + 5_000;
+        const readAt = new Date().toISOString();
+        const until = readAt.slice(0, 10);
+        const since = new Date(Date.parse(`${until}T00:00:00Z`) - 30 * 86_400_000).toISOString().slice(0, 10);
+        const through = new Date(Date.parse(`${until}T00:00:00Z`) - 86_400_000).toISOString().slice(0, 10);
+        const gaugeRead = await admin.readTenantStorageGauge(actor, tenantId, 500);
+        const gauge = gaugeRead.gauge;
+        const stale = gauge?.oldestReadAt ? Date.parse(readAt) - Date.parse(gauge.oldestReadAt) > 2 * 86_400_000 : false;
+        const storageState = gaugeRead.truncated ? 'truncated' : !gauge ? 'unavailable' : gauge.sampled === 0 ? (gauge.total === 0 ? 'empty' : 'not-sampled')
+            : gauge.failing > 0 ? 'failing' : stale ? 'stale' : gauge.sampled < gauge.total ? 'partial' : 'complete';
+        // Literal output allowlist: never spread a meter row (which also carries plan data).
+        const storage = {
+            state: storageState,
+            bytes: gauge && gauge.sampled > 0 ? gauge.bytes : null,
+            estimated: false,
+            lowerBound: gaugeRead.truncated,
+            truncatedReason: gaugeRead.truncated ? 'scope-cap' : null,
+            basis: 'scope-databases',
+            sampled: gauge?.sampled ?? 0,
+            total: gauge?.total ?? 0,
+            failing: gauge?.failing ?? 0,
+            oldestReadAt: gauge?.oldestReadAt ?? null,
+            excluded: gauge?.excluded ?? [],
+        };
+        let requests = {
+            state: 'unavailable', requests: null, estimated: true, lowerBound: false,
+            coveredDays: 0, totalDays: 30, sinceDay: since, untilDay: through,
+            lastReadAt: null, byVertical: [], breakdownTruncated: false,
+        };
+        if (usageNow() < deadline && admin.listTenantRequestMeter && admin.listRequestMeterDays) {
+            const [rows, days] = await Promise.all([
+                admin.listTenantRequestMeter(actor, tenantId, since, through, REQUEST_ROLLUP_LIMIT_MAX),
+                admin.listRequestMeterDays(actor, since, through),
+            ]);
+            const covered = days.filter((d) => d.readAt !== null && !d.saturated);
+            const coveredDaySet = new Set(covered.map((day) => day.day));
+            const clipped = rows.length === REQUEST_ROLLUP_LIMIT_MAX;
+            const groups = new Map();
+            let count = 0;
+            let countedRows = 0;
+            let requestLabelsTruncated = false;
+            for (const row of rows.slice(0, REQUEST_ROLLUP_LIMIT_MAX - 1)) {
+                if (!coveredDaySet.has(row.day))
+                    continue;
+                countedRows++;
+                count += row.requests;
+                if (row.labelTruncated)
+                    requestLabelsTruncated = true;
+                else
+                    groups.set(row.vertical, (groups.get(row.vertical) ?? 0) + row.requests);
+            }
+            const byVertical = [...groups].sort((a, b) => (a[0] ?? '').localeCompare(b[0] ?? ''));
+            const incomplete = covered.length < 30 || clipped;
+            requests = {
+                state: covered.length === 0 ? 'unavailable' : clipped ? 'truncated' : countedRows === 0 ? 'empty' : incomplete ? 'partial' : 'complete',
+                requests: countedRows > 0 ? count : null,
+                estimated: true,
+                lowerBound: countedRows > 0 && incomplete,
+                coveredDays: covered.length,
+                totalDays: 30,
+                sinceDay: since,
+                untilDay: through,
+                lastReadAt: covered.reduce((latest, day) => !latest || day.readAt > latest ? day.readAt : latest, null),
+                byVertical: covered.length > 0 ? byVertical.slice(0, 50).map(([vertical, n]) => ({ vertical, requests: n })) : [],
+                breakdownTruncated: covered.length > 0 && (byVertical.length > 50 || requestLabelsTruncated),
+            };
+        }
+        const groups = new Map();
+        let calls = 0;
+        let reportedCalls = 0;
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let oldestRecordedAt = null;
+        let newestRecordedAt = null;
+        let truncated = false;
+        let truncatedReason = null;
+        let modelSkipped = false;
+        let labelsTruncated = false;
+        const earlier = (a, b) => a === null || b < a ? b : a;
+        const later = (a, b) => a === null || b > a ? b : a;
+        if (typeof admin.listTenantModelUsageMeter === 'function') {
+            let cursor;
+            for (let page = 0; page < 25; page++) {
+                if (usageNow() >= deadline) {
+                    if (calls > 0) {
+                        truncated = true;
+                        truncatedReason = 'time-budget';
+                    }
+                    else
+                        modelSkipped = true;
+                    break;
+                }
+                const entries = await admin.listTenantModelUsageMeter(actor, { tenantId, since: `${since}T00:00:00Z`, until: `${until}T00:00:00Z`, limit: 501, ...(cursor ? { cursor } : {}) });
+                for (const entry of entries.slice(0, 500)) {
+                    calls++;
+                    if (entry.reported) {
+                        reportedCalls++;
+                        inputTokens += entry.inputTokens;
+                        outputTokens += entry.outputTokens;
+                    }
+                    oldestRecordedAt = earlier(oldestRecordedAt, entry.at);
+                    newestRecordedAt = later(newestRecordedAt, entry.at);
+                    if (entry.labelTruncated)
+                        labelsTruncated = true;
+                    else {
+                        const key = `${entry.vertical}\u0000${entry.model}`;
+                        const row = groups.get(key) ?? { vertical: entry.vertical, model: entry.model, calls: 0, reportedCalls: 0, inputTokens: 0, outputTokens: 0 };
+                        row.calls++;
+                        if (entry.reported) {
+                            row.reportedCalls++;
+                            row.inputTokens += entry.inputTokens;
+                            row.outputTokens += entry.outputTokens;
+                        }
+                        groups.set(key, row);
+                    }
+                }
+                truncated = entries.length > 500;
+                truncatedReason = truncated ? 'page-cap' : null;
+                if (!truncated)
+                    break;
+                cursor = { at: entries[499].at, id: entries[499].id };
+            }
+        }
+        const modelGroups = [...groups.values()].sort((a, b) => a.vertical.localeCompare(b.vertical) || a.model.localeCompare(b.model));
+        const models = {
+            state: typeof admin.listTenantModelUsageMeter !== 'function' || modelSkipped ? 'unavailable' : calls === 0 ? 'empty' : truncated ? 'truncated' : 'complete',
+            calls: calls > 0 ? calls : null,
+            reportedCalls,
+            inputTokens: reportedCalls > 0 ? inputTokens : null,
+            outputTokens: reportedCalls > 0 ? outputTokens : null,
+            estimated: false,
+            lowerBound: truncated,
+            truncatedReason,
+            since: `${since}T00:00:00Z`,
+            until: `${until}T00:00:00Z`,
+            oldestRecordedAt,
+            newestRecordedAt,
+            byVerticalModel: modelGroups.slice(0, 50).map((row) => ({ vertical: row.vertical, model: row.model, calls: row.calls, reportedCalls: row.reportedCalls, inputTokens: row.reportedCalls > 0 ? row.inputTokens : null, outputTokens: row.reportedCalls > 0 ? row.outputTokens : null })),
+            breakdownTruncated: modelGroups.length > 50 || labelsTruncated,
+        };
+        return c.json({
+            readAt,
+            retention: { storageMonths: STORAGE_GAUGE_RETENTION_MONTHS, modelDays: MODEL_USAGE_RETENTION_DAYS, requestMonths: BILLING_ROLLUP_RETENTION_MONTHS },
+            storage,
+            requests,
+            models,
+        });
+    });
     app.put('/tenants/:tenantId/entitlements/:key', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         // The body is the plan half (#33) and optional — a bodyless PUT is the
@@ -7201,6 +7370,16 @@ export function createControlPlaneApi(options) {
             calls: parsed?.calls ?? null,
         });
     });
+    // Published documentation only, never source files. Same owner/listed visibility as model.
+    app.get('/verticals/:slug/versions/:id/concept', async (c) => {
+        const p = c.get('principal');
+        const slug = await resolveVerticalId(c, c.req.param('slug'));
+        if (await notReadable(p, slug))
+            return refuse(c, 'not_found', 'not found');
+        const json = await c.var.admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
+        const parsed = json ? storedDeployManifest.parse(JSON.parse(json)) : null;
+        return c.json({ concept: parsed?.concept ?? null });
+    });
     app.get('/verticals/:slug/versions/:id/model', async (c) => {
         const p = c.get('principal');
         const slug = await resolveVerticalId(c, c.req.param('slug'));
@@ -7970,12 +8149,98 @@ export function createControlPlaneApi(options) {
     // 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.all('/projects', async (c) => {
+        if (!options.sourceBuilds)
+            return refuseStatus(c, 501, 'source builds are not configured');
+        const p = c.get('principal');
+        if (p.kind !== 'builder' && p.kind !== 'staff')
+            return refuse(c, 'forbidden', 'forbidden');
+        const tenant = p.kind === 'builder' ? p.tenantId : c.req.query('tenant');
+        if (!tenant)
+            return refuse(c, 'validation_failed', 'tenant id is required');
+        const tenants = await c.var.admin.listTenants(c.get('actor'));
+        if (!tenants.some((t) => t.id === tenant))
+            return refuse(c, 'not_found', 'unknown workspace');
+        let body;
+        if (c.req.method === 'POST') {
+            const input = z.object({ slug: z.string().min(1), name: z.string().min(1), repository: z.unknown().optional() }).parse(await c.req.json());
+            const team = tenants.find((t) => t.id === tenant);
+            const slug = await ownerOf(c.get('actor'), input.slug) === tenant || input.slug.startsWith(`${team.slug}/`) ? input.slug : `${team.slug}/${input.slug}`;
+            verticalSlug.parse(slug);
+            const owner = await ownerOf(c.get('actor'), slug);
+            if (owner !== undefined && owner !== tenant)
+                return refuse(c, 'forbidden', 'forbidden');
+            body = JSON.stringify({ ...input, slug });
+        }
+        else if (c.req.method !== 'GET')
+            return refuseStatus(c, 405, 'method not allowed');
+        return options.sourceBuilds.projects(tenant, new Request('https://source/projects', {
+            method: c.req.method, ...(body ? { headers: { 'content-type': 'application/json' }, body } : {}),
+        }));
+    });
+    app.post('/source/github-access', async (c) => {
+        if (c.get('principal').kind !== 'staff')
+            return refuse(c, 'forbidden', 'forbidden');
+        if (!options.githubRepositoryAccess)
+            return refuseStatus(c, 501, 'GitHub source access is not configured');
+        const input = z.object({ tenantId: tenantIdSchema, owner: z.string().regex(/^[\w-]+$/), repo: z.string().regex(/^[\w.-]+$/), scope: z.enum(['read', 'write']).default('read') }).parse(await c.req.json());
+        const connection = await c.var.admin.openConnection(input.tenantId, 'dashboard', 'github', input.owner);
+        const installationId = connection?.secret.installationId;
+        if (typeof installationId !== 'string')
+            return refuse(c, 'not_found', 'no connected GitHub installation for this tenant and owner');
+        return c.json(await options.githubRepositoryAccess(input.tenantId, input.owner, input.repo, installationId, input.scope));
+    });
     app.post('/verticals/:slug/deploy', async (c) => {
         if (!options.deployVertical) {
             return refuseStatus(c, 501, 'deploy is not configured on this control plane');
         }
         const p = c.get('principal');
-        const form = await c.req.formData();
+        let built;
+        let requestedVersion;
+        let form;
+        if (options.sourceBuilds) {
+            if (!c.req.header('content-type')?.startsWith('application/json')) {
+                return refuseStatus(c, 415, 'submit source JSON; client-built module uploads are no longer accepted');
+            }
+            const input = sourceBuildRequest.parse(await c.req.json());
+            const bare = c.req.param('slug');
+            let sourceSlug = bare;
+            let sourceTenant = null;
+            if (p.kind === 'builder') {
+                if (input.tenant && input.tenant !== p.tenantId && input.tenant !== p.tenantSlug) {
+                    return refuse(c, 'forbidden', `push is pinned to workspace '${input.tenant}' but this session acts for '${p.tenantSlug}'`);
+                }
+                sourceTenant = p.tenantId;
+                sourceSlug = effectiveSlug(p, bare);
+            }
+            else if (input.tenant) {
+                const tenant = (await c.var.admin.listTenants(c.get('actor'))).find((t) => t.id === input.tenant || t.slug === input.tenant);
+                if (!tenant)
+                    return refuse(c, 'not_found', 'unknown workspace');
+                sourceTenant = tenant.id;
+                sourceSlug = bare.startsWith(`${tenant.slug}/`) || await ownerOf(c.get('actor'), bare) === tenant.id ? bare : `${tenant.slug}/${bare}`;
+            }
+            const owner = await ownerOf(c.get('actor'), sourceSlug);
+            if (sourceTenant && owner !== undefined && owner !== sourceTenant)
+                return refuse(c, 'forbidden', 'forbidden');
+            sourceTenant ??= owner ?? null;
+            verticalSlug.parse(sourceSlug);
+            if (platformScriptCollision(sourceSlug))
+                return refuseStatus(c, 422, 'reserved platform script name');
+            requestedVersion = input.version;
+            built = await options.sourceBuilds.build(sourceTenant ?? 'platform', sourceSlug, input);
+            form = built.form;
+            // Addressing is the authenticated caller's, never a field emitted by project code.
+            form.delete('tenant');
+            if (input.tenant)
+                form.set('tenant', input.tenant);
+            form.delete('allowFork');
+            if (input.allowFork)
+                form.set('allowFork', '1');
+        }
+        else {
+            return refuseStatus(c, 501, 'platform source builds are not configured');
+        }
         const raw = form.get('manifest');
         if (typeof raw !== 'string')
             return refuse(c, 'validation_failed', 'missing manifest part');
@@ -7984,6 +8249,8 @@ export function createControlPlaneApi(options) {
             return refuse(c, 'validation_failed', 'manifest registry: required when modules are present');
         }
         const manifest = deployManifest.parse(parsed);
+        if (requestedVersion && manifest.version !== requestedVersion)
+            return refuseStatus(c, 502, 'build service produced a different release version');
         const moduleProblems = pushedModuleRegistryProblems(manifest.modules, manifest.registry);
         if (moduleProblems.length > 0)
             return refuse(c, 'validation_failed', `manifest registry.permissions: ${moduleProblems.join('; ')}`);
@@ -8055,7 +8322,7 @@ export function createControlPlaneApi(options) {
             // Otherwise the claim lands under the tenant prefix, exactly like a builder push —
             // same namespace, no claim race with other workspaces' bare names.
             const bareOwner = await ownerOf(c.get('actor'), bare);
-            slug = bareOwner === workspace.id ? bare : `${workspace.slug}/${bare}`;
+            slug = bare.startsWith(`${workspace.slug}/`) || bareOwner === workspace.id ? bare : `${workspace.slug}/${bare}`;
             const existingOwner = slug === bare ? bareOwner : await ownerOf(c.get('actor'), slug);
             if (existingOwner !== undefined && existingOwner !== workspace.id) {
                 return refuse(c, 'forbidden', `vertical '${slug}' is not owned by workspace '${pin}'`);
@@ -8333,7 +8600,7 @@ export function createControlPlaneApi(options) {
             }
         }
         const version = await c.var.admin.getVersion(c.get('actor'), id, slug);
-        return c.json({ ...version, ...(warnings.length ? { warnings } : {}) }, 201);
+        return c.json({ ...version, ...(built ? { projectId: built.projectId, revision: built.revision, dataLoss: built.dataLoss } : {}), ...(warnings.length ? { warnings } : {}) }, 201);
     });
     // -- where this platform runs (ops ergonomics) -----------------------------
     // The console renders refs it already has — `servingRef`, a store's `ref`, a version's
@@ -9374,6 +9641,47 @@ export function createControlPlaneApi(options) {
         const target = (await options.resolveVerticalVersion?.(slug, opts.versionId, actor)) ??
             options.verticals?.[slug] ??
             (await options.resolveVertical?.(slug, actor));
+        // Both the source and pushed versions must opt in to carrying an ordinary setting. A
+        // missing or invalid source declaration allows none. The parent deployment reads only
+        // these keys; the control plane never copies its whole config store.
+        const carrySettings = async (previewId, parent) => {
+            if (!parent)
+                return;
+            const eligibleKeys = (json) => {
+                if (!json)
+                    return new Set();
+                try {
+                    const declared = JSON.parse(json).envSpec;
+                    const specs = z.array(envVarSpec).safeParse(declared);
+                    if (!specs.success)
+                        return new Set();
+                    return new Set(specs.data.filter((spec) => spec.previewCarry && !spec.secret && spec.kind !== 'model').map((spec) => spec.key));
+                }
+                catch {
+                    return new Set();
+                }
+            };
+            const sourceJson = parent.verticalVersionId
+                ? await c.var.admin.versionManifest(actor, slug, parent.verticalVersionId)
+                : null;
+            const sourceKeys = eligibleKeys(sourceJson);
+            if (sourceKeys.size === 0)
+                return;
+            const incomingJson = await c.var.admin.versionManifest(actor, slug, opts.versionId);
+            const keys = [...eligibleKeys(incomingJson)].filter((key) => sourceKeys.has(key));
+            if (keys.length === 0)
+                return;
+            const sourceClient = await verticalForScope(c, parent);
+            if (!sourceClient || !target) {
+                throw new ControlPlaneError(501, 'the parent or preview deployment cannot deliver declared preview settings');
+            }
+            const requested = new Set(keys);
+            const values = await retryTransient(() => sourceClient.readPreviewConfig({ tenantId, scopeId: parent.id, keys }));
+            const entries = values.filter((entry) => requested.has(entry.key));
+            if (entries.length > 0) {
+                await retryTransient(() => target.configureInstance({ tenantId, scopeId: previewId, entries }));
+            }
+        };
         // The preview's own login (#1704), once it serves this version. Delivered into `target` —
         // THIS push's version deployment — and never "whatever the scope is bound to now", so an
         // older push can never overwrite a newer push's config store. A failure lands an
@@ -9415,8 +9723,8 @@ export function createControlPlaneApi(options) {
         };
         const notesFor = (parent) => parent
             ? [
-                "Settings: a preview does not carry over the app's per-install settings (the dashboard's Env tab); " +
-                    "it runs on the deployment's defaults.",
+                "Settings: only non-secret Env tab settings explicitly declared for preview carryover are delivered; " +
+                    "other settings use the deployment's defaults.",
             ]
             : [];
         // The `--<tag>` URL's base — the source's canonical hostname (fork) or the tenant-app
@@ -9503,6 +9811,7 @@ export function createControlPlaneApi(options) {
         const servedFork = async (p) => {
             const hostname = await bindPreviewHostname(c.var.admin, actor, baseHostname, tenantId, p.previewId, opts.tag, surface);
             await assertServesBoundVersion(p.previewId);
+            await carrySettings(p.previewId, p.parent);
             const auth = await wireLogin(p.previewId, hostname, p.parent);
             return {
                 scopeId: p.previewId,
@@ -9782,6 +10091,7 @@ export function createControlPlaneApi(options) {
             const parent = existing.forkedFrom
                 ? ((await c.var.admin.getScopeRecord(actor, tenantId, existing.forkedFrom)) ?? null)
                 : null;
+            await carrySettings(existing.id, parent);
             const auth = await wireLogin(existing.id, hostname, parent);
             return {
                 scopeId: existing.id,
@@ -10586,10 +10896,7 @@ export function createControlPlaneApi(options) {
      * `text/plain` beacon cannot set it without a CORS preflight, 415) and refuse a request a
      * browser marks as from another origin (403). A request with neither header is the CLI's.
      */
-    const byAPerson = async (c, words = { write: 'a store driver release write', person: 'a store driver release is published by a person' }) => {
-        if (!/^application\/json\s*(;|$)/i.test(c.req.header('content-type') ?? '')) {
-            throw new ControlPlaneError(415, `${words.write} takes application/json`);
-        }
+    const staffPerson = async (c, words) => {
         const origin = c.req.header('origin');
         const site = c.req.header('sec-fetch-site');
         if ((origin && origin !== new URL(c.req.url).origin) || (site && site !== 'same-origin' && site !== 'none')) {
@@ -10602,6 +10909,85 @@ export function createControlPlaneApi(options) {
         }
         return actor;
     };
+    const byAPerson = async (c, words = { write: 'a store driver release write', person: 'a store driver release is published by a person' }) => {
+        if (!/^application\/json\s*(;|$)/i.test(c.req.header('content-type') ?? '')) {
+            throw new ControlPlaneError(415, `${words.write} takes application/json`);
+        }
+        return staffPerson(c, words);
+    };
+    const approvalWords = { write: 'a store driver release approval', person: 'a store driver release is approved by a person' };
+    const revokeWords = { write: 'a store driver release revoke', person: 'a store driver release is revoked by a person' };
+    const statusWords = { write: 'store driver release status', person: 'store driver release status is read by a person' };
+    const nonPrinting = /[\p{Cc}\p{Cf}\u2028\u2029]/u;
+    const auditText = z.string().min(1).max(2048).refine((value) => value.trim().length > 0 && !nonPrinting.test(value), { message: 'must be printable text' });
+    const reviewEvidence = z.object({ met: z.boolean(), evidence: auditText }).strict();
+    const checkedEvidence = z.object({ checked: z.literal(true), evidence: auditText }).strict();
+    // D-66 stores the reviewer's exact references: one HTTPS repository URL and one hex revision.
+    const repositoryReference = z.string().min(1).max(1024).refine((value) => {
+        if (!value.startsWith('https://') || /[\s\\?#]/u.test(value) || nonPrinting.test(value))
+            return false;
+        try {
+            const url = new URL(value);
+            return url.protocol === 'https:' && !!url.hostname && !url.username && !url.password &&
+                !url.search && !url.hash && url.pathname.split('/').some(Boolean);
+        }
+        catch {
+            return false;
+        }
+    }, { message: 'a source repository is an HTTPS URL with a host and path' });
+    const sourceCommit = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/, { message: 'a source commit is 40 or 64 lowercase hex characters' });
+    // The release entry loads a Python class by identifier; catalog names keep their existing
+    // fixed-label grammar and additionally exclude characters that cannot safely appear in audit.
+    const approvalClassName = z.string().min(1).max(256).regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+    const approvalOperation = storeCatalogOperation.refine((name) => !nonPrinting.test(name));
+    const approvalBody = z.object({
+        reason: auditText,
+        sourceReferences: z.array(z.object({ repository: repositoryReference, commit: sourceCommit }).strict()).min(1).max(64),
+        isolationReview: z.object({
+            separateScriptPerTenant: reviewEvidence,
+            noOutboundAccess: reviewEvidence,
+            envelopeVerifiedOutsideDriver: reviewEvidence,
+            envelopeChecked: checkedEvidence,
+            reservedOperationsChecked: checkedEvidence,
+            noModuleStateChecked: checkedEvidence,
+        }).strict(),
+        schema: z.number().int().min(0),
+        className: approvalClassName,
+        operations: z.array(approvalOperation).max(256),
+    }).strict();
+    const revokeBody = z.object({ reason: auditText, emergency: z.boolean().optional() }).strict();
+    const approvalPathParts = new Set([
+        'reason', 'sourceReferences', 'repository', 'commit', 'isolationReview', 'separateScriptPerTenant',
+        'noOutboundAccess', 'envelopeVerifiedOutsideDriver', 'envelopeChecked', 'reservedOperationsChecked',
+        'noModuleStateChecked', 'met', 'checked', 'evidence', 'schema', 'className', 'operations', 'emergency',
+    ]);
+    const issueCodes = {
+        unrecognized_keys: 'unrecognized_key', invalid_type: 'invalid_type', too_small: 'out_of_range',
+        too_big: 'out_of_range', invalid_format: 'invalid_format', custom: 'invalid_value',
+    };
+    const safeIssue = (issue) => {
+        const knownPath = issue.path.every((part) => (typeof part === 'number' && Number.isSafeInteger(part) && part >= 0) ||
+            (typeof part === 'string' && approvalPathParts.has(part)));
+        const path = knownPath && issue.path.length ? issue.path.join('.') : '(body)';
+        return `${path}: ${issueCodes[issue.code] ?? 'invalid_value'}`;
+    };
+    const releaseSha = (value) => {
+        if (!/^[0-9a-f]{64}$/.test(value))
+            throw new ControlPlaneError(422, 'a release sha256 is 64 lowercase hex characters');
+        return value;
+    };
+    const parseApprovalBody = (raw) => {
+        const parsed = approvalBody.safeParse(raw);
+        if (!parsed.success)
+            throw new ControlPlaneError(422, `not a store driver approval: ${parsed.error.issues.map(safeIssue).join('; ')}`);
+        return parsed.data;
+    };
+    const parseRevokeBody = (raw) => {
+        const parsed = revokeBody.safeParse(raw);
+        if (!parsed.success)
+            throw new ControlPlaneError(422, `not a store driver revoke: ${parsed.error.issues.map(safeIssue).join('; ')}`);
+        return parsed.data;
+    };
     /** The pin a release is run under, or a refusal: the platform runs only what this repo pins. */
     const pinOf = async (c, registration, sha256) => {
         const stored = await c.var.admin.getStoreDriverRelease(c.get('actor'), registration.driver, sha256);
@@ -10656,10 +11042,14 @@ export function createControlPlaneApi(options) {
         return { fingerprint, ...storeRebuildStatus(walk, fingerprint, verticals, options.storeReleases?.settleMs), walk: walk ?? null };
     };
     app.get('/store-drivers/:driver', async (c) => {
+        await staffPerson(c, statusWords);
         const registration = registeredDriver(c.req.param('driver'));
-        const state = await c.var.admin.storeDriverState(c.get('actor'), registration.driver);
+        const [state, approvals] = await Promise.all([
+            c.var.admin.storeDriverState(c.get('actor'), registration.driver),
+            c.var.admin.storeDriverApprovals(c.get('actor'), registration.driver),
+        ]);
         const rebuild = await rebuildView(c.var.admin, c.get('actor'), registration.driver);
-        return c.json({ driver: registration.driver, pins: registration.releases, ...state, ...(rebuild ? { rebuild } : {}) });
+        return c.json({ driver: registration.driver, pins: registration.releases, approvals, ...state, ...(rebuild ? { rebuild } : {}) });
     });
     // Store a release's bytes, before or after its pin lands (D-63). Idempotent per bundle.
     app.put('/store-drivers/:driver/releases', async (c) => {
@@ -10670,6 +11060,51 @@ export function createControlPlaneApi(options) {
         const release = await storeDriverRelease({ admin: c.var.admin, actor, bytes: flow.bytes, driver: registration.driver, body });
         return c.json({ release, pinned: registration.releases.some((p) => p.sha256 === release.sha256 && p.sourceCommit === release.sourceCommit) }, 201);
     });
+    // The approval is a second, person-only write over bytes the platform already named by digest.
+    app.post('/store-drivers/:driver/releases/:sha256/approvals', async (c) => {
+        const registration = registeredDriver(c.req.param('driver'));
+        const actor = await byAPerson(c, approvalWords);
+        const sha256 = releaseSha(c.req.param('sha256'));
+        const body = parseApprovalBody(await readCappedJson(c.req.raw, 64 * 1024));
+        const flow = options.storeReleases;
+        if (!flow)
+            throw new ControlPlaneError(501, 'this control plane cannot read stored release bytes for approval');
+        const approval = await approveStoredDriverRelease({ admin: c.var.admin, actor, bytes: flow.bytes, driver: registration.driver, sha256, approval: body });
+        const state = await c.var.admin.storeDriverState(actor, registration.driver);
+        const approvals = state.current ? await c.var.admin.storeDriverApprovals(actor, registration.driver) : [];
+        const currentSchema = state.current
+            ? approvals.find((a) => a.sha256 === state.current.sha256)?.schema
+                ?? registration.releases.find((p) => p.sha256 === state.current.sha256)?.schema
+                ?? null
+            : null;
+        return c.json({ approval, currentSchema }, 201);
+    });
+    app.post('/store-drivers/:driver/releases/:sha256/revoke', async (c) => {
+        const registration = registeredDriver(c.req.param('driver'));
+        const actor = await byAPerson(c, revokeWords);
+        const sha256 = releaseSha(c.req.param('sha256'));
+        const body = parseRevokeBody(await readCappedJson(c.req.raw, 8 * 1024));
+        const flow = options.storeReleases;
+        if (!body.emergency && !flow?.readScriptRelease) {
+            throw new ControlPlaneError(501, 'this control plane cannot read store script releases for a guarded revoke');
+        }
+        const result = await runStoreDriverRevoke({
+            admin: c.var.admin,
+            actor,
+            driver: registration.driver,
+            sha256,
+            reason: body.reason,
+            emergency: body.emergency === true,
+            readScriptRelease: flow?.readScriptRelease ?? (async () => ({ exists: false })),
+            ensureCanary: async (to) => {
+                if (!flow)
+                    throw new ControlPlaneError(501, 'this control plane cannot move the store canary');
+                const loadRelease = storedReleaseLoader({ admin: c.var.admin, actor, bytes: flow.bytes });
+                await flow.ensureCanary({ driver: registration.driver, to, loadRelease });
+            },
+        });
+        return c.json(result, result.complete ? 200 : 202);
+    });
     // Roll a stored, pinned release out: the canary, then every vertical that ever declared the
     // driver. Posting the same release again converges a rollout that stopped.
     app.post('/store-drivers/:driver/rollouts', async (c) => {
@@ -10882,7 +11317,7 @@ const WIRE_WALK_REQUEST_MAX_BYTES = 64 * 1024;
  * The most a release upload's body may be: the decoded cap, as base64 (4 bytes per 3), plus room
  * for the JSON around it. A bigger body is refused (413) before it is read whole.
  */
-const STORE_RELEASE_REQUEST_MAX_BYTES = Math.ceil((STORE_RELEASE_MAX_BYTES * 4) / 3) + 1024 * 1024;
+const STORE_RELEASE_REQUEST_MAX_BYTES = STORE_RELEASE_STORED_MAX_BYTES;
 /** A JSON body read to at most `max` bytes: a declared length over it, or a stream past it, is 413. */
 async function readCappedJson(request, max) {
     const declared = Number(request.headers.get('content-length') ?? NaN);