@substrat-run/control-plane-api 0.14.0 → 0.17.0

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { ControlPlaneError } from './client.js';
 /**
  * Map an adapter throw onto an HTTP status.
  *
@@ -56,11 +57,23 @@ const STATUS_PATTERNS = [
     [/unknown scope /, 404],
     // A read-only introspection read (§5.4) for a table the scope's schema does not have.
     [/unknown table /, 404],
+    // The SQL console's gate (#219) refused the statement — a malformed request, not a
+    // server fault. The prefix is pinned by the contract suite against both adapters.
+    [/read-only console/, 400],
     [/unknown vertical /, 404],
     [/unknown version /, 404],
     [/scope has no tenant record/, 404],
 ];
 export function mapError(err) {
+    // A ControlPlaneError is a DELIBERATE downstream answer, not an unreviewed throw —
+    // the VerticalClient wraps the vertical's own JSON status/message in it. Passing it
+    // through verbatim is what lets an honest refusal (e.g. auth-server's 501 for an
+    // unimplemented verb) reach the dashboard as itself, instead of collapsing into the
+    // generic 500 below (the shape of the 2026-07-25 incident, on this side of the seam).
+    // Several routes hand-catch it already; this makes the boundary consistent for the rest.
+    if (err instanceof ControlPlaneError) {
+        return { status: err.status, body: { error: err.message } };
+    }
     const message = err instanceof Error ? err.message : String(err);
     for (const [pattern, status] of STATUS_PATTERNS) {
         if (pattern.test(message))

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;;;;GAOG;AACH,MAAM,eAAe,GAA8C;IACjE,gFAAgF;IAChF,wEAAwE;IACxE,CAAC,6CAA6C,EAAE,GAAG,CAAC;IACpD,CAAC,eAAe,EAAE,GAAG,CAAC;IACtB,CAAC,0BAA0B,EAAE,GAAG,CAAC;IACjC,CAAC,mBAAmB,EAAE,GAAG,CAAC;IAC1B,CAAC,sBAAsB,EAAE,GAAG,CAAC;IAC7B,iFAAiF;IACjF,mFAAmF;IACnF,CAAC,uBAAuB,EAAE,GAAG,CAAC;IAC9B,iFAAiF;IACjF,8EAA8E;IAC9E,kEAAkE;IAClE,CAAC,cAAc,EAAE,GAAG,CAAC;IACrB,CAAC,kCAAkC,EAAE,GAAG,CAAC;IACzC,CAAC,qBAAqB,EAAE,GAAG,CAAC;IAC5B,CAAC,cAAc,EAAE,GAAG,CAAC;IACrB,CAAC,cAAc,EAAE,GAAG,CAAC;IACrB,CAAC,sCAAsC,EAAE,GAAG,CAAC;IAC7C,+EAA+E;IAC/E,2EAA2E;IAC3E,CAAC,iBAAiB,EAAE,GAAG,CAAC;IACxB,6EAA6E;IAC7E,oEAAoE;IACpE,CAAC,iBAAiB,EAAE,GAAG,CAAC;IACxB,CAAC,0BAA0B,EAAE,GAAG,CAAC;IACjC,CAAC,gBAAgB,EAAE,GAAG,CAAC;IACvB,sFAAsF;IACtF,CAAC,gBAAgB,EAAE,GAAG,CAAC;IACvB,CAAC,mBAAmB,EAAE,GAAG,CAAC;IAC1B,CAAC,kBAAkB,EAAE,GAAG,CAAC;IACzB,CAAC,4BAA4B,EAAE,GAAG,CAAC;CACpC,CAAC;AAOF,MAAM,UAAU,QAAQ,CAAC,GAAY;IACnC,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,KAAK,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC;IACzE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;;;;GAOG;AACH,MAAM,eAAe,GAA8C;IACjE,gFAAgF;IAChF,wEAAwE;IACxE,CAAC,6CAA6C,EAAE,GAAG,CAAC;IACpD,CAAC,eAAe,EAAE,GAAG,CAAC;IACtB,CAAC,0BAA0B,EAAE,GAAG,CAAC;IACjC,CAAC,mBAAmB,EAAE,GAAG,CAAC;IAC1B,CAAC,sBAAsB,EAAE,GAAG,CAAC;IAC7B,iFAAiF;IACjF,mFAAmF;IACnF,CAAC,uBAAuB,EAAE,GAAG,CAAC;IAC9B,iFAAiF;IACjF,8EAA8E;IAC9E,kEAAkE;IAClE,CAAC,cAAc,EAAE,GAAG,CAAC;IACrB,CAAC,kCAAkC,EAAE,GAAG,CAAC;IACzC,CAAC,qBAAqB,EAAE,GAAG,CAAC;IAC5B,CAAC,cAAc,EAAE,GAAG,CAAC;IACrB,CAAC,cAAc,EAAE,GAAG,CAAC;IACrB,CAAC,sCAAsC,EAAE,GAAG,CAAC;IAC7C,+EAA+E;IAC/E,2EAA2E;IAC3E,CAAC,iBAAiB,EAAE,GAAG,CAAC;IACxB,6EAA6E;IAC7E,oEAAoE;IACpE,CAAC,iBAAiB,EAAE,GAAG,CAAC;IACxB,CAAC,0BAA0B,EAAE,GAAG,CAAC;IACjC,CAAC,gBAAgB,EAAE,GAAG,CAAC;IACvB,sFAAsF;IACtF,CAAC,gBAAgB,EAAE,GAAG,CAAC;IACvB,mFAAmF;IACnF,kFAAkF;IAClF,CAAC,mBAAmB,EAAE,GAAG,CAAC;IAC1B,CAAC,mBAAmB,EAAE,GAAG,CAAC;IAC1B,CAAC,kBAAkB,EAAE,GAAG,CAAC;IACzB,CAAC,4BAA4B,EAAE,GAAG,CAAC;CACpC,CAAC;AAOF,MAAM,UAAU,QAAQ,CAAC,GAAY;IACnC,mFAAmF;IACnF,oFAAoF;IACpF,iFAAiF;IACjF,oFAAoF;IACpF,sFAAsF;IACtF,yFAAyF;IACzF,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;QACrC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAA8B,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;IACtF,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,KAAK,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC;IACzE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,CAAC;AAC5D,CAAC"}

package/dist/index.d.ts

@@ -1,13 +1,17 @@
 export { createControlPlaneApi } from './api.js';
 export type { ControlPlaneApiOptions } from './api.js';
-export { DEV_ACTOR_HEADER, SERVICE_TOKEN_HEADER, UNSAFE_devPlatformActorAuth, sessionPlatformAuth, staffAllowlist, serviceTokenAuth, firstPlatformActorAuth, } from './auth.js';
+export { DEV_ACTOR_HEADER, SERVICE_TOKEN_HEADER, UNSAFE_devPlatformActorAuth, sessionPlatformAuth, staffAllowlist, serviceTokenAuth, firstPlatformActorAuth, firstBuilderAuth, } from './auth.js';
+export { mintPushToken, verifyPushToken, pushTokenBuilderAuth, pushActorFor } from './push-token.js';
 export type { PlatformActorAuth, StaffIdentity, StaffSessionReader, StaffActorResolver, BuilderIdentity, BuilderAuth, Principal, } from './auth.js';
 export { ControlPlaneClient, ControlPlaneError } from './client.js';
 export type { ControlPlaneClientOptions, ClientProvisionScopeInput } from './client.js';
 export { VerticalClient } from './vertical-client.js';
-export type { VerticalClientOptions, ProvisionInstanceInput, ProvisionedInstance, } from './vertical-client.js';
+export type { VerticalClientOptions, ProvisionInstanceInput, ProvisionedInstance, ConfigureInstanceInput, } from './vertical-client.js';
 export { assertSandboxContract, deployManifest, deploymentRefFor } from './deploy.js';
 export type { DeployVerticalFn, VerticalBundle, DeclaredBinding, DeployManifest } from './deploy.js';
 export { createWfpUploader } from './wfp.js';
 export type { WfpUploaderOptions } from './wfp.js';
+export type { ObservabilityReader, ServiceMetricsRow, RecentLogEvent } from './observability.js';
+export { createCfObservabilityReader } from './cf-observability.js';
+export type { CfObservabilityOptions } from './cf-observability.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtF,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrG,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACrG,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtF,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrG,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjG,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACpE,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,7 +1,9 @@
 export { createControlPlaneApi } from './api.js';
-export { DEV_ACTOR_HEADER, SERVICE_TOKEN_HEADER, UNSAFE_devPlatformActorAuth, sessionPlatformAuth, staffAllowlist, serviceTokenAuth, firstPlatformActorAuth, } from './auth.js';
+export { DEV_ACTOR_HEADER, SERVICE_TOKEN_HEADER, UNSAFE_devPlatformActorAuth, sessionPlatformAuth, staffAllowlist, serviceTokenAuth, firstPlatformActorAuth, firstBuilderAuth, } from './auth.js';
+export { mintPushToken, verifyPushToken, pushTokenBuilderAuth, pushActorFor } from './push-token.js';
 export { ControlPlaneClient, ControlPlaneError } from './client.js';
 export { VerticalClient } from './vertical-client.js';
 export { assertSandboxContract, deployManifest, deploymentRefFor } from './deploy.js';
 export { createWfpUploader } from './wfp.js';
+export { createCfObservabilityReader } from './cf-observability.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,WAAW,CAAC;AAUnB,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAMtD,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAUrG,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAOtD,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/mask.d.ts

@@ -0,0 +1,4 @@
+import type { ScopeDumpTable } from '@substrat-run/contracts';
+/** Mask one dump in place-shape (returns new arrays; never mutates the input). */
+export declare function maskDump(tables: ScopeDumpTable[]): ScopeDumpTable[];
+//# sourceMappingURL=mask.d.ts.map

