@synap-core/workspace-templates 0.7.1 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/workspace-templates",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "description": "Canonical workspace definitions — YAML source + typed exports for browser, backend, CLI, and marketplace",
@@ -19,10 +19,11 @@
     "type-check": "tsc --noEmit",
     "build:yaml": "node build.mjs",
     "check:converters": "node scripts/check-converters.mjs",
-    "build": "node build.mjs && tsup && node scripts/check-converters.mjs",
+    "check:concepts": "node scripts/check-concepts.mjs",
+    "build": "node build.mjs && tsup && node scripts/check-converters.mjs && node scripts/check-concepts.mjs",
     "provision": "node scripts/provision.mjs",
     "eval": "node scripts/eval-standard.mjs",
-    "prepublishOnly": "node build.mjs && tsup && node scripts/check-converters.mjs"
+    "prepublishOnly": "node build.mjs && tsup && node scripts/check-converters.mjs && node scripts/check-concepts.mjs"
   },
   "dependencies": {
     "zod": "^3.0.0",

package/src/business-developer.yaml

@@ -50,6 +50,12 @@ profiles:
     description: A person or company actively being qualified or contacted by this CRM workspace.
     scope: WORKSPACE
     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]
     properties:
       - slug: lifecycleStage
@@ -112,6 +118,8 @@ profiles:
     description: A CRM lead converted by a won commercial proposal and ready for handoff.
     scope: WORKSPACE
     profileKind: role
+    # Workspace tier of the `client` concept — see the note on `crm-lead` above.
+    semanticSlug: crm.client
     applicableKinds: [person, company]
     properties:
       - slug: becameClientAt

package/src/catalog.test.ts

@@ -1,11 +1,11 @@
 /**
- * Unit tests for the mergeCatalog door. Run: `npx tsx --test src/catalog.test.ts`
+ * Unit tests for the mergeCatalog door. Run: `npx vitest run packages/workspace-templates` (from the repo root).
  *
  * These test the SOURCE (`./catalog.js` → catalog.ts), never `dist/`, so no build
  * is required and there is no stale-generated-output trap.
  */
 
-import { test } from "node:test";
+import { test } from "vitest";
 import assert from "node:assert/strict";
 import { mergeCatalog, computeTemplateUpdates, type RemoteEntry } from "./catalog.js";
 import type { WorkspaceYaml } from "./types.js";

package/src/composition-graph.test.ts

