@synap-core/workspace-templates 0.9.4 → 0.11.0

package/src/blockchain-ecosystem.yaml

@@ -47,6 +47,10 @@ profiles:
     description: A liquidity provider — makes markets and provides depth for a token.
     scope: shared
     profileKind: role
+    # Shared supply-role category → the intro-matcher's roster spans ALL roles
+    # tagged "provider" via entity.query { roleCategory: "provider" } (no per-role
+    # hardcoding). Keep this string in sync with networking.yaml's solution-provider.
+    roleCategory: provider
     applicableKinds:
       - company
       - person
@@ -81,6 +85,10 @@ profiles:
     description: A security firm or individual that audits smart contracts and protocols.
     scope: shared
     profileKind: role
+    # Shared supply-role category → the intro-matcher's roster spans ALL roles
+    # tagged "provider" via entity.query { roleCategory: "provider" } (no per-role
+    # hardcoding). Keep this string in sync with networking.yaml's solution-provider.
+    roleCategory: provider
     applicableKinds:
       - company
       - person
@@ -115,6 +123,10 @@ profiles:
     description: An outsourced engineering studio or build partner.
     scope: shared
     profileKind: role
+    # Shared supply-role category → the intro-matcher's roster spans ALL roles
+    # tagged "provider" via entity.query { roleCategory: "provider" } (no per-role
+    # hardcoding). Keep this string in sync with networking.yaml's solution-provider.
+    roleCategory: provider
     applicableKinds:
       - company
       - person
@@ -149,6 +161,10 @@ profiles:
     description: A brand, growth, or content marketing agency.
     scope: shared
     profileKind: role
+    # Shared supply-role category → the intro-matcher's roster spans ALL roles
+    # tagged "provider" via entity.query { roleCategory: "provider" } (no per-role
+    # hardcoding). Keep this string in sync with networking.yaml's solution-provider.
+    roleCategory: provider
     applicableKinds:
       - company
       - person
@@ -183,6 +199,10 @@ profiles:
     description: A performance / paid-media buying agency.
     scope: shared
     profileKind: role
+    # Shared supply-role category → the intro-matcher's roster spans ALL roles
+    # tagged "provider" via entity.query { roleCategory: "provider" } (no per-role
+    # hardcoding). Keep this string in sync with networking.yaml's solution-provider.
+    roleCategory: provider
     applicableKinds:
       - company
       - person
@@ -217,6 +237,10 @@ profiles:
     description: A key opinion leader or influencer who amplifies reach.
     scope: shared
     profileKind: role
+    # Shared supply-role category → the intro-matcher's roster spans ALL roles
+    # tagged "provider" via entity.query { roleCategory: "provider" } (no per-role
+    # hardcoding). Keep this string in sync with networking.yaml's solution-provider.
+    roleCategory: provider
     applicableKinds:
       - company
       - person
@@ -243,6 +267,88 @@ profiles:
         valueType: string
         inputType: textarea
 
