@substrat-run/control-plane-api 0.81.0 → 0.83.0

package/dist/api.d.ts

@@ -55,6 +55,16 @@ export interface ControlPlaneApiOptions {
      * the same Workers-for-Platforms swap later.
      */
     verticals?: Record<string, VerticalClient>;
+    /**
+     * The standing grants each connector declares, by provider (#726 gap 2) — e.g.
+     * `{ scrive: SCRIVE_CONNECTION_GRANTS }`.
+     *
+     * Every reconcile heals a connection toward this floor before gathering, which is what
+     * makes a missing capability repairable by a PUSH rather than by re-typing a working
+     * credential. Absent ⇒ nothing is healed and the gather behaves exactly as before, so a
+     * host that configures no connectors is unaffected.
+     */
+    connectorGrants?: Readonly<Record<string, readonly string[]>>;
     /**
      * Resolves a vertical dynamically — the dispatch swap for provisioning (orchestration.md
      * §5.4), the mirror of the router's `verticalFor`. Given a slug, the host looks up 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

@@ -3,6 +3,7 @@ import { adminAction, ASSET_PART_PREFIX, assetHash, channelName, connectionActiv
 import { migrationProgress, ulid } from '@substrat-run/kernel';
 import { TENANT_HEADER } from './auth.js';
 import { connectionGrantsForScope } from './vertical-client.js';
+import { reconcileConnectionGrants } from './connection-grants.js';
 import { ConnectionRelayError, relayConnectionUpsert } from './connection-relay.js';
 import { ControlPlaneError } from './client.js';
 import { provisionSiblingScope } from './platform-drain.js';
@@ -1240,6 +1241,21 @@ export function createControlPlaneApi(options) {
         // #592: connection grants ride the same authoritative gather — the back-fill for a
         // scope provisioned before `grantToConnection` ran, and how a revoked connection's
         // grants stop being delivered (they are absent from the directory's live rows).
+        // #726 gap 2: heal FIRST, gather second. The gather only ever delivered grants that
+        // already existed as directory rows, so a capability the connector requires and the
+        // connection never received was repairable only by re-submitting the credential. This
+        // is the operator's existing lever (`substrat scope provision`, the idempotent
+        // repair), so a missing grant is now fixed by the same command that fixes everything
+        // else — and by a push, once a connector's declaration changes.
+        //
+        // Best-effort: healing reaches the directory and must never take the reconcile down
+        // with it. A failure here leaves exactly the behaviour that shipped before it existed.
+        try {
+            await reconcileConnectionGrants({ admin, actor, declared: options.connectorGrants ?? {} }, tenantId, scope.vertical);
+        }
+        catch {
+            // The next reconcile tries again; the read-back still shows what is missing.
+        }
         const connectionGrants = connectionGrantsForScope(await admin.listConnectionGrants(actor, tenantId), scope.vertical, scopeId);
         // #687: connection sealing keys ride the same gather — the back-fill for a scope
         // provisioned before its connection existed, and the channel a connection made AFTER
@@ -1257,23 +1273,63 @@ export function createControlPlaneApi(options) {
         // re-run by construction: both collectors are idempotent on (tenant, vertical, binding)
         // and the binding attach is additive, so a scope whose stores already exist re-resolves
         // the same refs and changes nothing.
+        //
+        // BEST-EFFORT, and each substrate independently (#828). Minting reaches Cloudflare, so
+        // it fails for reasons that have nothing to do with this scope — a credential missing a
+        // permission, a store API refusing, a client the deployment never configured. Letting
+        // that throw took the whole call down, which cost the caller the RECONCILE they came
+        // for: the owner re-grant and role re-projection that is this lever's original job
+        // (#332) and that has no relation to stores. It also answered a bare 500, so the
+        // operator could not tell a missing credential from a bad scope id.
+        //
+        // This is the posture the promote-path backfill already has (`backfillFleetStores`) and
+        // for the same reason: the repair must report what it could not do, not refuse to do
+        // the rest. The two paths now agree. What does NOT get this treatment is a NEW install
+        // (`POST /verticals/:slug/instances`, below): there the store is handed into the K-31
+        // ready-gate and a fresh install without it is simply broken, so a failed mint must
+        // fail the provision rather than hand back a half-built scope.
+        const storeErrors = [];
+        const mintBestEffort = async (stage, mint) => {
+            try {
+                return await mint();
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                console.error('stores.provision.failed', { tenantId, scopeId, vertical: scope.vertical, stage, detail: message });
+                recordFailure({
+                    actor,
+                    operation: 'scope.provision.stores',
+                    stage,
+                    tenantId,
+                    scopeId,
+                    vertical: scope.vertical,
+                    status: e instanceof ControlPlaneError ? e.status : null,
+                    message,
+                });
+                storeErrors.push(message);
+                return undefined;
+            }
+        };
+        // Independently, so a D1 refusal does not silently skip the R2 mint (and vice versa):
+        // a scope declaring both would otherwise report one fault, get half its stores, and
+        // need a second run to discover the other.
         const tenantStores = scope.vertical
-            ? await collectTenantStoreHandles({
+            ? ((await mintBestEffort('tenant-stores', () => collectTenantStoreHandles({
                 host: options.host,
                 actor,
                 slug: scope.vertical,
                 tenantId,
                 patchBindings: options.patchScriptBindings,
-            })
+            }))) ?? [])
             : [];
         if (scope.vertical) {
-            await collectBlobStoreHandles({
+            await mintBestEffort('blob-stores', () => collectBlobStoreHandles({
                 host: options.host,
                 actor,
                 slug: scope.vertical,
                 tenantId,
                 patchBindings: options.patchScriptBindings,
-            });
+            }));
         }
         try {
             const result = await vertical.reconcileInstance({
@@ -1288,11 +1344,20 @@ export function createControlPlaneApi(options) {
                 // but unmigrated database fails as loudly as an absent one.
                 ...(tenantStores.length ? { tenantStores } : {}),
             });
-            return c.json(result);
+            // The reconcile succeeded; a store that did not mint rides back as a diagnosis
+            // (`substrat scope provision` prints it, and `/health` keeps reporting the gap
+            // until it closes). Absent when nothing failed, so the response is unchanged for
+            // every scope that has no declared store or already has them all.
+            return c.json(storeErrors.length ? { ...result, storeError: storeErrors.join('; ') } : result);
         }
         catch (e) {
-            if (e instanceof ControlPlaneError)
-                return c.json({ error: e.message }, e.status);
+            if (e instanceof ControlPlaneError) {
+                // Both halves failed. The store fault is usually the CAUSE (an unmigrated or
+                // unbound store is exactly what makes a vertical refuse its own reconcile), so
+                // it must not be the half that gets dropped.
+                const detail = storeErrors.length ? `${e.message} (stores: ${storeErrors.join('; ')})` : e.message;
+                return c.json({ error: detail }, e.status);
+            }
             throw e;
         }
     });
@@ -2175,6 +2240,15 @@ export function createControlPlaneApi(options) {
         // install provisioned after `grantToConnection` holds the same `connection:<id>` tuple
         // as one provisioned before it, and the connector return path works without a human
         // replaying grants per install.
+        // #726 gap 2: heal before gathering here too, so a NEW install of a vertical whose
+        // connector has since declared another grant receives it — rather than inheriting the
+        // gap the tenant's first install was created with.
+        try {
+            await reconcileConnectionGrants({ admin, actor: c.get('actor'), declared: options.connectorGrants ?? {} }, input.tenantId, slug);
+        }
+        catch {
+            // Best-effort, exactly as on the reconcile route.
+        }
         const connectionGrants = connectionGrantsForScope(await admin.listConnectionGrants(c.get('actor'), input.tenantId), slug, input.scopeId);
         // #687: and the public sealing keys of this tenant's live connections for the same
         // vertical, so the new install can seal a value TO a connector from its first