package/dist/mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.d.ts","sourceRoot":"","sources":["../src/mask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAoD9D,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAqBnE"}

package/dist/mask.js

@@ -0,0 +1,71 @@
+/**
+ * The default masking pass over a scope dump (preview-and-snapshots.md §6/§8).
+ *
+ * A `scope pull` moves real customer data out of the governed environment, so the
+ * dump is masked BY DEFAULT and full fidelity is the explicit break-glass flag.
+ * This is the GENERIC sweep — §10's open question 2 answered for v1: a name-based
+ * column heuristic, with declarative per-vertical redaction rules as the later
+ * refinement. Two rules:
+ *
+ * 1. A string cell in a column whose name matches the PII heuristic is replaced
+ *    with `[masked]`. Non-strings (ids, counts, flags) pass through — the sweep
+ *    targets free text, and ids are what make the copy debuggable at all.
+ * 2. A string cell in a JSON-carrying column (`payload`, `detail`, `before`,
+ *    `after`, `data`) that parses as JSON is swept RECURSIVELY by key with the
+ *    same heuristic, then re-serialized — fat event payloads keep their shape
+ *    (consumers and timelines stay debuggable) while the PII fields inside them
+ *    are masked.
+ *
+ * Deliberately lossy and deliberately dumb: a heuristic sweep can miss a column
+ * named `x7`, which is why the pull is ALSO staff-gated, audited, and
+ * jurisdiction-checked — masking is one layer of §6's defense, not the gate.
+ */
+// Free-text/PII column names. `name` is included on purpose: entity names
+// (customers, properties, contacts) are customer data even when they look benign.
+const PII_COLUMN = /(^|_)(email|e?mail_address|phone|mobile|tel|address|street|city|postal|zip|ssn|personnummer|name|first_name|last_name|full_name|contact|note|notes|comment|comments|message|subject|body|description)($|_)/i;
+// Columns that carry JSON documents worth sweeping by key rather than blanking.
+const JSON_COLUMN = /(^|_)(payload|detail|details|data|before|after)($|_)/i;
+const MASKED = '[masked]';
+// Column names are snake_case but JSON payload keys are camelCase — normalize to
+// snake before testing so `customerEmail` matches the same heuristic as `email`.
+const matchesPii = (name) => PII_COLUMN.test(name.replace(/([a-z0-9])([A-Z])/g, '$1_$2'));
+function maskJsonValue(value, keyMatched) {
+    if (typeof value === 'string')
+        return keyMatched ? MASKED : value;
+    if (Array.isArray(value))
+        return value.map((v) => maskJsonValue(v, keyMatched));
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = maskJsonValue(v, keyMatched || matchesPii(k));
+        }
+        return out;
+    }
+    return value;
+}
+/** Mask one dump in place-shape (returns new arrays; never mutates the input). */
+export function maskDump(tables) {
+    return tables.map((t) => {
+        const piiCols = t.columns.map((c) => matchesPii(c));
+        const jsonCols = t.columns.map((c) => JSON_COLUMN.test(c));
+        if (!piiCols.some(Boolean) && !jsonCols.some(Boolean))
+            return t;
+        const rows = t.rows.map((row) => row.map((cell, i) => {
+            if (typeof cell !== 'string')
+                return cell;
+            if (piiCols[i])
+                return MASKED;
+            if (jsonCols[i]) {
+                try {
+                    return JSON.stringify(maskJsonValue(JSON.parse(cell), false));
+                }
+                catch {
+                    return cell; // not JSON — leave it; the column heuristic did not claim it
+                }
+            }
+            return cell;
+        }));
+        return { ...t, rows };
+    });
+}
+//# sourceMappingURL=mask.js.map

