@substrat-run/control-plane-api 0.98.1 → 0.104.0

package/dist/api.d.ts

@@ -260,7 +260,30 @@ export interface ControlPlaneApiOptions {
      * (correct for a deployment that mints no platform hostnames).
      */
     platformBaseDomains?: string[];
+    /**
+     * The CLI version advisory (#971) — what `substrat` reads off every response to nudge
+     * a builder whose CLI has fallen behind (`packages/cli/src/version.ts`). The control
+     * plane is the authority on whether a CLI is still *compatible*, which npm's `latest`
+     * tag is not, so the two values are deployment facts, not package metadata:
+     *   `minVersion`    the oldest CLI this platform still accepts pushes from (the floor)
+     *   `latestVersion` the newest published CLI
+     * Each is emitted only when supplied, as {@link CLI_MIN_VERSION_HEADER} /
+     * {@link CLI_LATEST_VERSION_HEADER}. Absent ⇒ no header at all, and a CLI that reads
+     * nothing says nothing — a server that stays silent costs nobody anything. Advisory
+     * only: this package does not refuse a push below the floor.
+     */
+    cliAdvisory?: {
+        minVersion?: string;
+        latestVersion?: string;
+    };
 }
+/**
+ * Response headers carrying the CLI version advisory (`ControlPlaneApiOptions.cliAdvisory`).
+ * The CLI reads these by the same spelling (`packages/cli/src/version.ts`); exported so a
+ * host or a test names the header rather than restating the string.
+ */
+export declare const CLI_MIN_VERSION_HEADER = "x-substrat-cli-min-version";
+export declare const CLI_LATEST_VERSION_HEADER = "x-substrat-cli-latest-version";
 type Vars = {
     actor: PlatformActorId;
     principal: Principal;

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
-import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, registerVerticalInput, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, } from '@substrat-run/contracts';
+import { parseHostname, withLabel, RESERVED_LABEL_SEPARATOR, adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActivity, connectionActivitySource, connectionCredential, connectionFilter, connectionProbe, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, errorCode, issueStatus, issueStatusInput, listPageQuery, matchesOutboundHost, pageOf, platformRequestFilter, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, DEFAULT_DENIAL_LIMIT, DENIAL_LIMIT_MAX, registerVerticalInput, serviceDimensions, sweepRunKind, sweepRunOutcome, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, PROBLEM_CONTENT_TYPE, toProblem, } from '@substrat-run/contracts';
+import { attributeFailure } from './failure-attribution.js';
 import { migrationProgress, ulid } from '@substrat-run/kernel';
 import { TENANT_HEADER } from './auth.js';
 import { connectionGrantsForScope } from './vertical-client.js';
@@ -30,6 +31,13 @@ import { mintPushToken, pushActorFor } from './push-token.js';
 import { namespacesForScript } from './do-namespaces.js';
 import { backupDirectoryIfDue } from './directory-backup.js';
 import { isCustomHostname, validateBindableHostname, } from './custom-hostnames.js';
+/**
+ * Response headers carrying the CLI version advisory (`ControlPlaneApiOptions.cliAdvisory`).
+ * The CLI reads these by the same spelling (`packages/cli/src/version.ts`); exported so a
+ * host or a test names the header rather than restating the string.
+ */
+export const CLI_MIN_VERSION_HEADER = 'x-substrat-cli-min-version';
+export const CLI_LATEST_VERSION_HEADER = 'x-substrat-cli-latest-version';
 // -- 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 —
@@ -253,14 +261,46 @@ const opsFailuresQuery = z.object({
     tenantId: tenantIdSchema.optional(),
     scopeId: scopeIdSchema.optional(),
     vertical: z.string().optional(),
+    // The version-registry id — the release-health narrowing (#1231).
+    version: z.string().optional(),
     operation: z.string().optional(),
     // Exact match — the lookup a CI log's `reference = <id>` line lands on.
     reference: z.string().optional(),
+    // The taxonomy code — the error-shape narrowing an issues view groups by (#1233).
+    code: errorCode.optional(),
     since: z.string().optional(),
     until: z.string().optional(),
     // Bounded by default exactly as /admin-log, and for the same reason.
     ...listPageQuery.shape,
 });