@@ -1,13 +1,13 @@
 /**
  * Unit tests for the `layerTemplateGraph` KEYSTONE engine.
- * Run: `npx tsx --test src/composition-graph.test.ts`
+ * Run: `npx vitest run packages/workspace-templates` (from the repo root).
  *
  * 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 { test } from "vitest";
 import assert from "node:assert/strict";
 import { layerTemplateGraph, type CompositionGraph } from "./composition-graph.js";
 import type { TemplateDependency } from "./types.js";

package/src/concept-guard.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Concept-guard tests.
+ *
+ * The first test is the gate: the SHIPPED corpus must be free of undeclared
+ * vocabulary forks. The rest prove the guard actually fires — a guard nobody
+ * has watched fail is decoration, so the failure cases are pinned here rather
+ * than demonstrated once by hand and forgotten.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  DECLARED_DIVERGENCES,
+  conceptTerm,
+  findConceptViolations,
+  formatConceptViolations,
+} from "./concept-guard.js";
+import { WORKSPACE_TEMPLATES } from "./templates.js";
+import type { WorkspaceYaml } from "./types.js";
+
+/** Minimal fixture corpus — only the fields the guard reads. */
+function corpus(
+  templates: Record<string, Array<Record<string, unknown>>>
+): Record<string, WorkspaceYaml> {
+  return Object.fromEntries(
+    Object.entries(templates).map(([slug, profiles]) => [slug, { profiles }])
+  ) as unknown as Record<string, WorkspaceYaml>;
+}
+
+const role = (slug: string, extra: Record<string, unknown> = {}) => ({
+  slug,
+  displayName: slug,
+  profileKind: "role",
+  properties: [],
+  ...extra,
+});
+
+describe("concept guard — shipped corpus", () => {
+  it("has no undeclared cross-template concept forks", () => {
+    const violations = findConceptViolations();
+    expect(
+      violations,
+      violations.length ? `\n${formatConceptViolations(violations)}\n` : ""
+    ).toEqual([]);
+  });
+
+  it("still sees the two-tier CRM divergence — declared, not absent", () => {
+    // If business-developer's crm-lead/crm-client ever stopped colliding with
+    // foundation's lead/client, the allowlist would be stale and rule 3 would
+    // fire. This asserts the allowlist is load-bearing, not inert.
+    const withoutAllowlist = Object.keys(DECLARED_DIVERGENCES);
+    expect(withoutAllowlist).toEqual(["crm-lead|lead", "client|crm-client"]);
+    expect(WORKSPACE_TEMPLATES["business-developer"]?.profiles.find((p) => p.slug === "crm-lead")
+      ?.semanticSlug).toBe("crm.lead");
+  });
+});
+
+describe("conceptTerm", () => {
+  it("reduces a qualified concept identifier to its bare noun", () => {
+    expect(conceptTerm("lead")).toBe("lead");
+    expect(conceptTerm("crm.lead")).toBe("lead");
+    expect(conceptTerm("crm-lead")).toBe("lead");
+    expect(conceptTerm("marketing.contact")).toBe("contact");
+  });
+});
+
+describe("concept guard — fires on a real fork", () => {
+  it("fails when a second template renames an existing role concept", () => {
+    const violations = findConceptViolations(
+      corpus({
+        foundation: [role("partner", { scope: "shared", applicableKinds: ["company"] })],
+        "some-addon": [role("channel-partner", { scope: "WORKSPACE" })],
+      })
+    );
+    // Fixture corpora never match the real allowlist, so the stale-allowlist
+    // findings are expected noise here — the collision is what is under test.
+    const forks = violations.filter((v) => v.rule !== "stale-allowlist");
+    expect(forks).toHaveLength(1);
+    expect(forks[0]!.rule).toBe("concept-collision");
+    expect(forks[0]!.concept).toBe("partner");
+    expect(forks[0]!.message).toContain("channel-partner");
+  });
+
+  it("suppresses exactly the pair an author declared — and nothing else", () => {
+    // The SAME shape as the test above, but with the slugs the allowlist names.
+    // This is the whole safety property of the escape hatch: it is per-pair, not
+    // per-concept, so a THIRD `lead` spelling would still fail.
+    const declared = findConceptViolations(
+      corpus({
+        foundation: [role("lead", { scope: "shared" })],
+        "business-developer": [role("crm-lead", { semanticSlug: "crm.lead", scope: "WORKSPACE" })],
+      })
+    );
+    expect(declared.filter((v) => v.rule === "concept-collision")).toEqual([]);
+
+    const third = findConceptViolations(
+      corpus({
+        foundation: [role("lead", { scope: "shared" })],
+        "business-developer": [role("crm-lead", { semanticSlug: "crm.lead", scope: "WORKSPACE" })],
+        "another-addon": [role("sales-lead", { scope: "WORKSPACE" })],
+      })
+    );
+    expect(third.filter((v) => v.rule === "concept-collision")).toHaveLength(2);
+  });
+
+  it("fires even when the fork hides behind a namespaced semanticSlug", () => {
+    const violations = findConceptViolations(
+      corpus({
+        foundation: [role("lead")],
+        other: [role("pipeline-lead", { semanticSlug: "sales.lead" })],
+      })
+    );
+    expect(violations.filter((v) => v.rule !== "stale-allowlist").map((v) => v.rule)).toEqual([
+      "concept-collision",
+    ]);
+  });
+
+  it("fails when two aliased profiles disagree on shape", () => {
+    const violations = findConceptViolations(
+      corpus({
+        a: [role("campaign", { semanticSlug: "marketing.campaign", scope: "shared" })],
+        b: [role("promo", { semanticSlug: "marketing.campaign", scope: "WORKSPACE" })],
+      })
+    );
+    expect(violations.map((v) => v.rule)).toContain("alias-shape-divergence");
+  });
+
+  it("fails when an allowlist entry stops matching anything", () => {
+    // DECLARED_DIVERGENCES is module-level, so an empty corpus makes every
+    // entry stale — exactly the state a resolved divergence would leave behind.
+    const violations = findConceptViolations(corpus({}));
+    expect(violations.every((v) => v.rule === "stale-allowlist")).toBe(true);
+    expect(violations).toHaveLength(Object.keys(DECLARED_DIVERGENCES).length);
+  });
+});
+
+describe("concept guard — stays green on legitimate patterns", () => {
+  it("allows the same slug re-declared across templates (overlay mechanism)", () => {
+    const violations = findConceptViolations(
+      corpus({
+        foundation: [role("lead", { scope: "shared", applicableKinds: ["person", "company"] })],
+        // A consumer legitimately OMITS row-level fields it does not own.
+        marketing: [role("lead", { scope: "shared" })],
+      })
+    );
+    expect(violations.filter((v) => v.rule !== "stale-allowlist")).toEqual([]);
+  });
+
+  it("allows sibling roles authored in ONE template to share a noun", () => {
+    const violations = findConceptViolations(
+      corpus({
+        "blockchain-ecosystem": [role("marketing-agency"), role("paid-ads-agency")],
+      })
+    );
+    expect(violations.filter((v) => v.rule !== "stale-allowlist")).toEqual([]);
+  });
+
+  it("allows an identical concept reused under one semanticSlug", () => {
+    const violations = findConceptViolations(
+      corpus({
+        "content-os": [role("campaign", { semanticSlug: "marketing.campaign", scope: "shared" })],
+        marketing: [role("campaign", { semanticSlug: "marketing.campaign", scope: "shared" })],
+      })
+    );
+    expect(violations.filter((v) => v.rule !== "stale-allowlist")).toEqual([]);
+  });
+
+  it("does not police non-role profiles", () => {
+    const violations = findConceptViolations(
+      corpus({
+        a: [{ slug: "note", displayName: "Note", properties: [] }],
+        b: [{ slug: "meeting-note", displayName: "Meeting Note", properties: [] }],
+      })
+    );
+    expect(violations.filter((v) => v.rule !== "stale-allowlist")).toEqual([]);
+  });
+});

