@growthub/cli 0.14.8 → 0.14.10

package/assets/worker-kits/growthub-custom-workspace-starter-v1/SKILL.md

@@ -39,6 +39,27 @@ mcpTools: []
 
 The **Workspace** is the top-level Growthub Local product object. This kit is the official starter that bootstraps every governed Workspace; everything else (worker kits, templates, workflows, hosted agents, source imports) is an input to a Workspace.
 
+## Your operating role (read first)
+
+**If you are an agent reading this, you are the operating layer.** A human gave you an outcome; you operate this governed Workspace on their behalf. When the requester is a super admin or workspace admin, you can act as the super-admin orchestrator inside the governed boundary; when the requester is a regular user, you still do the orchestration work, but approval, review, rollback, and authority stay with the workspace/super-admin surfaces. You are not editing files and hoping tests catch mistakes — you are operating a live domain model where the platform rejects invalid reality before it lands and remembers everything that does. The chat you are in *is* the user's steering surface; the no-code Workspace is the control and audit plane.
+
+**The human is usually non-technical, and asks for a business outcome — not workspace mechanics.** They will not mention the Data Model, metadata graph, routes, validators, the PATCH boundary, or the run console — those are the control plane and proof layer that exist so you can operate safely and the super admin can inspect everything. They ask in plain language: *research a customer avatar, run market/competitor research, generate this week's content batch, script and brief the next campaign, pull the latest campaign performance, update the client report, build an MRR-by-plan dashboard, run the revenue workflow, iterate on a feature, find what broke.* Your job is to translate that outcome into governed operations over **what already exists** in this Workspace (prebuilt workflows, objects, and procedures), execute it, and deliver the result — outputs saved, synced, inspectable, and governed. This **private repository is the customer's durable operating environment**: their kit, objects, workflows, procedures, rules, source records, docs, receipts, run history, and governance boundaries all live here; your session is just the operator entering that universe.
+
+The completion bar is the user's real-world outcome, not a partial proposal or a hidden local artifact. Continue the governed loop until the workspace has objective proof: the relevant workflow ran or object changed, output rows/ledgers reflect the count and state, durable storage or source records hold the deliverables, receipts/run ids explain what happened, and any human-review state remains explicit. Do not hard-code one client's workflow as the pattern; swap the client, rows, registries, brand constraints, storage prefix, dashboard, and quality criteria while keeping the same governed causation loop.
+
+Your loop, every time:
+
+1. **Inherit state** — read the `workspace:agent-outcomes` receipt stream (`GET /api/workspace/agent-outcomes`) and `.growthub-fork/project.md` to see what the last agent did; continue from `nextActions` / `rollbackRef`, don't redo work.
+2. **Check what exists** — a scheduled job, external API, data view, or multi-agent workflow is almost always already a governed object. Prefer operating an existing object over writing code.
+3. **Act only through governed routes** — `PATCH /api/workspace` (config) and `POST /api/workspace/sandbox-run` (execution); drafts via `workflow/publish`; proposals via `helper/apply`. There is no third path.
+4. **Let the validator correct you** — preflight, read the rejection reason, repair, retry. Rejections are navigation, not failure.
+5. **Persist the outcome** — count only connected, durable outputs; save accepted artifacts to the governed ledger/storage surface; keep generated binaries and secrets out of git.
+6. **Leave proof** — every governed action emits a secret-redacted receipt. The human does not need the mechanics; the super admin inspects all of it after the fact (Workspace Map, Run Console, outcome cockpit).
+
+**Three roles:** the human states outcomes → you (the agent) operate → the workspace admin/super admin governs and audits. The mechanics of the boundary are in [`skills/governed-workspace-mutation/SKILL.md`](./skills/governed-workspace-mutation/SKILL.md) — read it before any mutation.
+
+> **For the human operator:** you do not have to operate this Workspace yourself. Tell an agent what you want; it operates the Workspace through governed routes; you (or your admin) inspect every change with full proof and rollback. The no-code Builder is the governed substrate and the audit surface — not a tool you must personally drive.
+
 Every Growthub governed Workspace is materialised from this kit. The kit ships the `.growthub-fork/` contract (identity, policy, trace, optional authority), the `apps/workspace` no-code Workspace Builder, the validated `growthub.config.json` V1 contract, plus the six primitive layers Claude/Cursor/Codex agents operate against:
 
 1. **`SKILL.md`** — this file. Discovery entry + routing menu. Always loaded first; the full operator runbook (`skills.md`) is disclosed progressively when work begins.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/README.md

