@growthub/cli 0.13.9 → 0.14.1

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

@@ -0,0 +1,67 @@
+/**
+ * Server Resolver Write V1 — the single, confined, gated fs write for resolver
+ * files. Used by the helper apply route's resolver.create lane (and available
+ * to register-resolver). Server-only.
+ *
+ * AWaC topology: writes only in filesystem mode; read-only runtimes throw a
+ * coded error with guidance (the same 409 contract the rest of the workspace
+ * uses). Path is confined to lib/adapters/integrations/resolvers — never
+ * escapes. Never logs file contents.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { describePersistenceMode } from "@/lib/workspace-config";
+import { resolveResolverFilePath } from "@/lib/workspace-resolver-proposal";
+
+const MAX_RESOLVER_SIZE = 256 * 1024;
+
+/**
+ * Write a resolver file from a validated proposal. Returns
+ * { saved:true, path, filename } or throws a coded error:
+ *   - WORKSPACE_PERSISTENCE_READ_ONLY (read-only runtime; carries guidance)
+ *   - INVALID_RESOLVER_WRITE (bad path / code)
+ *   - WORKSPACE_PERSISTENCE_PATH_REFUSED (escaped the resolver dir)
+ */
+async function writeResolverProposalFile(proposal) {
+  const persistence = describePersistenceMode();
+  if (!persistence.canSave) {
+    const error = new Error(persistence.reason || "resolver write requires a writable filesystem runtime");
+    error.code = "WORKSPACE_PERSISTENCE_READ_ONLY";
+    error.guidance = persistence.guidance || "Set WORKSPACE_CONFIG_ALLOW_FS_WRITE=true or use local development mode.";
+    throw error;
+  }
+  const target = (proposal?.target && proposal.target.ok)
+    ? proposal.target
+    : resolveResolverFilePath(proposal?.payload?.integrationId);
+  if (!target || !target.ok) {
+    const error = new Error(target?.error || "invalid resolver target path");
+    error.code = "INVALID_RESOLVER_WRITE";
+    throw error;
+  }
+  const code = String(proposal?.code || "");
+  if (!code.includes("registerSourceResolver")) {
+    const error = new Error("resolver code must call registerSourceResolver()");
+    error.code = "INVALID_RESOLVER_WRITE";
+    throw error;
+  }
+  if (Buffer.byteLength(code, "utf8") > MAX_RESOLVER_SIZE) {
+    const error = new Error(`resolver file must be smaller than ${MAX_RESOLVER_SIZE / 1024} KB`);
+    error.code = "INVALID_RESOLVER_WRITE";
+    throw error;
+  }
+
+  const resolversDir = path.resolve(/*turbopackIgnore: true*/ process.cwd(), target.dir);
+  const outPath = path.join(resolversDir, target.filename);
+  if (path.dirname(outPath) !== resolversDir) {
+    const error = new Error("invalid filename — path traversal not allowed");
+    error.code = "WORKSPACE_PERSISTENCE_PATH_REFUSED";
+    throw error;
+  }
+
+  await fs.mkdir(resolversDir, { recursive: true });
+  await fs.writeFile(outPath, code, "utf8");
+  return { saved: true, path: target.path, filename: target.filename };
+}
+
+export { writeResolverProposalFile };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/serverless-upgrade.js

