@synap-core/workspace-templates 0.9.3 → 0.10.0

package/src/corpus-flow-validity.test.ts

@@ -0,0 +1,130 @@
+/**
+ * CORPUS guard: every automation flow we SHIP must pass `validateFlowDefinition`.
+ *
+ * Why this file exists. `validateTemplate` has called `validateFlowDefinition`
+ * for a while (`validate.ts:588`), and the package had 83 passing tests — yet
+ * `operations.yaml`'s "Pick up handed-off clients" shipped with four write nodes
+ * orphaned outside their loop body, creating entities and relations with EMPTY
+ * ids on every run of every pod that installed it. The rule existed and the
+ * validator was wired; nothing ever ran the two together over the real corpus.
+ * A validator no test points at the shipped data is a validator that only ever
+ * checks fixtures.
+ *
+ * So this reads the SAME YAML the build reads (`readYamlTemplates`, the source
+ * the generator consumes — not `templates.ts`, which is generated output and
+ * could drift) and asserts the shipped flows are clean. It fails loudly with the
+ * per-node messages, because "which node, and why" is the whole value.
+ */
+
+import { test } from "vitest";
+import assert from "node:assert/strict";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readYamlTemplates } from "./generate.mjs";
+import { validateFlowDefinition } from "./validate-flow.js";
+
+interface ShippedAutomation {
+  readonly key?: string;
+  readonly name?: string;
+  readonly flow?: unknown;
+}
+
+test("corpus: every shipped automation flow passes validateFlowDefinition", () => {
+  const templates = readYamlTemplates();
+  const failures: string[] = [];
+  let flowsChecked = 0;
+
+  // `readYamlTemplates()` yields `{ file, slug, data }` — the parsed YAML is
+  // under `data`, NOT spread onto the entry.
+  for (const entry of templates) {
+    const { slug, data } = entry as {
+      slug?: string;
+      data?: { automations?: ShippedAutomation[] };
+    };
+    const automations = data?.automations;
+    if (!Array.isArray(automations)) continue;
+
+    for (const automation of automations) {
+      if (!automation?.flow) continue;
+      flowsChecked++;
+      const { valid, errors } = validateFlowDefinition(automation.flow);
+      if (valid) continue;
+      const label = automation.key ?? automation.name ?? "<unnamed>";
+      for (const error of errors) {
+        failures.push(
+          `${slug ?? "<template>"} › ${label} › ` +
+            `${error.nodeId ?? "-"} [${error.code}] ${error.message}`
+        );
+      }
+    }
+  }
+
+  // Guard the guard: if the corpus ever stops yielding flows (a rename in
+  // `readYamlTemplates`, a schema move), this test would "pass" while checking
+  // nothing — the exact failure mode it was written to prevent.
+  assert.ok(
+    flowsChecked > 0,
+    "no automation flows found in the shipped corpus — this guard is checking nothing"
+  );
+
+  assert.deepEqual(
+    failures,
+    [],
+    `shipped automation flows failed validation:\n  ${failures.join("\n  ")}`
+  );
+});
+
+// ── The SECOND corpus: Control-Plane capability seeds ────────────────────────
+// The YAML sweep above was written after a shipped workspace template was found
+// writing entities with empty ids. It did not catch the IDENTICAL defect in
+// `client-comms-report.capability.json`, because that flow lives in a different
+// repo, in JSON, and nothing pointed a validator at it. Same bug, same week,
+// missed for the same reason: a corpus nobody sweeps.
+//
+// These seeds ship automations verbatim into user pods, so they are held to the
+// same contract. Skips when the CP checkout is absent, like the drift guards.
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CP_SEEDS = join(
+  HERE,
+  "../../../../synap-control-plane-api/src/seeds/capability-templates",
+);
+
+test("corpus: every CP capability seed's automation flow passes validateFlowDefinition", (t) => {
+  if (!existsSync(CP_SEEDS)) {
+    t.skip();
+    return;
+  }
+  const failures: string[] = [];
+  let flowsChecked = 0;
+
+  for (const file of readdirSync(CP_SEEDS).filter((f) => f.endsWith(".json"))) {
+    const seed = JSON.parse(readFileSync(join(CP_SEEDS, file), "utf8")) as {
+      automations?: Array<{ key?: string; name?: string; flowDefinition?: unknown }>;
+    };
+    for (const automation of seed.automations ?? []) {
+      if (!automation?.flowDefinition) continue;
+      flowsChecked++;
+      const { valid, errors } = validateFlowDefinition(automation.flowDefinition);
+      if (valid) continue;
+      const label = automation.key ?? automation.name ?? "<unnamed>";
+      for (const error of errors) {
+        failures.push(
+          `${file} › ${label} › ${error.nodeId ?? "-"} [${error.code}] ${error.message}`,
+        );
+      }
+    }
+  }
+
+  // Same self-guard as above: a rename in the seed shape must fail loudly
+  // rather than silently sweep nothing.
+  assert.ok(
+    flowsChecked > 0,
+    "no automation flows found in the CP capability seeds — this guard is checking nothing",
+  );
+  assert.deepEqual(
+    failures,
+    [],
+    `CP capability seed flows failed validation:\n  ${failures.join("\n  ")}`,
+  );
+});