package/src/concept-guard.ts

@@ -0,0 +1,219 @@
+/**
+ * Cross-template CONCEPT guard — catches vocabulary forks between templates.
+ *
+ * WHY THIS EXISTS (read before weakening or deleting it):
+ * `business-developer.yaml` introduced workspace-scoped `crm-lead`/`crm-client`
+ * for the same real-world concept that `foundation.yaml`/`crm.yaml` declare as
+ * pod-wide shared `lead`/`client`. Nothing failed. Three reasons:
+ *
+ *   1. `build.mjs`'s `validate()` runs PER FILE, inside the read loop, so it
+ *      structurally cannot see that another template already owns `lead`.
+ *   2. The only vocabulary rule that exists (`template-shared-role-ssot.test.ts`
+ *      in synap-backend) polices a HARDCODED five-slug set — and it FORBIDS
+ *      declaring one of those slugs workspace-scoped, which is exactly what the
+ *      two-tier design legitimately needed. So RENAMING was the path of least
+ *      resistance: `crm-lead` is outside the set and passes silently. That rule
+ *      polices SPELLING, not MEANING.
+ *   3. That test also cannot run in CI — it resolves this package across a
+ *      sibling-repo relative path that CI never checks out. It is green on a dev
+ *      machine and mute everywhere else.
+ *
+ * This guard lives HERE, in the repo that owns the template source, and runs in
+ * this repo's CI (`pnpm test`) and in `pnpm build` / `prepublishOnly` via
+ * `scripts/check-concepts.mjs`. It is deliberately NOT a hardcoded slug list —
+ * that is the pattern that failed.
+ *
+ * WHAT IT DOES NOT DO: it does not guess. There is no fuzzy name matching, no
+ * edit distance, no synonym table. A guesser nobody trusts is worse than no
+ * guard. It uses two exact, falsifiable signals only — see the rules below.
+ */
+
+import { WORKSPACE_TEMPLATES } from "./templates.js";
+import type { TemplateProfile, WorkspaceYaml } from "./types.js";
+
+export interface ConceptViolation {
+  rule: "concept-collision" | "alias-shape-divergence" | "stale-allowlist";
+  /** The concept term or semantic slug the finding is about. */
+  concept: string;
+  message: string;
+}
+
+/**
+ * DECLARED, INTENTIONAL divergences — the escape hatch, and deliberately the
+ * SECONDARY mechanism. An entry here is an author saying "yes, two spellings of
+ * one concept, on purpose, and here is why". Keep it tiny; every entry must
+ * carry its WHY. A key that stops matching anything FAILS the guard, so this
+ * list cannot rot into a graveyard.
+ *
+ * Key = the two colliding profile slugs, sorted, joined by "|".
+ */
+export const DECLARED_DIVERGENCES: Record<string, string> = {
+  // Two-tier lead vocabulary, documented at business-developer.yaml:1-16.
+  // Foundation's `lead` is a SHARED pod-wide role: being a lead is true
+  // everywhere. `crm-lead` is a WORKSPACE-scoped role so a person can be a lead
+  // inside one CRM workspace without becoming a lead across the whole pod. The
+  // tiers are intentionally separate rows; `semanticSlug: crm.lead` records the
+  // kinship so the two are discoverable as one concept via getBySemanticSlug.
+  "crm-lead|lead":
+    "business-developer: workspace-tier lead, deliberately NOT pod-wide foundation `lead` (two-tier CRM design)",
+  // Same reasoning for the post-sale side of the same lifecycle.
+  "client|crm-client":
+    "business-developer: workspace-tier client, deliberately NOT pod-wide foundation `client` (two-tier CRM design)",
+};
+
+/**
+ * A profile's concept identity. `semanticSlug` is the ONE field that can say
+ * "same concept, different spelling"; synap-backend's `profile-repository.ts`
+ * defaults it to the slug when unset, so this mirrors runtime truth exactly.
+ */
+function effectiveSemanticSlug(profile: TemplateProfile): string {
+  return profile.semanticSlug ?? profile.slug;
+}
+
+/**
+ * The bare noun a concept identifier ends in: `crm.lead` → `lead`,
+ * `crm-lead` → `lead`, `lead` → `lead`.
+ *
+ * This is EXACT terminal-token equality on the author's own qualified name —
+ * not a similarity heuristic. `crm-lead` and `lead` collide because the author
+ * literally wrote the same noun; `prospect` and `lead` do not collide, and that
+ * is honest: no guard can know they mean the same thing.
+ */
+export function conceptTerm(semanticSlug: string): string {
+  const tokens = semanticSlug.split(/[.\-_]/).filter(Boolean);
+  return (tokens[tokens.length - 1] ?? semanticSlug).toLowerCase();
+}
+
+/** `undefined`/`null` = the template makes NO claim, which cannot contradict one. */
+function declaredValue(profile: TemplateProfile, field: string): string | null {
+  const raw = (profile as unknown as Record<string, unknown>)[field];
+  if (raw === undefined || raw === null) return null;
+  if (field === "applicableKinds") {
+    return Array.isArray(raw) ? JSON.stringify([...(raw as string[])].sort()) : null;
+  }
+  // `scope` is authored as both `shared` and `WORKSPACE` across the corpus.
+  return JSON.stringify(String(raw).toLowerCase());
+}
+
+function pairKey(a: string, b: string): string {
+  return [a, b].sort().join("|");
+}
+
+interface ProfileRef {
+  template: string;
+  profile: TemplateProfile;
+}
+
+export function findConceptViolations(
+  templates: Record<string, WorkspaceYaml> = WORKSPACE_TEMPLATES
+): ConceptViolation[] {
+  const violations: ConceptViolation[] = [];
+  const all: ProfileRef[] = [];
+  for (const [templateSlug, template] of Object.entries(templates)) {
+    for (const profile of template.profiles ?? []) {
+      all.push({ template: templateSlug, profile });
+    }
+  }
+
+  // ── RULE 1 — concept collision across templates ────────────────────────────
+  // Two ROLE profiles, in DIFFERENT templates, with DIFFERENT slugs, whose
+  // concept identifiers end in the same noun. Every qualifier is load-bearing:
+  //   • ROLE only — roles are the facet vocabulary (the hat an entity wears),
+  //     where a fork actually hurts: the same person is a lead under one
+  //     spelling and not under the other. Kinds are things with their own life.
+  //   • DIFFERENT templates — sibling roles authored in ONE file are a
+  //     deliberate distinction the author had in front of them (blockchain-
+  //     ecosystem's `marketing-agency` + `paid-ads-agency`). A fork is by
+  //     definition cross-template drift. This qualifier is what takes the rule
+  //     from 1 false positive to 0 on the current corpus.
+  //   • DIFFERENT slugs — the SAME slug in several templates is the documented
+  //     overlay/reuse mechanism (`lead` in foundation + crm + marketing), not a
+  //     fork. That case is rule 2's business.
+  const roles = all.filter((r) => r.profile.profileKind === "role");
+  const usedAllowlistKeys = new Set<string>();
+  const reportedPairs = new Set<string>();
+
+  for (let i = 0; i < roles.length; i++) {
+    for (let j = i + 1; j < roles.length; j++) {
+      const a = roles[i]!;
+      const b = roles[j]!;
+      if (a.template === b.template) continue;
+      if (a.profile.slug === b.profile.slug) continue;
+      const term = conceptTerm(effectiveSemanticSlug(a.profile));
+      if (term !== conceptTerm(effectiveSemanticSlug(b.profile))) continue;
+
+      const key = pairKey(a.profile.slug, b.profile.slug);
+      if (key in DECLARED_DIVERGENCES) {
+        usedAllowlistKeys.add(key);
+        continue;
+      }
+      if (reportedPairs.has(key)) continue;
+      reportedPairs.add(key);
+      violations.push({
+        rule: "concept-collision",
+        concept: term,
+        message:
+          `two role profiles denote the concept "${term}" under different slugs: ` +
+          `"${a.profile.slug}" (${a.template}) vs "${b.profile.slug}" (${b.template}). ` +
+          `Either REUSE the existing slug, or — if the divergence is intentional — declare it: ` +
+          `set an explicit \`semanticSlug\` on the new profile and add "${key}" to ` +
+          `DECLARED_DIVERGENCES in src/concept-guard.ts with the reason.`,
+      });
+    }
+  }
+
+  // ── RULE 2 — declared alias, forked shape ──────────────────────────────────
+  // Two profiles with DIFFERENT slugs that claim the SAME `semanticSlug` are
+  // asserting "one concept". Then their row-level shape must agree, or the
+  // assertion is a lie and the field is decorative. Absence is not a conflict:
+  // a template that OMITS a row-level field makes no claim (that is exactly how
+  // marketing.yaml correctly stops restating what foundation owns).
+  // Same-slug re-declaration is NOT checked here — that is the overlay path.
+  const bySemantic = new Map<string, ProfileRef[]>();
+  for (const ref of all) {
+    const key = effectiveSemanticSlug(ref.profile);
+    const bucket = bySemantic.get(key);
+    if (bucket) bucket.push(ref);
+    else bySemantic.set(key, [ref]);
+  }
+  for (const [semantic, group] of bySemantic) {
+    if (new Set(group.map((r) => r.profile.slug)).size < 2) continue;
+    for (const field of ["profileKind", "scope", "applicableKinds"]) {
+      const claims = new Map<string, string>();
+      for (const ref of group) {
+        const value = declaredValue(ref.profile, field);
+        if (value === null) continue;
+        const existing = claims.get(value);
+        if (!existing) claims.set(value, `${ref.template}:${ref.profile.slug}`);
+      }
+      if (claims.size > 1) {
+        violations.push({
+          rule: "alias-shape-divergence",
+          concept: semantic,
+          message:
+            `profiles aliased to semanticSlug "${semantic}" disagree on \`${field}\`: ` +
+            [...claims].map(([v, who]) => `${who} declares ${v}`).join(", ") +
+            `. Aliased profiles assert one concept — make the shapes agree, or drop the alias.`,
+        });
+      }
+    }
+  }
+
+  // ── RULE 3 — the allowlist may not rot ─────────────────────────────────────
+  for (const key of Object.keys(DECLARED_DIVERGENCES)) {
+    if (usedAllowlistKeys.has(key)) continue;
+    violations.push({
+      rule: "stale-allowlist",
+      concept: key,
+      message:
+        `DECLARED_DIVERGENCES entry "${key}" no longer matches any collision — ` +
+        `the divergence was resolved or the profiles were renamed. Delete the entry.`,
+    });
+  }
+
+  return violations;
+}
+
+export function formatConceptViolations(violations: ConceptViolation[]): string {
+  return violations.map((v) => `  • [${v.rule}] ${v.message}`).join("\n");
+}