package/dist/mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.js","sourceRoot":"","sources":["../src/mask.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,0EAA0E;AAC1E,kFAAkF;AAClF,MAAM,UAAU,GAAG,6MAA6M,CAAC;AAEjO,gFAAgF;AAChF,MAAM,WAAW,GAAG,uDAAuD,CAAC;AAE5E,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B,iFAAiF;AACjF,iFAAiF;AACjF,MAAM,UAAU,GAAG,CAAC,IAAY,EAAW,EAAE,CAC3C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,CAAC;AAE/D,SAAS,aAAa,CAAC,KAAc,EAAE,UAAmB;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAChF,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,QAAQ,CAAC,MAAwB;IAC/C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACtB,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,CAAC,CAAC;QAChE,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAC9B,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YAClB,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC1C,IAAI,OAAO,CAAC,CAAC,CAAC;gBAAE,OAAO,MAAM,CAAC;YAC9B,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChB,IAAI,CAAC;oBACH,OAAO,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;gBAChE,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,IAAI,CAAC,CAAC,6DAA6D;gBAC5E,CAAC;YACH,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CACH,CAAC;QACF,OAAO,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/observability.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The observability read seam (design/observability.md §4.1) — what the console's
+ * fleet view and (later, owner-narrowed) the dashboard's builder view consume.
+ *
+ * This file is the CONTRACT, deliberately free of provider vocabulary: a "service"
+ * is a deployed unit of code (a Cloudflare worker script today, a container
+ * tomorrow), a "namespace" is whatever pool the platform runs pushed verticals in
+ * (a WfP dispatch namespace today). The same posture as `DeployVerticalFn` in
+ * `deploy.ts`: the seam lives here, each provider's implementation lives in its own
+ * module (`cf-observability.ts` for Cloudflare), and the host injects one — so an
+ * APM/OTel backend can slot in behind the identical routes later
+ * (master-plan §5.7, §6 "Convention + adapter") without touching this package's
+ * consumers. Absent ⇒ the observability routes 501, the platform's standard shape
+ * for an unconfigured capability.
+ */
+/** One service's invocation aggregates over the queried window. */
+export interface ServiceMetricsRow {
+    service: string;
+    /** The pushed-vertical pool the service runs in, or null for platform services. */
+    namespace: string | null;
+    requests: number;
+    errors: number;
+    subrequests: number;
+    /** Per-request CPU time quantiles, microseconds. */
+    cpuTimeP50: number;
+    cpuTimeP99: number;
+}
+export interface RecentLogEvent {
+    /** Unix ms, when the event was recorded. */
+    timestamp: number | null;
+    level: string | null;
+    message: string | null;
+    service: string | null;
+    /** How the invocation ended (e.g. `ok`, `exception`), provider-worded. */
+    outcome: string | null;
+    /** The event as the backend returned it — the fields above are a best-effort
+     *  projection, and the raw event is what makes a projection miss debuggable. */
+    raw: unknown;
+}
+export interface ObservabilityReader {
+    /** Per-service invocation metrics for the trailing window (fleet + builder views). */
+    serviceMetrics(input: {
+        hours: number;
+    }): Promise<ServiceMetricsRow[]>;
+    /** Recent log events, optionally narrowed to one service and/or level. */
+    recentLogs(input: {
+        service?: string;
+        level?: string;
+        hours: number;
+        limit: number;
+    }): Promise<RecentLogEvent[]>;
+}
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;oFACgF;IAChF,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,cAAc,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACvE,0EAA0E;IAC1E,UAAU,CAAC,KAAK,EAAE;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CAC/B"}