package/src/crm.yaml

@@ -18,13 +18,13 @@ meta:
     - contacts
   isPublic: true
 
-# Canonical hosted surface. Browser resolves auth from appId and launches this
-# URL with non-secret workspace/Pod context; CRM establishes its own session.
-app:
-  kind: url
-  appId: crm
-  url: https://crm.synap.live
-  title: CRM
+# CRM is a website, so Browser opens it in its normal first-party web session.
+# It deliberately does not use the SDK-hosted iframe/auth-broker path.
+layout:
+  primarySurface:
+    kind: url
+    url: https://crm.synap.live
+    title: CRM
 
 # SSOT ordering guarantee — this template REFERENCES foundation's pod-wide
 # shared `client`/`partner`/`lead`/`churned` roles below. The apply engine seeds
@@ -63,6 +63,12 @@ profiles:
     icon: user
     color: amber
     description: A prospect, stakeholder, or contact.
+    # Pod-wide identity: `entityScope: pod` lands the ROWS with `workspace_id =
+    # NULL` (one person record visible from every workspace); the CRM lenses onto
+    # it via a role facet (lead/client). `person` is a pod-wide SYSTEM kind, so
+    # `scope` is omitted (no claim) — the applier reuses the system row and these
+    # CRM props land as this workspace's property OVERLAY.
+    entityScope: pod
     properties:
       - slug: email
         label: Email
@@ -123,7 +129,13 @@ profiles:
     icon: building-2
     color: "#10B981"
     description: An organisation being qualified or sold to.
-    scope: WORKSPACE
+    # Pod-wide identity: `entityScope: pod` lands the ROWS with `workspace_id =
+    # NULL` (one company record visible from every workspace, auto-appearing on the
+    # Ecosystem graph), lensed onto this CRM by its role facet (lead/client).
+    # `company` is a pod-wide SYSTEM kind, so `scope` is omitted (no claim) — the
+    # applier reuses the system row and these CRM props land as an OVERLAY.
+    # (Was `scope: WORKSPACE`, which contradicted the pod-wide model.)
+    entityScope: pod
     properties:
       - slug: contextSummary
         label: Context
@@ -336,6 +348,14 @@ profiles:
           - healthy
           - at_risk
           - critical
+      - slug: driveLink
+        label: Drive folder
+        valueType: string
+        inputType: url
+      - slug: driveFolderId
+        label: Drive folder ID
+        valueType: string
+        inputType: text
 
   # ── Partner (referral source + co-delivery collaborator) ──────────────────
   - slug: partner
@@ -456,6 +476,21 @@ profiles:
         valueType: string
         inputType: textarea
 
+# `linked_to_deal` is the GENERIC counterparty edge and stays the SSOT for "who
+# is on this deal" — the handoff flow's `find-party` node reads exactly it and
+# requires exactly one match, so nothing below may replace it.
+#
+# The two ROLE-QUALIFIED edges are additive: some deals are brokered, and the
+# party on the client side is not the party on the partner side. `client` and
+# `partner` are CO-ATTACHABLE facets on the same person/company (a facet is a
+# hat, not an identity), so the side a party plays ON THIS DEAL cannot be read
+# off its facets — the same company can be the client on one deal and the
+# introducing partner on another. That is a property of the EDGE, which is why
+# it is expressed as two relation types rather than promoted to a kind or
+# inferred from a facet.
+#
+# Both are optional. A direct deal carries only `linked_to_deal` (+ optionally
+# `client_on_deal` naming the same party); nothing requires a partner side.
 entityLinks:
   - sourceProfileSlug: person
     targetProfileSlug: deal
