@growthub/cli 0.13.7 → 0.13.8

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

@@ -521,14 +521,1039 @@ function deriveWorkspaceActivationState(input = {}) {
   return deriveBlankWorkspaceActivationState(safeInput);
 }
 
+// ───────────────────────────────────────────────────────────────────────────
+// Workspace State Lenses — generalize the activation derivation primitive
+// ───────────────────────────────────────────────────────────────────────────
+//
+// The activation layer proved one idea: a delta in the workspace artifact is
+// causal — it re-derives a typed, self-describing "what's next" state. A *lens*
+// is the same primitive aimed at a different slice of the artifact. Every lens
+// is a pure function over the same envelope and emits the same step shape the
+// WorkspaceActivationPanel already renders, so new lenses cost no new UI.
+//
+// Lens output shape (sibling to the activation state):
+//
+//   {
+//     kind:        "growthub-workspace-lens-state-v1"
+//     lensId:      string
+//     title:       string
+//     headline:    string
+//     subheadline: string
+//     complete:    boolean
+//     completedCount / totalCount / nextStepId
+//     steps: [{ id, label, description, status, href, hint?, cta? }]
+//   }
+//
+// Invariants are inherited verbatim from the activation layer: pure derivation,
+// no secrets (booleans/counts only), never throws on partial input, and every
+// `href` routes into an existing workspace surface.
+
+const LENS_STATE_KIND = "growthub-workspace-lens-state-v1";
+const WORKSPACE_STATE_KIND = "growthub-workspace-state-v1";
+const SWARM_PACKET_KIND = "growthub-swarm-condition-packet-v1";
+
+/** Shared step scoring convention used by every lens. */
+function scoreLensSteps(steps) {
+  const required = steps.filter((step) => step.status !== "optional");
+  const totalCount = required.length;
+  const completedCount = required.filter((step) => step.status === "complete").length;
+  const complete = completedCount >= totalCount;
+  const nextStep = steps.find((step) => step.status === "pending" || step.status === "blocked");
+  return { totalCount, completedCount, complete, nextStepId: nextStep ? nextStep.id : null };
+}
+
+/** Collect every sandbox-environment workflow row across the data model. */
+function collectSandboxRows(workspaceConfig) {
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects)
+    ? workspaceConfig.dataModel.objects
+    : [];
+  const rows = [];
+  for (const object of objects) {
+    if (!isPlainObject(object) || object.objectType !== "sandbox-environment") continue;
+    for (const row of listObjectRows(object)) {
+      if (isPlainObject(row)) rows.push(row);
+    }
+  }
+  return rows;
+}
+
+/**
+ * Persistence & runtime-durability lens (roadmap Item 2 — derivation).
+ *
+ * Reads the resolved persistence mode/adapter (surfaced via
+ * metadataGraph.runtime when the server provides it) and whether durable run
+ * evidence exists, then nudges the workspace toward a store where workflow
+ * runs, source records, and agent-swarm evidence survive restart/redeploy.
+ *
+ * The persistence adapters themselves already ship
+ * (lib/adapters/persistence/{postgres,qstash-kv,provider-managed}.js); this
+ * lens is the self-describing activation pathway over them.
+ */
+function derivePersistenceLensState(input = {}) {
+  const cfg = isPlainObject(input?.workspaceConfig) ? input.workspaceConfig : {};
+  const graph = isPlainObject(input?.metadataGraph) ? input.metadataGraph : {};
+  const rt = isPlainObject(graph?.runtime) ? graph.runtime : {};
+
+  const persistenceMode = safeString(rt.persistenceMode).trim() || null; // filesystem|read-only|database
+  const persistenceAdapter = safeString(rt.persistenceAdapter).trim() || null;
+  const allowFsWrite = rt.allowFsWrite === true;
+
+  // Run evidence lives in sandbox-environment object ROWS (canonical shape —
+  // see findWorkflowRow / the project-management seed), not on the object.
+  const sandboxRows = collectSandboxRows(cfg);
+  const hasRunEvidence = sandboxRows.some(
+    (row) => safeString(row.lastResponse).trim() !== "" || safeString(row.lastRunId).trim() !== "",
+  );
+
+  const isDurableDatabase = persistenceMode === "database" && persistenceAdapter !== null;
+  const isDurableFilesystem = persistenceMode === "filesystem" && allowFsWrite;
+  const isDurable = isDurableDatabase || isDurableFilesystem;
+  const isReadOnly = persistenceMode === "read-only"
+    || (persistenceMode === "filesystem" && !allowFsWrite);
+  const modeResolved = persistenceMode !== null;
+
+  const steps = [];
+
+  steps.push({
+    id: "choose-persistence",
+    label: "Choose a persistence mode",
+    description: "Resolve where the workspace stores run state, source records, and agent-swarm evidence.",
+    status: modeResolved ? "complete" : "pending",
+    href: "/settings",
+    cta: modeResolved ? "Review persistence" : "Open persistence settings",
+  });
+
+  if (isDurable) {
+    steps.push({
+      id: "enable-durable-store",
+      label: "Enable a durable store",
+      description: "Runs and agent-swarm evidence are written to a persistent backing store and survive redeploy.",
+      status: "complete",
+      href: "/settings",
+      hint: isDurableDatabase ? `Durable database adapter active (${persistenceAdapter}).` : "Filesystem writes enabled.",
+      cta: "Review store",
+    });
+  } else if (!modeResolved) {
+    steps.push({
+      id: "enable-durable-store",
+      label: "Enable a durable store",
+      description: "Configure a database adapter or enable filesystem writes so run data persists across restarts.",
+      status: "blocked",
+      href: "/settings",
+      hint: "Resolve the persistence mode first — the workspace can't persist runs until a store is chosen.",
+      cta: "Configure persistence",
+    });
+  } else {
+    steps.push({
+      id: "enable-durable-store",
+      label: "Enable a durable store",
+      description: "Persistence is read-only: PATCH returns 409 and run data is held only in-process — it won't survive redeploy.",
+      status: "blocked",
+      href: "/settings",
+      hint: `Mode "${persistenceMode}" is read-only. Switch to "database" or set WORKSPACE_CONFIG_ALLOW_FS_WRITE for filesystem.`,
+      cta: "Switch to a durable store",
+    });
+  }
+
+  if (hasRunEvidence && isDurable) {
+    steps.push({
+      id: "verify-run-durability",
+      label: "Verify run durability",
+      description: "Workflow runs are recorded and the store is durable — evidence will survive redeploy.",
+      status: "complete",
+      href: "/workflows",
+      cta: "Review runs",
+    });
+  } else if (hasRunEvidence && !isDurable) {
+    steps.push({
+      id: "verify-run-durability",
+      label: "Verify run durability",
+      description: "Workflow runs exist but the store is read-only. This evidence is ephemeral and will be lost on redeploy.",
+      status: "blocked",
+      href: "/workflows",
+      hint: "Enable a durable store to preserve the run records you've already produced.",
+      cta: "Review affected runs",
+    });
+  } else {
+    steps.push({
+      id: "verify-run-durability",
+      label: "Verify run durability",
+      description: "After workflows run, this confirms run evidence is persisted to the durable store.",
+      status: "optional",
+      href: "/workflows",
+      cta: "Open workflows",
+    });
+  }
+
+  const { totalCount, completedCount, complete, nextStepId } = scoreLensSteps(steps);
+
+  let headline;
+  let subheadline;
+  if (complete && steps.every((step) => step.status !== "blocked")) {
+    headline = "Workspace persistence is durable.";
+    subheadline = "Run evidence and source records will survive redeploy.";
+  } else if (!modeResolved) {
+    headline = "Persistence mode is not configured.";
+    subheadline = "Next: choose a persistence mode in settings.";
+  } else if (isReadOnly && hasRunEvidence) {
+    headline = "Store is read-only — run evidence is ephemeral.";
+    subheadline = "Next: switch to a durable store to preserve existing runs.";
+  } else if (isReadOnly) {
+    headline = "Store is read-only — runs won't survive redeploy.";
+    subheadline = "Next: enable a durable adapter or allow filesystem writes.";
+  } else {
+    headline = "Durable store active.";
+    subheadline = "Run a workflow to confirm end-to-end durability.";
+  }
+
+  return {
+    kind: LENS_STATE_KIND,
+    lensId: "persistence",
+    title: "Runtime persistence",
+    headline,
+    subheadline,
+    complete,
+    completedCount,
+    totalCount,
+    nextStepId,
+    steps,
+  };
+}
+
+/**
+ * Orchestration-health / observability lens (roadmap Item 3 — derivation).
+ *
+ * Rolls up run-state deltas across every sandbox-environment workflow row into
+ * legible counts (healthy / failing / never-run) and points at the next action
+ * — launch an idle workflow or fix a failing one. This is the surface that
+ * makes an agent swarm's work steerable rather than opaque.
+ */
+function deriveObservabilityLensState(input = {}) {
+  const cfg = isPlainObject(input?.workspaceConfig) ? input.workspaceConfig : {};
+  const graph = isPlainObject(input?.metadataGraph) ? input.metadataGraph : {};
+
+  const rows = collectSandboxRows(cfg);
+  let healthy = 0;
+  let failing = 0;
+  let neverRun = 0;
+  for (const row of rows) {
+    const { status } = deriveLatestRunStatus(row);
+    if (status === "ok") healthy += 1;
+    else if (status === "failed") failing += 1;
+    else neverRun += 1;
+  }
+  const workflowsTotal = rows.length;
+  const agents = Array.isArray(graph?.runtime?.agents) ? graph.runtime.agents.length : 0;
+  const rollup = { workflowsTotal, healthy, failing, neverRun, agents };
+
+  const steps = [
+    {
+      id: "have-workflow",
+      label: "Register a workflow",
+      description: "Add at least one sandbox-environment workflow to begin orchestration.",
+      status: workflowsTotal > 0 ? "complete" : "pending",
+      href: "/workflows",
+      cta: workflowsTotal > 0 ? "Open Workflows" : "New workflow",
+    },
+    {
+      id: "first-healthy-run",
+      label: "Land a healthy run",
+      description: "At least one workflow must complete successfully.",
+      status: healthy > 0 ? "complete" : (workflowsTotal === 0 ? "blocked" : "pending"),
+      href: "/workflows",
+      hint: workflowsTotal === 0 ? "Register a workflow first." : "",
+      cta: healthy > 0 ? "View runs" : "Run a workflow",
+    },
+    {
+      id: "resolve-failures",
+      label: "Resolve failing runs",
+      description: "Every failing workflow should be fixed or disabled.",
+      status: workflowsTotal === 0 ? "pending" : (failing > 0 ? "blocked" : "complete"),
+      href: "/workflows",
+      hint: failing > 0 ? `${failing} workflow${failing === 1 ? " is" : "s are"} failing — open the run trace.` : "",
+      cta: failing > 0 ? "Open failing runs" : "Review",
+    },
+    {
+      id: "launch-next",
+      label: "Launch idle workflows",
+      description: "Kick off any workflow that has never run.",
+      status: neverRun > 0 ? "pending" : (workflowsTotal > 0 ? "complete" : "optional"),
+      href: "/workflows",
+      hint: neverRun > 0 ? `${neverRun} workflow${neverRun === 1 ? " has" : "s have"} never run.` : "",
+      cta: neverRun > 0 ? "Launch workflow" : "Review",
+    },
+  ];
+
+  // Drop empty hints so the rendered panel stays clean.
+  for (const step of steps) {
+    if (!step.hint) delete step.hint;
+  }
+
+  const { totalCount, completedCount, complete, nextStepId } = scoreLensSteps(steps);
+
+  let headline;
+  let subheadline;
+  if (workflowsTotal === 0) {
+    headline = "No workflows registered yet.";
+    subheadline = "Add a workflow to start tracking orchestration health.";
+  } else {
+    const parts = [];
+    if (healthy > 0) parts.push(`${healthy} healthy`);
+    if (failing > 0) parts.push(`${failing} failing`);
+    if (neverRun > 0) parts.push(`${neverRun} never run`);
+    headline = `${workflowsTotal} workflow${workflowsTotal === 1 ? "" : "s"}: ${parts.join(", ")}.`;
+    if (failing > 0) {
+      subheadline = `Next: fix ${failing} failing workflow${failing === 1 ? "" : "s"}.`;
+    } else if (neverRun > 0) {
+      subheadline = `Next: launch ${neverRun} idle workflow${neverRun === 1 ? "" : "s"}.`;
+    } else {
+      subheadline = "All workflows are healthy.";
+    }
+  }
+
+  return {
+    kind: LENS_STATE_KIND,
+    lensId: "observability",
+    title: "Orchestration health",
+    headline,
+    subheadline,
+    complete,
+    completedCount,
+    totalCount,
+    nextStepId,
+    steps,
+    rollup,
+  };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Lens registry + composed workspace state (roadmap Item 1 — the keystone)
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Shared runtime-durability read used by the deploy + app-build lenses. Mirrors
+ * the persistence lens truth table but as a small reusable descriptor.
+ */
+function deriveRuntimeDurability(metadataGraph) {
+  const rt = isPlainObject(metadataGraph?.runtime) ? metadataGraph.runtime : {};
+  const mode = safeString(rt.persistenceMode).trim();
+  const adapter = safeString(rt.persistenceAdapter).trim();
+  const allowFs = rt.allowFsWrite === true;
+  return {
+    mode,
+    adapter,
+    allowFs,
+    resolved: mode !== "",
+    durable: (mode === "database" && adapter !== "") || (mode === "filesystem" && allowFs),
+    readOnly: mode === "read-only" || (mode === "filesystem" && !allowFs),
+  };
+}
+
+/**
+ * Deploy-readiness lens (roadmap Item 5 — derivation).
+ *
+ * Pure derivation over deploy-check-shaped runtime signals
+ * (`metadataGraph.runtime.deploy`) + persistence durability + provenance. It
+ * never shells out and never fetches; it reads whatever safe deploy signal the
+ * runtime already exposes and otherwise emits a pending step into settings.
+ */
+function deriveDeployLensState(input = {}) {
+  const cfg = isPlainObject(input?.workspaceConfig) ? input.workspaceConfig : {};
+  const graph = isPlainObject(input?.metadataGraph) ? input.metadataGraph : {};
+  const rt = isPlainObject(graph?.runtime) ? graph.runtime : {};
+  const deploy = isPlainObject(rt.deploy) ? rt.deploy : {};
+  const provenance = deriveProvenance(cfg);
+  const dur = deriveRuntimeDurability(graph);
+
+  const target = safeString(deploy.target || rt.deployTarget).trim();
+  const surfaceResolved = Boolean(target) || provenance.hasProvenance;
+  const hasEnvSignal = deploy.envReady !== undefined || Array.isArray(deploy.envVarsNeeded);
+  const envReady = deploy.envReady === true
+    || (Array.isArray(deploy.envVarsNeeded) && deploy.envVarsNeeded.length === 0);
+  const checkPassed = deploy.checkPassed === true;
+  const hasCheckSignal = deploy.checkPassed !== undefined;
+  const deployed = deploy.deployed === true;
+
+  const steps = [
+    {
+      id: "resolve-app-surface",
+      label: "Resolve the app surface",
+      description: surfaceResolved
+        ? `Deploy surface resolved${target ? ` (target: ${target})` : ""}.`
+        : "Identify the app surface and deploy target for this workspace.",
+      status: surfaceResolved ? "complete" : "pending",
+      href: "/settings",
+      cta: surfaceResolved ? "Review" : "Open settings",
+    },
+    {
+      id: "verify-env",
+      label: "Verify required env vars",
+      description: envReady
+        ? "All required environment variables are present."
+        : "Confirm the runtime has every required environment variable before deploy.",
+      status: envReady ? "complete" : "pending",
+      href: "/settings",
+      hint: hasEnvSignal && !envReady && Array.isArray(deploy.envVarsNeeded)
+        ? `Missing ${deploy.envVarsNeeded.length} required env var${deploy.envVarsNeeded.length === 1 ? "" : "s"}.`
+        : "",
+      cta: "Open settings",
+    },
+    {
+      id: "verify-persistence",
+      label: "Verify durable persistence",
+      description: dur.durable
+        ? "Persistence is durable — deployed runs will survive redeploy."
+        : "A deploy needs durable persistence so run state isn't lost on redeploy.",
+      status: dur.durable ? "complete" : (dur.readOnly ? "blocked" : "pending"),
+      href: "/settings",
+      hint: dur.durable
+        ? ""
+        : (dur.readOnly
+          ? "Persistence is read-only — switch to a durable store before deploying."
+          : "Resolve a persistence mode first."),
+      cta: "Open persistence",
+    },
+    {
+      id: "run-deploy-check",
+      label: "Run the deploy check",
+      description: checkPassed
+        ? "Deploy check passed."
+        : "Run the deploy check and resolve any missing steps before shipping.",
+      status: checkPassed ? "complete" : (dur.durable ? "pending" : "blocked"),
+      href: "/settings",
+      hint: checkPassed
+        ? ""
+        : (dur.durable
+          ? (hasCheckSignal ? "Deploy check reported missing steps." : "Run the deploy check to surface missing steps.")
+          : "Make persistence durable first."),
+      cta: "Open settings",
+    },
+    {
+      id: "deploy-or-review",
+      label: deployed ? "Review deployment" : "Deploy the app",
+      description: deployed
+        ? "The app is deployed — review the live deployment."
+        : "Once checks pass, deploy the app to your target runtime.",
+      status: deployed ? "complete" : "optional",
+      href: "/settings",
+      cta: deployed ? "Review" : "Deploy",
+    },
+  ];
+  for (const step of steps) {
+    if (!step.hint) delete step.hint;
+  }
+
+  const { totalCount, completedCount, complete, nextStepId } = scoreLensSteps(steps);
+  const headline = complete
+    ? "This workspace is deploy-ready."
+    : (dur.readOnly
+      ? "Deploy blocked — persistence is read-only."
+      : "Get this workspace deploy-ready.");
+  const nextStep = steps.find((s) => s.id === nextStepId);
+  const subheadline = complete
+    ? "Review the live deployment or ship an update."
+    : (nextStep ? `Next: ${nextStep.label.toLowerCase()}.` : "Resolve the remaining deploy steps.");
+
+  return {
+    kind: LENS_STATE_KIND,
+    lensId: "deploy",
+    title: "Deploy readiness",
+    headline,
+    subheadline,
+    complete,
+    completedCount,
+    totalCount,
+    nextStepId,
+    steps,
+  };
+}
+
+/**
+ * Task-management lens (roadmap Item 6 — derivation).
+ *
+ * Pure derivation over governed Data Model rows. Detects a governed task object
+ * (objectType "task" or a task-named custom object) and/or source-backed task
+ * rows (a "task"-named data-source, e.g. the project-management Project Task
+ * Source). Never creates rows and never invents a schema.
+ */
+function deriveTaskLensState(input = {}) {
+  const cfg = isPlainObject(input?.workspaceConfig) ? input.workspaceConfig : {};
+  const objects = Array.isArray(cfg?.dataModel?.objects) ? cfg.dataModel.objects : [];
+  const SYSTEM_TYPES = new Set(["api-registry", "sandbox-environment", "data-source"]);
+  const nameBlob = (o) => `${safeString(o.id)} ${safeString(o.name)} ${safeString(o.label)}`.toLowerCase();
+
+  const taskObject = objects.find((o) => isPlainObject(o) && safeString(o.objectType) === "task")
+    || objects.find((o) => isPlainObject(o)
+      && !SYSTEM_TYPES.has(safeString(o.objectType))
+      && /\btask/.test(nameBlob(o)));
+  const sourceTaskObject = objects.find((o) => isPlainObject(o)
+    && safeString(o.objectType) === "data-source"
+    && /\btask/.test(nameBlob(o)));
+
+  const hasGoverned = Boolean(taskObject);
+  const hasSourceBacked = Boolean(sourceTaskObject);
+  const taskRows = taskObject ? listObjectRows(taskObject) : [];
+  const sourceRows = sourceTaskObject ? listObjectRows(sourceTaskObject) : [];
+  const rowsPresent = taskRows.length > 0 || sourceRows.length > 0;
+  const ownersAssigned = taskRows.some((r) => isPlainObject(r)
+    && safeString(r.owner || r.assignee || r.Assignee || r.status || r.Status).trim() !== "");
+  const blockedTasks = taskRows.some((r) => isPlainObject(r) && /block/i.test(safeString(r.status || r.Status)));
+
+  const taskBoundToView = (Array.isArray(cfg?.dashboards) ? cfg.dashboards : []).some((d) => {
+    const tabs = Array.isArray(d?.tabs) ? d.tabs : [];
+    return tabs.some((t) => (Array.isArray(t?.widgets) ? t.widgets : []).some((w) => {
+      const binding = isPlainObject(w?.config?.binding) ? w.config.binding : {};
+      return taskObject && safeString(binding.objectId).trim() === safeString(taskObject.id).trim();
+    }));
+  });
+
+  const steps = [
+    {
+      id: "create-task-object",
+      label: "Create or connect a task object",
+      description: hasGoverned
+        ? "A governed task object exists in your Data Model."
+        : (hasSourceBacked
+          ? "Source-backed task rows are present — model a governed task object to manage them."
+          : "Add a governed task object (or connect a task source) in the Data Model."),
+      status: hasGoverned ? "complete" : "pending",
+      href: "/data-model",
+      cta: hasGoverned ? "Open Data Model" : "Create task object",
+    },
+    {
+      id: "add-task-rows",
+      label: "Add active tasks",
+      description: rowsPresent
+        ? "Task rows are present."
+        : "Add task rows (or refresh the task source) so there's work to manage.",
+      status: rowsPresent ? "complete" : ((hasGoverned || hasSourceBacked) ? "pending" : "blocked"),
+      href: "/data-model",
+      hint: rowsPresent || hasGoverned || hasSourceBacked ? "" : "Create a task object first.",
+      cta: rowsPresent ? "Review tasks" : "Add tasks",
+    },
+    {
+      id: "assign-owners-status",
+      label: "Assign owners and status",
+      description: ownersAssigned
+        ? "Tasks carry owner/status values."
+        : "Set an owner and status on tasks so the swarm and humans can coordinate.",
+      status: ownersAssigned ? "complete" : (rowsPresent ? "pending" : "blocked"),
+      href: "/data-model",
+      hint: ownersAssigned || rowsPresent ? "" : "Add task rows first.",
+      cta: "Open Data Model",
+    },
+    {
+      id: "resolve-blocked-tasks",
+      label: "Resolve blocked tasks",
+      description: blockedTasks
+        ? "Some tasks are marked blocked — clear them."
+        : "No blocked tasks. This stays quiet until a task is blocked.",
+      status: blockedTasks ? "pending" : "optional",
+      href: "/data-model",
+      cta: blockedTasks ? "Review blocked" : "Review",
+    },
+    {
+      id: "bind-task-view",
+      label: "Bind a task view",
+      description: taskBoundToView
+        ? "A dashboard view is bound to the task object."
+        : "Bind the task object to a View widget so tasks are visible on a dashboard.",
+      status: taskBoundToView ? "complete" : (hasGoverned ? "pending" : "blocked"),
+      href: "/",
+      hint: taskBoundToView || hasGoverned ? "" : "Create a governed task object first.",
+      cta: taskBoundToView ? "Open dashboard" : "Bind view",
+    },
+  ];
+  for (const step of steps) {
+    if (!step.hint) delete step.hint;
+  }
+
+  const { totalCount, completedCount, complete, nextStepId } = scoreLensSteps(steps);
+  const headline = complete
+    ? "Task management is set up."
+    : (hasGoverned || hasSourceBacked ? "Finish wiring task management." : "Set up task management.");
+  const nextStep = steps.find((s) => s.id === nextStepId);
+  const subheadline = complete
+    ? "Humans and the swarm manage tasks on the same surface."
+    : (nextStep ? `Next: ${nextStep.label.toLowerCase()}.` : "Tasks are ready to manage.");
+
+  return {
+    kind: LENS_STATE_KIND,
+    lensId: "tasks",
+    title: "Task management",
+    headline,
+    subheadline,
+    complete,
+    completedCount,
+    totalCount,
+    nextStepId,
+    steps,
+  };
+}
+
+/**
+ * Application-buildout lens (roadmap Item 7 — derivation).
+ *
+ * A readiness lens (it scaffolds nothing) that activates after the primary
+ * activation loop has progress and points from "I have pieces" toward "I have
+ * a deployable application": modeled object → dashboard → workflow → run
+ * evidence → durable persistence → deploy readiness → packaged surface.
+ */
+function deriveAppBuildLensState(input = {}) {
+  const cfg = isPlainObject(input?.workspaceConfig) ? input.workspaceConfig : {};
+  const objects = Array.isArray(cfg?.dataModel?.objects) ? cfg.dataModel.objects : [];
+  const HIDDEN = new Set([
+    "workspace-helper-sandbox", "nav-folders", "helper-threads",
+    "sandbox-environments", "workflow-api-registry", "workspace-ui-cache",
+  ]);
+  const userObjects = objects.filter((o) => isPlainObject(o)
+    && safeString(o.id).trim()
+    && !HIDDEN.has(o.id)
+    && o.objectType !== "api-registry"
+    && o.objectType !== "sandbox-environment");
+  const dashboards = Array.isArray(cfg?.dashboards) ? cfg.dashboards : [];
+  const widgetCount = dashboards.reduce((acc, d) => acc
+    + (Array.isArray(d?.tabs) ? d.tabs : []).reduce((a, t) => a + (Array.isArray(t?.widgets) ? t.widgets : []).length, 0), 0);
+  const sandboxRows = collectSandboxRows(cfg);
+  const workflowCreated = sandboxRows.length > 0;
+  const healthyRun = sandboxRows.some((r) => deriveLatestRunStatus(r).ok);
+
+  const dur = deriveRuntimeDurability(input?.metadataGraph);
+  const deployReady = deriveDeployLensState(input).complete;
+
+  const steps = [
+    {
+      id: "model-object",
+      label: "Model a business object",
+      description: userObjects.length > 0 ? `${userObjects.length} object${userObjects.length === 1 ? "" : "s"} modeled.` : "Model the core business object your app revolves around.",
+      status: userObjects.length > 0 ? "complete" : "pending",
+      href: "/data-model",
+      cta: userObjects.length > 0 ? "Open Data Model" : "Model object",
+    },
+    {
+      id: "build-dashboard",
+      label: "Build a dashboard surface",
+      description: (dashboards.length > 0 && widgetCount > 0) ? "A dashboard with widgets is in place." : "Build a dashboard with at least one bound widget.",
+      status: (dashboards.length > 0 && widgetCount > 0) ? "complete" : (userObjects.length > 0 ? "pending" : "blocked"),
+      href: "/",
+      hint: (dashboards.length > 0 && widgetCount > 0) || userObjects.length > 0 ? "" : "Model an object first.",
+      cta: "Open Builder",
+    },
+    {
+      id: "add-workflow",
+      label: "Add a workflow runtime",
+      description: workflowCreated ? "A workflow runtime is registered." : "Add a workflow so the app can act, not just display.",
+      status: workflowCreated ? "complete" : "pending",
+      href: "/workflows",
+      cta: workflowCreated ? "Open Workflows" : "New workflow",
+    },
+    {
+      id: "land-run",
+      label: "Land run evidence",
+      description: healthyRun ? "A workflow has run successfully." : "Run the workflow at least once to produce evidence.",
+      status: healthyRun ? "complete" : (workflowCreated ? "pending" : "blocked"),
+      href: "/workflows",
+      hint: healthyRun || workflowCreated ? "" : "Add a workflow first.",
+      cta: healthyRun ? "View runs" : "Run workflow",
+    },
+    {
+      id: "durable-persistence",
+      label: "Verify durable persistence",
+      description: dur.durable ? "Persistence is durable." : "Make persistence durable so the app keeps its state.",
+      status: dur.durable ? "complete" : (dur.readOnly ? "blocked" : "pending"),
+      href: "/settings",
+      hint: dur.durable ? "" : (dur.readOnly ? "Persistence is read-only — switch to a durable store." : "Resolve a persistence mode."),
+      cta: "Open persistence",
+    },
+    {
+      id: "deploy-ready",
+      label: "Verify deploy readiness",
+      description: deployReady ? "The app is deploy-ready." : "Clear the deploy-readiness checks.",
+      status: deployReady ? "complete" : "pending",
+      href: "/settings",
+      cta: "Open deploy",
+    },
+    {
+      id: "package-surface",
+      label: "Package the app surface",
+      description: "Export or package the workspace as a distributable application surface.",
+      status: (userObjects.length > 0 && dashboards.length > 0 && workflowCreated && healthyRun && dur.durable && deployReady) ? "pending" : "optional",
+      href: "/settings",
+      cta: "Package app",
+    },
+  ];
+  for (const step of steps) {
+    if (!step.hint) delete step.hint;
+  }
+
+  const { totalCount, completedCount, complete, nextStepId } = scoreLensSteps(steps);
+  const started = userObjects.length > 0 || dashboards.length > 0 || workflowCreated;
+  const headline = complete
+    ? "This workspace is a deployable application."
+    : (started ? "Build this workspace into a full application." : "Start building a full application.");
+  const nextStep = steps.find((s) => s.id === nextStepId);
+  const subheadline = complete
+    ? "Package or export the app surface."
+    : (nextStep ? `Next: ${nextStep.label.toLowerCase()}.` : "Keep assembling the application.");
+
+  return {
+    kind: LENS_STATE_KIND,
+    lensId: "app-build",
+    title: "Application buildout",
+    headline,
+    subheadline,
+    complete,
+    completedCount,
+    totalCount,
+    nextStepId,
+    steps,
+  };
+}
+
+/**
+ * The lens registry. The activation deriver is the `primary` lens (it keeps
+ * its own v1 state kind for backwards compatibility); every other entry is a
+ * secondary lens that plugs into the same panel and the same swarm packet.
+ * Adding a roadmap item is "register a deriver" — no new surface.
+ *
+ * NB: a Fleet / multi-app lens (roadmap Item 4) is intentionally NOT registered
+ * — the exported workspace runtime exposes no in-artifact multi-app surface
+ * registry to derive from. See docs/ROADMAP_IMPACT_ITEMS_V1.md (it stays staged
+ * until a runtime surface-metadata source exists).
+ */
+const WORKSPACE_LENS_REGISTRY = [
+  { id: "activation", title: "Activation", primary: true, derive: deriveWorkspaceActivationState },
+  { id: "persistence", title: "Runtime persistence", primary: false, derive: derivePersistenceLensState },
+  { id: "observability", title: "Orchestration health", primary: false, derive: deriveObservabilityLensState },
+  { id: "deploy", title: "Deploy readiness", primary: false, derive: deriveDeployLensState },
+  { id: "tasks", title: "Task management", primary: false, derive: deriveTaskLensState },
+  { id: "app-build", title: "Application buildout", primary: false, derive: deriveAppBuildLensState },
+];
+
+function getLensEntry(lensId) {
+  return WORKSPACE_LENS_REGISTRY.find((entry) => entry.id === lensId) || null;
+}
+
+/**
+ * Compose every registered lens into a single workspace state and resolve the
+ * one highest-value next action across the whole workspace: prefer the primary
+ * activation step, then fall back to the first incomplete secondary lens.
+ */
+function deriveWorkspaceState(input = {}) {
+  const safeInput = {
+    workspaceConfig: isPlainObject(input.workspaceConfig) ? input.workspaceConfig : {},
+    workspaceSourceRecords: isPlainObject(input.workspaceSourceRecords) ? input.workspaceSourceRecords : {},
+    metadataGraph: isPlainObject(input.metadataGraph) ? input.metadataGraph : null,
+  };
+
+  const primaryEntry = WORKSPACE_LENS_REGISTRY.find((entry) => entry.primary);
+  const primary = primaryEntry.derive(safeInput);
+  const lenses = {};
+  for (const entry of WORKSPACE_LENS_REGISTRY) {
+    if (entry.primary) continue;
+    lenses[entry.id] = entry.derive(safeInput);
+  }
+
+  const stepFromState = (lensId, state) => {
+    if (!state || !state.nextStepId) return null;
+    const step = (state.steps || []).find((s) => s.id === state.nextStepId);
+    if (!step) return null;
+    return { lensId, stepId: step.id, label: step.label, status: step.status, href: step.href || "/" };
+  };
+
+  let nextAction = null;
+  if (!primary.complete) nextAction = stepFromState("activation", primary);
+  if (!nextAction) {
+    for (const entry of WORKSPACE_LENS_REGISTRY) {
+      if (entry.primary) continue;
+      const state = lenses[entry.id];
+      if (state && !state.complete) {
+        nextAction = stepFromState(entry.id, state);
+        if (nextAction) break;
+      }
+    }
+  }
+
+  const complete = primary.complete
+    && WORKSPACE_LENS_REGISTRY.every((entry) => entry.primary || lenses[entry.id].complete);
+
+  return {
+    kind: WORKSPACE_STATE_KIND,
+    version: 1,
+    primary,
+    lenses,
+    nextAction,
+    complete,
+  };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Swarm-assignable condition packet (roadmap Item 8)
+// ───────────────────────────────────────────────────────────────────────────
+
+/** Derive the safe tool surface available to an agent operating this workspace. */
+function deriveAvailableTools(workspaceConfig) {
+  const tools = [
+    "workspace UI (same surfaces a human uses)",
+    "PATCH /api/workspace (dashboards | widgetTypes | canvas | dataModel)",
+  ];
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects)
+    ? workspaceConfig.dataModel.objects
+    : [];
+  const hasRegistry = objects.some((o) => isPlainObject(o) && o.objectType === "api-registry");
+  const hasSandbox = objects.some((o) => isPlainObject(o) && o.objectType === "sandbox-environment");
+  if (hasRegistry) tools.push("Nango proxy (/api/workspace/integrations/nango/proxy)");
+  if (hasSandbox) tools.push("sandbox-run (POST /api/workspace/sandbox-run)");
+  return tools;
+}
+
+/**
+ * Compose any registered lens into the swarm assignment shape: a single
+ * read-only packet that hands an agent (or a swarm) a workspace *condition*
+ * instead of a vague prompt — goal, current state, the blocked step, its
+ * prerequisite, the tools available, and the evidence it must produce. The
+ * human panel and this packet read the identical derived state.
+ */
+function deriveSwarmConditionPacket(input = {}, options = {}) {
+  const safeInput = {
+    workspaceConfig: isPlainObject(input.workspaceConfig) ? input.workspaceConfig : {},
+    workspaceSourceRecords: isPlainObject(input.workspaceSourceRecords) ? input.workspaceSourceRecords : {},
+    metadataGraph: isPlainObject(input.metadataGraph) ? input.metadataGraph : null,
+  };
+  const lensId = safeString(options.lensId).trim() || "activation";
+  const entry = getLensEntry(lensId) || getLensEntry("activation");
+  const state = entry.derive(safeInput);
+  const steps = Array.isArray(state.steps) ? state.steps : [];
+
+  const blocked = steps.find((s) => s.status === "blocked") || null;
+  const nextStep = steps.find((s) => s.id === state.nextStepId) || null;
+  const blockedStep = blocked || nextStep;
+  // The prerequisite is the last completed step before the blocker, surfaced
+  // as guidance (the blocker's own hint already explains *why*).
+  const prerequisite = blockedStep
+    ? (safeString(blockedStep.hint).trim() || "Complete the prior step to unblock this one.")
+    : null;
+
+  return {
+    kind: SWARM_PACKET_KIND,
+    version: 1,
+    lensId: entry.id,
+    goal: safeString(state.headline).trim() || `Activate the ${safeString(state.title || state.templateName).trim()} workspace.`,
+    currentState: `${state.completedCount}/${state.totalCount}`,
+    complete: Boolean(state.complete),
+    nextAction: nextStep
+      ? { stepId: nextStep.id, label: nextStep.label, href: nextStep.href || "/", status: nextStep.status }
+      : null,
+    blockedStep: blockedStep
+      ? { stepId: blockedStep.id, label: blockedStep.label, status: blockedStep.status }
+      : null,
+    prerequisite,
+    availableTools: deriveAvailableTools(safeInput.workspaceConfig),
+    expectedEvidence: [
+      "run record (sandbox-environment row lastResponse)",
+      "hydrated source records",
+      "dashboard rollup reflecting the new state",
+    ],
+  };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Workspace contribution graph (daily-ritual visualization)
+// ───────────────────────────────────────────────────────────────────────────
+//
+// A GitHub-style contribution heatmap derived from the SAME artifact + data
+// flow the lenses read: every dated workspace activity event (workflow run
+// `ranAt`, source-record `fetchedAt`, sandbox `lastTested`) is bucketed by day
+// into a 53-week × 7-day grid with intensity levels 0–4. Pure derivation, no
+// secrets — counts and dates only. This closes the activation loop into an
+// ongoing daily behaviour: open Workspace Lens, see your activity, start work.
+
+const CONTRIBUTIONS_KIND = "growthub-workspace-contributions-v1";
+const CONTRIBUTION_WEEKS = 53;
+
+function toDayKey(value) {
+  const s = safeString(value).trim();
+  if (!s) return "";
+  const d = new Date(s);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toISOString().slice(0, 10);
+}
+
+function dayKeyFromDate(d) {
+  return d.toISOString().slice(0, 10);
+}
+
+function emptyContributionState() {
+  return { kind: CONTRIBUTIONS_KIND, version: 1, total: 0, max: 0, start: "", end: "", weeks: [] };
+}
+
+/**
+ * Derive the workspace contribution grid. Reads dated evidence from the same
+ * inputs as the lenses and never throws on partial input.
+ */
+function deriveWorkspaceContributions(input = {}, options = {}) {
+  const cfg = isPlainObject(input?.workspaceConfig) ? input.workspaceConfig : {};
+  const sources = isPlainObject(input?.workspaceSourceRecords) ? input.workspaceSourceRecords : {};
+
+  const rawDays = [];
+  const add = (value) => {
+    const key = toDayKey(value);
+    if (key) rawDays.push(key);
+  };
+  for (const row of collectSandboxRows(cfg)) {
+    const resp = parseSafe(row.lastResponse);
+    add(resp?.ranAt);
+    add(row.lastRunAt);
+    add(row.ranAt);
+    add(row.lastTested);
+  }
+  for (const key of Object.keys(sources)) {
+    const sidecar = sources[key];
+    if (!isPlainObject(sidecar)) continue;
+    add(sidecar.fetchedAt);
+    if (Array.isArray(sidecar.records)) {
+      for (const record of sidecar.records) {
+        if (!isPlainObject(record)) continue;
+        add(record.fetchedAt);
+        add(record.ranAt);
+        add(record.createdAt);
+      }
+    }
+  }
+
+  const endInput = options.endDate ? new Date(options.endDate) : new Date();
+  if (Number.isNaN(endInput.getTime())) return emptyContributionState();
+  const endUTC = new Date(Date.UTC(endInput.getUTCFullYear(), endInput.getUTCMonth(), endInput.getUTCDate()));
+  // Pad the final column out to Saturday so the grid is week-aligned.
+  const lastCell = new Date(endUTC);
+  lastCell.setUTCDate(endUTC.getUTCDate() + (6 - endUTC.getUTCDay()));
+  const firstCell = new Date(lastCell);
+  firstCell.setUTCDate(lastCell.getUTCDate() - (CONTRIBUTION_WEEKS * 7 - 1));
+
+  // Browser and runtime clocks can disagree around UTC day boundaries. Keep the
+  // GitHub-style mental model: activity that is real but slightly ahead of the
+  // local day still paints the latest visible cell instead of disappearing.
+  const endKey = dayKeyFromDate(endUTC);
+  const byDay = Object.create(null);
+  for (const rawDay of rawDays) {
+    const key = rawDay > endKey ? endKey : rawDay;
+    byDay[key] = (byDay[key] || 0) + 1;
+  }
+
+  const counts = Object.values(byDay);
+  const max = counts.length ? Math.max(...counts) : 0;
+  const levelFor = (count) => {
+    if (count <= 0) return 0;
+    if (max <= 1) return 2;
+    const q = count / max;
+    if (q > 0.75) return 4;
+    if (q > 0.5) return 3;
+    if (q > 0.25) return 2;
+    return 1;
+  };
+
+  let total = 0;
+  const weeks = [];
+  const cursor = new Date(firstCell);
+  for (let w = 0; w < CONTRIBUTION_WEEKS; w += 1) {
+    const days = [];
+    for (let d = 0; d < 7; d += 1) {
+      const date = dayKeyFromDate(cursor);
+      const future = cursor.getTime() > endUTC.getTime();
+      const count = future ? 0 : (byDay[date] || 0);
+      if (!future) total += count;
+      days.push({ date, count, level: future ? 0 : levelFor(count), future });
+      cursor.setUTCDate(cursor.getUTCDate() + 1);
+    }
+    weeks.push({ days });
+  }
+
+  return {
+    kind: CONTRIBUTIONS_KIND,
+    version: 1,
+    total,
+    max,
+    start: dayKeyFromDate(firstCell),
+    end: dayKeyFromDate(endUTC),
+    weeks,
+  };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Workspace Lens first-time walkthrough (one-time guided reveal)
+// ───────────────────────────────────────────────────────────────────────────
+//
+// The walkthrough is the dopamine handoff: it appears ONLY in the in-between
+// state — onboarding complete, Workspace Lens unlocked, but no activity yet
+// (not a power user). Once the workspace shows real activity, or once the user
+// dismisses it (persisted in the same workspace-ui-cache row the onboarding
+// dismiss uses), it never shows again.
+
+const LENS_WALKTHROUGH_DISMISS_FLAG = "lensWalkthroughDismissed";
+
+/** Read a flag from the governed workspace-ui-cache "activation" row. */
+function readUiCacheFlag(workspaceConfig, key) {
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  const cache = objects.find((o) => isPlainObject(o) && o.id === "workspace-ui-cache");
+  const row = cache && Array.isArray(cache.rows)
+    ? cache.rows.find((r) => isPlainObject(r) && r.id === "activation")
+    : null;
+  return row ? row[key] : undefined;
+}
+
+/**
+ * Derive whether the one-time Workspace Lens walkthrough should show.
+ * `show` is true iff: activation complete AND no workspace activity yet AND
+ * not previously dismissed. Pure; never throws.
+ */
+function deriveLensWalkthroughState(input = {}) {
+  const safe = {
+    workspaceConfig: isPlainObject(input.workspaceConfig) ? input.workspaceConfig : {},
+    workspaceSourceRecords: isPlainObject(input.workspaceSourceRecords) ? input.workspaceSourceRecords : {},
+    metadataGraph: isPlainObject(input.metadataGraph) ? input.metadataGraph : null,
+  };
+  const activationComplete = deriveWorkspaceActivationState(safe).complete;
+  const hasActivity = deriveWorkspaceContributions(safe).total > 0;
+  const flag = readUiCacheFlag(safe.workspaceConfig, LENS_WALKTHROUGH_DISMISS_FLAG);
+  const dismissed = flag === true || String(flag || "") === "true";
+  return {
+    kind: "growthub-lens-walkthrough-state-v1",
+    activationComplete,
+    hasActivity,
+    dismissed,
+    show: activationComplete && !hasActivity && !dismissed,
+  };
+}
+
 export {
   ACTIVATION_KIND,
   ACTIVATION_VERSION,
   TEMPLATE_PROJECT_MANAGEMENT,
+  CONTRIBUTIONS_KIND,
+  LENS_WALKTHROUGH_DISMISS_FLAG,
+  readUiCacheFlag,
+  deriveLensWalkthroughState,
+  LENS_STATE_KIND,
+  WORKSPACE_STATE_KIND,
+  SWARM_PACKET_KIND,
   deriveWorkspaceActivationState,
   deriveProjectManagementActivationState,
   deriveBlankWorkspaceActivationState,
   deriveProvenance,
   hasConnectionId,
   hasSourceRecords,
+  // Workspace State Lens registry (roadmap Item 1) + lenses (Items 2, 3, 5, 6, 7)
+  WORKSPACE_LENS_REGISTRY,
+  getLensEntry,
+  deriveWorkspaceState,
+  deriveRuntimeDurability,
+  derivePersistenceLensState,
+  deriveObservabilityLensState,
+  deriveDeployLensState,
+  deriveTaskLensState,
+  deriveAppBuildLensState,
+  // Swarm-assignable condition packet (roadmap Item 8)
+  deriveSwarmConditionPacket,
+  // Workspace contribution graph (daily-ritual visualization)
+  deriveWorkspaceContributions,
 };