@@ -18,7 +18,7 @@ It intentionally depends on adapter contracts:
 - `NANGO_ENVIRONMENT` (default `dev`)
 - `NANGO_MODE` (`cloud` | `self-hosted`, default `cloud`)
 
-The Growthub local-first operator shell remains at `../../studio`.
+This `apps/workspace` app is the only bundled app surface; the legacy `studio/` Vite shell has been removed. It is the governed control plane and audit surface — non-technical users do not operate it directly; an agent operates the Workspace on their behalf through the governed routes (see the workspace `SKILL.md` operating-role contract), while super admins use this app for inspection, proof, and governance.
 
 Settings exposes two universal integration lanes:
 

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/metadata-graph/route.js

@@ -35,6 +35,11 @@ import { readWorkspaceConfig, readWorkspaceSourceRecords } from "@/lib/workspace
 import { buildWorkspaceMetadataStore } from "@/lib/workspace-metadata-store";
 import { buildWorkspaceMetadataGraph } from "@/lib/workspace-metadata-graph";
 import { selectStaleMetadataGroups } from "@/lib/workspace-metadata-selectors";
+import { deriveBlastRadius } from "@/lib/workspace-metadata-impact";
+import { deriveStaleSurfaces } from "@/lib/workspace-stale-surfaces";
+import { deriveWorkflowImpact } from "@/lib/workspace-workflow-impact";
+import { deriveProvenanceLineage } from "@/lib/workspace-provenance-lineage";
+import { deriveAppReadiness } from "@/lib/workspace-app-readiness";
 
 const ENVELOPE_KIND = "growthub-workspace-metadata-graph-v1";
 const ENVELOPE_VERSION = 1;