@@ -463,6 +498,88 @@ entityLinks:
   - sourceProfileSlug: company
     targetProfileSlug: deal
     type: linked_to_deal
+  - sourceProfileSlug: person
+    targetProfileSlug: deal
+    type: client_on_deal
+    label: Client side
+  - sourceProfileSlug: company
+    targetProfileSlug: deal
+    type: client_on_deal
+    label: Client side
+  - sourceProfileSlug: person
+    targetProfileSlug: deal
+    type: partner_on_deal
+    label: Partner side
+  - sourceProfileSlug: company
+    targetProfileSlug: deal
+    type: partner_on_deal
+    label: Partner side
+
+onboarding:
+  goal: >
+    Turn the user's real commercial motion into a usable pipeline — the right
+    companies and people, their active opportunities, and an explicit next
+    step for every deal — so CRM becomes the place sales work moves forward.
+  framing: >
+    THE REVENUE OPERATOR: Act as a pragmatic sales lead setting up a CRM people
+    will actually maintain. Start from the user's existing motion, vocabulary,
+    and active conversations. Resolve before creating so imported or Pod-wide
+    people are reused rather than duplicated. Push for a concrete next step and
+    date; never invent revenue, probability, or contact details.
+  expertise:
+    starters:
+      - >
+        A useful first pipeline is deliberately small. Start with the few stages
+        that change how the team acts — contacted, qualifying, proposal,
+        negotiating, won, and lost — and keep the template's default stages
+        unless the user's real process needs a different view.
+      - >
+        Populate the workspace with live work, not a perfect historical archive:
+        propose the three to five opportunities the user is actively trying to
+        move, then add the companies and people needed to understand those deals.
+      - >
+        Every active deal needs one observable next step with a date. If the next
+        step is "follow up" or "keep warm", help turn it into a specific action
+        such as "send the revised proposal Thursday" before capturing it.
+    blindSpots:
+      - >
+        A deal without a real person is usually an account-shaped hope. If an
+        opportunity has no stakeholder, surface the gap instead of fabricating a
+        placeholder contact.
+      - >
+        Pipelines become fiction when stages describe confidence rather than an
+        event the buyer completed. Ask what evidence moves a deal into its current
+        stage, especially around proposal and negotiation.
+      - >
+        More fields do not create better sales hygiene. Prioritize stage, value
+        when known, expected close date, and next step; leave unverifiable fields
+        empty and offer enrichment separately.
+    bar: >
+      A sales lead can open the pipeline and immediately see the few live
+      opportunities, the real company and stakeholder behind each one, its
+      evidence-based stage, and the dated next action — with no duplicate people
+      and no invented commercial data.
+  collect:
+    - profileSlug: company
+      what: The real prospect organisations behind current conversations.
+      cardinality: few
+      keyFields: [website, industry, companySize, source, nextStep]
+    - profileSlug: person
+      what: The known stakeholders for those organisations and opportunities.
+      cardinality: few
+      keyFields: [email, jobTitle, company, source, nextFollowUpDate]
+    - profileSlug: deal
+      what: The live opportunities worth actively moving through the pipeline.
+      cardinality: few
+      keyFields: [dealStage, value, closeDate, nextStep]
+  openingQuestions:
+    - "Which three to five opportunities are you actively trying to move right now?"
+    - "For the most important one, which company and real stakeholder are involved?"
+    - "What has the buyer actually done so far, and what is the next dated action?"
+  doneWhen: >
+    At least one real opportunity is linked to its company or stakeholder and
+    has an evidence-based stage plus a concrete next step; the user can see how
+    to add or import the rest without duplicating existing people.
 
 # Playbook — enriches a lead/prospect from public sources (company site,
 # LinkedIn, firmographic signal) so ICP scoring and qualification start from