@@ -0,0 +1,89 @@
+/**
+ * Serverless Upgrade Onboarding V1 — derives the one-time "upgrade your
+ * localhost workflow to a persistent, scheduled serverless workflow" nudge from
+ * the workspace configuration state, following the same one-time onboarding
+ * pattern as the lens walkthrough (workspace-ui-cache dismiss flag).
+ *
+ * It reads only the existing model: sandbox-environment rows and their
+ * `runLocality` field (already part of the governed schema). When the operator
+ * has workflows but none are serverless — and hasn't dismissed the nudge — the
+ * upgrade path shows once.
+ *
+ * Pure + deterministic; never throws. The dismiss flag is read by the caller
+ * from the governed workspace-ui-cache row and passed in.
+ */
+
+const SERVERLESS_UPGRADE_DISMISS_FLAG = "serverlessUpgradeDismissed";
+const UPGRADE_STATE_KIND = "growthub-serverless-upgrade-state-v1";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+/** Is a sandbox row configured to run serverless? */
+function rowIsServerless(row) {
+  return isPlainObject(row) && clean(row.runLocality).toLowerCase() === "serverless";
+}
+
+/** Collect every sandbox-environment (workflow) row across the data model. */
+function collectWorkflowRows(workspaceConfig) {
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  const rows = [];
+  for (const object of objects) {
+    if (object?.objectType !== "sandbox-environment") continue;
+    for (const row of Array.isArray(object.rows) ? object.rows : []) {
+      if (isPlainObject(row)) rows.push(row);
+    }
+  }
+  return rows;
+}
+
+/**
+ * Derive the serverless-upgrade onboarding state.
+ *
+ * @param {object} workspaceConfig
+ * @param {object} [options]
+ * @param {boolean} [options.dismissed] dismiss flag from workspace-ui-cache
+ */
+function deriveServerlessUpgradeState(workspaceConfig, options = {}) {
+  const opts = isPlainObject(options) ? options : {};
+  const rows = collectWorkflowRows(workspaceConfig);
+  const serverlessCount = rows.filter(rowIsServerless).length;
+  const localCount = rows.length - serverlessCount;
+  const hasWorkflows = rows.length > 0;
+  const dismissed = opts.dismissed === true || String(opts.dismissed || "") === "true";
+  // Show the one-time path only when the operator has built workflows but none
+  // are serverless yet — the moment the upgrade mental model is most useful.
+  const showOnboarding = hasWorkflows && serverlessCount === 0 && !dismissed;
+  return {
+    kind: UPGRADE_STATE_KIND,
+    version: 1,
+    hasWorkflows,
+    workflowCount: rows.length,
+    serverlessCount,
+    localCount,
+    allLocal: hasWorkflows && serverlessCount === 0,
+    dismissed,
+    showOnboarding,
+    headline: showOnboarding
+      ? "Upgrade a workflow to serverless"
+      : serverlessCount > 0
+        ? "Serverless workflows are active"
+        : "Workflows run locally",
+    subheadline: showOnboarding
+      ? "Make it persistent and scheduled — it runs on invocation through your configured adapter, not just on this machine."
+      : "",
+  };
+}
+
+export {
+  SERVERLESS_UPGRADE_DISMISS_FLAG,
+  UPGRADE_STATE_KIND,
+  rowIsServerless,
+  collectWorkflowRows,
+  deriveServerlessUpgradeState,
+};

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

@@ -405,9 +405,15 @@ function deriveBlankWorkspaceActivationState({ workspaceConfig, workspaceSourceR
   }, 0);
   const widgetAdded = widgetCount > 0;
 
-  const workflowMatch = findWorkflowRow(workspaceConfig, () => true);
+  const workflowMatch = findWorkflowRow(workspaceConfig, (_row, object) => safeString(object?.id).trim() !== "workspace-helper-sandbox");
   const workflowCreated = Boolean(workflowMatch?.row);
   const workflowRun = deriveLatestRunStatus(workflowMatch?.row);