+  # ── Grant Program (the per-chain funding PROGRAM — parent of a round) ───────
+  # The 3-layer grants spine is PROGRAM ≠ ROUND ≠ APPLICATION. `round` (in
+  # grants.yaml) is the funding-cycle/deadline carrier; a program is the
+  # long-lived, chain-scoped funder above it (e.g. Stellar SCF, Optimism RetroPGF).
+  # It lives HERE, with the web3 vocabulary, because a program IS a blockchain-
+  # ecosystem thing (it carries a `blockchain` and program mechanics), and it is
+  # a real-world entity referenced from every workspace — hence pod-wide, mirroring
+  # company/person in ecosystem.yaml (`entityScope: pod`). `scope: shared` makes
+  # the profile DEF pod-wide too, so a REUSING template (grants.yaml `require`s this
+  # overlay) resolves `grant-program` for its `round → belongs_to → grant-program`
+  # edge and deadline view. `defaultPlaybook` is a text ref for now — Wave 2 will
+  # create the actual per-chain playbook and bind it.
+  - slug: grant-program
+    displayName: Grant Program
+    icon: landmark
+    color: emerald
+    description: A per-chain funding program (e.g. Stellar SCF, Optimism RetroPGF) — the long-lived funder above a round.
+    profileKind: kind
+    entityScope: pod
+    scope: shared
+    properties:
+      - slug: blockchain
+        label: Blockchain / Chain
+        valueType: string
+        inputType: text
+      - slug: programName
+        label: Program Name
+        valueType: string
+        inputType: text
+      - slug: programType
+        label: Program Type
+        valueType: string
+        inputType: select
+        enumValues:
+          - direct
+          - retroactive
+          - quadratic
+          - rfp
+      - slug: status
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues:
+          - active
+          - paused
+          - retired
+      - slug: url
+        label: Program URL
+        valueType: string
+        inputType: url
+      - slug: cadence
+        label: Cadence
+        valueType: string
+        inputType: text
+        placeholder: every 6 weeks
+      - slug: nextDeadline
+        label: Next Deadline
+        valueType: date
+        inputType: date
+      - slug: submissionTracks
+        label: Submission Tracks
+        valueType: array
+        inputType: text
+      - slug: trancheModel
+        label: Tranche Model
+        valueType: string
+        inputType: text
+        placeholder: 4 tranches / 90 days
+      - slug: defaultPlaybook
+        label: Default Playbook
+        valueType: string
+        inputType: text
+        # Defaults to the BASE grant playbook (grants.yaml `Grant Process`), the
+        # data-driven process that reads THIS program's cadence/tracks/tranche
+        # model at runtime. Override per-program only for a differently-shaped chain.
+        constraints:
+          defaultValue: Grant Process
+      - slug: description
+        label: Description
+        valueType: string
+        inputType: textarea
+
 # Web3 actor↔actor relations (company→company). `company` resolves from the
 # Ecosystem base — not redeclared here.
 entityLinks:

package/src/business-developer.template.test.ts

@@ -47,17 +47,30 @@ describe("Business Developer workspace overlay", () => {
     expect(template.workspace.visibility).toBeUndefined();
   });
 