+// The issues read (#1233). No cursor by design: grouping IS the compression —
+// cardinality is the number of distinct failure shapes — and `limit` bounds it.
+const issuesQuery = z.object({
+    status: issueStatus.optional(),
+    operation: z.string().optional(),
+    code: errorCode.optional(),
+    limit: z.coerce.number().int().min(1).max(500).optional(),
+});
+// The lifecycle verdict (#1233). The fingerprint rides in the BODY, not the path:
+// it embeds U+001F by construction, and a path segment would force every caller
+// through percent-encoding it can get subtly wrong.
+const issueStatusUpdate = z.object({
+    fingerprint: z.string().min(1),
+    status: issueStatusInput,
+});
+const sweepRunsQuery = z.object({
+    kind: sweepRunKind.optional(),
+    unit: z.string().optional(),
+    outcome: sweepRunOutcome.optional(),
+    tenantId: tenantIdSchema.optional(),
+    scopeId: scopeIdSchema.optional(),
+    vertical: z.string().optional(),
+    connectionId: z.string().optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    // Bounded by default exactly as /ops-failures, and for the same reason.
+    ...listPageQuery.shape,
+});
 const modelUsageQuery = z.object({
     tenantId: tenantIdSchema.optional(),
     scopeId: scopeIdSchema.optional(),
@@ -311,6 +351,20 @@ export function createControlPlaneApi(options) {
     const { host, authenticate, authenticateBuilder } = options;
     const admin = host.admin;
     const app = new Hono();
+    // The CLI version advisory (#971), stamped on EVERY response — including the 401 the
+    // auth middleware below answers with, since a CLI too old to authenticate is exactly
+    // the one that needs to hear it. Registered first so nothing can return around it.
+    // Nothing configured ⇒ no header touched, byte-identical to before this existed.
+    const advisory = options.cliAdvisory;
+    if (advisory?.minVersion || advisory?.latestVersion) {
+        app.use('*', async (c, next) => {
+            await next();
+            if (advisory.minVersion)
+                c.header(CLI_MIN_VERSION_HEADER, advisory.minVersion);
+            if (advisory.latestVersion)
+                c.header(CLI_LATEST_VERSION_HEADER, advisory.latestVersion);
+        });
+    }
     // Fail closed, before any route runs: no principal, no reach. Staff/service first
     // (unchanged, a superset); a builder session only when staff declines.
     app.use('*', async (c, next) => {
@@ -355,6 +409,10 @@ export function createControlPlaneApi(options) {
         // The declared permission registry of one version (D-39, #336) — owner-narrowed in the
         // handler like the versions list; the builder-facing Permissions tab reads it.
         { method: 'GET', re: /\/verticals\/[^/]+\/versions\/[^/]+\/registry$/ },
+        // 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\/[^/]+\/schedules$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/channels$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/channels\/[^/]+\/history$/ },
         { method: 'POST', re: /\/verticals\/[^/]+\/channels\/[^/]+\/promote$/ },
@@ -399,6 +457,14 @@ export function createControlPlaneApi(options) {
         // preview / provision fail. Tenant-narrowed in the handler (the forced-filter
         // pattern, like GET /scopes); the allowlist alone is not authz.
         { method: 'GET', re: /\/ops-failures$/ },
+        // The service→(vertical, version) join (#1231): what MY deployed scripts mean in
+        // signal dimensions. Tenant-narrowed in the handler (the same forced-filter
+        // pattern); the allowlist alone is not authz.
+        { method: 'GET', re: /\/service-refs$/ },
+        // The sweep record (#1232): when were MY connections last swept, and how did it
+        // go. Tenant-narrowed in the handler (the forced-filter pattern); the allowlist
+        // alone is not authz.
+        { method: 'GET', re: /\/sweep-runs$/ },
     ];
     app.use('*', async (c, next) => {
         if (c.get('principal').kind === 'builder') {
@@ -412,10 +478,21 @@ export function createControlPlaneApi(options) {
     // mask the failure it is recording, so every path through this swallows its own
     // errors. The upstream reference is extracted here — one place — so a caller
     // that only has the message still lands a searchable row.
-    const recordFailure = (entry) => {
+    // Not `cause?: unknown` with an undefined check: a caught value CAN be literally
+    // `undefined` (`throw undefined`, a bare rejection), and that throw deserves an
+    // `unknown` attribution, not a skipped one. Only true omission skips.
+    const NO_CAUSE = Symbol('no-cause');
+    const recordFailure = (entry, cause = NO_CAUSE) => {
+        // The error SHAPE rides beside the prose (#1233): attributed here — one place,
+        // from the throw itself — so a fingerprint groups on a column and never has to
+        // regex a message. A caller with no throw in hand leaves the columns null,
+        // which reads as "nobody classified this" rather than a guess nobody made.
+        const attributed = cause === NO_CAUSE ? undefined : attributeFailure(cause);
         void admin
             .recordOpsFailure({
             ...entry,
+            origin: entry.origin ?? attributed?.origin ?? null,
+            code: entry.code ?? attributed?.code ?? null,
             reference: entry.reference ?? UPSTREAM_REFERENCE.exec(entry.message)?.[1] ?? null,
         })
             .catch(() => undefined);
@@ -474,7 +551,7 @@ export function createControlPlaneApi(options) {
                 scopeId: c.req.param('scopeId') ?? null,
                 status,
                 message: err instanceof Error ? err.message : String(err),
-            });
+            }, err);
         }
         // A 500 is, by definition, a throw whose message `mapError` did not recognise — so the
         // client gets a GENERIC body that discloses nothing, and until now nothing recorded WHAT
@@ -1350,9 +1427,10 @@ export function createControlPlaneApi(options) {
                     tenantId,
                     scopeId,
                     vertical: scope.vertical,
+                    version: scope.verticalVersionId ?? null,
                     status: e instanceof ControlPlaneError ? e.status : null,
                     message,
-                });
+                }, e);
                 storeErrors.push(message);
                 return undefined;
             }
@@ -2490,7 +2568,7 @@ export function createControlPlaneApi(options) {
                         tenantId: input.tenantId,
                         status: e.status,
                         message: e.message,
-                    });
+                    }, e);
                 }
                 return c.json({ error: e.message }, e.status);
             }