package/dist/observability.js

@@ -0,0 +1,17 @@
+/**
+ * The observability read seam (design/observability.md §4.1) — what the console's
+ * fleet view and (later, owner-narrowed) the dashboard's builder view consume.
+ *
+ * This file is the CONTRACT, deliberately free of provider vocabulary: a "service"
+ * is a deployed unit of code (a Cloudflare worker script today, a container
+ * tomorrow), a "namespace" is whatever pool the platform runs pushed verticals in
+ * (a WfP dispatch namespace today). The same posture as `DeployVerticalFn` in
+ * `deploy.ts`: the seam lives here, each provider's implementation lives in its own
+ * module (`cf-observability.ts` for Cloudflare), and the host injects one — so an
+ * APM/OTel backend can slot in behind the identical routes later
+ * (master-plan §5.7, §6 "Convention + adapter") without touching this package's
+ * consumers. Absent ⇒ the observability routes 501, the platform's standard shape
+ * for an unconfigured capability.
+ */
+export {};
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/push-token.d.ts

@@ -0,0 +1,33 @@
+import { type TenantId } from '@substrat-run/contracts';
+import { type BuilderAuth } from './auth.js';
+interface PushTokenClaim {
+    v: 1;
+    tenantId: string;
+    tenantSlug: string;
+    actor: string;
+    iat: number;
+}
+/**
+ * The audited subject for a tenant's CI pushes — deterministic from the tenant, so
+ * every push from that tenant's pipelines lands in the admin log under ONE nameable
+ * actor (the mirror of builder-auth's `builderActorFor`, which is per-human; CI is
+ * per-tenant because the pipeline, not a person, is what authenticated).
+ */
+export declare function pushActorFor(tenantId: TenantId): Promise<string>;
+/** Mint a push token for one tenant. `iat` is informational (no expiry in v1). */
+export declare function mintPushToken(secret: string, identity: {
+    actor: string;
+    tenantId: TenantId;
+    tenantSlug: string;
+}): Promise<string>;
+/** Verify a push token string → its claim, or null (bad prefix/shape/signature). */
+export declare function verifyPushToken(secret: string, token: string): Promise<PushTokenClaim | null>;
+/**
+ * A `BuilderAuth` over push tokens: reads `x-service-token`, handles only `spt1.…`
+ * values (anything else → null, falling through to the other readers), verifies, and
+ * returns the builder principal the token carries. Compose with the OIDC reader via
+ * `firstBuilderAuth`.
+ */
+export declare function pushTokenBuilderAuth(secret: string): BuilderAuth;
+export {};
+//# sourceMappingURL=push-token.d.ts.map