-  it("keeps CRM lifecycle facets workspace-local", () => {
-    for (const slug of ["crm-lead", "crm-client"]) {
+  it("extends the SHARED lead/client roles instead of forking them", () => {
+    // The lifecycle roles are the pod-wide foundation SSOT, re-declared so this
+    // workspace receives the grant. Row-level fields must match foundation
+    // VERBATIM (one row, no overlay mechanism — shared-role-ssot rule (c)); the
+    // business-development fields ride along as workspace-overlay PROPERTIES.
+    for (const slug of ["lead", "client"]) {
       const facet = profile(slug);
-      expect(facet.scope).toBe("WORKSPACE");
+      expect(facet.scope).toBe("shared");
       expect(facet.profileKind).toBe("role");
-      expect(facet.applicableKinds).toEqual(["person", "company"]);
+      expect(facet.applicableKinds).toEqual(["company", "person"]);
+      expect(facet.semanticSlug).toBeUndefined();
     }
 
-    expect(template.profiles.some((candidate) => ["lead", "client"].includes(candidate.slug))).toBe(false);
+    // The forked spellings are GONE — reintroducing either is the regression.
+    expect(
+      template.profiles.some((candidate) => ["crm-lead", "crm-client"].includes(candidate.slug)),
+    ).toBe(false);
+
+    // Extras only: foundation's own `leadStage` / `clientStatus` / `notes` are
+    // NOT restated here (restating with a different definition is base drift).
+    expect([...propertySlugs("lead")]).not.toContain("leadStage");
+    expect([...propertySlugs("client")]).not.toContain("clientStatus");
 
-    expect([...propertySlugs("crm-lead")].sort()).toEqual([
+    expect([...propertySlugs("lead")].sort()).toEqual([
     "assignedUserId",
     "convertedAt",
     "disqualificationReason",
@@ -70,6 +83,13 @@ describe("Business Developer workspace overlay", () => {
     "qualificationNotes",
     "source",
     ].sort());
+
+    expect([...propertySlugs("client")].sort()).toEqual([
+      "becameClientAt",
+      "handoffDestination",
+      "handoffNotes",
+      "handoffStatus",
+    ].sort());
   });
 
   it("models proposals and auditable commission separately from leads", () => {
@@ -136,6 +156,10 @@ describe("Business Developer workspace overlay", () => {
   });
 
   it("relies on CRM's single generic counterparty relationship", () => {
+    // `linked_to_deal` stays the ONE generic counterparty edge the handoff
+    // flow's `find-party` node reads. The role-qualified edges beside it are
+    // ADDITIVE (a brokered deal has a client side and a partner side) and must
+    // never displace it — hence the exact-order assertion.
     expect(
       crmTemplate.entityLinks?.map(({ sourceProfileSlug, targetProfileSlug, type }) => ({
         sourceProfileSlug,
@@ -145,6 +169,20 @@ describe("Business Developer workspace overlay", () => {
     ).toEqual([
       { sourceProfileSlug: "person", targetProfileSlug: "deal", type: "linked_to_deal" },
       { sourceProfileSlug: "company", targetProfileSlug: "deal", type: "linked_to_deal" },
+      { sourceProfileSlug: "person", targetProfileSlug: "deal", type: "client_on_deal" },
+      { sourceProfileSlug: "company", targetProfileSlug: "deal", type: "client_on_deal" },
+      { sourceProfileSlug: "person", targetProfileSlug: "deal", type: "partner_on_deal" },
+      { sourceProfileSlug: "company", targetProfileSlug: "deal", type: "partner_on_deal" },
+    ]);
+
+    // The handoff still reads ONLY the generic edge — a brokered deal's partner
+    // side must not be mistaken for the counterparty that becomes the client.
+    const handoff = template.automations?.find((a) => a.name === "Win and hand off");
+    const findParty = (handoff?.flow.nodes as Array<{ id?: string; data?: unknown }>).find(
+      (n) => n.id === "find-party",
+    );
+    expect((findParty?.data as { relationTypes?: string[] }).relationTypes).toEqual([
+      "linked_to_deal",
     ]);
   });
 
@@ -152,7 +190,7 @@ describe("Business Developer workspace overlay", () => {
     expect(
       template.playbooks?.map(({ name, subjectProfile }) => ({ name, profileSlug: subjectProfile?.profileSlug })),
     ).toEqual([
-      { name: "Qualify a CRM lead", profileSlug: "crm-lead" },
+      { name: "Qualify a CRM lead", profileSlug: "lead" },
       { name: "Advance a commercial proposal", profileSlug: "deal" },
     ]);
     expect(template.playbooks?.[0]?.goalTemplate ?? "").toMatch(/Do not create a deal/);
@@ -215,18 +253,49 @@ describe("Business Developer workspace overlay", () => {
       }),
     );
 
+    // The handoff writes the SHARED role slugs — this is what makes the party
+    // a client pod-wide (and therefore visible to the Operations pickup).
+    expect(handoff?.flow.nodes).toContainEqual(
+      expect.objectContaining({
+        id: "attach-client",
+        data: expect.objectContaining({
+          outputType: "facet_attach",
+          config: expect.objectContaining({ facetSlug: "client" }),
+        }),
+      }),
+    );
+    expect(handoff?.flow.nodes).toContainEqual(
+      expect.objectContaining({
+        id: "convert-lead",
+        data: expect.objectContaining({
+          outputType: "facet_update",
+          config: expect.objectContaining({ facetSlug: "lead" }),
+        }),
+      }),
+    );
+    expect(handoff?.flow.nodes).toContainEqual(
+      expect.objectContaining({
+        id: "guard-lead",
+        data: expect.objectContaining({
+          checks: expect.arrayContaining([
+            expect.objectContaining({ arrayIncludes: "lead" }),
+          ]),
+        }),
+      }),
+    );
+
     expect(template.actionPlacements).toEqual([
       expect.objectContaining({
         profileSlug: "person",
         kind: "playbook",
         ref: "Qualify a CRM lead",
-        when: { requiredFacetSlugs: ["crm-lead"] },
+        when: { requiredFacetSlugs: ["lead"] },
       }),
       expect.objectContaining({
         profileSlug: "company",
         kind: "playbook",
         ref: "Qualify a CRM lead",
-        when: { requiredFacetSlugs: ["crm-lead"] },
+        when: { requiredFacetSlugs: ["lead"] },
       }),
       expect.objectContaining({
         profileSlug: "deal",
@@ -256,7 +325,7 @@ describe("Business Developer workspace overlay", () => {
     expect(playbooks).toHaveLength(2);
     expect(playbooks[0]).toMatchObject({
       name: "Qualify a CRM lead",
-      subjectProfile: { profileSlug: "crm-lead" },
+      subjectProfile: { profileSlug: "lead" },
       params: [{ name: "lead", type: "string", description: "CRM lead" }],
     });
     expect(playbooks[1]).toMatchObject({

package/src/business-developer.yaml

@@ -1,13 +1,19 @@
 # Business Developer — a composable, lead-first CRM operating model.
 #
 # This is an ADDITIVE overlay on the CRM workspace, not a second CRM and not a
-# rewrite of shared identity profiles. It deliberately uses workspace-scoped
-# `crm-lead` and `crm-client` role facets instead of the pod-wide `lead` and
-# `client` vocabulary from Foundation. A person or company can therefore be a
-# lead in one CRM workspace without becoming a lead everywhere in the pod.
+# rewrite of shared identity profiles. It REUSES the pod-wide `lead` and
+# `client` roles from Foundation (`scope: shared`, `profileKind: role`) and adds
+# its business-development properties to them as WORKSPACE OVERLAYS — the
+# documented extension mechanism (`getEffectiveProperties`, and rule (b) of
+# `shared-role-ssot.test.ts`). It used to fork them into workspace-scoped
+# `crm-lead` / `crm-client`; that was a vocabulary fork of one real-world
+# concept: the same company was a "lead" under one spelling and not under the
+# other, so pod-wide surfaces, the Operations handoff, and the CRM app
+# disagreed about who was a client. One concept, one slug, workspace-specific
+# FIELDS.
 #
 # Lifecycle:
-#   person / company + crm-lead → optional deal(s) → won deal → crm-client
+#   person / company + lead → optional deal(s) → won deal → client
 #
 # Deals are commercial proposals attached through CRM's existing
 # `linked_to_deal` relation. The CRM requires one counterparty before a deal
@@ -41,23 +47,33 @@ workspace:
     - crm.business-development
 
 profiles:
-  # Workspace-local operational status. This is intentionally separate from
-  # Foundation's shared `lead` role: lead ownership, next actions, and CRM
-  # lifecycle status must be visible to this CRM workspace's members only.
-  - slug: crm-lead
-    displayName: CRM Lead
-    icon: user-round-search
-    color: amber
-    description: A person or company actively being qualified or contacted by this CRM workspace.
-    scope: WORKSPACE
+  # ── Lead (reused shared role — SSOT is foundation.yaml) ───────────────────
+  # NOT a workspace-local copy: this RE-DECLARES foundation's pod-wide `lead`
+  # role so the CRM workspace receives the grant (shared profiles are
+  # grant-gated — a workspace only sees a shared role if it references the
+  # slug), and ADDS the business-development properties below.
+  #
+  # Row-level fields (displayName/icon/color/description/applicableKinds) are
+  # restated VERBATIM from foundation, exactly as crm.yaml does: there is ONE
+  # pod-wide row and no overlay mechanism for row-level fields, so a divergent
+  # value here would be silently false on every pod depending on apply order
+  # (shared-role-ssot rule (c)).
+  #
+  # The properties are EXTRAS ONLY. Foundation's own `leadStage` / `notes` are
+  # deliberately NOT restated — omitting is "no claim", and restating with a
+  # different definition is the base-drift rule (b) forbids. Extras land as
+  # WORKSPACE OVERLAYS via getEffectiveProperties, so this workspace's members
+  # see lifecycle/ownership fields that other workspaces don't.
+  - slug: lead
+    displayName: Lead
+    icon: user-plus
+    color: yellow
+    description: An early-pipeline prospect — not yet a client, being qualified or nurtured.
+    scope: shared
     profileKind: role
-    # Explicit concept identity: this is the WORKSPACE tier of the `lead`
-    # concept, not a second, unrelated one. Declaring it makes the two-tier
-    # design machine-readable (both tiers are reachable via getBySemanticSlug)
-    # and is what the cross-template concept guard requires alongside its
-    # DECLARED_DIVERGENCES entry — see src/concept-guard.ts.
-    semanticSlug: crm.lead
-    applicableKinds: [person, company]
+    applicableKinds:
+      - company
+      - person
     properties:
       - slug: lifecycleStage
         label: Lifecycle stage
@@ -129,19 +145,22 @@ profiles:
         valueType: date
         inputType: date
 
-  # The same counterparty receives this facet when one of its commercial
-  # proposals is won. It intentionally carries only handoff context; client
-  # delivery, renewal, and service health remain outside this pre-sale addon.
-  - slug: crm-client
-    displayName: CRM Client
-    icon: badge-check
+  # ── Client (reused shared role — SSOT is foundation.yaml) ─────────────────
+  # Same pattern as `lead` above: foundation's pod-wide `client` role, restated
+  # verbatim at row level, EXTENDED with the handoff context this pre-sale
+  # addon owns. Client delivery, renewal, and service health belong to
+  # operations.yaml, which reads the SAME `client` role pod-wide — that shared
+  # slug is what makes the CRM → Operations handoff possible at all.
+  - slug: client
+    displayName: Client
+    icon: briefcase
     color: emerald
-    description: A CRM lead converted by a won commercial proposal and ready for handoff.
-    scope: WORKSPACE
+    description: An active commercial relationship — created when a deal is won.
+    scope: shared
     profileKind: role
-    # Workspace tier of the `client` concept — see the note on `crm-lead` above.
-    semanticSlug: crm.client
-    applicableKinds: [person, company]
+    applicableKinds:
+      - company
+      - person
     properties:
       - slug: becameClientAt
         label: Became client at
@@ -404,7 +423,7 @@ playbooks:
       deal simply because the lead is qualified. If a commercial proposal is
       warranted, explain why and ask for or propose that next step separately.
     subjectProfile:
-      profileSlug: crm-lead
+      profileSlug: lead
     params:
       - { name: lead, type: entity, label: CRM lead, required: true }
     executor: is-agent
@@ -477,8 +496,11 @@ automations:
               - path: steps.read-deal.output.entity.properties.handoffStatus
                 notEquals: handed_off
                 message: This proposal has already been handed off.
+              # minLength, NOT exists: `exists` is a null check, so an empty
+              # string satisfies it and the handoff would proceed with no
+              # sourcer actually set. The intent here is "has a value".
               - path: steps.read-deal.output.entity.properties.sourcedByUserId
-                exists: true
+                minLength: 1
                 message: Set the business developer who sourced this proposal before handing it off.
               - path: steps.read-deal.output.entity.properties.synapFeeAmount
                 numberGte: 0
@@ -518,7 +540,7 @@ automations:
             label: Confirm qualified CRM lead
             checks:
               - path: steps.read-party.output.entity.facetSlugs
-                arrayIncludes: crm-lead
+                arrayIncludes: lead
                 message: The commercial counterparty must still be a CRM lead before it becomes a CRM client.
 
         # Source-deal claim is the durable idempotency boundary for the whole
@@ -699,7 +721,7 @@ automations:
             outputType: facet_attach
             config:
               entityId: "{{steps.read-party.output.entity.id}}"
-              facetSlug: crm-client
+              facetSlug: client
               properties:
                 becameClientAt: "{{steps.handoff-time.output.result}}"
                 handoffStatus: handed_off
@@ -712,7 +734,7 @@ automations:
             outputType: facet_update
             config:
               entityId: "{{steps.read-party.output.entity.id}}"
-              facetSlug: crm-lead
+              facetSlug: lead
               properties:
                 lifecycleStage: converted
                 convertedAt: "{{steps.handoff-time.output.result}}"
@@ -809,14 +831,14 @@ actionPlacements:
     kind: playbook
     ref: Qualify a CRM lead
     label: Qualify lead
-    when: { requiredFacetSlugs: [crm-lead] }
+    when: { requiredFacetSlugs: [lead] }
 
   - profileSlug: company
     surface: entity-detail
     kind: playbook
     ref: Qualify a CRM lead
     label: Qualify lead
-    when: { requiredFacetSlugs: [crm-lead] }
+    when: { requiredFacetSlugs: [lead] }
 
   - profileSlug: deal
     surface: entity-detail

package/src/catalog.ts

@@ -33,6 +33,20 @@ import type { WorkspaceYaml } from "./types.js";
 // Inputs
 // ============================================================================
 
+/**
+ * A lightweight, QUERY-TIME summary of one sub-object a package carries (a cell
+ * today; the shape generalizes to views/automations without change). Rides the
+ * catalog LIST projection so a surface can match/surface a sub-item WITHOUT the
+ * full `definition` — it carries `key + name` only, never the sub-object's code.
+ * `kind` is DERIVED (in the CP SELECT, from which sub-array the row came from),
+ * never a stored taxonomy.
+ */
+export interface PackageItemSummary {
+  kind: string;
+  key: string;
+  name: string;
+}
+
 /**
  * A bundled template — the canonical `WorkspaceYaml` this package ships. Callers
  * pass `listPublicTemplates()` (18) or `listWorkspaceTemplates()` (21); the door
@@ -69,6 +83,13 @@ export interface RemoteEntry {
    * never "unknown-so-hide".
    */
   isPrivate?: boolean;
+  /**
+   * Lightweight computed summary of the row's sub-objects (cells), carried on the
+   * LIST projection so a surface can surface a matching sub-item without the full
+   * `definition`. `undefined` on sources that don't compute it (bundled) — treated
+   * as "no known sub-items". See `PackageItemSummary`.
+   */
+  items?: PackageItemSummary[];
   /**
    * The CP `definition` jsonb — opaque install payload. The door reads only
    * `definition.sourcePackage.version` (the winner signal). Absent on browse rows
@@ -128,6 +149,11 @@ export interface CpPackageRow {
   icon?: string | null;
   /** Present only on `/mine` rows. `false` ⇒ private. Browse rows omit it. */
   isPublic?: boolean;
+  /**
+   * Computed sub-object summary from `GET /api/packages` / `/mine` (query-time,
+   * not a stored column). Carries `key + name` per cell; never the cell code.
+   */
+  items?: PackageItemSummary[];
 }
 
 /**
@@ -154,6 +180,7 @@ export function rowToRemoteEntry(
     tags: row.tags ?? [],
     icon: row.icon ?? null,
     isPrivate,
+    items: row.items,
     // Both list routes strip `definition`; absence ⇒ bundle wins a slug conflict,
     // and the install path fetches the full definition per-slug when needed.
   };
@@ -175,6 +202,12 @@ interface CatalogEntryBase {
   icon?: string | null;
   /** `true` ⇒ not publicly listed (internal bundled template, or private CP row). */
   isPrivate: boolean;
+  /**
+   * The entry's sub-object summary (cells). Always present (defaults to `[]`) so a
+   * consumer can match sub-items uniformly. Bundled workspace templates carry no
+   * cells → `[]` (honest); a remote row carries its CP-computed `items`.
+   */
+  items: PackageItemSummary[];
 }
 
 /** A catalog entry backed by a bundled template. Install via `toWorkspaceDefinition()` / `toPackageDefinition()` on `template`. */
@@ -256,6 +289,8 @@ function bundledToEntry(tpl: WorkspaceYaml): BundledCatalogEntry {
     tags: tpl.meta.tags ?? [],
     icon: tpl.meta.icon,
     isPrivate: tpl.meta.isPublic === false,
+    // Bundled workspace templates carry no cells — be honest, not `undefined`.
+    items: [],
     template: tpl,
   };
 }
@@ -271,6 +306,7 @@ function remoteToEntry(row: RemoteEntry): RemoteCatalogEntry {
     tags: row.tags ?? [],
     icon: row.icon ?? null,
     isPrivate: row.isPrivate ?? false,
+    items: row.items ?? [],
     remote: row,
   };
 }