@@ -2562,6 +2640,68 @@ export function createControlPlaneApi(options) {
         const visible = p.kind === 'builder' ? all.filter((v) => v.ownerTenant === p.tenantId) : all;
         return c.json(pageSlice(visible, page, (v) => v.slug));
     });
+    // -- the service→dimensions resolver (#1231's last item) -----------------------
+    // What a Cloudflare service ref MEANS: each owned vertical's serving script and
+    // per-version archive scripts, mapped to the signals stamp {vertical, version}
+    // plus the human label beside it. A DIRECTORY read — deliberately not behind the
+    // `options.observability` 501 guard, because the join must answer (for the
+    // release-health and issues views) whether or not a telemetry backend is
+    // configured. The dashboard's ownedServiceRefs() fetches this instead of
+    // re-deriving it, so every consumer means the same thing by `version`.
+    app.get('/service-refs', async (c) => {
+        const p = c.get('principal');
+        // The /ops-failures forced-filter pattern: a builder's tenant comes from the
+        // principal, never the query. A staff/service caller must SAY whose view it
+        // wants — answering fleet-wide on a forgotten param would leak, so refuse.
+        const tenantId = p.kind === 'builder' ? p.tenantId : c.req.query('tenantId');
+        if (!tenantId)
+            throw new ControlPlaneError(400, 'tenantId is required');
+        const query = z
+            .object({ tenantId: tenantIdSchema, vertical: z.string().optional() })
+            .parse({ tenantId, vertical: c.req.query('vertical') });
+        const actor = c.get('actor');
+        const all = (await admin.listVerticals(actor)).filter((v) => v.ownerTenant === query.tenantId);
+        let considered = all;
+        if (query.vertical !== undefined) {
+            const slug = await resolveVerticalId(c, query.vertical);
+            considered = all.filter((v) => v.slug === slug);
+            // Non-ownership reads as absence (K-3), exactly like the per-slug registry reads.
+            if (considered.length === 0)
+                throw new ControlPlaneError(404, 'not found');
+        }
+        // Cap the per-vertical fan-out and REPORT the cut — truncating silently is the
+        // defect the egress route names (#859), and the same posture holds here.
+        const MAX_VERTICALS = 50;
+        const verticalsTruncated = considered.length > MAX_VERTICALS;
+        const entries = [];
+        for (const v of considered.slice(0, MAX_VERTICALS)) {
+            const versions = await admin.listVersions(actor, v.slug);
+            const labelOf = new Map(versions.map((ver) => [ver.id, ver.version]));
+            // The stable serving script — where real traffic lands. Its version is the
+            // registry row's own servingVersionId: authoritative, not the scope-derived
+            // approximation the dashboard used to make.
+            if (v.servingRef && v.servingVersionId) {
+                entries.push(serviceDimensions.parse({
+                    service: v.servingRef,
+                    role: 'serving',
+                    stamp: { vertical: v.slug, version: v.servingVersionId },
+                    versionLabel: labelOf.get(v.servingVersionId) ?? null,
+                }));
+            }
+            // Each per-version archive script IS its version (previews serve these).
+            for (const ver of versions) {
+                if (!ver.deploymentRef)
+                    continue;
+                entries.push(serviceDimensions.parse({
+                    service: ver.deploymentRef,
+                    role: 'archive',
+                    stamp: { vertical: v.slug, version: ver.id },
+                    versionLabel: ver.version,
+                }));
+            }
+        }
+        return c.json({ entries, verticalsTruncated });
+    });
     app.post('/verticals', async (c) => {
         const input = registerVerticalInput.parse(await c.req.json());
         const p = c.get('principal');
@@ -2628,6 +2768,35 @@ export function createControlPlaneApi(options) {
         const registry = json ? (storedDeployManifest.parse(JSON.parse(json)).registry ?? null) : null;
         return c.json({ registry });
     });
+    // The emitted entity model (#1214) one version ships: entities, field schemas, parent
+    // edges, declared lifecycles — read out of the same retained manifest as the registry
+    // above, and owner-narrowed the same way. `model` is null for a version pushed by a
+    // pre-#1214 CLI or by a vertical with no model.json — the dashboard's Model tab renders
+    // an empty state for both, and distinguishing them buys the tenant nothing.
+    // #1232: the declared schedules of ONE version — what the dashboard's schedule-health
+    // view joins the sweep record against. Null for a version pushed before the field.
+    app.get('/verticals/:slug/versions/:id/schedules', async (c) => {
+        const p = c.get('principal');
+        const slug = await resolveVerticalId(c, c.req.param('slug'));
+        if (p.kind === 'builder' && (await ownerOf(p.actor, slug)) !== p.tenantId) {
+            return c.json({ error: 'not found' }, 404);
+        }
+        const json = await admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
+        const parsed = json ? storedDeployManifest.parse(JSON.parse(json)) : null;
+        // #1232: freshness rides the same read — the manifest is already in hand, and a
+        // sibling route would cost a second full parse for a field sitting beside this one.
+        return c.json({ schedules: parsed?.schedules ?? null, freshness: parsed?.freshness ?? null });
+    });
+    app.get('/verticals/:slug/versions/:id/model', async (c) => {
+        const p = c.get('principal');
+        const slug = await resolveVerticalId(c, c.req.param('slug'));
+        if (p.kind === 'builder' && (await ownerOf(p.actor, slug)) !== p.tenantId) {
+            return c.json({ error: 'not found' }, 404);
+        }
+        const json = await admin.versionManifest(c.get('actor'), slug, c.req.param('id'));
+        const model = json ? (storedDeployManifest.parse(JSON.parse(json)).model ?? null) : null;
+        return c.json({ model });
+    });
     // The static files (#340) one version ships: path, size, content type, content address —
     // read straight out of the retained manifest, which is where they were persisted for the
     // promote path anyway. Owner-narrowed exactly like the registry route above. `assets` is
@@ -2792,6 +2961,11 @@ export function createControlPlaneApi(options) {
             modules,
             doClasses: manifest.doClasses,
             bindings: [...manifest.bindings, ...storeBindings],
+            // #1242: the version now being served, injected as `SUBSTRAT_VERSION_ID` so the
+            // scope host stamps the signals `version` dimension. The serving script is one
+            // stable script updated in place, so this refresh is what keeps the binding
+            // naming the code that actually runs.
+            versionId,
             // #1054: the model runtime is bound only for a version that ASKED for it, so the
             // capability is visible in the manifest diff at admit rather than fleet-wide.
             ...(manifest.usesModels ? { usesModels: true } : {}),
@@ -2883,7 +3057,7 @@ export function createControlPlaneApi(options) {
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
             console.error('stores.backfill.failed', { slug, detail: message });
-            recordFailure({ actor, operation: 'promote.store-backfill', vertical: slug, message });
+            recordFailure({ actor, operation: 'promote.store-backfill', vertical: slug, message }, e);
             return { minted: [], error: message };
         }
     };
@@ -3178,6 +3352,9 @@ export function createControlPlaneApi(options) {
                 modules,
                 doClasses: manifest.doClasses,
                 bindings: manifest.bindings,
+                // #1242: the freshly minted version id — this archive script IS that version,
+                // and a preview routed at it stamps the signals `version` dimension honestly.
+                versionId: id,
                 // #340: the verified bytes go up with the bundle. The manifest's routing config
                 // rides along untouched — it decides what the RUNTIME does with paths, and carries
                 // no reach, so there is nothing in it for the sandbox contract to refuse.
@@ -3210,7 +3387,7 @@ export function createControlPlaneApi(options) {
                 tenantId: ownerTenant ?? null,
                 status: rejected ? 422 : 502,
                 message: detail,
-            });
+            }, e);
             return rejected
                 ? c.json({ error: 'deploy rejected', detail }, 422)
                 : c.json({ error: 'deploy upload failed', detail }, 502);
