@substrat-run/control-plane-api 0.54.0 → 0.56.0

package/dist/api.d.ts

@@ -3,7 +3,7 @@ import type { PlatformActorId } from '@substrat-run/contracts';
 import type { ScopeHost } from '@substrat-run/kernel';
 import type { PlatformActorAuth, BuilderAuth, Principal } from './auth.js';
 import type { VerticalClient } from './vertical-client.js';
-import type { DeployVerticalFn, FetchVerticalModulesFn } from './deploy.js';
+import type { DeployVerticalFn, FetchVerticalAssetFn, FetchVerticalModulesFn } from './deploy.js';
 import type { PatchScriptBindingsFn } from './wfp.js';
 import type { ObservabilityReader } from './observability.js';
 import type { PlatformRuntime } from './platform-runtime.js';
@@ -63,6 +63,15 @@ export interface ControlPlaneApiOptions {
      * place (the pre-#286 behavior: scopes stay on per-version dispatch).
      */
     fetchVerticalModules?: FetchVerticalModulesFn;
+    /**
+     * Reads one static file back from a script's runtime-served assets (#578) — how a
+     * serving upload recovers asset bytes the stable script's upload session reports
+     * missing (the asset store dedups per script, so the push's upload to the archive
+     * script does not cover a re-serve). Host-injected like `fetchVerticalModules`.
+     * Absent ⇒ a re-serve of an asset-carrying version refuses when the runtime wants
+     * bytes (the pre-#578 behavior).
+     */
+    fetchVerticalAsset?: FetchVerticalAssetFn;
     /**
      * Ensures per-tenant store D1 bindings exist on a dispatch script without a redeploy
      * (#301) — the attach step that makes a freshly-minted tenant store reachable in the

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,5 @@
 import { Hono } from 'hono';
-import { adminAction, ASSET_PART_PREFIX, assetHash, channelName, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, listPageQuery, pageOf, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, registerVerticalInput, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, z, } from '@substrat-run/contracts';
+import { adminAction, ASSET_PART_PREFIX, assetHash, channelName, createTenantInput, entitlementGrantInput, hostname as hostnameSchema, hostnameRegion, hostnameStatus, identityLink, listPageQuery, pageOf, principalId as principalIdSchema, promotionAcknowledgement, provisionableJurisdiction, publishVersionInput, queryScopeInput, readScopeTableInput, registerVerticalInput, scopeDump, dataSubjectId as dataSubjectIdSchema, scopeId as scopeIdSchema, scopeStatus, storageShape, surfaceName, tenantId as tenantIdSchema, tenantStatus, versionOrigin, z, } from '@substrat-run/contracts';
 import { migrationProgress, ulid } from '@substrat-run/kernel';
 import { TENANT_HEADER } from './auth.js';
 import { ControlPlaneError } from './client.js';
@@ -346,6 +346,10 @@ export function createControlPlaneApi(options) {
         { method: 'POST', re: /\/verticals\/[^/]+\/previews$/ },
         { method: 'GET', re: /\/verticals\/[^/]+\/previews$/ },
         { method: 'DELETE', re: /\/verticals\/[^/]+\/previews\/[^/]+$/ },
+        // The builder's slice of the ops-failure record (#559 step 5): why did MY deploy /
+        // 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$/ },
     ];
     app.use('*', async (c, next) => {
         if (c.get('principal').kind === 'builder') {
@@ -367,6 +371,31 @@ export function createControlPlaneApi(options) {
         })
             .catch(() => undefined);
     };
+    // Rides out a transient downstream window: the install path's binding-attach →
+    // script-settings propagation race (#424 case 2), and a one-shot DO storage blip
+    // during an export→restore or snapshot copy (#559 (2)). Retrying is cheap at THESE
+    // call sites specifically — the dump is already in memory and the far end is
+    // drop-then-replay idempotent — unlike CI's retry, which burns a pushed version per
+    // attempt. Honest refusals (4xx, and 501 = not implemented) surface immediately:
+    // retrying a refusal only delays the real message. ~3s worst case on the default
+    // delays, well inside a Worker request budget; a persistent fault still exhausts
+    // and surfaces (and lands an ops-failure row via the paths that record).
+    const PROVISION_RETRY_DELAYS_MS = [750, 2500];
+    const retryTransient = async (fn) => {
+        const delays = options.provisionRetryDelaysMs ?? PROVISION_RETRY_DELAYS_MS;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (e) {
+                const transient = e instanceof ControlPlaneError && (e.status === 0 || (e.status >= 500 && e.status !== 501));
+                const delay = delays[attempt];
+                if (!transient || delay === undefined)
+                    throw e;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    };
     // One error boundary for every route: adapters throw plain Errors, and each
     // one is a fail-closed refusal that must reach the caller as a status, not a
     // stack trace.
@@ -804,7 +833,7 @@ export function createControlPlaneApi(options) {
             throw new ControlPlaneError(501, 'adopt-serving needs dispatch resolution for both ends');
         }
         const dump = await source.exportScope(scopeId);
-        const restored = await dest.restoreScope(tenantId, scopeId, dump);
+        const restored = await retryTransient(() => dest.restoreScope(tenantId, scopeId, dump));
         // Data landed — only now flip routing and move the version pointer.
         await admin.setScopeServingRef(actor, tenantId, scopeId, serving.ref);
         await admin.bindScopeVersion(actor, tenantId, scopeId, serving.versionId);
@@ -910,7 +939,7 @@ export function createControlPlaneApi(options) {
             throw new ControlPlaneError(501, 'rebind-vertical needs dispatch resolution for both ends');
         }
         const dump = await source.exportScope(scopeId);
-        const restored = await dest.restoreScope(tenantId, scopeId, dump);
+        const restored = await retryTransient(() => dest.restoreScope(tenantId, scopeId, dump));
         // Data landed on the target script — only now flip routing and cross the pointer.
         // `bindScopeVersion` rewrites `scopes.vertical` from the version row, audited. No
         // extra snapshot here (adopt-serving's precedent): the source script's copy is the
@@ -1110,7 +1139,7 @@ export function createControlPlaneApi(options) {
             forkedAt: new Date().toISOString(),
             expiresAt: opts.expiresAt,
         });
-        await vertical.snapshotScope({ sourceScopeId: scope.id, newScopeId: snapId });
+        await retryTransient(() => vertical.snapshotScope({ sourceScopeId: scope.id, newScopeId: snapId }));
         await admin.activateScope(actor, tenantId, snapId);
         // Bound to the SOURCE's current version: source and fork share a deployment, so
         // the fork resolves to the DO namespace its bytes actually live in.
@@ -1633,7 +1662,7 @@ export function createControlPlaneApi(options) {
             await host.restoreScope(actor, tenantId, scopeId, landing);
             const vertical = await verticalForScope(c, scope);
             if (vertical)
-                await vertical.restoreScope(tenantId, scopeId, tables);
+                await retryTransient(() => vertical.restoreScope(tenantId, scopeId, tables));
             return c.json({ restored: scopeId, tables: tables.length });
         }
         catch (e) {
@@ -1826,10 +1855,6 @@ export function createControlPlaneApi(options) {
     // orphaned scope nobody can see, rather than a directory row promising a scope
     // that does not exist. `scopeStatus` has a `provisioning` state for expressing the
     // in-between properly, and it is still unused — see the PR.
-    // Rides out the binding-attach → script-settings propagation window (see the
-    // `provisionRetryDelaysMs` option); the same shape as the dashboard's #391
-    // configure retry. ~3s worst case, well inside a Worker request budget.
-    const PROVISION_RETRY_DELAYS_MS = [750, 2500];
     app.post('/verticals/:slug/instances', async (c) => {
         const slug = c.req.param('slug');
         // The install kill-switch: a blocked vertical takes no NEW instances, for anyone
@@ -1883,29 +1908,13 @@ export function createControlPlaneApi(options) {
             // #424 case 2: the binding attach above races Cloudflare script-settings
             // propagation, so the vertical's FIRST answer can be a transient 5xx that a
             // retry moments later heals. `provisionInstance` is idempotent at the far end
-            // (K-31), so ride the window out on a short backoff. Honest refusals (4xx, and
-            // 501 = not implemented) surface immediately — retrying a refusal only delays
-            // the real message.
-            const delays = options.provisionRetryDelaysMs ?? PROVISION_RETRY_DELAYS_MS;
-            let instance;
-            for (let attempt = 0;; attempt++) {
-                try {
-                    instance = await vertical.provisionInstance({
-                        ...input,
-                        entitlements,
-                        identityLinks,
-                        ...(tenantStores.length ? { tenantStores } : {}),
-                    });
-                    break;
-                }
-                catch (e) {
-                    const transient = e instanceof ControlPlaneError && (e.status === 0 || (e.status >= 500 && e.status !== 501));
-                    const delay = delays[attempt];
-                    if (!transient || delay === undefined)
-                        throw e;
-                    await new Promise((resolve) => setTimeout(resolve, delay));
-                }
-            }
+            // (K-31), so ride the window out on a short backoff.
+            const instance = await retryTransient(() => vertical.provisionInstance({
+                ...input,
+                entitlements,
+                identityLinks,
+                ...(tenantStores.length ? { tenantStores } : {}),
+            }));
             return c.json(instance, 201);
         }
         catch (e) {
@@ -2227,12 +2236,26 @@ export function createControlPlaneApi(options) {
             doClasses: manifest.doClasses,
             bindings: [...manifest.bindings, ...storeBindings],
             // #340: the version's static files travel with it onto the serving script — from
-            // the RETAINED manifest, with no bytes. An asset upload session is driven by
-            // content addresses, and the runtime's asset store is namespace-wide and deduped,
-            // so re-declaring the same hashes re-attaches the same files. This is why the
-            // manifest is retained rather than the bytes: the archive script gives back the
-            // modules (#286), and the asset store gives back the assets.
-            ...(manifest.assets ? { assets: manifest.assets } : {}),
+            // the RETAINED manifest, with no bytes up front. The asset store dedups PER
+            // SCRIPT (#578), so hashes the push uploaded to the archive script are still
+            // missing for the stable script — each file therefore carries a `fetchContent`
+            // that reads the bytes back from the archive script's runtime-served assets,
+            // invoked (and hash-verified) only for hashes the upload session reports
+            // missing. The archive script gives back the modules (#286) AND the assets:
+            // nothing but the manifest is retained.
+            ...(manifest.assets
+                ? {
+                    assets: {
+                        ...manifest.assets,
+                        files: manifest.assets.files.map((f) => ({
+                            ...f,
+                            ...(options.fetchVerticalAsset
+                                ? { fetchContent: () => options.fetchVerticalAsset(version.deploymentRef, f.path) }
+                                : {}),
+                        })),
+                    },
+                }
+                : {}),
         }, serving
             ? { priorDoClasses: serving.doClasses, priorMigrationTag: serving.migrationTag }
             : undefined);
@@ -2341,6 +2364,21 @@ export function createControlPlaneApi(options) {
         // silently dropped. An old CLI that sends no pin keeps today's behavior on all paths.
         const pinField = form.get('tenant');
         const pin = typeof pinField === 'string' && pinField.length > 0 ? pinField : null;
+        // The push's self-reported provenance (git CI vs a terminal) — a label the dashboard
+        // shows, never authority, so a missing or malformed field must not fail the push
+        // (an old CLI sends none). Lenient by construction: safeParse, drop on mismatch.
+        const originField = form.get('origin');
+        const origin = (() => {
+            if (typeof originField !== 'string')
+                return undefined;
+            try {
+                const parsed = versionOrigin.safeParse(JSON.parse(originField));
+                return parsed.success ? parsed.data : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
         // Resolve the registry id + owner this push acts on. Checked BEFORE the upload so a
         // refused push never leaves an orphaned namespace script.
         const bare = c.req.param('slug');
@@ -2577,6 +2615,7 @@ export function createControlPlaneApi(options) {
             permissionDigest: manifest.digests.permission,
             migrationDigest: manifest.digests.migration,
             deploymentRef,
+            ...(origin ? { origin } : {}),
             // Retained for the serving upload (#286): the archive script keeps the module
             // bytes, this keeps their shape (entry, compat, doClasses, bindings).
             manifestJson: JSON.stringify(manifest),
@@ -3014,6 +3053,30 @@ export function createControlPlaneApi(options) {
         if (existing && stale)
             await reapPreview(c, existing);
         const previewId = scopeIdSchema.parse(ulid());
+        // The founding #559 case lands its durable row HERE, not in onError: the previews
+        // route answers a ControlPlaneError directly (its own catch, never the app-level
+        // recorder), and only this frame knows the preview's scopeId — the key that lets
+        // the console explain the stranded `provisioning` row this throw leaves behind.
+        const restoreOrRecord = async (fn) => {
+            try {
+                await retryTransient(fn);
+            }
+            catch (e) {
+                if (e instanceof ControlPlaneError && e.status >= 500 && e.status !== 501) {
+                    recordFailure({
+                        actor,
+                        operation: 'preview.create',
+                        stage: 'restore',
+                        tenantId,
+                        scopeId: previewId,
+                        vertical: slug,
+                        status: e.status,
+                        message: e.message,
+                    });
+                }
+                throw e;
+            }
+        };
         if (source) {
             // A fresh fork. Export from where the prod data lives TODAY. The canonical
             // `admin.exportScope` first — it writes the K-24 audit entry (and the co-located
@@ -3041,8 +3104,10 @@ export function createControlPlaneApi(options) {
                 expiresAt: expiresAt ?? undefined,
             });
             // Load the fork into the PR version's deployment (materializes the preview scope DO
-            // there; restore re-projects the vertical's roles from the dump's tuples).
-            await target.restoreScope(tenantId, previewId, tables);
+            // there; restore re-projects the vertical's roles from the dump's tuples). A one-shot
+            // DO storage blip heals on the in-request retry WITHOUT burning a CI attempt (which
+            // pushes a fresh version per try) — #559 (2).
+            await restoreOrRecord(() => target.restoreScope(tenantId, previewId, tables));
         }
         else {
             // A clean-room preview (#509 (b)): an EMPTY scope, no source to export. No `forkedFrom`
@@ -3061,7 +3126,7 @@ export function createControlPlaneApi(options) {
                 expiresAt: expiresAt ?? undefined,
             });
             if (target)
-                await target.restoreScope(tenantId, previewId, []);
+                await restoreOrRecord(() => target.restoreScope(tenantId, previewId, []));
         }
         await admin.activateScope(actor, tenantId, previewId);
         // Bind the PR version. A private vertical's push self-admitted, so this is accepted; a
@@ -3215,13 +3280,14 @@ export function createControlPlaneApi(options) {
         return c.json(pageOf(entries, filter.limit, (e) => e.id));
     });
     // The recorded operational failures (#559) — the console's failures view, and the
-    // "what does this `reference = <id>` belong to" lookup. Staff-only by omission from
-    // BUILDER_ROUTES (a builder-scoped slice is step 5's concern, deliberately not
-    // pre-opened here). Newest first by default, unlike /admin-log: an operator asks
-    // "what broke lately".
+    // "what does this `reference = <id>` belong to" lookup. Newest first by default,
+    // unlike /admin-log: an operator asks "what broke lately". A builder reads only its
+    // OWN tenant's rows — the filter is forced, not trusted from the query (step 5: a
+    // red CI run is explainable from the dashboard without staff involvement).
     app.get('/ops-failures', async (c) => {
+        const p = c.get('principal');
         const filter = opsFailuresQuery.parse({
-            tenantId: c.req.query('tenantId'),
+            tenantId: p.kind === 'builder' ? p.tenantId : c.req.query('tenantId'),
             scopeId: c.req.query('scopeId'),
             vertical: c.req.query('vertical'),
             operation: c.req.query('operation'),