@synap-core/workspace-templates 0.12.0 → 0.23.0

package/src/presentation-declarations.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Presentation DECLARATIONS (entity rendering, decision 8) — a kind declares
+ * how it renders on its catalog profile; the pod stores it as
+ * `uiHints.presentation`.
+ *
+ * Pinned:
+ *  - the whole corpus validates with zero `presentation-*` errors;
+ *  - the declared kinds carry the family the plan assigns (non-vacuity: the
+ *    corpus really declares them, so a deleted block fails here);
+ *  - every declaration parses under the ONE parser (`@synap-core/types/presentation`);
+ *  - each rule fires on a broken clone (self-checks): parser issue, unknown
+ *    property, entityRef on a non-entity_id property, divergence across
+ *    templates. Absent on another declaration is NOT a divergence.
+ */
+import { describe, expect, it } from "vitest";
+import { parseProfilePresentation } from "@synap-core/types/presentation";
+import { validateTemplate } from "./validate.js";
+import type { WorkspaceYaml } from "./types.js";
+import { readYamlTemplates } from "./generate.mjs";
+
+const corpus = readYamlTemplates().map((t) => t.data as WorkspaceYaml);
+const tpl = (slug: string) => corpus.find((t) => t.meta.slug === slug)!;
+const presentationErrors = (t: WorkspaceYaml, c: WorkspaceYaml[] = corpus) =>
+  validateTemplate(t, { corpus: c }).errors.filter((e) =>
+    e.rule.startsWith("presentation-")
+  );
+const clone = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
+
+describe("presentation declarations — the corpus", () => {
+  it("validates with zero presentation-* errors", () => {
+    for (const t of corpus)
+      expect(presentationErrors(t), t.meta.slug).toEqual([]);
+  });
+
+  it("the plan's kinds declare their family", () => {
+    const expected: Array<[string, string, string]> = [
+      ["brand-library", "brand-asset", "media"],
+      ["brand-library", "brand-reference", "link"],
+      ["brand-library", "content-guideline", "document"],
+      ["content-os", "render-job", "media"],
+      ["content-os", "post", "work"],
+      ["social", "post", "work"],
+      ["builder-workspace", "ui-design", "media"],
+      ["life-os", "bookmark", "link"],
+      ["life-os", "book", "record"],
+    ];
+    for (const [t, profile, family] of expected) {
+      const p = tpl(t)?.profiles.find((x) => x.slug === profile);
+      expect(p?.presentation?.family, `${t}/${profile}`).toBe(family);
+    }
+  });
+
+  it("every declaration parses under the ONE parser", () => {
+    let declared = 0;
+    for (const t of corpus)
+      for (const p of t.profiles ?? []) {
+        if (p.presentation === undefined) continue;
+        declared++;
+        expect(
+          parseProfilePresentation(p.presentation).ok,
+          `${t.meta.slug}/${p.slug}`
+        ).toBe(true);
+      }
+    expect(declared).toBeGreaterThanOrEqual(20);
+  });
+});
+
+describe("presentation declarations — each rule fires (self-checks)", () => {
+  const brand = () => clone(tpl("brand-library"));
+  const asset = (t: WorkspaceYaml) =>
+    t.profiles.find((p) => p.slug === "brand-asset")!;
+
+  it("presentation-invalid: the parser's issues", () => {
+    const t = brand();
+    (asset(t) as { presentation: unknown }).presentation = {
+      family: "gallery",
+    };
+    const errs = presentationErrors(t);
+    expect(errs.map((e) => e.rule)).toContain("presentation-invalid");
+    expect(
+      errs.find((e) => e.rule === "presentation-invalid")!.message
+    ).toMatch(/family/);
+  });
+
+  it("presentation-property-unknown: a media property the profile lacks", () => {
+    const t = brand();
+    asset(t).presentation = {
+      family: "media",
+      media: { source: { property: "no-such-field" } },
+    };
+    expect(presentationErrors(t).map((e) => e.rule)).toContain(
+      "presentation-property-unknown"
+    );
+  });
+
+  it("presentation-property-unknown: a card field the profile lacks", () => {
+    const t = brand();
+    asset(t).presentation = {
+      family: "media",
+      fields: { card: ["asset-kind", "nope"] },
+    };
+    const errs = presentationErrors(t, [t]);
+    expect(errs).toHaveLength(1);
+    expect(errs[0]).toMatchObject({
+      rule: "presentation-property-unknown",
+      path: "profiles.brand-asset.presentation.fields.card[1]",
+    });
+  });
+
+  it("presentation-property-unknown: a FALLBACK property the profile lacks, at its own path", () => {
+    const t = brand();
+    asset(t).presentation = {
+      family: "media",
+      media: {
+        source: { property: "asset-document-id" },
+        fallbacks: [{ property: "asset-url" }, { property: "gone" }],
+      },
+    };
+    const errs = presentationErrors(t, [t]);
+    expect(errs).toHaveLength(1);
+    expect(errs[0]).toMatchObject({
+      rule: "presentation-property-unknown",
+      path: "profiles.brand-asset.presentation.media.fallbacks[1].property",
+    });
+  });
+
+  it("brand-asset declares every home of its picture: the upload, then the external URL", () => {
+    expect(asset(tpl("brand-library")).presentation?.media).toEqual({
+      source: { property: "asset-document-id" },
+      fallbacks: [{ property: "asset-url" }],
+    });
+  });
+
+  it("presentation-entityref-type: an entityRef that is not an entity_id", () => {
+    const t = brand();
+    asset(t).presentation = {
+      family: "media",
+      media: { source: { entityRef: "asset-kind" } },
+    };
+    const rules = presentationErrors(t).map((e) => e.rule);
+    expect(rules).toContain("presentation-entityref-type");
+    // The property exists — its TYPE is wrong; never reported as unknown.
+    expect(rules).not.toContain("presentation-property-unknown");
+  });
+
+  it("documentId: true names no property and is accepted", () => {
+    const t = brand();
+    asset(t).presentation = {
+      family: "media",
+      media: { source: { documentId: true } },
+    };
+    expect(presentationErrors(t, [t])).toEqual([]);
+  });
+
+  it("presentation-diverges: two templates declare the same kind differently", () => {
+    const os = clone(tpl("content-os"));
+    os.profiles.find((p) => p.slug === "post")!.presentation = {
+      family: "document",
+    };
+    const rest = corpus.filter((t) => t.meta.slug !== "content-os");
+    expect(presentationErrors(os, [...rest, os]).map((e) => e.rule)).toContain(
+      "presentation-diverges"
+    );
+  });
+
+  it("absent on another declaration is not a divergence", () => {
+    const social = clone(tpl("social"));
+    delete social.profiles.find((p) => p.slug === "post")!.presentation;
+    const rest = corpus.filter((t) => t.meta.slug !== "social");
+    expect(presentationErrors(tpl("content-os"), [...rest, social])).toEqual(
+      []
+    );
+  });
+});

