@synap-core/workspace-templates 0.7.2 → 0.7.3

package/src/shared-role-ssot.test.ts

@@ -0,0 +1,268 @@
+/**
+ * TRIPWIRE — shared ecosystem roles are a single pod-wide SSOT.
+ *
+ * Ratified principle: the ecosystem role vocabulary (client, partner, sponsor,
+ * lead, churned, …) is defined ONCE (foundation.yaml) as `scope: shared`,
+ * `profileKind: role`, and merely REFERENCED by every other template. The
+ * template apply/dedup layer resolves a declared slug to the ONE pod-wide
+ * profile — so if two templates declare the same shared slug with DIFFERENT
+ * property bodies, they silently fight over one row (drift), and if a template
+ * declares one of these role slugs as a `kind` or workspace-scoped, it forks a
+ * second identity for a hat.
+ *
+ * WHY THIS LIVES HERE NOW (read before re-adding a backend copy):
+ * synap-backend once carried this guard at
+ * `packages/api/src/__tripwires__/template-shared-role-ssot.test.ts`, reaching
+ * ACROSS repos to read `synap-app/.../src/templates.ts` by relative path. That
+ * path is absent in synap-backend CI, so the guard was green locally and
+ * NON-FUNCTIONAL in CI — it guarded nothing where it mattered. The corpus it
+ * asserts against is authored HERE and the generated `templates.ts` (which
+ * `templates-freshness.test.ts` keeps in lockstep with the YAML) lives HERE, so
+ * this is where the guard belongs: it runs in THIS package's `pnpm test`,
+ * alongside `concept-guard.test.ts`, against the real bundled corpus.
+ * (synap-backend owns DELETING its now-redundant copy — see the coordination
+ * note in the handoff; this file does not touch it.)
+ *
+ * DERIVE, DON'T HARDCODE. The backend copy hardcoded
+ * `{client, partner, sponsor, lead, competitor}` — which had DRIFTED from the
+ * SSOT: foundation.yaml declares `churned`, not `competitor` (competitor is
+ * ecosystem.yaml's own shared role, not a foundation-owned one). We derive the
+ * shared-ROLE vocabulary from foundation.yaml itself, so the guarded set can
+ * never drift from the SSOT it guards. Shared KINDS are not centralized in
+ * foundation today (e.g. `platform` is owned by content-os), so the shared-kind
+ * set is derived from the corpus — still not a hardcoded list.
+ *
+ *   (a) No template declares a foundation-owned shared-role slug as
+ *       `profileKind: kind` or workspace-scoped.
+ *   (a2) Mirror for shared KINDS: no template declares a shared-kind slug as a
+ *       `role` or workspace-scoped.
+ *   (b) No two templates declare the SAME property slug on the same `scope:
+ *       shared` profile with DIFFERENT definitions. EXTRA properties are ALLOWED
+ *       (they land as workspace overlays — the legitimate extension mechanism).
+ *   (c) No two templates declare the same shared profile with CONFLICTING
+ *       ROW-LEVEL fields (no overlay mechanism exists for these — one row, one
+ *       value; absence = no claim).
+ *   (d) Every shared ROLE slug has a non-empty `applicableKinds` declared by at
+ *       least one template (else the pod-wide row accepts ANY kind as the role —
+ *       `FacetRepository.attach` skips the gate when applicableKinds is empty).
+ */
+
+import { describe, expect, it } from "vitest";
+import { WORKSPACE_TEMPLATES } from "./templates.js";
+import type { TemplateProfile, TemplateProperty, WorkspaceYaml } from "./types.js";
+
+const templates: WorkspaceYaml[] = Object.values(WORKSPACE_TEMPLATES);
+
+const profilesOf = (tpl: WorkspaceYaml): TemplateProfile[] => tpl.profiles ?? [];
+const templateSlug = (tpl: WorkspaceYaml): string => tpl.meta?.slug ?? "(unknown)";
+
+const isSharedScope = (scope?: string): boolean =>
+  (scope ?? "").toLowerCase() === "shared";
+const isWorkspaceScope = (scope?: string): boolean =>
+  // Omitted scope defaults to workspace-scoped.
+  (scope ?? "workspace").toLowerCase() === "workspace";
+const normalizeKind = (k?: string): "kind" | "role" => (k === "role" ? "role" : "kind");
+
+// ── Derive the shared vocabulary (NOT a hardcoded list) ──────────────────────
+// Shared ROLES: foundation.yaml is the SSOT — its `scope: shared` roles.
+const foundation = WORKSPACE_TEMPLATES["foundation"];
+const SHARED_ROLE_SLUGS = new Set(
+  profilesOf(foundation ?? ({} as WorkspaceYaml))
+    .filter((p) => isSharedScope(p.scope) && normalizeKind(p.profileKind) === "role")
+    .map((p) => p.slug)
+);
+// Shared KINDS: not centralized in foundation (e.g. `platform` lives in
+// content-os), so derive from wherever the corpus declares scope:shared + kind.
+const SHARED_KIND_SLUGS = new Set<string>();
+for (const tpl of templates) {
+  for (const p of profilesOf(tpl)) {
+    if (isSharedScope(p.scope) && normalizeKind(p.profileKind) === "kind") {
+      SHARED_KIND_SLUGS.add(p.slug);
+    }
+  }
+}
+
+/** Stable fingerprint of a SINGLE property's DEFINITION (presentation excluded). */
+function propertyDefFingerprint(p: TemplateProperty): string {
+  const constraints = (p.constraints ?? {}) as { defaultValue?: unknown };
+  return JSON.stringify({
+    valueType: p.valueType ?? null,
+    inputType: p.inputType ?? null,
+    enumValues: Array.isArray(p.enumValues) ? [...p.enumValues].sort() : null,
+    defaultValue: constraints.defaultValue ?? null,
+  });
+}
+
+/** ROW-LEVEL fields — the columns of the ONE pod-wide profile row. */
+const ROW_LEVEL_FIELDS = [
+  "profileKind",
+  "applicableKinds",
+  "displayName",
+  "icon",
+  "color",
+  "description",
+  "semanticSlug",
+] as const;
+
+/** Canonical, comparable form of ONE row-level field, or null for "not declared". */
+function rowFieldValue(p: TemplateProfile, field: string): string | null {
+  const raw = (p as unknown as Record<string, unknown>)[field];
+  if (raw === undefined || raw === null) return null;
+  if (field === "applicableKinds") {
+    if (!Array.isArray(raw)) return null;
+    // Order-INSENSITIVE: applicableKinds is a SET (foundation vs grants declare
+    // client/partner/sponsor in opposite orders but mean the same thing).
+    return JSON.stringify([...(raw as string[])].sort());
+  }
+  return JSON.stringify(raw);
+}
+
+describe("workspace-templates — shared ecosystem role SSOT (corpus)", () => {
+  it("derives a non-empty shared-role vocabulary from foundation.yaml", () => {
+    // Guards the derivation itself: if foundation ever stops declaring its
+    // shared roles, rule (a) would silently guard nothing.
+    expect(foundation, "foundation template must exist in the corpus").toBeDefined();
+    expect([...SHARED_ROLE_SLUGS].sort()).toEqual(
+      ["churned", "client", "lead", "partner", "sponsor"]
+    );
+  });
+
+  it("(a) never declares a shared-role slug as a kind or workspace-scoped profile", () => {
+    const violations: string[] = [];
+    for (const tpl of templates) {
+      const tplSlug = templateSlug(tpl);
+      for (const p of profilesOf(tpl)) {
+        if (!SHARED_ROLE_SLUGS.has(p.slug)) continue;
+        if (normalizeKind(p.profileKind) !== "role") {
+          violations.push(
+            `${tplSlug}: role slug '${p.slug}' declared as profileKind='${normalizeKind(
+              p.profileKind
+            )}' (must be 'role')`
+          );
+        }
+        if (isWorkspaceScope(p.scope)) {
+          violations.push(
+            `${tplSlug}: role slug '${p.slug}' is workspace-scoped (scope='${
+              p.scope ?? "workspace"
+            }') — must be scope: shared`
+          );
+        }
+      }
+    }
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("(a2) never declares a shared-KIND slug as a role or workspace-scoped profile", () => {
+    const violations: string[] = [];
+    for (const tpl of templates) {
+      const tplSlug = templateSlug(tpl);
+      for (const p of profilesOf(tpl)) {
+        if (!SHARED_KIND_SLUGS.has(p.slug)) continue;
+        if (normalizeKind(p.profileKind) !== "kind") {
+          violations.push(
+            `${tplSlug}: shared-kind slug '${p.slug}' declared as profileKind='role' (must be a kind)`
+          );
+        }
+        if (isWorkspaceScope(p.scope)) {
+          violations.push(
+            `${tplSlug}: shared-kind slug '${p.slug}' is workspace-scoped (scope='${
+              p.scope ?? "workspace"
+            }') — must be scope: shared so require-consumers reuse the pod-wide row`
+          );
+        }
+      }
+    }
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("(b) never declares the same shared-profile property with CONFLICTING definitions (extras are legal overlays)", () => {
+    const defs = new Map<string, Map<string, Map<string, string[]>>>();
+    for (const tpl of templates) {
+      const tplSlug = templateSlug(tpl);
+      for (const p of profilesOf(tpl)) {
+        if (!isSharedScope(p.scope)) continue;
+        const perProfile = defs.get(p.slug) ?? new Map<string, Map<string, string[]>>();
+        for (const prop of p.properties ?? []) {
+          const propSlug = String(prop.slug);
+          const perProp = perProfile.get(propSlug) ?? new Map<string, string[]>();
+          const fp = propertyDefFingerprint(prop);
+          perProp.set(fp, [...(perProp.get(fp) ?? []), tplSlug]);
+          perProfile.set(propSlug, perProp);
+        }
+        defs.set(p.slug, perProfile);
+      }
+    }
+
+    const violations: string[] = [];
+    for (const [slug, perProfile] of defs) {
+      for (const [propSlug, perProp] of perProfile) {
+        if (perProp.size <= 1) continue;
+        const detail = [...perProp.entries()]
+          .map(([fp, carriers]) => `[${carriers.join(", ")}] => ${fp}`)
+          .join("  VS  ");
+        violations.push(
+          `shared '${slug}.${propSlug}' is declared with ${perProp.size} DIFFERENT definitions — ` +
+            `they target the SAME pod-wide column, so the survivor depends on apply order (base drift): ${detail}`
+        );
+      }
+    }
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("(c) never declares the same shared profile with CONFLICTING ROW-LEVEL fields (absence = no claim)", () => {
+    const decls = new Map<string, Map<string, Map<string, string[]>>>();
+    for (const tpl of templates) {
+      const tplSlug = templateSlug(tpl);
+      for (const p of profilesOf(tpl)) {
+        if (!isSharedScope(p.scope)) continue;
+        const perProfile = decls.get(p.slug) ?? new Map<string, Map<string, string[]>>();
+        for (const field of ROW_LEVEL_FIELDS) {
+          const value = rowFieldValue(p, field);
+          if (value === null) continue; // omitted = makes no claim
+          const perField = perProfile.get(field) ?? new Map<string, string[]>();
+          perField.set(value, [...(perField.get(value) ?? []), tplSlug]);
+          perProfile.set(field, perField);
+        }
+        decls.set(p.slug, perProfile);
+      }
+    }
+
+    const violations: string[] = [];
+    for (const [slug, perProfile] of decls) {
+      for (const [field, perField] of perProfile) {
+        if (perField.size <= 1) continue;
+        const detail = [...perField.entries()]
+          .map(([value, carriers]) => `[${carriers.join(", ")}] => ${value}`)
+          .join("  VS  ");
+        violations.push(
+          `shared '${slug}.${field}' is declared with ${perField.size} DIFFERENT values — ` +
+            `there is ONE pod-wide row and no overlay mechanism for row-level fields, so the ` +
+            `losing template's value is simply false on every pod and which one loses depends ` +
+            `on apply order. The fix is for the template that does NOT own this slug to stop ` +
+            `redeclaring it (omitting = no claim): ${detail}`
+        );
+      }
+    }
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("(d) every shared ROLE slug has applicableKinds declared by at least one template", () => {
+    const declared = new Map<string, boolean>();
+    for (const tpl of templates) {
+      for (const p of profilesOf(tpl)) {
+        if (!isSharedScope(p.scope)) continue;
+        if (normalizeKind(p.profileKind) !== "role") continue;
+        const has = Array.isArray(p.applicableKinds) && p.applicableKinds.length > 0;
+        declared.set(p.slug, (declared.get(p.slug) ?? false) || has);
+      }
+    }
+    const violations = [...declared.entries()]
+      .filter(([, has]) => !has)
+      .map(
+        ([slug]) =>
+          `shared role '${slug}' has NO template declaring a non-empty applicableKinds — ` +
+          `the pod-wide row would accept ANY entity kind as this role.`
+      );
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+});

package/src/social.yaml

@@ -6,6 +6,7 @@
 
 meta:
   slug: social
+  domain: content
   name: Social
   description: "Plan, schedule, and publish across your channels — then track how each post performs. Channels, posts, schedules, and engagement signals, all connected."
   icon: share-2
@@ -13,6 +14,17 @@ meta:
   tags: [social, distribution, publishing, channels]
   isPublic: true
 
+# Social REUSES Content OS's pod-wide `platform` (publishing-account) vocabulary
+# instead of forking its own `channel` kind. `platform` is `scope: shared` in
+# content-os, so a `require`-consumer gains access by RE-DECLARING the slug (the
+# resolver writes the grant on declare). This is a real standalone workspace —
+# hence `require` (deps-first install), not `compose`.
+dependencies:
+  - slug: content-os
+    kind: workspace
+    relation: require
+    reason: "Reuses Content OS's shared platform (publishing-account) vocabulary."
+
 workspace:
   name: Social
   description: "The distribution layer — the channels you publish on, the posts and schedules that pace them, and the engagement signals that tell you what's working."
@@ -28,35 +40,91 @@ workspace:
     social: provider
 
 profiles:
-  - slug: channel
-    displayName: Channel
-    icon: radio
-    color: "#1D9BF0"
-    description: "A social account you publish on — a platform, a handle, and its audience."
+  # ── Platform (shared publishing-account vocabulary — SSOT is content-os.yaml) ─
+  # RE-DECLARED from content-os's `platform` (post-shared). This declaration is
+  # what grants THIS workspace the shared vocabulary — a `require`-consumer must
+  # DECLARE the shared slug, not merely reference it across the boundary. (It
+  # shares the profile DEFINITION, not the platform entities — no `entityScope:
+  # pod`.) The body must not conflict with content-os's — guarded locally by the
+  # shared-role SSOT check, not a CI gate.
+  - slug: platform
+    displayName: Platform
+    icon: share-2
+    color: "#06B6D4"
+    description: "A social account, newsletter publication, or podcast channel. Each platform has its own audience metrics and publishing rhythm."
+    scope: shared
     properties:
-      - slug: platform
-        label: Platform
+      - slug: platform-type
+        label: Type
         valueType: string
         inputType: select
-        enumValues: [x, linkedin, instagram, tiktok, youtube, facebook, threads, other]
+        enumValues:
+          [
+            "LinkedIn",
+            "Instagram",
+            "TikTok",
+            "YouTube",
+            "Twitter / X",
+            "Threads",
+            "Bluesky",
+            "Newsletter",
+            "Podcast",
+            "Blog / Website",
+            "Other",
+          ]
       - slug: handle
         label: Handle
         valueType: string
         inputType: text
-      - slug: channel-url
-        label: URL
+        placeholder: "@username"
+      - slug: platform-status
+        label: Status
         valueType: string
-        inputType: url
+        inputType: select
+        enumValues: ["Active", "Building", "Maintenance Mode", "Inactive"]
+      - slug: platform-url
+        label: Profile URL
+        valueType: string
+        inputType: text
+        placeholder: "https://..."
+        constraints: { format: url }
       - slug: follower-count
-        label: Followers
+        label: "Follower / Subscriber Count"
         valueType: number
         inputType: number
-      - slug: channel-status
-        label: Status
+      - slug: follower-target
+        label: Target Count
+        valueType: number
+        inputType: number
+      - slug: avg-engagement-rate
+        label: "Avg Engagement Rate (%)"
+        valueType: number
+        inputType: number
+      - slug: platform-posting-freq
+        label: Posting Frequency
         valueType: string
         inputType: select
-        enumValues: [active, paused, archived]
-        constraints: { defaultValue: active }
+        enumValues:
+          [
+            "Daily",
+            "3x / week",
+            "2x / week",
+            "Weekly",
+            "Bi-weekly",
+            "Monthly",
+            "As Needed",
+          ]
+      - slug: last-post-date
+        label: Last Post Date
+        valueType: date
+      - slug: platform-notes
+        label: Notes
+        valueType: string
+        inputType: text
+        placeholder: "What works here? Tone, format, best times..."
+      - slug: platform-tags
+        label: Tags
+        valueType: array
 
   - slug: social-post
     displayName: Post
@@ -70,10 +138,10 @@ profiles:
         inputType: select
         enumValues: [draft, scheduled, published, failed]
         constraints: { defaultValue: draft }
-      - slug: post-channel
-        label: Channel
+      - slug: post-platform
+        label: Platform
         valueType: entity_id
-        targetProfileSlug: channel
+        targetProfileSlug: platform
         inputType: entity_select
       - slug: post-content
         label: Content
@@ -102,10 +170,10 @@ profiles:
     color: "#8B5CF6"
     description: "A recurring cadence for a channel — the slot pattern that keeps posting consistent."
     properties:
-      - slug: schedule-channel
-        label: Channel
+      - slug: schedule-platform
+        label: Platform
         valueType: entity_id
-        targetProfileSlug: channel
+        targetProfileSlug: platform
         inputType: entity_select
       - slug: cadence
         label: Cadence
@@ -127,10 +195,10 @@ profiles:
     color: "#10B981"
     description: "A performance reading for a channel over a period — reach, impressions, and the reactions that came back."
     properties:
-      - slug: signal-channel
-        label: Channel
+      - slug: signal-platform
+        label: Platform
         valueType: entity_id
-        targetProfileSlug: channel
+        targetProfileSlug: platform
         inputType: entity_select
       - slug: reach
         label: Reach
@@ -173,11 +241,11 @@ views:
     scopeProfileSlug: social-post
     groupBy: post-status
     description: "Posts on a board by status — draft to published."
-  - name: Channels
-    slug: channels
+  - name: Platforms
+    slug: platforms
     type: table
-    scopeProfileSlug: channel
-    description: "The channels you publish on, with platform, handle, and audience."
+    scopeProfileSlug: platform
+    description: "The platforms you publish on, with type, handle, and audience."
   - name: Signals
     slug: signals
     type: table
@@ -196,14 +264,14 @@ onboarding:
     spraying thin across five. Refuse "we post everywhere" — ask which channel
     actually earns attention, and what the real cadence is.
   collect:
-    - profileSlug: channel
-      what: The channels you actually publish on — one per real account, with its platform and handle.
+    - profileSlug: platform
+      what: The platforms you actually publish on — one per real account, with its type and handle.
       cardinality: few
-      keyFields: [platform, handle]
+      keyFields: [platform-type, handle]
     - profileSlug: social-post
-      what: The posts in motion — drafts, scheduled, and recently published — each tied to its channel.
+      what: The posts in motion — drafts, scheduled, and recently published — each tied to its platform.
       cardinality: several
-      keyFields: [post-status, post-channel]
+      keyFields: [post-status, post-platform]
   openingQuestions:
     - "Which channels are you actually active on right now, and which one earns the most attention?"
     - "What's your posting cadence per channel — daily, weekly, ad-hoc?"
@@ -226,8 +294,8 @@ layout:
       label: Content Calendar
       icon: calendar-clock
     - kind: view
-      viewName: Channels
-      label: Channels
+      viewName: Platforms
+      label: Platforms
       icon: radio
     - kind: view
       viewName: Signals
@@ -239,7 +307,7 @@ bento:
   viewName: Content Calendar
   blocks:
     - kind: view
-      viewName: Channels
+      viewName: Platforms
       pos: { x: 0, y: 0, w: 6, h: 5 }
     - kind: view
       viewName: Signals