package/src/define.primary-surface.test.ts

@@ -59,13 +59,11 @@ describe('workspace primary-surface conversion', () => {
     });
   });
 
-  it('ships the generated CRM template as a hosted primary surface', () => {
+  it('ships the generated CRM template as an ordinary website surface', () => {
     expect(
       toWorkspaceDefinition('crm').definition.layoutConfig?.primarySurface
     ).toEqual({
-      kind: 'app',
-      appId: 'crm',
-      rendererType: 'external',
+      kind: 'url',
       url: 'https://crm.synap.live',
       title: 'CRM',
     });

package/src/define.ts

@@ -272,6 +272,19 @@ export interface WorkspaceDefinitionInput {
   seedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
   suggestedRelations?: WorkspaceYaml['suggestedRelations'];
   displayTemplates?: WorkspaceYaml['displayTemplates'];
+  /**
+   * Domain-level relation TYPE vocabulary — the door find-or-creates a
+   * `relation_defs` row per entry (idempotent by slug within the workspace). NOT
+   * `entityLinks` (those are profile→profile edges and drop the rich metadata).
+   * Carried verbatim; the authored form IS the wire form.
+   */
+  relationDefs?: WorkspaceYaml['relationDefs'];
+  /**
+   * Workspace intelligence commands — the door find-or-creates an
+   * `intelligence_commands` row per entry (idempotent by title). Carried
+   * verbatim; the authored form IS the wire form.
+   */
+  commands?: WorkspaceYaml['commands'];
   layoutConfig: WorkspaceYaml['layout'] | undefined;
   bentoViewName?: string;
   /**
@@ -398,6 +411,11 @@ export function toWorkspaceDefinition(
     seedEntities: tpl.seedEntities ?? [],
     suggestedRelations: tpl.suggestedRelations,
     displayTemplates: tpl.displayTemplates,
+    // Relation-type vocabulary + intelligence commands — carried verbatim so the
+    // one reconcile door can seed the universal defaults (the `base` template)
+    // that three hardcoded seeders used to. Authored form IS the wire form.
+    relationDefs: tpl.relationDefs,
+    commands: tpl.commands,
     layoutConfig: normalizeTemplateLayout(tpl.layout, tpl.app),
     bentoViewName: tpl.bento?.viewName,
     bentoLayout: bento.bentoLayout,
@@ -472,6 +490,8 @@ type WorkspaceDefinitionForwarded =
   | 'seedEntities'
   | 'suggestedRelations'
   | 'displayTemplates'
+  | 'relationDefs'  // → carried verbatim; door find-or-creates relation_defs rows
+  | 'commands'      // → carried verbatim; door find-or-creates intelligence_commands rows
   | 'layout'        // → layoutConfig
   | 'bento'         // → bentoViewName + bentoLayout (widgets) + bentoViewBlocks (views)
   | 'profileEntityBentoTemplates'
@@ -544,6 +564,10 @@ export interface PackageDefinitionOutput {
   suggestedRelations?: WorkspaceYaml['suggestedRelations'];
   displayTemplates?: WorkspaceYaml['displayTemplates'];
   entityLinks?: WorkspaceYaml['entityLinks'];
+  /** Relation-type vocabulary — carried verbatim (authored form IS the wire form). */
+  relationDefs?: WorkspaceYaml['relationDefs'];
+  /** Intelligence commands — carried verbatim (authored form IS the wire form). */
+  commands?: WorkspaceYaml['commands'];
   /** WIDGET half of the authored bento union — mapped by the pod via `widgetType`. */
   bentoLayout?: BentoWidgetBlockWire[];
   /**
@@ -619,6 +643,8 @@ export function toPackageDefinition(
     suggestedRelations: tpl.suggestedRelations,
     displayTemplates: tpl.displayTemplates,
     entityLinks: tpl.entityLinks,
+    relationDefs: tpl.relationDefs,
+    commands: tpl.commands,
     bentoLayout: bento.bentoLayout,
     bentoViewBlocks: bento.bentoViewBlocks,
     bentoViewName: tpl.bento?.viewName,
@@ -650,6 +676,8 @@ type PackageDefinitionForwarded =
   | 'suggestedRelations'
   | 'displayTemplates'
   | 'entityLinks'
+  | 'relationDefs'  // → carried verbatim
+  | 'commands'      // → carried verbatim
   | 'bento'         // → bentoViewName + bentoLayout (widgets) + bentoViewBlocks (views)
   | 'profileEntityBentoTemplates'
   | 'layout'        // → layoutConfig

package/src/ecosystem.yaml

@@ -51,6 +51,14 @@ profiles:
     icon: user
     color: amber
     description: A person in the ecosystem — a founder, operator, or contact.
+    # Pod-wide identity. `person` is a pod-wide SYSTEM kind, so `entityScope: pod`
+    # is the load-bearing axis: the ROWS land with `workspace_id = NULL`, visible
+    # from every workspace (auto-appearing on the Ecosystem graph) and lensed onto
+    # a CRM only where it wears a role facet (lead/client/partner). `scope` is
+    # deliberately OMITTED: it is already a system profile (more pod-wide than
+    # `shared`), so any scope claim only forks the row-level SSOT (see
+    # shared-role-ssot.test.ts (c)); the applier reuses the existing system row.
+    entityScope: pod
     properties:
       - slug: email
         label: Email
@@ -66,6 +74,12 @@ profiles:
     icon: building-2
     color: "#10B981"
     description: A company in the ecosystem — a player you operate around.
+    # Pod-wide identity — same rationale as `person` above: `company` is a pod-wide
+    # SYSTEM kind, so `entityScope: pod` lands the ROWS with `workspace_id = NULL`
+    # (visible from every workspace, auto-appearing on the Ecosystem graph, lensed
+    # onto CRM only by its role facet). `scope` omitted so the applier reuses the
+    # existing system row without forking the row-level SSOT.
+    entityScope: pod
     properties:
       - slug: website
         label: Website

package/src/enterprise-os.yaml

@@ -51,7 +51,7 @@ dependencies:
   - slug: business-developer
     kind: workspace
     relation: require
-    reason: "The lead-first sales motion (crm-lead/crm-client roles, commercial proposals, commission handoff) that the CRM app runs on. Composes onto the CRM workspace above — without it the CRM lens is provisioned with pod-wide lead/client only and the app's pipeline is empty."
+    reason: "The lead-first sales motion (the business-development overlay on the pod-wide lead/client roles, commercial proposals, commission handoff) that the CRM app runs on. Composes onto the CRM workspace above — without it the CRM lens has the bare lead/client roles with no lifecycle or handoff fields and the app's pipeline is empty."
   - slug: content-os
     kind: workspace
     relation: require

package/src/foundation.yaml

@@ -371,6 +371,14 @@ profiles:
           - healthy
           - at_risk
           - critical
+      - slug: driveLink
+        label: Drive folder
+        valueType: string
+        inputType: url
+      - slug: driveFolderId
+        label: Drive folder ID
+        valueType: string
+        inputType: text
 
   # ── Partner (referral source + co-delivery collaborator) ──────────────────
   - slug: partner

package/src/grants.yaml

@@ -730,6 +730,14 @@ profiles:
           - healthy
           - at_risk
           - critical
+      - slug: driveLink
+        label: Drive folder
+        valueType: string
+        inputType: url
+      - slug: driveFolderId
+        label: Drive folder ID
+        valueType: string
+        inputType: text
   # ── Partner (shared ecosystem role — SSOT is foundation.yaml) ─────────────
   - slug: partner
     displayName: Partner

package/src/life-os.yaml

@@ -207,7 +207,12 @@ profiles:
     icon: User
     color: "#06B6D4"
     description: People in your intellectual and professional world.
-    scope: WORKSPACE
+    # Pod-wide identity: `person` is ONE pod-wide SYSTEM kind, not a life-os-local
+    # copy. `entityScope: pod` lands the ROWS with `workspace_id = NULL` (visible
+    # from every workspace); `scope` omitted (no claim) so the applier reuses the
+    # system row and these life-os props land as this workspace's OVERLAY.
+    # (Was `scope: WORKSPACE`, which contradicted the pod-wide model.)
+    entityScope: pod
     properties:
       - slug: name
         label: Name