package/src/process-contract.validate.test.ts

@@ -0,0 +1,352 @@
+/**
+ * The process contract a playbook declares is checked at authoring time
+ * (`checkProcessContract` in validate.ts), because every one of these mistakes
+ * is STORED by the pod and then silently never fires:
+ *   - a `statusProperty` that is not a select of the subject kind → the stage's
+ *     status write lands on a field nobody reads;
+ *   - a `subjectStatus` / activator `status` / `humanOnlyStatuses` value that is
+ *     not one of the enum values → a write the select refuses, or a rule on a
+ *     value no entity ever enters;
+ *   - an `onFail.toStage` naming no stage → a rejected gate with nowhere to go;
+ *   - a `relationToSubject` naming no relation → an edge type nothing renders.
+ *
+ * Each rule has a failing fixture below, built by mutating ONE field of a clean
+ * fixture, and the clean fixture is asserted clean — so a fixture that fails for
+ * an unrelated reason cannot pass for the wrong one.
+ */
+
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { MAX_SESSION_CRITERIA, validateTemplate } from "./validate.js";
+import type { WorkspaceYaml } from "./types.js";
+import { readYamlTemplates } from "./generate.mjs";
+
+const PROCESS_RULES = new Set([
+  "playbook-status-property-no-subject",
+  "playbook-status-property-unknown",
+  "playbook-status-property-not-select",
+  "stage-subject-status-unknown",
+  "stage-subject-status-unknown-no-property",
+  "stage-onfail-unknown",
+  "activator-on-invalid",
+  "activator-mode-invalid",
+  "activator-no-subject",
+  "activator-status-required",
+  "activator-status-unknown",
+  "activator-status-unknown-no-property",
+  "activator-status-unexpected",
+  "human-only-status-unknown",
+  "human-only-status-unknown-no-property",
+  "output-relation-no-subject",
+  "output-relation-unknown",
+  "output-optional-not-boolean",
+  "playbook-criteria-over-session-cap",
+]);
+
+/**
+ * `owner` OWNS the shared kind `widget` (with its lifecycle select). `proc`
+ * requires it and only re-declares `widget` with no properties — so resolving
+ * `widget-stage` proves the status property is found ACROSS the corpus.
+ */
+const owner = {
+  meta: { slug: "owner", name: "Owner", description: "d", icon: "x", color: "gray" },
+  workspace: { name: "Owner", description: "d" },
+  profiles: [
+    {
+      slug: "widget",
+      displayName: "Widget",
+      scope: "shared",
+      properties: [
+        { slug: "widget-stage", label: "Stage", valueType: "string", inputType: "select", enumValues: ["New", "Built", "Shipped", "Archived"] },
+        { slug: "widget-notes", label: "Notes", valueType: "string", inputType: "text" },
+      ],
+    },
+  ],
+  entityLinks: [{ sourceProfileSlug: "widget", targetProfileSlug: "widget", type: "spawned_from", label: "Spawned from" }],
+} as unknown as WorkspaceYaml;
+
+function proc(mutate: (pb: Record<string, any>) => void = () => {}): WorkspaceYaml {
+  const pb: Record<string, any> = {
+    name: "Build Widget",
+    goalTemplate: "Build {widget}",
+    params: [{ name: "widget", type: "entity", required: true }],
+    subjectProfile: { profileSlug: "widget", statusProperty: "widget-stage" },
+    humanOnlyStatuses: ["New", "Archived"],
+    activators: [{ on: "enters_status", status: "Built", mode: "propose" }],
+    expectedOutputs: [{ kind: "widget", label: "Spin-off", relationToSubject: "spawned_from" }],
+    stages: [
+      { key: "build", name: "Build", category: "started", subjectStatus: "Built" },
+      {
+        key: "ship",
+        name: "Ship",
+        category: "completed",
+        subjectStatus: "Shipped",
+        gate: { kind: "human" },
+        onFail: { toStage: "build" },
+        expectedOutputs: [{ kind: "widget", label: "Release", relationToSubject: "spawned_from" }],
+      },
+    ],
+  };
+  mutate(pb);
+  return {
+    meta: { slug: "proc", name: "Proc", description: "d", icon: "x", color: "gray" },
+    workspace: { name: "Proc", description: "d" },
+    dependencies: [{ slug: "owner", kind: "workspace", relation: "require" }],
+    profiles: [{ slug: "widget", displayName: "Widget", scope: "shared", properties: [] }],
+    playbooks: [pb],
+  } as unknown as WorkspaceYaml;
+}
+
+function processErrors(tpl: WorkspaceYaml) {
+  const { errors } = validateTemplate(tpl, { corpus: [owner, tpl] });
+  return errors.filter((e) => PROCESS_RULES.has(e.rule));
+}
+const rulesOf = (tpl: WorkspaceYaml) => processErrors(tpl).map((e) => e.rule);
+
+describe("process contract — the clean fixture is clean", () => {
+  it("a kind owned by a DEPENDENCY resolves its status property and relation", () => {
+    expect(processErrors(proc())).toEqual([]);
+  });
+});
+
+describe("process contract — each rule fires on its own fixture", () => {
+  it("statusProperty that the kind does not carry", () => {
+    expect(rulesOf(proc((pb) => (pb.subjectProfile.statusProperty = "widget-phase")))).toEqual([
+      "playbook-status-property-unknown",
+    ]);
+  });
+
+  it("statusProperty that is not a select", () => {
+    expect(
+      rulesOf(
+        proc((pb) => {
+          pb.subjectProfile.statusProperty = "widget-notes";
+          // Without a resolvable vocabulary the statuses are not re-reported.
+        })
+      )
+    ).toEqual(["playbook-status-property-not-select"]);
+  });
+
+  it("statusProperty with no subject kind", () => {
+    const rules = rulesOf(proc((pb) => (pb.subjectProfile = { statusProperty: "widget-stage" })));
+    expect(rules).toContain("playbook-status-property-no-subject");
+  });
+
+  it("a stage subjectStatus outside the enum", () => {
+    expect(rulesOf(proc((pb) => (pb.stages[0].subjectStatus = "Done")))).toEqual([
+      "stage-subject-status-unknown",
+    ]);
+  });
+
+  it("a stage subjectStatus with no statusProperty to belong to", () => {
+    const rules = rulesOf(
+      proc((pb) => {
+        delete pb.subjectProfile.statusProperty;
+        delete pb.humanOnlyStatuses;
+        pb.activators = [{ on: "created", mode: "propose" }];
+      })
+    );
+    expect(rules).toEqual([
+      "stage-subject-status-unknown-no-property",
+      "stage-subject-status-unknown-no-property",
+    ]);
+  });
+
+  it("onFail.toStage naming no stage of the playbook", () => {
+    expect(rulesOf(proc((pb) => (pb.stages[1].onFail = { toStage: "qa" })))).toEqual([
+      "stage-onfail-unknown",
+    ]);
+  });
+
+  it("onFail.toStage may name a stage by its name", () => {
+    expect(rulesOf(proc((pb) => (pb.stages[1].onFail = { toStage: "Build" })))).toEqual([]);
+  });
+
+  it("an activator status outside the enum", () => {
+    expect(
+      rulesOf(proc((pb) => (pb.activators = [{ on: "enters_status", status: "Done", mode: "run" }])))
+    ).toEqual(["activator-status-unknown"]);
+  });
+
+  it("an enters_status activator with no status", () => {
+    expect(rulesOf(proc((pb) => (pb.activators = [{ on: "enters_status", mode: "propose" }])))).toEqual([
+      "activator-status-required",
+    ]);
+  });
+
+  it("an activator with an unknown trigger or mode", () => {
+    expect(rulesOf(proc((pb) => (pb.activators = [{ on: "updated", mode: "always" }])))).toEqual([
+      "activator-on-invalid",
+      "activator-mode-invalid",
+    ]);
+  });
+
+  /**
+   * arch F8: the catalog speaks the pod's worker grammar. Rows rule out: a
+   * validator still limited to created/enters_status (count, schedule,
+   * manual refused); a count whose status is not checked against the enum; a
+   * manual or created trigger taking a status.
+   */
+  it("count, schedule and manual workers validate, with their statuses checked", () => {
+    expect(
+      rulesOf(
+        proc(
+          (pb) =>
+            (pb.activators = [
+              { on: "count", status: "Built", min: 5, size: "per_moment", mode: "propose", maxPendingApprovals: 10 },
+              { on: "schedule", cron: "0 9 * * 1", status: "Built", mode: "run" },
+              { on: "manual", mode: "propose" },
+            ])
+        )
+      )
+    ).toEqual([]);
+    expect(
+      rulesOf(proc((pb) => (pb.activators = [{ on: "count", status: "Done", min: 5, mode: "propose" }])))
+    ).toEqual(["activator-status-unknown"]);
+    expect(rulesOf(proc((pb) => (pb.activators = [{ on: "count", min: 5, mode: "propose" }])))).toEqual([
+      "activator-status-required",
+    ]);
+    expect(rulesOf(proc((pb) => (pb.activators = [{ on: "manual", status: "Built", mode: "propose" }])))).toEqual([
+      "activator-status-unexpected",
+    ]);
+  });
+
+  it("an activator on a playbook with no subject kind", () => {
+    const rules = rulesOf(
+      proc((pb) => {
+        delete pb.subjectProfile;
+        delete pb.stages;
+        delete pb.humanOnlyStatuses;
+        delete pb.expectedOutputs;
+        pb.activators = [{ on: "created", mode: "propose" }];
+      })
+    );
+    expect(rules).toEqual(["activator-no-subject"]);
+  });
+
+  it("a humanOnlyStatuses value outside the enum", () => {
+    expect(rulesOf(proc((pb) => (pb.humanOnlyStatuses = ["New", "Retired"])))).toEqual([
+      "human-only-status-unknown",
+    ]);
+  });
+
+  it("a playbook-level relationToSubject the corpus does not define", () => {
+    expect(rulesOf(proc((pb) => (pb.expectedOutputs[0].relationToSubject = "spawned_by")))).toEqual([
+      "output-relation-unknown",
+    ]);
+  });
+
+  it("a stage-level relationToSubject the corpus does not define", () => {
+    expect(
+      rulesOf(proc((pb) => (pb.stages[1].expectedOutputs[0].relationToSubject = "spawned_by")))
+    ).toEqual(["output-relation-unknown"]);
+  });
+
+  it("an output `optional` that is not a boolean, at playbook and stage level", () => {
+    // The pod reads `optional` strictly (only a real `true`): a quoted value
+    // would leave the slot owed while the YAML reads as if it were not.
+    expect(rulesOf(proc((pb) => (pb.expectedOutputs[0].optional = "true")))).toEqual([
+      "output-optional-not-boolean",
+    ]);
+    expect(rulesOf(proc((pb) => (pb.stages[1].expectedOutputs[0].optional = "false")))).toEqual([
+      "output-optional-not-boolean",
+    ]);
+    // A real boolean is clean at both levels.
+    expect(
+      rulesOf(
+        proc((pb) => {
+          pb.expectedOutputs[0].optional = true;
+          pb.stages[1].expectedOutputs[0].optional = false;
+        })
+      )
+    ).toEqual([]);
+  });
+
+  it("a DEFAULT relation (base.yaml relationDefs) resolves through the corpus", () => {
+    const base = readYamlTemplates().find((t) => t.slug === "base")!.data as WorkspaceYaml;
+    const tpl = proc((pb) => (pb.expectedOutputs[0].relationToSubject = "relates_to"));
+    const { errors } = validateTemplate(tpl, { corpus: [owner, base, tpl] });
+    expect(errors.filter((e) => PROCESS_RULES.has(e.rule))).toEqual([]);
+    // …and the same value is refused when base is not in the corpus.
+    expect(rulesOf(tpl)).toEqual(["output-relation-unknown"]);
+  });
+
+  it("relationToSubject on a subject-less playbook must be `none`", () => {
+    const strip = (pb: Record<string, any>) => {
+      delete pb.subjectProfile;
+      delete pb.stages;
+      delete pb.humanOnlyStatuses;
+      delete pb.activators;
+    };
+    expect(rulesOf(proc(strip))).toEqual(["output-relation-no-subject"]);
+    expect(
+      rulesOf(
+        proc((pb) => {
+          strip(pb);
+          pb.expectedOutputs[0].relationToSubject = "none";
+        })
+      )
+    ).toEqual([]);
+  });
+});
+
+describe("process contract — a session keeps at most MAX_SESSION_CRITERIA criteria", () => {
+  const crit = (key: string) => ({ key, statement: `${key} holds.`, check: { kind: "judge" } });
+  const withCriteria = (playbookLevel: number, perStage: number) =>
+    proc((pb) => {
+      pb.criteria = Array.from({ length: playbookLevel }, (_, i) => crit(`pb-${i}`));
+      pb.stages.forEach((s: Record<string, any>) => {
+        s.criteria = Array.from({ length: perStage }, (_, i) => crit(`${s.key}-${i}`));
+      });
+    });
+
+  it("playbook-level plus stage criteria at the cap pass", () => {
+    // 2 playbook-level + 2 stages × 5 = 12
+    expect(rulesOf(withCriteria(2, 5))).toEqual([]);
+  });
+
+  it("one over the cap is refused (the pod drops the extra one silently)", () => {
+    // 3 + 2 × 5 = 13
+    expect(rulesOf(withCriteria(3, 5))).toEqual(["playbook-criteria-over-session-cap"]);
+  });
+
+  it("a key repeated across stages counts once, as the pod keeps it once", () => {
+    const tpl = proc((pb) => {
+      pb.criteria = Array.from({ length: 12 }, (_, i) => crit(`k-${i}`));
+      pb.stages[0].criteria = [crit("k-0")];
+    });
+    expect(rulesOf(tpl)).toEqual([]);
+  });
+});
+
+const BACKEND_PLAYBOOKS = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../synap-backend/packages/playbooks/src/index.ts"
+);
+describe.skipIf(!existsSync(BACKEND_PLAYBOOKS))("MAX_SESSION_CRITERIA mirrors the pod's cap", () => {
+  if (!existsSync(BACKEND_PLAYBOOKS))
+    console.warn(`[process-contract] SKIP: no synap-backend checkout at ${BACKEND_PLAYBOOKS}`);
+  it("equals @synap/playbooks MAX_SESSION_CRITERIA", () => {
+    const m = readFileSync(BACKEND_PLAYBOOKS, "utf8").match(/export const MAX_SESSION_CRITERIA = (\d+);/);
+    expect(m, "the pod's MAX_SESSION_CRITERIA declaration was not found").not.toBeNull();
+    expect(MAX_SESSION_CRITERIA).toBe(Number(m![1]));
+  });
+});
+
+describe("process contract — the shipped corpus", () => {
+  it("non-vacuity: Content OS declares the contract, and the whole corpus passes it", () => {
+    const corpus = readYamlTemplates().map((t) => t.data as WorkspaceYaml);
+    const contentOs = corpus.find((t) => t.meta.slug === "content-os")!;
+    const produce = contentOs.playbooks!.find((p) => p.name === "Produce Content")!;
+    expect(produce.subjectProfile?.statusProperty).toBe("post-status");
+    expect(produce.stages!.filter((s) => s.subjectStatus).length).toBe(6);
+    const errs = corpus.flatMap((t) =>
+      validateTemplate(t, { corpus })
+        .errors.filter((e) => PROCESS_RULES.has(e.rule))
+        .map((e) => `${t.meta.slug}: ${e.message}`)
+    );
+    expect(errs).toEqual([]);
+  });
+});