package/dist/push-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-token.d.ts","sourceRoot":"","sources":["../src/push-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+C,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACrG,OAAO,EAAwB,KAAK,WAAW,EAAwB,MAAM,WAAW,CAAC;AA6BzF,UAAU,cAAc;IACtB,CAAC,EAAE,CAAC,CAAC;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAgBD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAOtE;AAED,kFAAkF;AAClF,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAClE,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED,oFAAoF;AACpF,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA4BnG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAYhE"}

package/dist/push-token.js

@@ -0,0 +1,114 @@
+import { platformActorId, tenantId as tenantIdSchema } from '@substrat-run/contracts';
+import { SERVICE_TOKEN_HEADER } from './auth.js';
+/**
+ * Tenant-scoped push tokens — the CI credential the builder plane was missing.
+ *
+ * A builder's OIDC session (builder-auth in the worker) is per-human and short-lived;
+ * the platform `SERVICE_TOKEN` is staff-equivalent and must never land in a customer
+ * repo. A push token sits between: a long-lived MACHINE credential that authenticates
+ * as a **builder principal** for ONE tenant — so it reaches only the builder-allowlisted
+ * routes, only that tenant's `<tenantSlug>/…` namespace, and never prod promotion or
+ * admission (those checks live in api.ts and apply to every builder alike).
+ *
+ * Format: `spt1.<b64url payload>.<b64url HMAC-SHA256 sig>` — stateless, verified
+ * against a dedicated `pushTokenSecret`. Deliberately NOT the platform secrets:
+ * PLATFORM_SECRET is injected into every pushed vertical (a vertical holding the
+ * push-token signing key could forge tokens for any tenant), and deriving from
+ * SERVICE_TOKEN would tie CI-credential rotation to service-token rotation. Rotating
+ * the dedicated secret invalidates every issued push token (customers reconnect) —
+ * that is the whole revocation story in v1, so treat it as set-once like the
+ * dashboard's SECRET_BOX_KEY and keep it out of routine rotation.
+ *
+ * The token is presented in the SAME header the CLI already sends its credential in
+ * (`x-service-token`, via `SUBSTRAT_SERVICE_TOKEN`), discriminated by the `spt1.`
+ * prefix — a random-hex service token can never collide with it, and the CLI and the
+ * generated CI workflow need no changes at all.
+ */
+const PREFIX = 'spt1';
+const enc = new TextEncoder();
+const b64url = (bytes) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+const b64urlToBytes = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
+async function hmacKey(secret, usage) {
+    return crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, [usage]);
+}
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * The audited subject for a tenant's CI pushes — deterministic from the tenant, so
+ * every push from that tenant's pipelines lands in the admin log under ONE nameable
+ * actor (the mirror of builder-auth's `builderActorFor`, which is per-human; CI is
+ * per-tenant because the pipeline, not a person, is what authenticated).
+ */
+export async function pushActorFor(tenantId) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', enc.encode(`push-token:${tenantId}`)));
+    let s = '';
+    for (let i = 0; i < 26; i++)
+        s += CROCKFORD[digest[i] % 32];
+    return platformActorId.parse(s);
+}
+/** Mint a push token for one tenant. `iat` is informational (no expiry in v1). */
+export async function mintPushToken(secret, identity) {
+    const claim = {
+        v: 1,
+        tenantId: identity.tenantId,
+        tenantSlug: identity.tenantSlug,
+        actor: identity.actor,
+        iat: Date.now(),
+    };
+    const payload = b64url(enc.encode(JSON.stringify(claim)));
+    const signingInput = `${PREFIX}.${payload}`;
+    const sig = new Uint8Array(await crypto.subtle.sign('HMAC', await hmacKey(secret, 'sign'), enc.encode(signingInput)));
+    return `${signingInput}.${b64url(sig)}`;
+}
+/** Verify a push token string → its claim, or null (bad prefix/shape/signature). */
+export async function verifyPushToken(secret, token) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || parts[0] !== PREFIX)
+        return null;
+    const [, payload, sig] = parts;
+    let ok = false;
+    try {
+        ok = await crypto.subtle.verify('HMAC', await hmacKey(secret, 'verify'), b64urlToBytes(sig), enc.encode(`${PREFIX}.${payload}`));
+    }
+    catch {
+        return null;
+    }
+    if (!ok)
+        return null;
+    try {
+        const claim = JSON.parse(new TextDecoder().decode(b64urlToBytes(payload)));
+        if (claim.v !== 1)
+            return null;
+        // Parse, don't trust — the signature proves WE minted it, the parse proves the
+        // fields still are what a BuilderIdentity needs (a future format bump fails closed).
+        tenantIdSchema.parse(claim.tenantId);
+        platformActorId.parse(claim.actor);
+        if (typeof claim.tenantSlug !== 'string' || !claim.tenantSlug)
+            return null;
+        return claim;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A `BuilderAuth` over push tokens: reads `x-service-token`, handles only `spt1.…`
+ * values (anything else → null, falling through to the other readers), verifies, and
+ * returns the builder principal the token carries. Compose with the OIDC reader via
+ * `firstBuilderAuth`.
+ */
+export function pushTokenBuilderAuth(secret) {
+    return async (request) => {
+        const presented = request.headers.get(SERVICE_TOKEN_HEADER);
+        if (!presented || !presented.startsWith(`${PREFIX}.`))
+            return null;
+        const claim = await verifyPushToken(secret, presented);
+        if (!claim)
+            return null;
+        return {
+            actor: platformActorId.parse(claim.actor),
+            tenantId: tenantIdSchema.parse(claim.tenantId),
+            tenantSlug: claim.tenantSlug,
+        };
+    };
+}
+//# sourceMappingURL=push-token.js.map

package/dist/push-token.js.map

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

package/dist/vertical-client.d.ts

@@ -1,4 +1,4 @@
-import type { PrincipalId, ReadScopeTableInput, ScopeId, ScopeTable, ScopeTablePage, TenantId } from '@substrat-run/contracts';
+import type { PrincipalId, QueryScopeInput, ReadScopeTableInput, ScopeDumpTable, ScopeId, ScopeQueryResult, ScopeTable, ScopeTablePage, TenantId } from '@substrat-run/contracts';
 /**
  * The platform's client for calling a VERTICAL (K-31).
  *
@@ -8,10 +8,16 @@ import type { PrincipalId, ReadScopeTableInput, ScopeId, ScopeTable, ScopeTableP
  * because only the vertical can create a usable scope DO — the DO class bundles the
  * modules and lives in the vertical's own deployment.
  *
- * Deliberately tiny. The platform asks a vertical to do two kinds of thing: create an
- * instance (K-31), and — read-only — introspect a scope's own database (§5.4), because
- * the scope's data DO lives in the vertical's deployment, not the platform's. Every
- * other verb would be authority the platform holds over someone else's code.
+ * Deliberately tiny. The platform asks a vertical to do three kinds of thing: create an
+ * instance (K-31); — read-only — introspect a scope's own database (§5.4), because the
+ * scope's data DO lives in the vertical's deployment, not the platform's; and manage
+ * scope-STORAGE lifecycle — snapshot a scope into a sibling, wipe a reaped fork
+ * (preview-and-snapshots.md §9, the ratified trust line: infrastructure verbs over the
+ * DO's storage, extending the authority provisionInstance already asserts). Every other
+ * verb — anything that reads or writes DOMAIN data — would be authority the platform
+ * holds over someone else's code. Note the lifecycle verbs move no data across the
+ * boundary: a snapshot copies between two DOs inside the vertical's own deployment and
+ * returns only a table count.
  */
 export interface VerticalClientOptions {
     /**
@@ -32,6 +38,24 @@ export interface ProvisionInstanceInput {
     owner: PrincipalId;
     slug: string;
     name: string;
+    /**
+     * Per-instance config delivered WITH provisioning, so a new app arrives configured
+     * atomically — no window where the instance is live but unconfigured (an issuer with
+     * no admin, an app with no auth). Same entries `configureInstance` upserts later; a
+     * vertical that predates the field ignores it (its body parse strips unknown keys).
+     */
+    config?: Record<string, string>;
+}
+export interface ConfigureInstanceInput {
+    /** The scope's tenant — CP-less verticals shard identity/config storage per tenant
+     *  (e.g. Meridian's IdentityDO is addressed by tenant id), so the address rides along. */
+    tenantId: TenantId;
+    scopeId: ScopeId;
+    /** Upserts, key by key — never a full replace, so partial writes compose. */
+    entries: Array<{
+        key: string;
+        value: string;
+    }>;
 }
 export interface ProvisionedInstance {
     tenantId: TenantId;
@@ -49,6 +73,15 @@ export declare class VerticalClient {
      * phase of a two-phase creation and the reconciliation sweep re-runs exactly it.
      */
     provisionInstance(input: ProvisionInstanceInput): Promise<ProvisionedInstance>;
+    /**
+     * Deliver per-instance CONFIG to the scope's own storage (vertical-auth-detach.md
+     * §2.2) — the write half of the dashboard's Env tab, and the same trust line as
+     * provisionInstance: the platform names a scope inside the vertical's deployment and
+     * hands it settings; the vertical owns what they mean. Idempotent upserts, so the
+     * reconciliation sweep can re-run it. A vertical that has no live-config support
+     * answers 501, which the caller may treat as "authored but not delivered".
+     */
+    configureInstance(input: ConfigureInstanceInput): Promise<void>;
     /**
      * Read the scope's OWN database tables (kernel-design §5.4 admin-query RPC).
      *
@@ -60,6 +93,44 @@ export declare class VerticalClient {
     listScopeTables(scopeId: ScopeId): Promise<ScopeTable[]>;
     /** A bounded page of one of the scope's tables. */
     readScopeTable(scopeId: ScopeId, input: ReadScopeTableInput): Promise<ScopeTablePage>;
+    /**
+     * One read-only SQL statement against the scope's DB — the console (#219). The
+     * vertical enforces read-only-ness in its own deployment (the kernel gate + the
+     * DO's rolled-back transaction); a vertical that cannot answer safely (e.g. one
+     * that redacts secret columns on table reads) refuses with its own status, which
+     * the ControlPlaneError relays verbatim.
+     */
+    queryScope(scopeId: ScopeId, input: QueryScopeInput): Promise<ScopeQueryResult>;
+    /**
+     * Copy one scope's data into a fresh sibling scope DO, inside the vertical's own
+     * deployment (§9's data half). The platform names source and destination; the bytes
+     * never cross the boundary — the response is a table count, not a dump. The
+     * directory half (provenance row, activation, version bind) is the caller's job.
+     */
+    snapshotScope(input: {
+        sourceScopeId: ScopeId;
+        newScopeId: ScopeId;
+    }): Promise<{
+        tables: number;
+    }>;
+    /**
+     * Wipe a reaped fork's storage (§9's reap half). The platform calls this before
+     * deleting the directory row — same storage-before-row ordering as the in-process
+     * deleteSnapshot, so a crash between the two converges on retry. The fork-only
+     * refusal lives with the directory record, on the platform's side.
+     */
+    deleteScope(input: {
+        scopeId: ScopeId;
+    }): Promise<void>;
+    /**
+     * The scope's full dump — the ONE verb here that deliberately moves scope bytes
+     * across the boundary, for the governed `scope pull` (§8). The control-plane route
+     * in front of it is the gate: staff-only, audited, masked by default, jurisdiction-
+     * checked. Everything else on this surface stays byte-free by design.
+     */
+    exportScope(scopeId: ScopeId): Promise<ScopeDumpTable[]>;
+    /** A platform-authenticated POST to the vertical's `/internal/*` surface. */
+    private postInternal;
     /** A platform-authenticated GET to the vertical's `/internal/*` surface. */
     private getInternal;
 }

package/dist/vertical-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vertical-client.d.ts","sourceRoot":"","sources":["../src/vertical-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACnB,OAAO,EACP,UAAU,EACV,cAAc,EACd,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,qBAAqB,EAAI;IAE/D;;;;;;OAMG;IACG,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqBnF;IAED;;;;;;;OAOG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAE7D;IAED,mDAAmD;IAC7C,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAS1F;IAED,4EAA4E;YAC9D,WAAW;CAc1B"}
+{"version":3,"file":"vertical-client.d.ts","sourceRoot":"","sources":["../src/vertical-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,OAAO,EACP,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC;8FAC0F;IAC1F,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,qBAAqB,EAAI;IAE/D;;;;;;OAMG;IACG,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqBnF;IAED;;;;;;;OAOG;IACG,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpE;IAED;;;;;;;OAOG;IACG,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAE7D;IAED,mDAAmD;IAC7C,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAS1F;IAED;;;;;;OAMG;IACG,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEpF;IAED;;;;;OAKG;IACG,aAAa,CAAC,KAAK,EAAE;QACzB,aAAa,EAAE,OAAO,CAAC;QACvB,UAAU,EAAE,OAAO,CAAC;KACrB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAE9B;IAED;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;IAED;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAI7D;IAED,6EAA6E;YAC/D,YAAY;IAoB1B,4EAA4E;YAC9D,WAAW;CAc1B"}

package/dist/vertical-client.js

@@ -30,6 +30,17 @@ export class VerticalClient {
         }
         return (await res.json());
     }
+    /**
+     * Deliver per-instance CONFIG to the scope's own storage (vertical-auth-detach.md
+     * §2.2) — the write half of the dashboard's Env tab, and the same trust line as
+     * provisionInstance: the platform names a scope inside the vertical's deployment and
+     * hands it settings; the vertical owns what they mean. Idempotent upserts, so the
+     * reconciliation sweep can re-run it. A vertical that has no live-config support
+     * answers 501, which the caller may treat as "authored but not delivered".
+     */
+    async configureInstance(input) {
+        await this.postInternal('/internal/configure', input, 'configure');
+    }
     /**
      * Read the scope's OWN database tables (kernel-design §5.4 admin-query RPC).
      *
@@ -50,6 +61,60 @@ export class VerticalClient {
         });
         return this.getInternal(`/internal/tables/${encodeURIComponent(input.table)}?${q}`);
     }
+    /**
+     * One read-only SQL statement against the scope's DB — the console (#219). The
+     * vertical enforces read-only-ness in its own deployment (the kernel gate + the
+     * DO's rolled-back transaction); a vertical that cannot answer safely (e.g. one
+     * that redacts secret columns on table reads) refuses with its own status, which
+     * the ControlPlaneError relays verbatim.
+     */
+    async queryScope(scopeId, input) {
+        return this.postInternal('/internal/query', { scopeId, sql: input.sql }, 'query');
+    }
+    /**
+     * Copy one scope's data into a fresh sibling scope DO, inside the vertical's own
+     * deployment (§9's data half). The platform names source and destination; the bytes
+     * never cross the boundary — the response is a table count, not a dump. The
+     * directory half (provenance row, activation, version bind) is the caller's job.
+     */
+    async snapshotScope(input) {
+        return this.postInternal('/internal/snapshot', input, 'snapshot');
+    }
+    /**
+     * Wipe a reaped fork's storage (§9's reap half). The platform calls this before
+     * deleting the directory row — same storage-before-row ordering as the in-process
+     * deleteSnapshot, so a crash between the two converges on retry. The fork-only
+     * refusal lives with the directory record, on the platform's side.
+     */
+    async deleteScope(input) {
+        await this.postInternal('/internal/delete-scope', input, 'delete-scope');
+    }
+    /**
+     * The scope's full dump — the ONE verb here that deliberately moves scope bytes
+     * across the boundary, for the governed `scope pull` (§8). The control-plane route
+     * in front of it is the gate: staff-only, audited, masked by default, jurisdiction-
+     * checked. Everything else on this surface stays byte-free by design.
+     */
+    async exportScope(scopeId) {
+        return this.getInternal(`/internal/export?scopeId=${encodeURIComponent(scopeId)}`);
+    }
+    /** A platform-authenticated POST to the vertical's `/internal/*` surface. */
+    async postInternal(path, body, verb) {
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        const res = await this.options.fetch(`${base}${path}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                [PLATFORM_SECRET_HEADER]: this.options.platformSecret,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const parsed = (await res.json().catch(() => null));
+            throw new ControlPlaneError(res.status, parsed?.error ?? `vertical refused ${verb}: ${res.status} ${res.statusText}`);
+        }
+        return (await res.json());
+    }
     /** A platform-authenticated GET to the vertical's `/internal/*` surface. */
     async getInternal(path) {
         const base = this.options.baseUrl ?? 'https://vertical.invalid';