@synap-core/workspace-templates 0.10.0 → 0.12.0

package/src/the-arch.yaml

@@ -50,6 +50,10 @@ dependencies:
     kind: workspace
     relation: require
     reason: "The engineering / ops dashboard — the build-side view of the company."
+  - slug: networking
+    kind: workspace
+    relation: require
+    reason: "The partner-intro layer — need → intro-matcher → intro → billed_as → deal, with the A↔B confidentiality firewall; the Stellar Client-Sync emits needs that depend on it."
 
 workspace:
   name: The Arch

package/src/types.ts

@@ -607,46 +607,44 @@ export interface TemplateExtendsRef {
  * PACKAGE_DEPENDENCY_KINDS — the dependency-kind vocabulary, declared ONCE.
  *
  * This tuple exists so consumers can IMPORT the vocabulary instead of
- * hand-copying it. `TemplateDependency` is currently mirrored by hand in six
- * other places, four of which carry a comment promising they match "VERBATIM so
- * the wire shape never drifts" — a comment doing a type's job. A comment cannot
- * fail a build; an import can. Those mirrors live in repos this package does not
- * own, so this tuple does not fix them by existing — it makes the fix possible:
+ * hand-copying it. `TemplateDependency` is mirrored by hand in several other
+ * places — a comment cannot fail a build, an import can, but these mirrors live
+ * in repos this package does not own, so they must match this list EXACTLY:
  *
- *   - marketplace            `types.ts:102`
- *   - onboarding             `workspace-templates.ts:27`
- *   - synap-backend          `package-definition.ts:204` (exports its own
- *                            `PackageDependencyKind` — the closest peer)
- *   - hub-protocol REST      `rest/packages.ts:140` (zod enum)
- *   - browser                `InstallPackageDialog.tsx:262`
- *   - control-plane-api      `routes/packages.ts:436` (zod enum)
+ *   - marketplace            `features/marketplace/src/types.ts`
+ *   - onboarding             `features/onboarding/src/{templates/workspace-templates,components/WorkspacePreview}.ts(x)`
+ *   - browser                `InstallPackageDialog.tsx`
+ *   - synap-backend          `package-definition.ts` (`PackageDependencyKind`)
+ *   - hub-protocol REST      `rest/packages.ts` (zod enum)
+ *   - control-plane-api      `db/schema/packages.ts` (`TemplateDependency` type)
+ *                            + `routes/packages.ts` (`DEPENDENCY_KINDS` zod enum)
  *
- * ⚠️ `'automation'` IS RETIRED VOCABULARY, deliberately still listed here.
- * CP migration `0049_package_vocabulary` retired the `automation` package
- * category in favour of `workflow` ("workflow — a triggered/sequenced run
- * (absorbs 'automation' + 'playbook')", `PACKAGE_TYPES` in CP
- * `db/schema/packages.ts`). A dependency's `kind` names the TYPE of package it
- * points at, so this vocabulary should track `PACKAGE_TYPES` — meaning the live
- * spelling is `workflow`, not `automation`.
+ * These are the 7 literals the wire accepts, in lockstep with the CP publish
+ * enum (`DEPENDENCY_KINDS = [...PACKAGE_TYPES, "automation"]`, CP
+ * `routes/packages.ts`), the hub install enum (`rest/packages.ts`), and the
+ * backend resolver's `PackageDependencyKind` (`@synap/database`).
  *
- * It is NOT renamed here, on purpose. This is latent, not live: 0/21 templates
- * declare any `kind` other than the default `'workspace'`. And all four wire
- * enums (CP + hub zod, above) still accept `'automation'` and do NOT accept
- * `'workflow'` — so emitting `'workflow'` today would be rejected with a 400 at
- * both doors, and dropping `'automation'` from this tuple would make any
- * consumer that derives a zod enum from it start rejecting a value the wire
- * still legally accepts (a published third-party package may carry it; CP's own
- * schema permits it). Narrowing must therefore follow the wire, not lead it.
+ * Resolver behaviour (backend `package-dependency-resolver.ts`):
+ *   - `workspace`         → resolve+install; the ONLY kind that may `compose`.
+ *   - `capability` / `cell` → resolve+install, always `require`d (presence).
+ *   - `skill` / `workflow` / `view` / `automation` → ACCEPTED and `require`d
+ *     present, surfaced as `required-absent` (non-fatal) — no standalone by-slug
+ *     applier on the pod yet; when one grows, give the kind its own branch.
  *
- * ORDERED FIX (each step deployable alone, no flag day):
- *   1. Widen the CP + hub zod enums to accept BOTH `'automation'` and `'workflow'`.
- *   2. Add `'workflow'` here; mark `'automation'` deprecated; migrate any authored use.
- *   3. Once no payload carries `'automation'`, drop it from the wire enums and this tuple.
+ * `'automation'` is legacy vocabulary: CP migration `0049_package_vocabulary`
+ * renamed the `automation` package category → `workflow` (which absorbs
+ * automation + playbook, `PACKAGE_TYPES` in CP `db/schema/packages.ts`). It
+ * stays accepted on the wire — and therefore in this tuple — for back-compat
+ * with dependencies published before the rename.
  */
 export const PACKAGE_DEPENDENCY_KINDS = [
   "workspace",
   "capability",
-  /** @deprecated Retired by CP 0049 in favour of `workflow`. See note above. */
+  "skill",
+  "workflow",
+  "view",
+  "cell",
+  /** @deprecated Legacy alias for `workflow` (CP 0049). Still accepted on the wire. */
   "automation",
 ] as const;
 
@@ -658,8 +656,8 @@ export interface TemplateDependency {
   slug: string;
   /**
    * What the dependency is. Default `'workspace'`. Only `'workspace'`
-   * dependencies can be `compose`d; `'capability'`/`'automation'` are always
-   * `require`d present without merging.
+   * dependencies can be `compose`d; every other kind is always `require`d
+   * present without merging.
    */
   kind?: PackageDependencyKind;
   /**

package/src/validate-flow.ts

@@ -667,7 +667,17 @@ function collectLoopBindingRefs(data: unknown): string[] {
       return;
     }
     if (isRecord(v)) {
-      for (const x of Object.values(v)) walk(x);
+      // Skip AUTHORING NOTES. An `_`-prefixed key is documentation the runtime
+      // never evaluates (`_filterNote` and friends explain what DOWNSTREAM
+      // nodes do, and so legitimately quote `{{loop.item...}}` in prose).
+      // Reading them as live references made a correct flow fail validation:
+      // `stellar-grant-client` was reported as "references {{loop.item}} but is
+      // not inside a loop body" purely because its note DESCRIBED the nodes
+      // that do. Kept identical in all three copies of this walker.
+      for (const [k, x] of Object.entries(v)) {
+        if (k.startsWith("_")) continue;
+        walk(x);
+      }
     }
   };
   walk(data);

package/src/validate.test.ts

@@ -80,6 +80,92 @@ describe("validateTemplate — clean template", () => {
   });
 });
 
+describe("validateTemplate — system Knowledge contract", () => {
+  const template = (overrides: Record<string, unknown> = {}): WorkspaceYaml =>
+    ({
+      meta: {
+        slug: "knowledge-consumer",
+        name: "Knowledge consumer",
+        description: "d",
+        icon: "brain",
+        color: "#000000",
+      },
+      workspace: { name: "Knowledge consumer", description: "d" },
+      profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+      views: [
+        {
+          name: "Knowledge",
+          type: "table",
+          scopeProfileSlug: "knowledge",
+          config: { columns: ["title", "knowledgeForm"] },
+        },
+      ],
+      ...overrides,
+    }) as WorkspaceYaml;
+
+  it("allows templates to consume system Knowledge without redeclaring it", () => {
+    const result = validateTemplate(
+      template({
+        seedEntities: [
+          {
+            profileSlug: "knowledge",
+            title: "Write migrations that preserve meaning",
+            properties: { knowledgeForm: "insight" },
+          },
+        ],
+      })
+    );
+
+    expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
+  });
+
+  it("rejects a template-owned Knowledge profile", () => {
+    const result = validateTemplate(
+      template({
+        profiles: [
+          {
+            slug: "knowledge",
+            displayName: "Knowledge",
+            properties: [
+              {
+                slug: "ek_type",
+                label: "Type",
+                valueType: "string",
+                inputType: "select",
+                enumValues: ["gotcha", "lesson"],
+              },
+            ],
+          },
+        ],
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    expect(
+      result.errors.some((error) => error.rule === "system-profile-redefined")
+    ).toBe(true);
+  });
+
+  it("rejects a legacy or missing Knowledge form on seeded Knowledge", () => {
+    const result = validateTemplate(
+      template({
+        seedEntities: [
+          {
+            profileSlug: "knowledge",
+            title: "Legacy knowledge",
+            properties: { ek_type: "gotcha" },
+          },
+        ],
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    expect(
+      result.errors.map((error) => error.rule).sort()
+    ).toEqual(["knowledge-seed-form-invalid", "knowledge-seed-legacy-form"]);
+  });
+});
+
 // Regression: before wiring `validateFlowDefinition` into validateTemplate, a
 // template automation with a broken FLOW (bogus node type / dangling edge / cycle
 // / typo'd channelType) passed the template gate green and then silently never

package/src/validate.ts

@@ -159,6 +159,22 @@ export const SYSTEM_PROFILES = new Set([
   "report",
 ]);
 
+/**
+ * System-owned profiles whose schema is defined by the pod, rather than by a
+ * workspace template. A template may scope a view, link, sidebar item, or seed
+ * entity to `knowledge` because it is in {@link SYSTEM_PROFILES}; it must never
+ * declare the profile itself. Re-declaring it would turn a shared contract into
+ * whichever template happened to be applied first.
+ *
+ * `knowledgeForm` is intentionally an enum property on the Knowledge kind, not
+ * a facet/role: a knowledge entity has exactly one form, while Synap roles are
+ * additive. Keep this guard local to the template corpus; the actual profile
+ * schema and its migration are owned by the backend seeder.
+ */
+const TEMPLATE_FORBIDDEN_SYSTEM_PROFILE_SLUGS = new Set(["knowledge"]);
+const KNOWLEDGE_FORMS = new Set(["insight", "caution"]);
+const LEGACY_KNOWLEDGE_SEED_FIELDS = new Set(["ek_type", "type"]);
+
 // ── Dependency-vocabulary closure (compose vs require semantics) ─────────────
 
 /**
@@ -396,6 +412,20 @@ export function validateTemplate(
   const known = (s: string) =>
     slugs.has(s) || SYSTEM_PROFILES.has(s) || baseProfileSlugs.has(s);
 
+  // ── System-owned Knowledge contract ─────────────────────────────────────
+  // `knowledge` is available to every template through SYSTEM_PROFILES. It is
+  // not an overlay point: allowing a template to declare it lets a workspace
+  // fork its base property definitions, enum vocabulary, or profile row-level
+  // metadata. Templates consume it through views/links/seeds only.
+  for (const profile of tpl.profiles || []) {
+    if (!TEMPLATE_FORBIDDEN_SYSTEM_PROFILE_SLUGS.has(profile.slug)) continue;
+    add(
+      "system-profile-redefined",
+      `profiles.${profile.slug}`,
+      `Profile "${profile.slug}" is system-owned. Reference it from views, links, sidebar items, or seedEntities; do not declare template-owned properties or metadata.`
+    );
+  }
+
   // Views: structured views need a scope; scoped profiles must resolve.
   for (const v of tpl.views || []) {
     const type = String(v.type || "").toLowerCase();
@@ -579,6 +609,25 @@ export function validateTemplate(
         "seedEntities",
         `seedEntity references unknown profile "${s.profileSlug}"`
       );
+
+    if (s.profileSlug !== "knowledge") continue;
+    const properties = s.properties ?? {};
+    for (const field of LEGACY_KNOWLEDGE_SEED_FIELDS) {
+      if (!(field in properties)) continue;
+      add(
+        "knowledge-seed-legacy-form",
+        `seedEntities.${s.title}.properties.${field}`,
+        `Knowledge seed entities use "knowledgeForm" ("insight" | "caution"), not the legacy "${field}" field.`
+      );
+    }
+    const form = properties.knowledgeForm;
+    if (!KNOWLEDGE_FORMS.has(String(form))) {
+      add(
+        "knowledge-seed-form-invalid",
+        `seedEntities.${s.title}.properties.knowledgeForm`,
+        `Knowledge seed entities require knowledgeForm to be "insight" or "caution".`
+      );
+    }
   }
 
   // profileSlug referential integrity, part 2 — every OTHER site that names a