@synap-core/workspace-templates 0.6.4 → 0.7.1

package/src/composition-graph.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Unit tests for the `layerTemplateGraph` KEYSTONE engine.
+ * Run: `npx tsx --test src/composition-graph.test.ts`
+ *
+ * These test the SOURCE (`./composition-graph.js` → composition-graph.ts),
+ * never `dist/`, so no build is required and there is no stale-generated-
+ * output trap (same convention as `catalog.test.ts`).
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { layerTemplateGraph, type CompositionGraph } from "./composition-graph.js";
+import type { TemplateDependency } from "./types.js";
+
+/** Build a small `edgesOf` from a plain adjacency map, for test fixtures. */
+function edgesFrom(map: Record<string, TemplateDependency[]>) {
+  return (slug: string): readonly TemplateDependency[] => map[slug] ?? [];
+}
+
+function flat(graph: CompositionGraph): string[] {
+  return graph.layers.flat().map((n) => n.slug);
+}
+
+// ── Longest-path: deeper occurrence wins (bedrock behavior) ────────────────
+test("longest-path: a node required at depth 1 by one root and depth 3 by another lands at the deeper layer", () => {
+  // root-a -> shared (depth 1)
+  // root-b -> mid -> deep -> shared (depth 3)
+  const edgesOf = edgesFrom({
+    "root-a": [{ slug: "shared" }],
+    "root-b": [{ slug: "mid" }],
+    mid: [{ slug: "deep" }],
+    deep: [{ slug: "shared" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["root-a", "root-b"], edgesOf });
+  const shared = graph.nodes.get("shared")!;
+  assert.equal(shared.layer, 3, "shared must sink to the DEEPER of its two reachable depths");
+});
+
+// ── Dedupe / fan-in ──────────────────────────────────────────────────────────
+test("dedupe/fan-in: a node reachable from 6 parents appears ONCE with dependents.length === 6", () => {
+  const parents = Array.from({ length: 6 }, (_, i) => `parent-${i}`);
+  const edgesOf = edgesFrom({
+    root: parents.map((p) => ({ slug: p })),
+    ...Object.fromEntries(parents.map((p) => [p, [{ slug: "foundation" }]])),
+  });
+
+  const graph = layerTemplateGraph({ roots: ["root"], edgesOf });
+  const foundationNodes = [...graph.nodes.values()].filter((n) => n.slug === "foundation");
+  assert.equal(foundationNodes.length, 1, "foundation must appear exactly once in the node map");
+  assert.equal(foundationNodes[0]!.dependents.length, 6, "foundation must carry TRUE fan-in from all 6 parents");
+});
+
+// ── Multi-root ───────────────────────────────────────────────────────────────
+test("multi-root: two roots both reaching a shared node → roots lists both", () => {
+  const edgesOf = edgesFrom({
+    "root-a": [{ slug: "shared" }],
+    "root-b": [{ slug: "shared" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["root-a", "root-b"], edgesOf });
+  const shared = graph.nodes.get("shared")!;
+  assert.deepEqual(shared.roots, ["root-a", "root-b"]);
+});
+
+// ── Compose overlays ─────────────────────────────────────────────────────────
+test("compose: a relation:compose dep appears in the base's overlays[] and NOT in layers", () => {
+  // `grants` composes onto `operations` — mirrors the real grants.yaml/operations.yaml pair.
+  const edgesOf = edgesFrom({
+    grants: [{ slug: "operations", relation: "compose", reason: "overlay" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["grants"], edgesOf });
+
+  const operations = graph.nodes.get("operations")!;
+  assert.ok(operations, "operations (the base) must be a real node");
+  assert.deepEqual(
+    operations.overlays.map((o) => o.slug),
+    ["grants"],
+    "the compose source must be attached as an overlay on the base"
+  );
+
+  assert.equal(graph.nodes.has("grants"), false, "the compose SOURCE must never be its own node");
+  assert.ok(!flat(graph).includes("grants"), "the compose source must never appear in layers[][]");
+
+  const composeEdge = graph.edges.find((e) => e.from === "grants" && e.to === "operations");
+  assert.ok(composeEdge, "the compose edge must still be recorded in edges[]");
+  assert.equal(composeEdge!.relation, "compose");
+});
+
+// ── Ghost nodes ──────────────────────────────────────────────────────────────
+test("ghost: an uninstalled dep is present with installed:false", () => {
+  const edgesOf = edgesFrom({
+    root: [{ slug: "not-installed-yet" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["root"], edgesOf, installed: [] });
+  const ghost = graph.nodes.get("not-installed-yet")!;
+  assert.equal(ghost.installed, false);
+  assert.deepEqual(ghost.workspaceIds, []);
+  // The gap IS the information: it still occupies its layer.
+  assert.equal(graph.layers[ghost.layer]!.some((n) => n.slug === "not-installed-yet"), true);
+});
+
+// ── Cycles ───────────────────────────────────────────────────────────────────
+test("cycle: A→B→A terminates and reports the broken edge in cycles[]", () => {
+  const edgesOf = edgesFrom({
+    A: [{ slug: "B" }],
+    B: [{ slug: "A" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["A"], edgesOf });
+
+  assert.equal(graph.cycles.length, 1);
+  assert.deepEqual(graph.cycles[0], ["B", "A"]);
+
+  // Still terminates and produces a usable graph.
+  assert.ok(graph.nodes.has("A"));
+  assert.ok(graph.nodes.has("B"));
+  assert.equal(graph.nodes.get("A")!.layer, 0);
+});
+
+// ── edgesOf injection ─────────────────────────────────────────────────────────
+test("edgesOf injection: deps supplied for a slug NOT in the bundled map are still walked", () => {
+  // "private-remote-pkg" does not exist in the bundled WORKSPACE_TEMPLATES map
+  // at all — this is the live bug rule 5 fixes: a caller-supplied edgesOf must
+  // still be able to walk it.
+  const edgesOf = edgesFrom({
+    "private-remote-pkg": [{ slug: "some-base", relation: "require" }],
+  });
+
+  const graph = layerTemplateGraph({ roots: ["private-remote-pkg"], edgesOf });
+  assert.ok(graph.nodes.has("some-base"), "a dependency declared only by the injected edgesOf must still be walked");
+  assert.equal(graph.nodes.get("some-base")!.layer, 1);
+});

package/src/composition-graph.ts

@@ -0,0 +1,298 @@
+/**
+ * layerTemplateGraph — the KEYSTONE composition-graph engine.
+ * ============================================================
+ *
+ * Today the CLI (`synap-cli/src/commands/market.ts` `buildCompositionTrees`)
+ * renders template composition as a nested TREE: `buildDependencyNode`
+ * rebuilds a fresh `TreeNode` for every OCCURRENCE of a slug on every path, so
+ * a widely-required base (e.g. `foundation`) prints once per branch that
+ * reaches it (6× under a suite like `enterprise-os`). Its "shared" tag is only
+ * top-level-package granularity — there is no true fan-in count.
+ *
+ * This module replaces that with a LAYERED DAG: every node appears EXACTLY
+ * ONCE, positioned at its longest-path depth, with edges converging on it —
+ * so `foundation` sinks to the bedrock row with N inbound edges instead of
+ * being redrawn N times. It is the single source of truth for template
+ * composition; the CLI, browser dialogs, backend boot-ordering, and (later)
+ * the Atlas all consume it.
+ *
+ * PURE + TRANSPORT-AGNOSTIC (same discipline as `catalog.ts`): this is the
+ * ONLY module `synap-cli`, `browser`, `synap-control-plane-api`, and
+ * `synap-backend` can all resolve. No React, no dagre/d3, no fetch, no
+ * Node-only APIs. Pixel layout lives elsewhere (browser-only) — this module
+ * only computes topology (layers + edges + memoized nodes), never coordinates.
+ *
+ * CONSUMES drift, never recomputes it: `installed` / `updates` are read
+ * straight off `catalog.ts`'s `InstalledTemplate`-shaped rows and
+ * `computeTemplateUpdates()` output — this module does no semver comparison
+ * of its own.
+ */
+
+import type { TemplateDependency } from "./types.js";
+import { getWorkspaceTemplate } from "./templates.js";
+import type { TemplateUpdateCheck } from "./catalog.js";
+
+// ============================================================================
+// Inputs
+// ============================================================================
+
+/**
+ * An installed template row, keyed by slug — the shape this engine needs to
+ * mark a node `installed` and populate `workspaceIds`.
+ *
+ * NOTE ON NAMING: `catalog.ts`'s `InstalledTemplate` is `{ slug, version }`
+ * only — it was built for `computeTemplateUpdates`'s narrower need (a version
+ * to diff) and carries no `workspaceId`. `CompositionNode.workspaceIds` is
+ * part of the ratified API and cannot be populated from that shape, so this
+ * is a REAL conflict, not a preference: this module declares its own,
+ * slightly richer row instead of importing `catalog.ts`'s `InstalledTemplate`
+ * under that name. Every field of `catalog.ts`'s `InstalledTemplate` is a
+ * subset of this one, so a caller building `InstalledTemplate[]` for
+ * `computeTemplateUpdates` can build ONE array of `CompositionInstalledEntry`
+ * and pass it to both doors.
+ */
+export interface CompositionInstalledEntry {
+  slug: string;
+  workspaceId: string;
+  workspaceName?: string;
+  /** `settings.packageVersion`, when the pod stamped one. Omit when unknown. */
+  version?: string;
+}
+
+/** One compose-relation dependency, attached to the BASE node it overlays onto. */
+export interface CompositionOverlay {
+  slug: string;
+  name: string;
+  installed: boolean;
+}
+
+/** One edge in the raw dependency graph, exactly as declared (kept even when broken by a cycle). */
+export interface CompositionEdge {
+  from: string;
+  to: string;
+  relation: "compose" | "require";
+  depKind?: string;
+}
+
+export interface CompositionNode {
+  slug: string;
+  name: string;
+  /** Longest-path depth: `1 + max(layer of every node that depends on this one)`. Roots = 0, bedrock = max. */
+  layer: number;
+  /** TRUE fan-in — every slug (node or compose-only overlay source) that declares a dependency on this one. */
+  dependents: string[];
+  /** Which of the input `roots` transitively reach this node (self-inclusive for a root). */
+  roots: string[];
+  installed: boolean;
+  workspaceIds: string[];
+  installedVersion?: string;
+  latestVersion?: string | null;
+  updateAvailable: boolean;
+  noVersionInfo: boolean;
+  /** `compose`-relation deps that overlay onto THIS node (see rule 2 — the overlay source itself is never a layer node). */
+  overlays: CompositionOverlay[];
+}
+
+export interface CompositionGraph {
+  nodes: Map<string, CompositionNode>;
+  edges: CompositionEdge[];
+  /** `layers[0]` = roots … `layers[n]` = bedrock. Compose-overlay SOURCES never appear here (rule 2). */
+  layers: CompositionNode[][];
+  /** Broken back-edges `[from, to]` — surfaced, never silently swallowed (rule 4). */
+  cycles: string[][];
+}
+
+export interface LayerTemplateGraphInput {
+  /** Top-level slugs to walk from. Always land at `layer: 0`. */
+  roots: string[];
+  /** INJECTED edge source (rule 5) — never hardcoded to the bundled map. See `bundledEdgesOf`. */
+  edgesOf: (slug: string) => readonly TemplateDependency[];
+  nameOf?: (slug: string) => string | undefined;
+  installed?: CompositionInstalledEntry[];
+  updates?: TemplateUpdateCheck[];
+}
+
+/**
+ * Default `edgesOf` — reads `dependencies[]` off the BUNDLED template map
+ * only. This is what the current CLI walker is hardcoded to, which is
+ * precisely the live bug rule 5 fixes: a remote/private CP-only package's
+ * `definition.dependencies` are invisible to it, so its subtree silently
+ * renders empty. Callers with a remote catalog entry available should pass
+ * their OWN `edgesOf` that falls back to `entry.remote.definition.dependencies`
+ * (or similar) for slugs this default can't see.
+ */
+export function bundledEdgesOf(slug: string): readonly TemplateDependency[] {
+  return getWorkspaceTemplate(slug)?.dependencies ?? [];
+}
+
+// ============================================================================
+// The engine
+// ============================================================================
+
+export function layerTemplateGraph(input: LayerTemplateGraphInput): CompositionGraph {
+  const { roots, edgesOf } = input;
+  const nameOf = input.nameOf ?? (() => undefined);
+  const rootSet = new Set(roots);
+
+  const installedBySlug = new Map<string, CompositionInstalledEntry[]>();
+  for (const entry of input.installed ?? []) {
+    const list = installedBySlug.get(entry.slug);
+    if (list) list.push(entry);
+    else installedBySlug.set(entry.slug, [entry]);
+  }
+  const updatesBySlug = new Map((input.updates ?? []).map((u) => [u.slug, u]));
+
+  // ── Phase 1: discovery — walk every root, global memo (rule 1) ───────────
+  const edges: CompositionEdge[] = [];
+  const cycles: string[][] = [];
+  /** Every edge target/source touched, whether or not it ends up a layer node. */
+  const touched = new Set<string>(roots);
+  /** dependent -> Set(dependency) for EVERY edge (both relations) — reachability adjacency. */
+  const adjacency = new Map<string, Set<string>>();
+  /** dependency -> Set(dependent) for every NON-broken edge (both relations) — true fan-in + layering DP. */
+  const dependentsMap = new Map<string, Set<string>>();
+  /** Compose-relation edges, kept separately to build overlays + the node-exclusion set. */
+  const composeEdges: Array<{ from: string; to: string; depKind?: string }> = [];
+  /** A slug's `edgesOf` has already been walked — prevents re-expanding a shared node's children (rule 1). */
+  const discovered = new Set<string>();
+
+  function addAdjacency(from: string, to: string): void {
+    const set = adjacency.get(from);
+    if (set) set.add(to);
+    else adjacency.set(from, new Set([to]));
+  }
+
+  function addDependent(dependency: string, dependent: string): void {
+    const set = dependentsMap.get(dependency);
+    if (set) set.add(dependent);
+    else dependentsMap.set(dependency, new Set([dependent]));
+  }
+
+  function walk(slug: string, ancestors: Set<string>): void {
+    const deps = edgesOf(slug) ?? [];
+    for (const dep of deps) {
+      const relation: "compose" | "require" = dep.relation ?? "require";
+      touched.add(dep.slug);
+
+      if (ancestors.has(dep.slug)) {
+        // Broken back-edge — surfaced, not swallowed (rule 4). Still recorded
+        // in `edges` (the honest picture of what was declared), but excluded
+        // from `dependentsMap`/`adjacency` so it can't loop the DP/BFS below.
+        cycles.push([slug, dep.slug]);
+        edges.push({ from: slug, to: dep.slug, relation, depKind: dep.kind });
+        continue;
+      }
+
+      edges.push({ from: slug, to: dep.slug, relation, depKind: dep.kind });
+      addAdjacency(slug, dep.slug);
+      addDependent(dep.slug, slug);
+      if (relation === "compose") {
+        composeEdges.push({ from: slug, to: dep.slug, depKind: dep.kind });
+      }
+
+      if (!discovered.has(dep.slug)) {
+        discovered.add(dep.slug);
+        const nextAncestors = new Set(ancestors);
+        nextAncestors.add(slug);
+        walk(dep.slug, nextAncestors);
+      }
+    }
+  }
+
+  for (const root of roots) {
+    if (discovered.has(root)) continue;
+    discovered.add(root);
+    walk(root, new Set([root]));
+  }
+
+  // ── Phase 2: compose-relation sources are never layer nodes (rule 2) ─────
+  const composeSources = new Set(composeEdges.map((e) => e.from));
+  const overlaysByBase = new Map<string, CompositionOverlay[]>();
+  for (const e of composeEdges) {
+    const isInstalled = installedBySlug.has(e.from);
+    const overlay: CompositionOverlay = { slug: e.from, name: nameOf(e.from) ?? e.from, installed: isInstalled };
+    const list = overlaysByBase.get(e.to);
+    if (list) list.push(overlay);
+    else overlaysByBase.set(e.to, [overlay]);
+  }
+
+  // ── Phase 3: which touched slugs are real layer nodes ────────────────────
+  const nodeSlugs = [...touched].filter((s) => !composeSources.has(s)).sort();
+
+  // ── Phase 4: reachability — which input roots reach each slug ────────────
+  const rootsReaching = new Map<string, Set<string>>();
+  for (const root of roots) {
+    const visited = new Set<string>([root]);
+    const queue: string[] = [root];
+    const addReach = (s: string) => {
+      const set = rootsReaching.get(s);
+      if (set) set.add(root);
+      else rootsReaching.set(s, new Set([root]));
+    };
+    addReach(root);
+    while (queue.length) {
+      const cur = queue.shift()!;
+      for (const next of adjacency.get(cur) ?? []) {
+        if (visited.has(next)) continue;
+        visited.add(next);
+        addReach(next);
+        queue.push(next);
+      }
+    }
+  }
+
+  // ── Phase 5: longest-path layering (rule 1) ───────────────────────────────
+  // layer(n) = 1 + max(layer of every node that depends on n); roots = 0.
+  // Works for ANY slug (node or compose-only overlay source) so a compose
+  // source's OWN layer still feeds the DP for the base it composes onto —
+  // e.g. `grants` (excluded from `nodes`) still positions `operations` one
+  // layer below wherever `grants` itself sits.
+  const layerMemo = new Map<string, number>();
+  function layerOf(slug: string, stack: Set<string>): number {
+    if (rootSet.has(slug)) return 0;
+    const memoized = layerMemo.get(slug);
+    if (memoized !== undefined) return memoized;
+    if (stack.has(slug)) return 0; // defensive — cycle edges are already excluded from dependentsMap
+    stack.add(slug);
+    const dependents = dependentsMap.get(slug);
+    const layer = !dependents || dependents.size === 0
+      ? 0
+      : 1 + Math.max(...[...dependents].map((d) => layerOf(d, stack)));
+    stack.delete(slug);
+    layerMemo.set(slug, layer);
+    return layer;
+  }
+
+  // ── Phase 6: build nodes ──────────────────────────────────────────────────
+  const nodes = new Map<string, CompositionNode>();
+  for (const slug of nodeSlugs) {
+    const installedEntries = installedBySlug.get(slug) ?? [];
+    const workspaceIds = installedEntries.map((e) => e.workspaceId).filter(Boolean);
+    const installed = workspaceIds.length > 0;
+    const update = updatesBySlug.get(slug);
+    const installedVersion = update?.installedVersion || installedEntries[0]?.version;
+    const noVersionInfo = installed && (update === undefined || update.latestVersion === undefined);
+
+    nodes.set(slug, {
+      slug,
+      name: nameOf(slug) ?? slug,
+      layer: layerOf(slug, new Set()),
+      dependents: [...(dependentsMap.get(slug) ?? [])].sort(),
+      roots: [...(rootsReaching.get(slug) ?? [])].sort(),
+      installed,
+      workspaceIds,
+      installedVersion,
+      latestVersion: update?.latestVersion ?? null,
+      updateAvailable: update?.updateAvailable ?? false,
+      noVersionInfo,
+      overlays: overlaysByBase.get(slug) ?? [],
+    });
+  }
+
+  const maxLayer = Math.max(0, ...[...nodes.values()].map((n) => n.layer));
+  const layers: CompositionNode[][] = Array.from({ length: maxLayer + 1 }, () => []);
+  for (const node of nodes.values()) layers[node.layer].push(node);
+  for (const bucket of layers) bucket.sort((a, b) => a.slug.localeCompare(b.slug));
+
+  return { nodes, edges, layers, cycles };
+}

package/src/crm.yaml

@@ -1,8 +1,8 @@
 # CRM workspace template
 # The CRM owns pre-sale work only. A won deal is handed to the operating
 # workspace; this template deliberately does not provision client delivery,
-# campaigns, tasks, documents, or automations. It DOES seed funnel playbooks
-# (the action layer) so the pipeline is operable via sessions — see `playbooks:`.
+# campaigns, tasks, documents, automations, or sales-specific playbooks. A
+# use-case overlay (for example `business-developer`) may add those workflows.
 
 meta:
   slug: crm
@@ -17,6 +17,20 @@ meta:
     - contacts
   isPublic: true
 
+# SSOT ordering guarantee — this template REFERENCES foundation's pod-wide
+# shared `client`/`partner`/`lead`/`churned` roles below. The apply engine seeds
+# a shared profile's pod-wide BASE property body from whichever template
+# creates it FIRST, and adds a REUSING template's extra props as workspace
+# OVERLAYS. Requiring foundation makes the resolver install it first
+# (deps-first), so the base is always foundation's SSOT body and never this
+# template's. `require`, not `compose`: foundation is a real workspace, not an
+# overlay.
+dependencies:
+  - slug: foundation
+    kind: workspace
+    relation: require
+    reason: "Provides the pod-wide client/partner/lead/churned role vocabulary this workspace reuses."
+
 workspace:
   name: CRM
   description: A focused pre-sale workspace for contacts, companies, and deals.
@@ -407,67 +421,33 @@ entityLinks:
     targetProfileSlug: deal
     type: linked_to_deal
 
-# Playbooks — session templates seeded with the workspace. The CRM's action layer.
-# `subjectProfile` binds each playbook to a funnel subject so the Capture → Session
-# matcher (`playbooks.matchForEntity`, filtering `subject_profile->>'profileSlug'`)
-# can offer it when that subject is captured — a captured lead surfaces "Enrich this
-# lead" / "Qualify this lead"; a deal surfaces "Work this deal". The subject entity
-# is passed as the matching entity param and substituted into the goalTemplate.
-#
-# Two subjects are used: `lead` (a shared ROLE facet on a person/company — the same
-# facet-role subject pattern ecosystem.yaml uses for `competitor`) and `deal` (a
-# primary CRM kind). The matcher keys purely on the profileSlug string, so a role
-# facet and a kind are matched identically.
-#
-# No `grants:` on "Enrich this lead": enrichment tools (Apify/Unipile-LinkedIn) are
-# workspace-conditional and may not be granted, so the goalTemplate context-injects
-# the intent and the session agent uses whatever enrichment capability the workspace
-# actually has — mirroring how "Produce Content" (content-os) grants nothing and
-# leans on the workspace's tools, rather than hardcoding a tool that might be absent.
+# Playbook — enriches a lead/prospect from public sources (company site,
+# LinkedIn, firmographic signal) so ICP scoring and qualification start from
+# real data instead of a blank record. Bound to `lead` so a newly captured
+# lead can offer this as a session.
 playbooks:
-  - name: Enrich this lead
-    description: Take a thin, freshly-captured lead and fill it out — company, title, LinkedIn, and the relationships around it.
+  - name: Enrich Lead/Company
+    description: Enrich a lead or company from public sources — firmographics, company size, and recent signal — to sharpen ICP scoring and qualification.
     goalTemplate: >-
-      Enrich this lead ({lead}). Starting from whatever is known, fill out the
-      missing detail — company, job title, LinkedIn URL, location, and the people
-      and companies around them — and record it on the lead. Draw on whatever
-      enrichment capability this workspace has connected (e.g. an Apify or
-      Unipile/LinkedIn tool); if none is available, enrich from the public web and
-      what is already in the pod. Link the lead to its company and any related
-      contacts, and note where information is still missing.
+      Enrich {target} using public sources. Scrape their website and LinkedIn
+      presence (via Apify) for firmographics: company size, industry, location,
+      and any recent signal (funding, hiring, product launches). Fill in the
+      missing profile fields (industry, companySize, location, icpScore) with
+      what you find, and note anything that changes qualification. Do not
+      fabricate — leave a field blank rather than guess.
     subjectProfile:
       profileSlug: lead
     params:
-      - { name: lead, type: entity, label: Lead, required: true }
+      - { name: target, type: entity, label: Lead or company, required: true }
     executor: is-agent
+    grants:
+      - apify_run_actor
+      - entity.create
     status: active
 
-  - name: Qualify this lead
-    description: Assess a lead against the ICP, score the fit, and decide the next step — advance, nurture, or disqualify.
-    goalTemplate: >-
-      Qualify this lead ({lead}). Assess how well they fit our ideal customer
-      profile — company, role, industry, size, and the signals of intent or need —
-      and set an ICP score. Decide the next step: advance them toward a deal,
-      keep nurturing, or disqualify. Write the reasoning and the decision back onto
-      the lead (its stage, score, and next step) so the call is auditable.
-    subjectProfile:
-      profileSlug: lead
-    params:
-      - { name: lead, type: entity, label: Lead, required: true }
-    executor: is-agent
-    status: active
-
-  - name: Work this deal
-    description: Move a deal toward Won — read the current stage, find the blocker, and propose the next step and owner.
-    goalTemplate: >-
-      Work this deal ({deal}) toward Won. Assess where it stands — its current
-      stage, value, and close date — and identify the single thing blocking it from
-      advancing. Propose the concrete next step, who owns it, and by when, and
-      update the deal's next step accordingly. If the stage should change, say so
-      and why.
-    subjectProfile:
-      profileSlug: deal
-    params:
-      - { name: deal, type: entity, label: Deal, required: true }
-    executor: is-agent
-    status: active
+# Apify powers the enrichment playbook (scrape public sources for a lead's
+# firmographics). Composed pod-wide at provisioning via the existing
+# integrations door; the user supplies the Apify API key once on install — a
+# missing key fails gracefully per-skill, not the whole workspace.
+integrations:
+  - templateKey: apify

package/src/define.flow-automations.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { toWorkspaceDefinition } from "./define.js";
+import type { WorkspaceYaml } from "./types.js";
+
+const workflowTemplate: WorkspaceYaml = {
+  meta: {
+    slug: "workflow-contract-test",
+    name: "Workflow contract test",
+    description: "Test template",
+    icon: "workflow",
+    color: "blue",
+  },
+  workspace: { name: "Workflow contract test", description: "Test" },
+  profiles: [],
+  automations: [
+    {
+      name: "A manual workflow",
+      triggerType: "manual",
+      flow: {
+        nodes: [{ id: "trigger", type: "trigger" }],
+        edges: [],
+        precondition: "trigger.payload.ready === true",
+      },
+    },
+  ],
+  actionPlacements: [
+    {
+      profileSlug: "person",
+      surface: "entity-detail",
+      kind: "automation",
+      ref: "A manual workflow",
+      label: "Run workflow",
+      when: {
+        requiredFacetSlugs: ["lead"],
+        propertyEquals: { stage: "ready" },
+      },
+      confirmation: { title: "Continue?", confirmLabel: "Run" },
+    },
+  ],
+};
+
+describe("toWorkspaceDefinition flow automations", () => {
+  it("keeps graph workflows distinct from legacy loop automations", () => {
+    const { definition } = toWorkspaceDefinition(workflowTemplate);
+
+    expect(definition.flowAutomations).toEqual([
+      expect.objectContaining({
+        name: "A manual workflow",
+        triggerType: "manual",
+        flowDefinition: expect.objectContaining({
+          precondition: "trigger.payload.ready === true",
+        }),
+      }),
+    ]);
+    expect("automations" in definition).toBe(false);
+  });
+
+  it("preserves action applicability and confirmation policy", () => {
+    const { definition } = toWorkspaceDefinition(workflowTemplate);
+    expect(definition.actionPlacements?.[0]).toMatchObject({
+      when: { requiredFacetSlugs: ["lead"], propertyEquals: { stage: "ready" } },
+      confirmation: { title: "Continue?", confirmLabel: "Run" },
+    });
+  });
+});