@growthub/cli 0.14.4 → 0.14.5

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/data-model/components/OrchestrationGraphEmptyCanvas.jsx

@@ -16,7 +16,7 @@ export function OrchestrationGraphEmptyCanvas({
     <div className="dm-orchestration-canvas dm-orchestration-canvas--empty-state" aria-label="Empty orchestration graph">
       <div className="dm-orchestration-canvas__empty-card">
         <h3>Start orchestration graph</h3>
-        <p>Create a governed run plan for this sandbox tool. Nothing executes until Run sandbox.</p>
+        <p>Create a governed workflow plan. Nothing executes until you run the workflow.</p>
         <div className="dm-orchestration-canvas__empty-actions">
           <button type="button" className="dm-btn-primary-sm" disabled={disabled} onClick={onStartFromRegistry}>
             Start from API Registry

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/data-model/components/OrchestrationRunTracePanel.jsx

@@ -531,7 +531,7 @@ export function OrchestrationRunTracePanel({
             Runs <span aria-hidden="true">/</span> <code>{activeConsoleRecord?.runId || "preview"}</code>
           </span>
           <h2>Run console</h2>
-          <p>{summaryText} · {row?.Name || "Sandbox tool"}</p>
+          <p>{summaryText} · {row?.Name || "Workflow"}</p>
         </div>
         <div className="dm-run-console__head-actions">
           {canReplay && (

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/data-model/components/SandboxOrchestrationEditorPanel.jsx

@@ -131,7 +131,7 @@ export function SandboxOrchestrationEditorPanel({
         </button>
         <div className="dm-orchestration-header__titles">
           <h2>Orchestration graph</h2>
-          <p>{sandboxRow?.Name || "Sandbox tool"}</p>
+          <p>{sandboxRow?.Name || "Workflow"}</p>
         </div>
       </header>
 

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/globals.css

@@ -5046,6 +5046,9 @@ body.workspace-rail-collapsed .workspace-builder.dm-workflow-page {
 }
 .dm-api-action-card-success { grid-template-columns: 1fr auto; }
 .dm-api-action-card-muted { grid-template-columns: 1fr; background: #fafafa; }
+.dm-api-action-card-workflow { grid-template-columns: 1fr; }
+.dm-api-action-card-workflow .dm-api-action-card-actions { align-items: flex-start; }
+.dm-api-action-card-workflow .dm-api-action-card-cta { align-self: flex-start; }
 .dm-api-action-card-note { font-size: 11px; color: #6b7280; margin-top: 4px; }
 .dm-api-action-checklist { margin: 8px 0 0; padding: 0; list-style: none; display: grid; gap: 6px; }
 .dm-api-action-checklist li { display: flex; align-items: center; gap: 8px; font-size: 12px; color: #374151; }

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/api-registry-creation-flow.js

@@ -6,13 +6,13 @@
  * row being edited, the source-records sidecar, and the safe runtime signal, it
  * resolves the full operator journey for THIS API as an ordered list of steps:
  *
- *   register → configure auth → test → (resolver) → sandbox tool → data source
- *   → refresh records
+ *   register → configure auth → test → (resolver) → data source → refresh
+ *   records, then a separate workflow canvas CTA after activation.
  *
  * Each step carries a status (complete | active | pending | blocked | optional),
  * a human description, and — when the operator can act — an `action` descriptor
  * the drawer maps to an existing handler (test / create-data-source /
- * create-sandbox-tool / open-data-source / refresh-source). The cockpit renders
+ * open-data-source / refresh-source / create-workflow-canvas). The cockpit renders
  * this verbatim, so the journey is one derivation, not UI guesswork.
  *
  * Invariants:
@@ -78,14 +78,18 @@ function sandboxRowsForIntegration(workspaceConfig, integrationId) {
   const rows = [];
   for (const object of findObjectsByType(workspaceConfig, "sandbox-environment")) {
     for (const row of Array.isArray(object.rows) ? object.rows : []) {
-      const envRefs = clean(row?.envRefs);
       const schedulerId = clean(row?.schedulerRegistryId);
-      const cfg = parseMaybeJson(row?.orchestrationConfig);
+      const cfg = parseMaybeJson(
+        row?.orchestrationConfig
+          || row?.orchestrationGraph
+          || row?.orchestrationDraftConfig
+          || row?.orchestrationDraftGraph
+      );
       const callsApi = Array.isArray(cfg?.nodes) && cfg.nodes.some(
         (n) => n?.type === "api-registry-call"
           && clean(n?.config?.registryId || n?.config?.integrationId) === id,
       );
-      if (callsApi || schedulerId === id || envRefs.split(",").map(clean).includes(clean(row?.authRef))) {
+      if (callsApi || schedulerId === id) {
         rows.push(row);
       }
     }
@@ -213,8 +217,11 @@ function deriveApiRegistryCreationState(input = {}) {
     status: resolverWired ? "complete" : (tested ? "optional" : "blocked"),
     description: resolverWired
       ? `Resolver "${resolverTemplate}" shapes the response into rows.`
-      : "Optional: add a resolver to normalize the response into governed rows. Raw passthrough works without one.",
-    action: tested && !resolverWired ? { id: "open-resolver", label: "Add resolver", href: "/api/workspace/resolver-templates" } : null,
+      : "Optional: construct a resolver to normalize the response into governed rows. Raw passthrough works without one.",
+    // CMS SDK v1.5.1 — the action constructs the governed resolver from the
+    // tested response shape (no blank form). The cockpit stages it for one-screen
+    // review, applies through the governed lane, and re-tests.
+    action: tested && !resolverWired ? { id: "construct-resolver", label: "Construct resolver" } : null,
   });
 
   step({
@@ -245,17 +252,6 @@ function deriveApiRegistryCreationState(input = {}) {
       : null,
   });
 
-  // Optional automation lane — a sandbox/workflow that calls this API.
-  step({
-    id: "sandbox-tool",
-    label: "Automate (sandbox tool)",
-    status: sandboxExists ? "complete" : (tested ? "optional" : "blocked"),
-    description: sandboxExists
-      ? "A sandbox tool calls this API."
-      : "Optional: wrap this API in a sandbox/workflow you can run or schedule.",
-    action: tested && !sandboxExists ? { id: "create-sandbox-tool", label: "Create sandbox tool" } : null,
-  });
-
   for (const s of steps) { if (!s.hint) delete s.hint; }
 
   const required = steps.filter((s) => s.status !== "optional");
@@ -297,6 +293,15 @@ function deriveApiRegistryCreationState(input = {}) {
     score,
     nextStepId: nextStep ? nextStep.id : null,
     nextAction: nextStep && nextStep.action ? { stepId: nextStep.id, ...nextStep.action } : null,
+    workflowAction: tested
+      ? {
+          id: sandboxExists ? "open-workflow-canvas" : "create-workflow-canvas",
+          label: sandboxExists ? "Open workflow canvas" : "Create workflow",
+          description: sandboxExists
+            ? "Open the workflow canvas that uses this API Registry node."
+            : "Open a workflow canvas with this API Registry call already drafted.",
+        }
+      : null,
     headline: !registered
       ? "Register this API to begin."
       : complete

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/orchestration-graph.js

@@ -28,7 +28,7 @@ const KNOWN_NODE_TYPES = new Set([
 
 const API_REGISTRY_SETUP_FIELDS = ["integrationId", "baseUrl", "endpoint", "method", "authRef"];
 
-const CANONICAL_NODE_ORDER = ["input", "api-request", "transform", "result"];
+const CANONICAL_NODE_ORDER = ["human-input", "input", "api-request", "transform", "result"];
 
 function slugifyName(value) {
   return String(value || "")
@@ -91,34 +91,6 @@ function isApiRegistrySetupComplete(registryRow) {
   return getApiRegistrySetupChecklist(registryRow).every((item) => item.ok);
 }
 
-/**
- * Sidecar action state for API Registry → sandbox tool bridge (UI only).
- */
-function getApiRegistrySandboxToolState(registryRow, workspaceConfig) {
-  if (!isApiRegistrySetupComplete(registryRow)) {
-    return { kind: "incomplete", checklist: getApiRegistrySetupChecklist(registryRow) };
-  }
-  if (!isApiRegistryTestSuccessful(registryRow)) {
-    const status = String(registryRow?.status || "").trim().toLowerCase();
-    if (status === "failed") {
-      return {
-        kind: "failed",
-        message: "Connection test failed. Fix the endpoint or auth reference, then test again."
-      };
-    }
-    return {
-      kind: "untested",
-      message: "Test connection first. Sandbox tool creation unlocks after a successful test."
-    };
-  }
-  const integrationId = String(registryRow?.integrationId || "").trim();
-  const existing = findSandboxRowsForRegistry(workspaceConfig, integrationId);
-  if (existing.length > 0) {
-    return { kind: "existing", row: existing[0] };
-  }
-  return { kind: "create" };
-}
-
 function validateOrchestrationGraph(graph) {
   const errors = [];
   if (!graph || typeof graph !== "object") {
@@ -306,7 +278,12 @@ function findSandboxRowsForRegistry(workspaceConfig, integrationId) {
   if (!sandboxObject) return [];
   const rows = Array.isArray(sandboxObject.rows) ? sandboxObject.rows : [];
   return rows.filter((row) => {
-    const graph = parseOrchestrationGraph(row?.orchestrationConfig || row?.orchestrationGraph);
+    const graph = parseOrchestrationGraph(
+      row?.orchestrationConfig
+        || row?.orchestrationGraph
+        || row?.orchestrationDraftConfig
+        || row?.orchestrationDraftGraph
+    );
     if (!graph?.nodes) return String(row?.schedulerRegistryId || "").trim() === id;
     return graph.nodes.some(
       (node) => node?.type === "api-registry-call"
@@ -315,56 +292,6 @@ function findSandboxRowsForRegistry(workspaceConfig, integrationId) {
   });
 }
 
-function buildSandboxRowFromApiRegistry(workspaceConfig, registryRow, options = {}) {
-  const integrationId = String(registryRow?.integrationId || "").trim();
-  const baseName = String(options.name || registryRow?.Name || integrationId || "Sandbox Tool").trim();
-  const name = baseName.endsWith(" Tool") ? baseName : `${baseName} Tool`;
-  const runLocality = String(options.runLocality || "local").trim() === "serverless" ? "serverless" : "local";
-  const adapter = String(options.adapter || (runLocality === "serverless" ? "serverless" : "local-process")).trim();
-  const graph = options.orchestrationGraph
-    ? (typeof options.orchestrationGraph === "string"
-      ? parseOrchestrationGraph(options.orchestrationGraph)
-      : options.orchestrationGraph)
-    : buildDefaultOrchestrationGraphFromRegistry(registryRow, options);
-
-  const apiNode = graph?.nodes?.find((n) => n?.type === "api-registry-call");
-  const authRef = String(options.authRef || apiNode?.config?.authRef || registryRow?.authRef || integrationId).trim();
-  const transformNode = graph?.nodes?.find((n) => n?.type === "transform-filter" || n?.type === "normalize-output");
-  const rootPath = transformNode?.config?.rootPath || "data";
-  const method = String(registryRow?.method || apiNode?.config?.method || "GET").trim().toUpperCase();
-  const endpoint = String(registryRow?.endpoint || apiNode?.config?.endpoint || "").trim();
-  const baseUrl = String(registryRow?.baseUrl || apiNode?.config?.baseUrl || "").trim();
-
-  return {
-    Name: name,
-    slug: options.slug || slugifyName(name) || slugifyName(integrationId),
-    objectType: "sandbox-environment",
-    lifecycleStatus: "draft",
-    version: "1",
-    runLocality,
-    schedulerRegistryId: runLocality === "serverless" ? integrationId : "",
-    runtime: String(options.runtime || "node").trim(),
-    adapter,
-    agentHost: String(options.agentHost || "").trim(),
-    envRefs: Array.isArray(options.envRefs) ? options.envRefs.join(",") : String(options.envRefs || "").trim(),
-    networkAllow: options.networkAllow === true ? "true" : "",
-    allowList: String(options.allowList || "").trim(),
-    instructions: String(
-      options.instructions
-        || `Governed sandbox tool for ${integrationId}. Calls ${method} ${endpoint || baseUrl} and normalizes at "${rootPath}". authRef ${authRef} only — secrets resolve server-side.`
-    ).trim(),
-    command: String(options.command || "").trim(),
-    timeoutMs: String(options.timeoutMs || "30000").trim(),
-    status: "untested",
-    lastTested: "",
-    lastRunId: "",
-    lastSourceId: "",
-    lastResponse: "",
-    orchestrationConfig: serializeOrchestrationGraph(graph),
-    description: String(options.description || registryRow?.description || "").trim()
-  };
-}
-
 /**
  * Find existing data-source rows that already resolve through a given API
  * Registry integration (by `registryId`). Mirrors findSandboxRowsForRegistry so
@@ -986,7 +913,6 @@ export {
   getOrchestrationGraphUiState,
   getNextCanonicalNodeId,
   addCanonicalNodeToGraph,
-  buildSandboxRowFromApiRegistry,
   buildDataSourceRowFromApiRegistry,
   findDataSourceRowsForRegistry,
   extractApiRegistryCallNode,
@@ -996,7 +922,6 @@ export {
   findSandboxObject,
   findSandboxRowsForRegistry,
   getApiRegistrySetupChecklist,
-  getApiRegistrySandboxToolState,
   isApiRegistrySetupComplete,
   isApiRegistryTestSuccessful,
   normalizeJsonAtPath,

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/resolver-constructor.js

@@ -0,0 +1,217 @@
+/**
+ * Resolver Constructor V1 (CMS SDK v1.5.1) — closes the no-code "too many open
+ * fields" gap. Instead of asking a non-technical user to hand-author a
+ * resolver's rootPath / idField / entityType / auth header, this constructs the
+ * governed resolver from facts ALREADY computed: the tested response profile
+ * (`profileApiResponse`) and the resolver recommendation (`recommendResolver`),
+ * plus the row's own auth config (mirrored from how test-api-record sent it, so
+ * the resolver behaves exactly like the test that just passed).
+ *
+ * Agnostic across the normalized governance taxonomy (http | custom | tool | mcp
+ * | chrome | nango), via a single builder dispatch (`getResolverBuilder`), the
+ * Nango precedent generalized:
+ *   - HTTP-shaped kinds (http / custom / and any non-reserved value, including a
+ *     literal "webhook" an operator may type) materialize a server file built
+ *     from the response shape;
+ *   - nango is config-driven (no file) with honest readiness;
+ *   - reserved kinds (mcp | chrome | tool) cannot be auto-constructed from an
+ *     HTTP response — advertised truthfully with a concrete next action, never
+ *     left blank or mislabeled.
+ *
+ * `connectorKind` is operator-editable text and is honored verbatim — it is
+ * never silently normalized.
+ *
+ * Pure: no fetch, no secrets, never throws. The returned `proposal` (file mode)
+ * flows ONLY through the governed apply lane (helper/apply → writeResolverProposalFile)
+ * and the no-code cockpit — never a hand edit.
+ */
+
+import { buildResolverProposal } from "./workspace-resolver-proposal.js";
+import { slugifyIntegrationId, RESOLVER_ENDPOINT_BASE } from "./unified-resolver-registry.js";
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+/** The canonical governed endpoint a row will be exposed at once registered. */
+function endpointFor(integrationId) {
+  const slug = slugifyIntegrationId(integrationId, "");
+  return slug ? `${RESOLVER_ENDPOINT_BASE}/${slug}` : null;
+}
+
+/**
+ * A plain-language "what the system detected" summary + a confidence band, so the
+ * review panel can SHOW understanding ("I found 42 records under data.items…")
+ * instead of a developer form. Pure; derived from the tested response profile.
+ *   high   — top-level/clean records: direct apply is safe.
+ *   medium — records nested under a container: review the mapping, then apply.
+ *   low    — pagination or no record array: needs human review before trust.
+ */
+function detectShape(profile, recommendation) {
+  if (!profile || !profile.parsed) return null;
+  const level = clean(recommendation?.level);
+  let confidence = "high";
+  if (profile.hasPagination || !profile.usable) confidence = "low";
+  else if (level === "recommended") confidence = "medium";
+  else if (level === "required") confidence = "low";
+  const recordPath = clean(profile.arrayPath);
+  const entityType = clean(profile.suggestedEntityType) || "records";
+  const idField = clean(profile.candidates?.id) || "id";
+  return {
+    confidence,
+    recordCount: Number.isFinite(profile.recordCount) ? profile.recordCount : 0,
+    recordPath,
+    idField,
+    entityType,
+    hasPagination: Boolean(profile.hasPagination),
+    // One human sentence the panel can show verbatim.
+    sentence: profile.usable
+      ? `Found ${profile.recordCount} ${entityType}${recordPath ? ` under "${recordPath}"` : " (top-level)"}, keyed by "${idField}"${profile.hasPagination ? " — paginated, so a resolver is required to fetch every page" : ""}.`
+      : "No record array detected — review the response before activating.",
+  };
+}
+
+/**
+ * The auth header/prefix the resolver must send — mirrored from how
+ * test-api-record built its request (authHeaderName || authHeader || x-api-key;
+ * authPrefix), so a constructed resolver matches the test that just succeeded.
+ */
+function deriveAuthHeader(row) {
+  const headerName = clean(row?.authHeaderName) || clean(row?.authHeader) || "x-api-key";
+  const prefix = clean(row?.authPrefix);
+  return { headerName, prefix };
+}
+
+function constructCustomHttpProposal({ row, profile, recommendation, recordRef }) {
+  const { headerName, prefix } = deriveAuthHeader(row);
+  const rootPath = clean(profile?.arrayPath) || clean(recommendation?.rootPath);
+  const idField = clean(profile?.candidates?.id) || "id";
+  const entityType = clean(profile?.suggestedEntityType) || clean(row?.entityTypes) || "records";
+
+  const blanks = [];
+  if (!clean(row?.integrationId)) blanks.push("integrationId");
+  if (!clean(row?.baseUrl) && !clean(row?.endpoint)) blanks.push("target (baseUrl or endpoint)");
+
+  const proposal = buildResolverProposal({
+    integrationId: row?.integrationId,
+    baseUrl: row?.baseUrl,
+    endpoint: row?.endpoint,
+    method: row?.method,
+    authRef: row?.authRef,
+    headerName,
+    prefix,
+    rootPath,
+    idField,
+    entityType,
+    recordRef,
+  });
+
+  const detected = detectShape(profile, recommendation);
+  // Respect the row's declared governance kind (http / custom / webhook / …);
+  // default to http when unset. Only the resolver IMPLEMENTATION is HTTP here.
+  const declaredKind = clean(row?.connectorKind).toLowerCase() || "http";
+  return {
+    ok: blanks.length === 0,
+    mode: "file",
+    connectorKind: declaredKind,
+    endpoint: endpointFor(row?.integrationId),
+    proposal,
+    prefill: { rootPath, idField, entityType, headerName, prefix },
+    detected,
+    confidence: detected ? detected.confidence : "low",
+    authRef: clean(row?.authRef),
+    blanks,
+    reason: blanks.length
+      ? `Fill ${blanks.join(", ")} on the row before constructing a resolver.`
+      : (recommendation?.reason || "Resolver constructed from the tested response shape."),
+  };
+}
+
+/**
+ * Honest readiness for a config-driven (Nango) row. A resolver registers from
+ * the row automatically — but only if the row actually carries the minimum
+ * binding. We never report "nothing to apply / done" when the endpoint would not
+ * be usable; missing config returns an actionable next step instead.
+ */
+function constructNangoReadiness({ row }) {
+  const blanks = [];
+  const providerKey = clean(row?.providerConfigKey) || clean(row?.integrationId);
+  if (!providerKey) blanks.push("providerConfigKey (or integrationId)");
+  const hasConnection =
+    clean(row?.connectionIds) || clean(row?.connectionId) || clean(row?.nangoConnectionId);
+  if (!hasConnection) blanks.push("connectionIds");
+  if (!clean(row?.endpoint)) blanks.push("endpoint (Nango proxy path)");
+  const ready = blanks.length === 0;
+  return {
+    ok: ready,
+    mode: "config-driven",
+    connectorKind: "nango",
+    endpoint: endpointFor(row?.integrationId),
+    proposal: null,
+    prefill: null,
+    detected: null,
+    blanks,
+    state: ready ? "config-driven-ready" : "config-driven-missing-config",
+    reason: ready
+      ? "Config-driven via Nango — the resolver registers from this row automatically once it loads; no file to write. Confirm it appears as registered in the registry."
+      : `Config-driven via Nango, but the row is missing ${blanks.join(", ")}. Add these so the resolver can register and the endpoint becomes usable.`,
+    nextAction: ready ? null : { id: "edit", label: `Add ${blanks.join(", ")} to the row` },
+  };
+}
+
+/**
+ * Resolve a builder for a connector kind. Each builder emits the same
+ * `{ ok, mode, connectorKind, proposal, prefill, blanks, reason }` contract.
+ *   - custom-http (default) → file mode (materialized resolver)
+ *   - nango                 → config-driven (no file; built from the row)
+ *   - mcp/webhook/chrome    → not yet supported (truthful, not blank)
+ */
+function getResolverBuilder(connectorKind) {
+  const kind = clean(connectorKind).toLowerCase();
+  if (kind === "nango") {
+    return (args) => constructNangoReadiness(args);
+  }
+  // Reserved for auto-construction — these need their own resolver implementation
+  // and cannot be derived from an HTTP response shape (taxonomy: mcp|chrome|tool).
+  if (["mcp", "chrome", "tool"].includes(kind)) {
+    return (args) => ({
+      ok: false,
+      mode: "unsupported",
+      reserved: true,
+      connectorKind: kind,
+      endpoint: endpointFor(args?.row?.integrationId),
+      proposal: null,
+      prefill: null,
+      detected: null,
+      blanks: [],
+      // Reserved should build confidence, not feel like a dead end: say what is
+      // reserved, what works now, and the concrete next move.
+      reason: `Auto-construction for "${kind}" connectors is reserved for a future release. What works today: set this row's connector to custom-http and construct a resolver, or ask the governed helper to propose a plan. Your record stays governed either way.`,
+      nextAction: { id: "use-custom-http", label: "Switch to a custom-http resolver" },
+    });
+  }
+  return (args) => constructCustomHttpProposal(args);
+}
+
+/**
+ * Construct a governed resolver for one API Registry row from its tested shape.
+ *
+ * @param {object} input
+ * @param {object} input.row             the api-registry row (drawer draft)
+ * @param {object} [input.profile]       profileApiResponse(row.lastResponse)
+ * @param {object} [input.recommendation] recommendResolver(profile)
+ * @param {object} [input.recordRef]     { objectId, rowName } of the governed record
+ * @returns {{ ok, mode, connectorKind, proposal, prefill, blanks, reason }}
+ */
+function constructResolverProposal(input = {}) {
+  const row = input.row && typeof input.row === "object" ? input.row : {};
+  const builder = getResolverBuilder(row.connectorKind);
+  return builder({
+    row,
+    profile: input.profile || null,
+    recommendation: input.recommendation || null,
+    recordRef: input.recordRef || null,
+  });
+}
+
+export { constructResolverProposal, getResolverBuilder };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/server-resolver-registry.js

@@ -0,0 +1,99 @@
+/**
+ * Server Resolver Registry IO V1 — the confined, server-only bridge between the
+ * pure unified-resolver-registry deriver and the filesystem.
+ *
+ * Responsibilities (server-only; the browser never imports this):
+ *   - read the provenance header off each resolver file (to tag
+ *     helper-generated vs static-file provenance)
+ *   - persist the externalized, agent-readable index artifact and the endpoint
+ *     manifest (gated by persistence mode — read-only runtimes skip silently
+ *     and the live derivation is still returned over the API)
+ *
+ * The artifacts are PROJECTIONS of the governed records — do-not-edit, and kept
+ * in sync by this write-through. Never logs file contents. Contract:
+ * `@growthub/api-contract/resolver-registry`.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { describePersistenceMode } from "@/lib/workspace-config";
+import {
+  RESOLVER_REGISTRY_DIR,
+  RESOLVER_REGISTRY_INDEX_FILE,
+  RESOLVER_ENDPOINT_MANIFEST_FILE,
+  parseResolverFileHeader,
+  slugifyIntegrationId,
+  buildEndpointManifest,
+} from "@/lib/unified-resolver-registry";
+
+const HEADER_BYTES = 600;
+
+function resolversDirAbs() {
+  return path.resolve(/*turbopackIgnore: true*/ process.cwd(), RESOLVER_REGISTRY_DIR);
+}
+
+/**
+ * Read the provenance header of every resolver file.
+ * Returns { [slug]: { generated, integrationId, record } }. Never throws.
+ */
+async function readResolverFileMeta() {
+  const dir = resolversDirAbs();
+  const meta = {};
+  let entries;
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return meta;
+  }
+  const jsFiles = entries.filter((f) => f.endsWith(".js") && !f.startsWith("_") && !f.startsWith("."));
+  await Promise.all(
+    jsFiles.map(async (file) => {
+      const slug = slugifyIntegrationId(file, "");
+      if (!slug) return;
+      try {
+        const handle = await fs.open(path.join(dir, file), "r");
+        try {
+          const buf = Buffer.alloc(HEADER_BYTES);
+          const { bytesRead } = await handle.read(buf, 0, HEADER_BYTES, 0);
+          meta[slug] = parseResolverFileHeader(buf.toString("utf8", 0, bytesRead));
+        } finally {
+          await handle.close();
+        }
+      } catch {
+        // Unreadable file — leave it out of meta; the deriver still sees the
+        // filename via `files` and classifies it as static-file.
+      }
+    }),
+  );
+  return meta;
+}
+
+/**
+ * Persist the index + endpoint manifest artifacts (gated). Returns
+ * { written: boolean, reason?: string }. Read-only runtimes are not an error —
+ * the live API derivation remains the source of truth at request time.
+ */
+async function persistResolverRegistryArtifacts(index) {
+  const persistence = describePersistenceMode();
+  if (!persistence.canSave) {
+    return { written: false, reason: persistence.reason || "read-only runtime" };
+  }
+  const dir = resolversDirAbs();
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    const indexPath = path.resolve(/*turbopackIgnore: true*/ process.cwd(), RESOLVER_REGISTRY_INDEX_FILE);
+    const manifestPath = path.resolve(/*turbopackIgnore: true*/ process.cwd(), RESOLVER_ENDPOINT_MANIFEST_FILE);
+    // Confinement — both artifacts live directly in the resolvers dir.
+    if (path.dirname(indexPath) !== dir || path.dirname(manifestPath) !== dir) {
+      return { written: false, reason: "artifact path escaped the resolvers dir" };
+    }
+    const manifest = buildEndpointManifest(index, index.generatedAt);
+    await fs.writeFile(indexPath, `${JSON.stringify(index, null, 2)}\n`, "utf8");
+    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return { written: true };
+  } catch (err) {
+    return { written: false, reason: err?.message || "artifact write failed" };
+  }
+}
+
+export { readResolverFileMeta, persistResolverRegistryArtifacts };