@@ -3801,9 +3978,10 @@ export function createControlPlaneApi(options) {
                         tenantId,
                         scopeId: previewId,
                         vertical: slug,
+                        version: opts.versionId,
                         status: e.status,
                         message: e.message,
-                    });
+                    }, e);
                 }
                 throw e;
             }
@@ -4021,7 +4199,9 @@ export function createControlPlaneApi(options) {
             tenantId: p.kind === 'builder' ? p.tenantId : c.req.query('tenantId'),
             scopeId: c.req.query('scopeId'),
             vertical: c.req.query('vertical'),
+            version: c.req.query('version'),
             operation: c.req.query('operation'),
+            code: c.req.query('code'),
             reference: c.req.query('reference'),
             since: c.req.query('since'),
             until: c.req.query('until'),
@@ -4032,6 +4212,54 @@ export function createControlPlaneApi(options) {
         const entries = await admin.listOpsFailures(c.get('actor'), filter);
         return c.json(pageOf(entries, filter.limit, (e) => e.id));
     });
+    // -- sweep runs (#1232): the durable record of what a sweep pass touched -------
+    // Staff read fleet-wide (the console's later view); a builder's tenant is forced
+    // from the principal, the /ops-failures posture exactly.
+    app.get('/sweep-runs', async (c) => {
+        const p = c.get('principal');
+        const filter = sweepRunsQuery.parse({
+            kind: c.req.query('kind'),
+            unit: c.req.query('unit'),
+            outcome: c.req.query('outcome'),
+            tenantId: p.kind === 'builder' ? p.tenantId : c.req.query('tenantId'),
+            scopeId: c.req.query('scopeId'),
+            vertical: c.req.query('vertical'),
+            connectionId: c.req.query('connectionId'),
+            since: c.req.query('since'),
+            until: c.req.query('until'),
+            limit: c.req.query('limit'),
+            cursor: c.req.query('cursor'),
+            order: c.req.query('order'),
+        });
+        const entries = await admin.listSweepRuns(c.get('actor'), filter);
+        return c.json(pageOf(entries, filter.limit, (e) => e.id));
+    });
+    // -- issues (#1233): failures grouped by fingerprint, with a lifecycle --------
+    // Staff-only (absent from BUILDER_ROUTES): an issue is a fleet-scoped aggregate
+    // with no tenant column, so the forced-filter posture cannot narrow it — a
+    // builder's per-app view derives from their tenant-forced /ops-failures instead.
+    app.get('/issues', async (c) => {
+        const filter = issuesQuery.parse({
+            status: c.req.query('status'),
+            operation: c.req.query('operation'),
+            code: c.req.query('code'),
+            limit: c.req.query('limit'),
+        });
+        const entries = await admin.listIssues(c.get('actor'), filter);
+        // No cursor, deliberately — see issuesQuery. `entries` alone, so a client
+        // never walks a continuation that cannot exist.
+        return c.json({ entries });
+    });
+    // The staff verdict on one issue: resolve, ignore, or reopen. `regressed` is
+    // ingest's word and the input schema refuses it. 404 for an unknown fingerprint
+    // rather than an invented row.
+    app.put('/issues/status', async (c) => {
+        const input = issueStatusUpdate.parse(await c.req.json());
+        const updated = await admin.setIssueStatus(c.get('actor'), input.fingerprint, input.status);
+        if (!updated)
+            return c.json({ error: 'unknown issue fingerprint' }, 404);
+        return c.json(updated);
+    });
     // -- model usage (#1054): meter 3, the one D-30 could not compute -------------
     // The ledger the `model-usage` intents drain into. Staff-only: the tenant-facing
     // read is the vertical's own usage screen over its metering engine; this is the