package/src/ecosystem.yaml

@@ -536,7 +536,10 @@ layout:
       icon: database
 
 bento:
-  viewName: Ecosystem Map
+  # Distinct from the "Ecosystem Map" graph view it embeds — the bento is created
+  # as its OWN view row, so reusing an embedded view's name puts two identically
+  # named views in the switcher.
+  viewName: Ecosystem Home
   blocks:
     - kind: view
       viewName: Ecosystem Map

package/src/generate.d.mts

@@ -0,0 +1,15 @@
+/** Types for `generate.mjs` — the shared renderer for `src/templates.ts`. */
+
+export interface RawTemplateEntry {
+  /** Source file name, e.g. `business-developer.yaml`. */
+  file: string;
+  /** `meta.slug` as declared in the YAML. */
+  slug: string;
+  /** The parsed YAML document, untyped on purpose (build-time shape). */
+  data: unknown;
+}
+
+export declare const SRC_DIR: string;
+export declare const TEMPLATES_FILE: string;
+export declare function readYamlTemplates(): RawTemplateEntry[];
+export declare function renderTemplatesModule(templates: RawTemplateEntry[]): string;

package/src/generate.mjs

@@ -0,0 +1,86 @@
+/**
+ * The ONE renderer for the generated `src/templates.ts` corpus.
+ *
+ * WHY THIS FILE EXISTS (read before inlining it back into build.mjs):
+ * `src/templates.ts` is auto-generated from `src/*.yaml` AND committed to git
+ * (it has to be — `browser/tsconfig.json` aliases this package straight at
+ * `src/`, with no build step, and synap-backend's
+ * `__tripwires__/template-shared-role-ssot.test.ts` reads the file by path).
+ * A committed artifact can go stale: edit a YAML, run `pnpm test`, and every
+ * template-corpus check — including `concept-guard` — passes against
+ * vocabulary that no longer exists on disk. Only `pnpm build` regenerated.
+ *
+ * So the render logic lives HERE, and two callers share it:
+ *   • `build.mjs`            — validates, renders, WRITES the file.
+ *   • `src/templates-freshness.test.ts` — renders in memory and asserts the
+ *     committed file matches byte-for-byte. Runs in `pnpm test`, i.e. in CI.
+ *
+ * Duplicating the template string into the test would recreate the same class
+ * of drift one level up, so don't.
+ */
+
+import { readFileSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+
+export const SRC_DIR = dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES_FILE = join(SRC_DIR, 'templates.ts');
+
+/**
+ * Read + parse every `src/*.yaml`, in the same (readdir) order build.mjs used.
+ * No validation here — validation stays in build.mjs, which is the writer.
+ */
+export function readYamlTemplates() {
+  return readdirSync(SRC_DIR)
+    .filter((f) => f.endsWith('.yaml'))
+    .map((file) => {
+      const parsed = yaml.load(readFileSync(join(SRC_DIR, file), 'utf-8'));
+      return { file, slug: parsed?.meta?.slug, data: parsed };
+    });
+}
+
+/** Render the full text of `src/templates.ts` for a corpus. Pure. */
+export function renderTemplatesModule(templates) {
+  const data = JSON.stringify(
+    Object.fromEntries(templates.map((t) => [t.slug, t.data])),
+    null,
+    2,
+  );
+
+  return `// ═══════════════════════════════════════════════════════════════════════
+// AUTO-GENERATED from YAML source files in src/*.yaml
+// DO NOT EDIT — run \`node build.mjs\` or \`pnpm build\` to regenerate
+// ═══════════════════════════════════════════════════════════════════════
+
+import type { WorkspaceYaml } from './types.js';
+
+const DATA = ${data} as unknown as Record<string, WorkspaceYaml>;
+
+export const WORKSPACE_TEMPLATES: Record<string, WorkspaceYaml> = DATA;
+
+export type WorkspaceTemplateSlug = keyof typeof WORKSPACE_TEMPLATES;
+
+export function getWorkspaceTemplate(slug: string): WorkspaceYaml | undefined {
+  return WORKSPACE_TEMPLATES[slug];
+}
+
+export function listWorkspaceTemplates(): WorkspaceYaml[] {
+  return Object.values(WORKSPACE_TEMPLATES);
+}
+
+/**
+ * Public templates only (\`meta.isPublic !== false\`). This is a CONVENIENCE
+ * filter for the default picker — NOT a security boundary: the private YAML
+ * still ships in the published tarball, so anything that must not leak cannot
+ * rely on this. \`listWorkspaceTemplates()\` returns all of them (CLI, seeder,
+ * tripwire need the full set). Publicity is also expressed per-entry as
+ * \`CatalogEntry.isPrivate\` by \`mergeCatalog()\`, so a caller can pass ALL
+ * templates and filter at the presentation layer instead of choosing a list
+ * function up front — the merge door itself never filters (it stays pure).
+ */
+export function listPublicTemplates(): WorkspaceYaml[] {
+  return Object.values(WORKSPACE_TEMPLATES).filter(t => t.meta?.isPublic !== false);
+}
+`;
+}

package/src/index.ts

@@ -98,6 +98,17 @@ export type {
   LayerTemplateGraphInput,
 } from "./composition-graph.js";
 
+// Cross-template vocabulary-fork guard. Exported because the build/publish gate
+// (`scripts/check-concepts.mjs`) runs it off `dist/` — one implementation, two
+// enforcement points (CI `pnpm test` + `pnpm build`).
+export {
+  findConceptViolations,
+  formatConceptViolations,
+  conceptTerm,
+  DECLARED_DIVERGENCES,
+} from "./concept-guard.js";
+export type { ConceptViolation } from "./concept-guard.js";
+
 export {
   toWorkspaceDefinition,
   toPackageDefinition,