+  const workflowObjectId = safeString(workflowMatch?.object?.id).trim();
+  const workflowRowName = safeString(workflowMatch?.row?.Name || workflowMatch?.row?.name || workflowMatch?.row?.slug || workflowMatch?.row?.id).trim();
+  const workflowField = workflowMatch?.row?.orchestrationConfig !== undefined ? "orchestrationConfig" : "orchestrationGraph";
+  const workflowHref = workflowObjectId && workflowRowName
+    ? `/workflows?object=${encodeURIComponent(workflowObjectId)}&row=${encodeURIComponent(workflowRowName)}&field=${encodeURIComponent(workflowField)}`
+    : "";
 
   const steps = [
     {
@@ -449,8 +455,9 @@ function deriveBlankWorkspaceActivationState({ workspaceConfig, workspaceSourceR
         ? "Sandbox workflow scaffolded."
         : "Open Workflows to assemble your first automation.",
       status: workflowCreated ? "complete" : "pending",
-      href: "/workflows",
-      cta: workflowCreated ? "Open Workflows" : "New workflow",
+      href: workflowCreated ? workflowHref : "",
+      action: workflowCreated ? "" : "create-workflow",
+      cta: workflowCreated ? "Open workflow" : "New workflow",
     },
     {
       id: "run-workflow",
@@ -461,7 +468,7 @@ function deriveBlankWorkspaceActivationState({ workspaceConfig, workspaceSourceR
           ? "Last run failed — open the trace and fix the failing node."
           : "Click Test inside the workflow to do a first run.",
       status: workflowRun.ok ? "complete" : (workflowCreated ? "pending" : "blocked"),
-      href: "/workflows",
+      href: workflowCreated ? workflowHref : "",
       hint: workflowRun.ok || workflowCreated ? "" : "Create a workflow first.",
       cta: workflowRun.ok ? "View runs" : "Open workflow",
     },

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-data-model.js

@@ -937,6 +937,13 @@ function createTypedBusinessObject(workspaceConfig, { name, objectType = "custom
       ? workspaceConfig.dataModel
       : {};
   const id = uniqueObjectId(workspaceConfig, label);
+  const relations = preset.relations
+    ? preset.relations.map((relation) => {
+        const next = { ...relation };
+        if (next.statusAllowlist == null) delete next.statusAllowlist;
+        return next;
+      })
+    : [];
   const object = {
     id,
     label,
@@ -946,7 +953,7 @@ function createTypedBusinessObject(workspaceConfig, { name, objectType = "custom
     columns,
     rows: [],
     binding: { mode: "manual", source: "Data Model" },
-    relations: preset.relations ? preset.relations.map((r) => ({ ...r })) : [],
+    relations,
     fieldSettings: normalizeFieldSettings({}, columns)
   };
   return {

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

@@ -37,6 +37,15 @@ const WORKSPACE_HELPER_PROPOSAL_TYPES = [
   "dataModel.row.add",
   "repair.binding",
   "explain.object",
+  // Server-file lane (AWaC: NOT a config PATCH field). Routed in helper/apply to
+  // the confined, gated resolver write — never through writeWorkspaceConfig.
+  "resolver.create",
+  // Swarm lane — governed sandbox-environment rows in the EXISTING dataModel
+  // patch field. Apply normalizes the intent payload into an agent-swarm-v1
+  // graph via buildDefaultAgentSwarmGraph; execution stays behind sandbox-run.
+  "swarm.run.propose",
+  "swarm.workflow.save",
+  "swarm.run.resume",
 ];
 
 const PROPOSAL_TYPE_TO_PATCH_FIELD = {
@@ -50,6 +59,13 @@ const PROPOSAL_TYPE_TO_PATCH_FIELD = {
   "dataModel.row.add": "dataModel",
   "repair.binding": "dataModel",
   "explain.object": "dataModel",
+  // Sentinel — resolver.create writes a server file, not a config field. It is
+  // explicitly excluded from the PATCH allowlist and handled by its own lane.
+  "resolver.create": "server-file",
+  // Swarm rows are dataModel rows. No new PATCH field is introduced.
+  "swarm.run.propose": "dataModel",
+  "swarm.workflow.save": "dataModel",
+  "swarm.run.resume": "dataModel",
 };
 
 const KNOWN_WIDGET_KINDS = ["chart", "view", "iframe", "rich-text"];
@@ -62,7 +78,7 @@ const INTENT_DESCRIPTIONS = {
   create_widget:
     "Suggest which widgetTypes belong on the workspace based on the object schema and target KPIs. Propose widgetType entries and canvas widget placements.",
   register_api:
-    "Draft API Registry rows (dataModel object of objectType api-registry) including integration labels, credential prompts, base URL, endpoint, auth header, and method.",
+    "Draft API Registry rows (dataModel object of objectType api-registry) including integration labels, credential prompts, base URL, endpoint, auth header, and method. When the user wants the response shaped into governed rows (a Data Source) or describes a nested/paginated response, also recommend a resolver in the `summary` and propose the matching data-source object (objectType data-source) that references the registry row by registryId — guiding them into the resolver / Data Source lane. Credentials are runtime env keys (REF / REF_API_KEY / REF_TOKEN in .env.local), never stored in config.",
   create_object:
     "Translate the user's domain language into a new dataModel object: objectType, label, columns, starter rows, and field settings that make sense for their business.",
   edit_view:
@@ -71,6 +87,8 @@ const INTENT_DESCRIPTIONS = {
     "Inspect the workspace snapshot for broken references, missing bindings, empty objects, or incomplete views. Propose the minimum changes needed to repair each issue.",
   explain:
     "Return a clear explanation of what one or more workspace objects, widgets, or configurations do. Use the explain.object proposal type — payload is { explanation: string }.",
+  swarm:
+    "Propose a governed agent swarm via swarm.run.propose. You are propose-only: do not execute, do not store credentials. Describe the swarm objective, agent roles, task prompts, tools, maxConcurrency, and outcomeCriteria as an intent payload — the server normalizes it into the governed agent-swarm-v1 graph and execution happens only through sandbox-run after the user applies the proposal.",
 };
 
 /**
@@ -85,6 +103,10 @@ const INTENT_DESCRIPTIONS = {
  * `create_object` when the prompt mentions both "object" and "API".
  */
 const INTENT_HEURISTIC_PATTERNS = [
+  { intent: "swarm", patterns: [
+    /\b(swarm|sub-?agents?|multi-?agent|agent\s+team|orchestrat(e|or|ion))\b/i,
+    /\b(run|launch|spawn|dispatch)\b.*\b(agents?|workers?)\b.*\b(parallel|swarm|workflow)\b/i,
+  ]},
   { intent: "register_api", patterns: [
     /\b(api|endpoint|webhook|integration|connector|oauth|bearer\s+token|auth\s+header)\b/i,
     /\b(register|connect|wire|hook\s*up)\b.*\b(api|endpoint|webhook|service|integration)\b/i,
@@ -196,6 +218,13 @@ function buildStableSystemPrompt(intent) {
     "- Reset invalid axis, filter, group, and sort settings when source changes.",
     "- Mark recomputed values as unsaved unless PATCH succeeds.",
     "",
+    "## When proposing agent swarms (swarm.run.propose)",
+    "- You may propose swarm.run.propose. You are propose-only. Do not execute. Do not store credentials.",
+    "- Describe the swarm objective, agent roles, tasks, tools, maxConcurrency, and outcomeCriteria.",
+    "- The server will normalize this into the governed agent-swarm graph; execution happens only through sandbox-run after apply.",
+    "- payload shape: { name, description?, objective, agents: [{ id?, role, description?, taskPrompt, tools?, required?, maxTokens?, timeoutMs? }], maxConcurrency?, outcomeCriteria?, runLocality?, agentHost?, adapter? }",
+    "- adapter, when set, must be local-agent-host or local-intelligence.",
+    "",
     "## Valid proposal types and their target patch field",
     WORKSPACE_HELPER_PROPOSAL_TYPES.map(
       (t) => `  ${t} → ${PROPOSAL_TYPE_TO_PATCH_FIELD[t]}`

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-metadata-store.js

@@ -545,8 +545,8 @@ function deriveWorkspaceWorkflowMetadataItems(workspaceConfig, objectItems) {
       const graphEdges = Array.isArray(graph?.edges) ? graph.edges : [];
       const workflowMetadataId = stableId("workflow", objectId, rowName);
       const sandboxMetadataId = stableId("sandbox", objectId, rowName);
-      const agentHost = safeString(row.agentHost).trim();
-      const adapter = safeString(row.adapter).trim();
+        const rowAgentHost = safeString(row.agentHost).trim();
+        const rowAdapter = safeString(row.adapter).trim();
       const inputSchema = graphNodes.length ? discoverRunInputSchema(graph) : { requiresInput: false, fields: [] };
       const inputFields = Array.isArray(inputSchema?.fields) ? inputSchema.fields : [];
 
@@ -560,8 +560,8 @@ function deriveWorkspaceWorkflowMetadataItems(workspaceConfig, objectItems) {
         lifecycleStatus: safeString(row.lifecycleStatus).trim() || "draft",
         version: safeString(row.version).trim() || "1",
         sandboxMetadataId,
-        agentHost,
-        adapter,
+        agentHost: rowAgentHost,
+        adapter: rowAdapter,
         runLocality: safeString(row.runLocality).trim(),
         nodeCount: graphNodes.length,
         edgeCount: graphEdges.length,
@@ -578,6 +578,8 @@ function deriveWorkspaceWorkflowMetadataItems(workspaceConfig, objectItems) {
         const sourceType = safeString(config.sourceType).trim();
         const sourceId = safeString(config.sourceId).trim();
         const integrationId = safeString(config.integrationId).trim();
+        const nodeAgentHost = safeString(config.agentHost || rowAgentHost).trim();
+        const nodeAdapter = safeString(config.adapter || rowAdapter).trim();
         const filterClauses = collectFilterClauses({ op: config.filterMode, clauses: config.filters });
         const writesObjectId = safeString(config.writeObjectId || config.targetObjectId).trim();
         const readsObjectId = sourceId || safeString(config.objectId).trim();
@@ -603,8 +605,8 @@ function deriveWorkspaceWorkflowMetadataItems(workspaceConfig, objectItems) {
           inputFieldCount: inputs.length,
           inputFieldIds: inputs.map((field) => field.id),
           sandboxMetadataId,
-          agentHost,
-          adapter,
+          agentHost: nodeAgentHost,
+          adapter: nodeAdapter,
           permissions: nodeType === "api-registry-call" ? ["integration:read"] : []
         });
       }

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

@@ -0,0 +1,200 @@
+/**
+ * Workspace Resolver Proposal V1 — the governed resolver-file lane for the
+ * helper, aligned to AWaC topology + the Causation-ITT loop.
+ *
+ * AWaC boundary: a resolver is a SERVER FILE under
+ * lib/adapters/integrations/resolvers/, NOT workspace config. It therefore must
+ * NOT travel through the PATCH allowlist (dashboards|widgetTypes|canvas|
+ * dataModel). It is its own proposal lane with affectedField "server-file",
+ * gated by the same filesystem/read-only persistence rule, and it emits a
+ * receipt — so "state → eligibility → guidance → action → evidence" closes.
+ *
+ * This module is PURE (build/validate/generate). The actual confined fs write
+ * lives in lib/server-resolver-write.js (server-only). Secret-safe: the
+ * generated resolver reads its secret from the server env at run time via the
+ * authRef candidate keys — never an inlined value.
+ */
+
+const RESOLVER_PROPOSAL_TYPE = "resolver.create";
+const RESOLVER_AFFECTED_FIELD = "server-file";
+const RESOLVER_DIR = "lib/adapters/integrations/resolvers";
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function slugify(value, fallback = "resolver") {
+  const slug = clean(value)
+    .toLowerCase()
+    .replace(/\.js$/, "")
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 64);
+  return slug || fallback;
+}
+
+function envCandidates(ref) {
+  const token = clean(ref).replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toUpperCase();
+  if (!token) return [];
+  return Array.from(new Set([token, `${token}_API_KEY`, `${token}_TOKEN`]));
+}
+
+/**
+ * Confine a resolver filename to the resolver dir. Mirrors the register-resolver
+ * route's traversal guard so the studio previews exactly what the write accepts.
+ */
+function resolveResolverFilePath(name) {
+  const base = slugify(name, "resolver");
+  if (base.includes("/") || base.includes("..")) {
+    return { ok: false, path: null, filename: null, dir: RESOLVER_DIR, error: "resolver filename must not contain path segments" };
+  }
+  const filename = `${base}.js`;
+  return { ok: true, path: `${RESOLVER_DIR}/${filename}`, filename, dir: RESOLVER_DIR, error: null };
+}
+
+function safeJsString(value) {
+  return JSON.stringify(clean(value));
+}
+
+/**
+ * Generate a concrete, runnable resolver module for a specific API. baseUrl /
+ * endpoint / rootPath / idField are baked in from the registry row + the
+ * response profile, so the file works for THIS API. The secret is read from the
+ * server env via the authRef candidate keys at run time — never inlined.
+ */
+function generateResolverCode({ integrationId, baseUrl, endpoint, method, authRef, headerName, prefix, rootPath, idField, entityType }) {
+  const id = slugify(integrationId, "integration");
+  const url = `${clean(baseUrl).replace(/\/+$/, "")}/${clean(endpoint).replace(/^\/+/, "")}`.replace(/\/$/, "") || clean(baseUrl) || clean(endpoint);
+  const m = (clean(method).toUpperCase() || "GET");
+  const candidates = envCandidates(authRef);
+  const header = clean(headerName) || "authorization";
+  const pfx = clean(prefix);
+  const root = clean(rootPath);
+  const idf = clean(idField) || "id";
+  const ent = clean(entityType) || "records";
+
+  return `// Resolver for "${id}" — generated by the governed helper resolver studio.
+// Server file. Reads its secret from the server env at run time (candidates:
+// ${candidates.join(", ") || "none"}); never hard-code a secret here.
+import { registerSourceResolver } from "../source-resolver-registry.js";
+
+const ENV_CANDIDATES = ${JSON.stringify(candidates)};
+function readSecret() {
+  for (const key of ENV_CANDIDATES) {
+    if (process.env[key]) return process.env[key];
+  }
+  return "";
+}
+function valueAtPath(obj, path) {
+  if (!path) return obj;
+  return String(path).split(".").filter(Boolean).reduce((acc, part) => (acc == null ? acc : acc[part]), obj);
+}
+
+registerSourceResolver({
+  integrationId: ${safeJsString(id)},
+  label: ${safeJsString(`${id} (${ent})`)},
+  // fetchRecords runs server-side. Secret stays in the server env.
+  fetchRecords: async () => {
+    const secret = readSecret();
+    const res = await fetch(${safeJsString(url)}, {
+      method: ${safeJsString(m)},
+      headers: {
+        accept: "application/json",
+        ...(secret ? { ${safeJsString(header)}: ${pfx ? `\`${pfx} \${secret}\`` : "secret"} } : {}),
+      },
+    });
+    const raw = res.headers.get("content-type")?.includes("application/json") ? await res.json() : await res.text();
+    const extracted = valueAtPath(raw, ${safeJsString(root)});
+    const items = Array.isArray(extracted) ? extracted : (Array.isArray(raw) ? raw : []);
+    return items.map((item, index) => ({
+      id: item && item[${safeJsString(idf)}] != null ? String(item[${safeJsString(idf)}]) : String(index),
+      ...item,
+    }));
+  },
+});
+`;
+}
+
+/**
+ * Build an inert resolver.create proposal. Carries the target path, the
+ * generated code, security notes, and the resolver's input/output contract.
+ * Nothing is written until the apply lane writes the file (gated).
+ */
+function buildResolverProposal(input = {}) {
+  const integrationId = slugify(input.integrationId, "integration");
+  const target = resolveResolverFilePath(integrationId);
+  const code = generateResolverCode({
+    integrationId,
+    baseUrl: input.baseUrl,
+    endpoint: input.endpoint,
+    method: input.method,
+    authRef: input.authRef,
+    headerName: input.headerName,
+    prefix: input.prefix,
+    rootPath: input.rootPath,
+    idField: input.idField,
+    entityType: input.entityType,
+  });
+  return {
+    type: RESOLVER_PROPOSAL_TYPE,
+    affectedField: RESOLVER_AFFECTED_FIELD,
+    rationale: `Generate a server resolver that shapes ${integrationId}'s response${clean(input.rootPath) ? ` at "${clean(input.rootPath)}"` : ""} into governed rows.`,
+    confidence: 0.85,
+    target,
+    language: "javascript",
+    code,
+    security: [
+      "Server file — only written in filesystem mode (read-only runtimes get a 409 + guidance).",
+      "Reads its secret from the server env at run time; never inlines a value.",
+      `Path confined to ${RESOLVER_DIR}.`,
+    ],
+    contract: {
+      inputs: ["registry baseUrl/endpoint", `authRef env (${envCandidates(input.authRef).join(", ") || "none"})`],
+      output: `Record[] with a stable id (from "${clean(input.idField) || "id"}").`,
+    },
+    payload: {
+      integrationId,
+      rootPath: clean(input.rootPath),
+      entityType: clean(input.entityType) || "records",
+      filename: target.filename,
+    },
+  };
+}
+
+/**
+ * Validate a resolver.create proposal before the apply lane writes it.
+ * Returns { ok, error }.
+ */
+function validateResolverProposal(proposal) {
+  if (!proposal || proposal.type !== RESOLVER_PROPOSAL_TYPE) {
+    return { ok: false, error: "not a resolver.create proposal" };
+  }
+  if (proposal.affectedField !== RESOLVER_AFFECTED_FIELD) {
+    return { ok: false, error: `resolver.create affectedField must be "${RESOLVER_AFFECTED_FIELD}"` };
+  }
+  const target = proposal.target || resolveResolverFilePath(proposal.payload?.integrationId);
+  if (!target || !target.ok) {
+    return { ok: false, error: target?.error || "invalid resolver target path" };
+  }
+  const code = clean(proposal.code);
+  if (!code) return { ok: false, error: "resolver code is empty" };
+  if (!code.includes("registerSourceResolver")) {
+    return { ok: false, error: "resolver code must call registerSourceResolver()" };
+  }
+  if (!target.filename.endsWith(".js")) {
+    return { ok: false, error: "resolver file must have a .js extension" };
+  }
+  return { ok: true, error: null, target };
+}
+
+export {
+  RESOLVER_PROPOSAL_TYPE,
+  RESOLVER_AFFECTED_FIELD,
+  RESOLVER_DIR,
+  resolveResolverFilePath,
+  generateResolverCode,
+  buildResolverProposal,
+  validateResolverProposal,
+  envCandidates,
+};