@@ -111,10 +116,17 @@ async function GET(request) {
   // Optional stale-group selector via query params.
   let staleGroups = [];
   let staleReasons = [];
+  // Parse all causal query params from one URL read.
+  let impactId = "";
+  let lineageId = "";
+  let lineageDirection = "both";
   try {
     const url = request && request.url ? new URL(request.url) : null;
     const staleKind = url ? (url.searchParams.get("staleKind") || "").trim() : "";
     const staleId = url ? (url.searchParams.get("staleId") || "").trim() : "";
+    impactId = url ? (url.searchParams.get("impactId") || "").trim() : "";
+    lineageId = url ? (url.searchParams.get("lineageId") || "").trim() : "";
+    lineageDirection = url ? (url.searchParams.get("lineageDirection") || "both").trim() : "both";
     if (staleKind && staleId) {
       const result = selectStaleMetadataGroups(metadataStore, { kind: staleKind, id: staleId });
       staleGroups = Array.isArray(result?.groups) ? result.groups : [];
@@ -124,6 +136,30 @@ async function GET(request) {
     warnings.push(`Failed to compute stale groups: ${error?.message || "unknown error"}`);
   }
 
+  // Causal derivations over the same read-only graph (Mutation → Law →
+  // Intelligence). All pure, all bounded, all secret-free. `staleSurfaces` is
+  // the unconditional freshness baseline (timestamps already in the graph);
+  // `impact` and `lineage` are computed on demand for one node.
+  let staleSurfaces = null;
+  let readiness = null;
+  let impact = null;
+  let lineage = null;
+  try {
+    staleSurfaces = deriveStaleSurfaces(graph);
+    readiness = deriveAppReadiness(graph);
+    if (impactId) {
+      impact = {
+        blastRadius: deriveBlastRadius(graph, impactId),
+        workflowImpact: deriveWorkflowImpact(graph, impactId)
+      };
+    }
+    if (lineageId) {
+      lineage = deriveProvenanceLineage(graph, lineageId, { direction: lineageDirection });
+    }
+  } catch (error) {
+    warnings.push(`Failed to compute causal derivations: ${error?.message || "unknown error"}`);
+  }
+
   return NextResponse.json({
     kind: ENVELOPE_KIND,
     version: ENVELOPE_VERSION,
@@ -163,6 +199,11 @@ async function GET(request) {
       groups: staleGroups,
       reasons: staleReasons
     },
+    // Causal intelligence layer — read-only derivations over `graph` above.
+    staleSurfaces,
+    readiness,
+    ...(impact ? { impact } : {}),
+    ...(lineage ? { lineage } : {}),
     warnings,
     selectors: {
       // Manifest of selectors the route honours. Only `selectStaleMetadataGroups`
@@ -170,7 +211,14 @@ async function GET(request) {
       // selectors are exposed as importable helpers for server-side consumers
       // and the read-only inspector; they are NOT toggled through query
       // params in V1.
-      httpEnabled: ["selectStaleMetadataGroups"],
+      httpEnabled: [
+        "selectStaleMetadataGroups",
+        "deriveStaleSurfaces",
+        "deriveBlastRadius",
+        "deriveWorkflowImpact",
+        "deriveProvenanceLineage",
+        "deriveAppReadiness"
+      ],
       helperOnly: [
         "selectWidgetRequiredFields",
         "selectWorkflowNodeInputSchema",

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/patch/preflight/route.js

@@ -35,6 +35,38 @@ import {
 } from "@/lib/workspace-patch-policy";
 import { evaluateAppScope, requireAppScope } from "@/lib/workspace-app-registry";
 import { appendOutcomeReceipt } from "@/lib/workspace-outcome-receipts";
+import { readWorkspaceSourceRecords } from "@/lib/workspace-config";
+import { buildWorkspaceMetadataStore } from "@/lib/workspace-metadata-store";
+import { buildWorkspaceMetadataGraph } from "@/lib/workspace-metadata-graph";
+import { derivePatchImpact } from "@/lib/workspace-patch-impact";
+
+/**
+ * Report the blast radius of a proposed patch BEFORE the write — the S1
+ * spine's intended preflight consumption. Builds the metadata graph from the
+ * MERGED config (what the workspace becomes if this patch lands), maps the
+ * patched dataModel objects / dashboards to their graph node ids, and runs the
+ * pure `deriveStaleSurfaces` seed path over them. Pure, additive, never
+ * throws — on any failure the preflight verdict is unaffected and `impact`
+ * is simply omitted.
+ */
+async function computePatchImpact(currentConfig, mergedConfig, patch) {
+  try {
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) return null;
+    let sourceRecords = {};
+    try { sourceRecords = (await readWorkspaceSourceRecords()) || {}; } catch { sourceRecords = {}; }
+    // Build BOTH graphs so the impact deriver can report not just added/modified
+    // (on the merged graph) but also REMOVED objects/dashboards (whose downstream
+    // lived in the current graph). One shared, unit-tested deriver does the diff.
+    const buildGraph = (cfg) => buildWorkspaceMetadataGraph(buildWorkspaceMetadataStore({ workspaceConfig: cfg || {}, workspaceSourceRecords: sourceRecords }));
+    const currentGraph = buildGraph(currentConfig);
+    const mergedGraph = buildGraph(mergedConfig);
+    const impact = derivePatchImpact(currentGraph, mergedGraph, currentConfig || {}, mergedConfig || {});
+    if (!impact.total && !impact.removed.length) return null;
+    return impact;
+  } catch {
+    return null;
+  }
+}
 
 async function POST(request) {
   let patch;
@@ -66,12 +98,14 @@ async function POST(request) {
   // PATCH about the merged result. Skipped when the body is not a plain
   // object (policy already reports that).
   let schema = { ok: true, errors: [] };
+  let mergedConfig = null;
   if (patch && typeof patch === "object" && !Array.isArray(patch)) {
     const sanitized = {};
     for (const key of WORKSPACE_PATCH_ALLOWED_FIELDS) {
       if (Object.prototype.hasOwnProperty.call(patch, key)) sanitized[key] = patch[key];
     }
     const merged = applyWorkspaceConfigPatch(currentConfig || {}, sanitized);
+    mergedConfig = merged;
     try {
       validateWorkspaceConfig({
         dashboards: merged.dashboards,
@@ -103,6 +137,9 @@ async function POST(request) {
     }
   }
 
+  // Blast radius of this patch BEFORE the write (additive; never blocks).
+  const impact = await computePatchImpact(currentConfig, mergedConfig, patch);
+
   const persistence = describePersistenceMode();
   const ok = policy.ok && schema.ok && (appScopeVerdict ? appScopeVerdict.allowed : true);
   const repairPlan = repairPlanForViolations(policy.violations);
@@ -140,6 +177,7 @@ async function POST(request) {
     schema,
     repairPlan,
     ...(appScopeVerdict ? { appScopeVerdict } : {}),
+    ...(impact ? { impact } : {}),
     ...(safeNextStep ? { safeNextStep } : {}),
     persistence: {
       mode: persistence.mode,

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

@@ -62,6 +62,27 @@ function buildAuthHeaders(record, secretValue) {
   return { [headerName]: prefix ? `${prefix} ${secretValue}` : secretValue };
 }
 
+function executeFeatureSeedMock(url, { registryId, method, startedAt }) {
+  if (!String(url || "").startsWith("mock://growthub-feature-seed/")) return null;
+  return {
+    ok: true,
+    exitCode: 0,
+    durationMs: Date.now() - startedAt,
+    stdout: JSON.stringify({ ok: true, status: 200, data: [{ id: "rec-1", label: "Probe record", registryId }] }, null, 2),
+    stderr: "",
+    rawPayload: { ok: true, status: 200, data: [{ id: "rec-1", label: "Probe record", registryId }] },
+    httpStatus: 200,
+    adapterMeta: {
+      mode: "orchestration-graph",
+      registryId,
+      url,
+      httpStatus: 200,
+      method,
+      transport: "feature-seed-mock"
+    }
+  };
+}
+
 function findRegistryRecord(workspaceConfig, registryId) {
   const id = String(registryId || "").trim();
   if (!id) return null;
@@ -203,6 +224,12 @@ async function executeApiRegistryCall(workspaceConfig, nodeConfig, inputPayload,
     }
   }
 
+  const mockResult = executeFeatureSeedMock(url, { registryId, method, startedAt });
+  if (mockResult) {
+    clearTimeout(timer);
+    return mockResult;
+  }
+
   try {
     const response = await fetch(url, {
       method,

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

@@ -0,0 +1,212 @@
+/**
+ * Growthub Workspace App-Readiness V1 — ship-readiness deriver.
+ *
+ * Composes the signals the workspace already records into ONE app-scoped
+ * eligibility verdict: `{ ready, blocking[], nextAction }`. Eligibility, not a
+ * flag — readiness is computed from the live state every call, never stored.
+ *
+ * Signal sources, all already present in the read-only metadata graph the
+ * Workspace Map builds:
+ *   - integration.status      — an unconnected integration blocks its dependents
+ *   - sandbox.authStatus      — an unauthenticated sandbox cannot run
+ *   - pipelineHealth.status / latestOk — an untested or failing pipeline blocks
+ *   - workflow.lifecycleStatus — a draft-only workflow is a soft (non-blocking)
+ *                                signal that proof is still pending
+ *
+ * Callers that hold richer signals (env-status, deploy check shape, swarm
+ * eligibility) may pass them via `options.extraBlockers` / `options.extraSignals`
+ * — they are merged in without changing the shape. Pure: no fetch, no fs, no
+ * writes, no secrets. Deterministic ordering so receipts/diffs stay clean.
+ */
+
+const APP_READINESS_KIND = "growthub-workspace-app-readiness-v1";
+const APP_READINESS_VERSION = 1;
+
+// Severity rank → lower sorts first (most urgent blocker becomes nextAction).
+const SEVERITY = { blocker: 0, warning: 1 };
+
+function safeString(value) {
+  if (value == null) return "";
+  return typeof value === "string" ? value : String(value);
+}
+
+function isConnected(status) {
+  const s = safeString(status).toLowerCase();
+  return s === "connected" || s === "ok" || s === "active" || s === "ready";
+}
+
+// Three-state auth: "authed" | "unauthed" | "unknown". Empty is UNKNOWN, never
+// silently "authed" — unknown auth must not pass as ready (review finding D).
+function authState(status) {
+  const s = safeString(status).toLowerCase();
+  if (["authed", "authenticated", "ok", "connected", "ready"].includes(s)) return "authed";
+  if (!s) return "unknown";
+  return "unauthed";
+}
+
+// A local / no-auth sandbox legitimately has no credential — an intentional
+// exception, not a silent default.
+function isNoAuthSandbox(summary) {
+  const locality = safeString(summary.runLocality).toLowerCase();
+  const adapter = safeString(summary.adapter).toLowerCase();
+  const provider = safeString(summary.authProvider).toLowerCase();
+  return locality === "local" || adapter.includes("local") || provider === "none" || provider === "local";
+}
+
+/**
+ * @param {object} graph a `buildWorkspaceMetadataGraph` envelope
+ * @param {object} [options]
+ * @param {string} [options.appId] restrict to nodes scoped to this app (when
+ *        node summaries carry `appId`/`appScope`); omit for workspace scope.
+ * @param {Array<{severity?:string,code:string,message:string,nextAction?:string}>} [options.extraBlockers]
+ * @param {object} [options.extraSignals] merged verbatim into `signals`.
+ * @returns {object} `{ kind, version, appId, ready, score, blocking[], warnings[], signals, nextAction, summary }`
+ */
+function deriveAppReadiness(graph, options = {}) {
+  const appId = safeString(options.appId).trim() || null;
+
+  const empty = (warning) => ({
+    kind: APP_READINESS_KIND,
+    version: APP_READINESS_VERSION,
+    appId,
+    ready: false,
+    score: 0,
+    blocking: [],
+    warnings: warning ? [warning] : [],
+    signals: {},
+    nextAction: null,
+    summary: "No readiness computed."
+  });
+
+  if (!graph || typeof graph !== "object" || !Array.isArray(graph.nodes)) {
+    return empty("graph missing or malformed");
+  }
+
+  const inScope = (node) => {
+    if (!appId) return true;
+    const scope = node.summary && (node.summary.appId || node.summary.appScope);
+    return safeString(scope) === appId;
+  };
+
+  const nodes = graph.nodes.filter(inScope);
+  const issues = [];
+  const counts = { integrations: 0, sandboxes: 0, pipelines: 0, workflows: 0 };
+
+  for (const node of nodes) {
+    const s = node.summary || {};
+    if (node.type === "integration") {
+      counts.integrations += 1;
+      if (!isConnected(s.status)) {
+        issues.push({
+          severity: "blocker",
+          code: "integration_not_connected",
+          subject: node.label || node.id,
+          message: `Integration "${node.label || node.id}" is ${safeString(s.status) || "not connected"}.`,
+          nextAction: `Connect integration "${node.label || node.id}" (test-source / auth), then re-check readiness.`
+        });
+      }
+    } else if (node.type === "sandbox") {
+      counts.sandboxes += 1;
+      const state = authState(s.authStatus);
+      const subject = node.label || node.id;
+      if (state === "authed" || isNoAuthSandbox(s)) {
+        // authed, or a deliberate local/no-auth sandbox — ready.
+      } else if (state === "unknown") {
+        issues.push({
+          severity: "warning",
+          code: "sandbox_auth_unknown",
+          subject,
+          message: `Sandbox "${subject}" has no auth status — cannot confirm it can run, and it is not marked local/no-auth.`,
+          nextAction: `Authenticate sandbox "${subject}", or mark it local/no-auth (runLocality: local) if it needs no credential.`
+        });
+      } else {
+        issues.push({
+          severity: "blocker",
+          code: "sandbox_unauthenticated",
+          subject,
+          message: `Sandbox "${subject}" auth status is ${safeString(s.authStatus)}.`,
+          nextAction: `Authenticate sandbox "${subject}" before running.`
+        });
+      }
+    } else if (node.type === "pipelineHealth") {
+      counts.pipelines += 1;
+      const status = safeString(s.status).toLowerCase();
+      if (status === "untested" || s.latestOk === false) {
+        issues.push({
+          severity: status === "untested" ? "warning" : "blocker",
+          code: status === "untested" ? "pipeline_untested" : "pipeline_failing",
+          subject: node.label || node.id,
+          message: `Pipeline "${node.label || node.id}" is ${status || "failing"}.`,
+          nextAction: status === "untested"
+            ? `Run "${node.label || node.id}" once to prove it (POST /api/workspace/sandbox-run).`
+            : `Investigate the last failing run of "${node.label || node.id}".`
+        });
+      }
+    } else if (node.type === "workflow") {
+      counts.workflows += 1;
+      if (safeString(s.lifecycleStatus).toLowerCase() === "draft") {
+        issues.push({
+          severity: "warning",
+          code: "workflow_draft_only",
+          subject: node.label || node.id,
+          message: `Workflow "${node.label || node.id}" is draft-only — durable proof pending.`,
+          nextAction: `Prove "${node.label || node.id}" with a sandbox run, then publish.`
+        });
+      }
+    }
+  }
+
+  for (const extra of Array.isArray(options.extraBlockers) ? options.extraBlockers : []) {
+    if (!extra || !extra.code) continue;
+    issues.push({
+      severity: extra.severity === "warning" ? "warning" : "blocker",
+      code: safeString(extra.code),
+      subject: safeString(extra.subject) || safeString(extra.code),
+      message: safeString(extra.message) || safeString(extra.code),
+      nextAction: extra.nextAction ? safeString(extra.nextAction) : null
+    });
+  }
+
+  issues.sort((a, b) =>
+    (SEVERITY[a.severity] ?? 9) - (SEVERITY[b.severity] ?? 9) ||
+    a.code.localeCompare(b.code) ||
+    a.subject.localeCompare(b.subject)
+  );
+
+  const blocking = issues.filter((i) => i.severity === "blocker");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  const ready = blocking.length === 0;
+
+  // Score: 100 when ready and clean; each blocker −25, each warning −5, floored at 0.
+  const score = Math.max(0, 100 - blocking.length * 25 - warnings.length * 5);
+  const nextAction = (blocking[0]?.nextAction)
+    || (warnings[0]?.nextAction)
+    || (ready ? "Ready — promote/deploy through the governed lane." : null);
+
+  return {
+    kind: APP_READINESS_KIND,
+    version: APP_READINESS_VERSION,
+    appId,
+    ready,
+    score,
+    blocking,
+    warnings,
+    signals: { ...counts, ...(options.extraSignals && typeof options.extraSignals === "object" ? options.extraSignals : {}) },
+    nextAction,
+    summary: summarizeReadiness(appId, ready, blocking, warnings, score)
+  };
+}
+
+function summarizeReadiness(appId, ready, blocking, warnings, score) {
+  const scope = appId ? `App "${appId}"` : "Workspace";
+  if (ready && !warnings.length) return `${scope} is ready to ship (score ${score}).`;
+  if (ready) return `${scope} is ready (score ${score}) with ${warnings.length} warning(s).`;
+  return `${scope} is blocked (score ${score}): ${blocking.length} blocker(s), ${warnings.length} warning(s).`;
+}
+
+export {
+  APP_READINESS_KIND,
+  APP_READINESS_VERSION,
+  deriveAppReadiness,
+  summarizeReadiness
+};

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

@@ -0,0 +1,168 @@
+/**
+ * Growthub Workspace Contract-Compliance V1 — governed-mutation predicate.
+ *
+ * Given a PROPOSED mutation and a role/SKILL contract, derive the set of proofs,
+ * ledgers, and review states that must be satisfied for the mutation to be
+ * legal — and which of those are already satisfied by the supplied evidence.
+ *
+ * This is a PURE PREDICATE over law artifacts the caller already holds (the
+ * contract rules + the evidence gathered from receipts/review state). It reads
+ * NO state itself, writes nothing, and exposes no secrets. It does not widen
+ * any mutation boundary — it only reports what the existing governed lanes
+ * require, the same rules the `governed-workspace-mutation` SKILL encodes:
+ *   - live workflow fields are never PATCHed directly — they need a draft, a
+ *     proving sandbox-run, then publish;
+ *   - dataModel / dashboard mutations need a preflight receipt;
+ *   - anything outside the PATCH allowlist is rejected by construction.
+ *
+ * Default contract (when none supplied) mirrors the shipped boundary so the
+ * predicate is useful out of the box; callers pass a stricter contract per role.
+ */
+
+const CONTRACT_COMPLIANCE_KIND = "growthub-workspace-contract-compliance-v1";
+const CONTRACT_COMPLIANCE_VERSION = 1;
+
+// The permanent PATCH allowlist — the floor every contract inherits.
+const DEFAULT_ALLOWED_FIELDS = ["dashboards", "widgetTypes", "canvas", "dataModel"];
+
+function safeString(value) {
+  if (value == null) return "";
+  return typeof value === "string" ? value : String(value);
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function defaultContract() {
+  return {
+    role: "default",
+    allowedFields: DEFAULT_ALLOWED_FIELDS.slice(),
+    // Field groups that require a recorded preflight receipt before the write.
+    requiresReceiptFor: ["dataModel", "dashboards"],
+    // Field groups that require a human/super-admin review state.
+    requiresReviewFor: [],
+    // Live workflow changes must go draft → sandbox-run proof → publish.
+    liveWorkflowRequiresPublishProof: true
+  };
+}
+
+/**
+ * @param {object} mutation the proposed change.
+ *   `{ changedFields: string[], touchesLiveWorkflow?: boolean, lane?: string }`
+ * @param {object} [contract] role/SKILL contract (see `defaultContract`).
+ * @param {object} [evidence] proof already gathered.
+ *   `{ hasPreflightReceipt?: boolean, hasPublishProof?: boolean, reviewState?: string }`
+ * @returns {object} `{ kind, version, role, compliant, required[], satisfied[], missing[], violations[], nextAction, summary }`
+ */
+function deriveContractCompliance(mutation, contract, evidence = {}) {
+  const rules = { ...defaultContract(), ...(contract && typeof contract === "object" ? contract : {}) };
+  const role = safeString(rules.role) || "default";
+
+  const empty = (warning) => ({
+    kind: CONTRACT_COMPLIANCE_KIND,
+    version: CONTRACT_COMPLIANCE_VERSION,
+    role,
+    compliant: false,
+    required: [],
+    satisfied: [],
+    missing: [],
+    violations: warning ? [{ code: "invalid_input", message: warning }] : [],
+    nextAction: null,
+    summary: warning || "No compliance computed."
+  });
+
+  if (!mutation || typeof mutation !== "object") return empty("mutation missing or malformed");
+
+  const changedFields = asArray(mutation.changedFields).map(safeString).filter(Boolean);
+  const allowed = new Set(asArray(rules.allowedFields).map(safeString));
+  const required = [];
+  const satisfied = [];
+  const missing = [];
+  const violations = [];
+
+  // 1. Allowlist — disallowed fields are a hard violation (rejected by the route).
+  for (const field of changedFields) {
+    if (!allowed.has(field)) {
+      violations.push({
+        code: "field_not_allowed",
+        field,
+        message: `Field "${field}" is outside the PATCH allowlist (${Array.from(allowed).join(", ")}).`
+      });
+    }
+  }
+
+  // 2. Preflight receipt requirement.
+  const receiptGroups = new Set(asArray(rules.requiresReceiptFor).map(safeString));
+  if (changedFields.some((f) => receiptGroups.has(f))) {
+    const req = { code: "preflight_receipt", message: "A recorded patch-preflight receipt is required." };
+    required.push(req);
+    (evidence.hasPreflightReceipt ? satisfied : missing).push(req);
+  }
+
+  // 3. Review state requirement.
+  const reviewGroups = new Set(asArray(rules.requiresReviewFor).map(safeString));
+  if (changedFields.some((f) => reviewGroups.has(f))) {
+    const req = { code: "review_state", message: "A human/super-admin review state is required (e.g. approved)." };
+    required.push(req);
+    const reviewOk = ["approved", "accepted", "merged"].includes(safeString(evidence.reviewState).toLowerCase());
+    (reviewOk ? satisfied : missing).push(req);
+  }
+
+  // 4. Live workflow proof chain.
+  if (mutation.touchesLiveWorkflow && rules.liveWorkflowRequiresPublishProof) {
+    const req = { code: "publish_proof", message: "Live workflow change requires draft → sandbox-run proof → publish." };
+    required.push(req);
+    (evidence.hasPublishProof ? satisfied : missing).push(req);
+  }
+
+  const compliant = violations.length === 0 && missing.length === 0;
+  const nextAction = violations.length
+    ? `Remove disallowed field(s): ${violations.filter((v) => v.code === "field_not_allowed").map((v) => v.field).join(", ") || "see violations"}.`
+    : (missing[0]
+      ? missingNextAction(missing[0])
+      : (compliant ? "Compliant — proceed through the governed PATCH/publish lane." : null));
+
+  return {
+    kind: CONTRACT_COMPLIANCE_KIND,
+    version: CONTRACT_COMPLIANCE_VERSION,
+    role,
+    compliant,
+    required,
+    satisfied,
+    missing,
+    violations,
+    nextAction,
+    summary: summarizeCompliance(role, compliant, required, missing, violations)
+  };
+}
+
+function missingNextAction(req) {
+  switch (req.code) {
+    case "preflight_receipt": return "Run POST /api/workspace/patch/preflight and record the receipt before PATCH.";
+    case "review_state": return "Obtain an approved review state before applying.";
+    case "publish_proof": return "Save a draft, prove it with sandbox-run, then POST /api/workspace/workflow/publish.";
+    default: return `Satisfy: ${req.message}`;
+  }
+}
+
+function summarizeCompliance(role, compliant, required, missing, violations) {
+  if (violations.length) {
+    return `Non-compliant (${role}): ${violations.length} hard violation(s) — ${violations[0].message}`;
+  }
+  if (compliant) {
+    return required.length
+      ? `Compliant (${role}): all ${required.length} requirement(s) satisfied.`
+      : `Compliant (${role}): no governed requirements triggered.`;
+  }
+  return `Non-compliant (${role}): ${missing.length} of ${required.length} requirement(s) unmet.`;
+}
+
+export {
+  CONTRACT_COMPLIANCE_KIND,
+  CONTRACT_COMPLIANCE_VERSION,
+  DEFAULT_ALLOWED_FIELDS,
+  defaultContract,
+  deriveContractCompliance,
+  summarizeCompliance
+};