@synap-core/workspace-templates 0.29.0 → 0.31.0

package/src/types.ts

@@ -555,12 +555,11 @@ export interface TemplatePlaybook {
    * `playbooks.matchForEntity` (filters `subject_profile->>'profileSlug'`), so a
    * captured entity of this kind can auto-launch the playbook as a session.
    *
-   * `statusProperty` names the subject kind's SELECT property that holds its
-   * lifecycle (e.g. `post-status`). It is what ties `stages[].subjectStatus`
-   * to the subject: advancing into a stage writes that value (governed), and
-   * the subject entering the value advances an open run to the stage.
-   * `validate.ts` checks it is a select property of the kind, and that every
-   * `subjectStatus` / activator `status` is one of its enum values.
+   * The process FOLLOWS the kind's declared lifecycle (`profiles[].lifecycle`):
+   * that property is what `stages[].subjectStatus` and activator `status` are
+   * values of (`validate.ts`). A playbook never names it again — the
+   * `statusProperty`, `onEnd` and `humanOnlyStatuses` fields are retired from
+   * the catalog (One model decision 4; rule `playbook-field-retired`).
    */
   subjectProfile?: {
     profileSlug: string;
@@ -572,7 +571,6 @@ export interface TemplatePlaybook {
      * fan-out is refused, so the schedule would silently never be created.
      */
     filter?: string;
-    statusProperty?: string;
   };
   /**
    * Playbook-level slots: what a run of this process is expected to produce.
@@ -593,14 +591,6 @@ export interface TemplatePlaybook {
    * `automations:`. Public templates default to `mode: propose`.
    */
   activators?: TemplatePlaybookActivator[];
-  /**
-   * TEMPLATE-AUTHORING ONLY. Values of `subjectProfile.statusProperty` that no
-   * stage owns because a PERSON sets them (e.g. Idea, Archived). The lifecycle
-   * coverage ratchet (`lifecycle-coverage.test.ts`) requires every enum value
-   * of the status property to be either a stage's `subjectStatus` or listed
-   * here, so a lifecycle state can never be silently orphaned by a process.
-   */
-  humanOnlyStatuses?: string[];
   status?: "draft" | "active" | "paused";
   /**
    * `project` = a TRACK template (a method a project runs over its `stages`);
@@ -640,7 +630,7 @@ export interface TemplatePlaybookStage {
    */
   gate?: { kind: "human" | "check"; proposalType?: "playbook.stage_gate" };
   /**
-   * The value of the playbook's `subjectProfile.statusProperty` this stage
+   * The value of the subject kind's lifecycle property this stage
    * corresponds to. Advancing INTO the stage writes it to the subject
    * (governed); the subject ENTERING it advances an open run to the stage.
    */
@@ -1004,6 +994,15 @@ export interface TemplateMeta {
   start?: TemplateStart;
 }
 
+/**
+ * The kind a start is about: its own `profile` when it names another kind,
+ * else the space's primary output. The ONE derivation — the validator and the
+ * wire converter (`define.ts`) both read it.
+ */
+export function startProfileOf(meta: Pick<TemplateMeta, "intent" | "start">): string | undefined {
+  return meta.start?.profile ?? meta.intent?.primary;
+}
+
 /** `meta.start.label` reuses {@link INTENT_LABEL_MAX}; these bound the lists. */
 export const START_VIEWS_MAX = 3;
 export const START_EXAMPLE_RANGE = [4, 6] as const;
@@ -1018,8 +1017,12 @@ export interface TemplateStart {
   promise: string;
   /** Identity ids this start is suggested for; each id belongs to one start. */
   suggestFor: string[];
-  /** The produced kind the views and the first session are about. */
-  profile: string;
+  /**
+   * The kind the views and the first session are about. Omit it: it defaults
+   * to `meta.intent.primary` (one source; `define.ts` fills it on the wire).
+   * Name it only when the start is about another kind than the primary.
+   */
+  profile?: string;
   /** 1-3 slugs of THIS template's views, scoped to `profile`; first = default. */
   views: string[];
   /** Preview rows, never written. `values` keys are properties of `profile`. */
@@ -1036,6 +1039,13 @@ export const INTENT_LABEL_MAX = 24;
 export interface TemplateIntent {
   /** ≤ {@link INTENT_LABEL_MAX} chars. */
   label: string;
+  /**
+   * The space's ONE primary output (One model decision 3): the kind or role
+   * its main flow produces, the one its home leads with. Required when the
+   * space produces anything, and one of `produces` (the rest of `produces` are
+   * its operational kinds). A library (no `produces`) names none.
+   */
+  primary?: string;
   produces?: Array<{ profile: string }>;
 }
 

package/src/validate.ts

@@ -57,7 +57,7 @@ import type {
 // eslint-disable-next-line import/extensions -- .ts extension is intentional; see header.
 import { validateFlowDefinition } from "./validate-flow.ts";
 // eslint-disable-next-line import/extensions -- .ts extension is intentional; see header.
-import { INTENT_LABEL_MAX, START_EXAMPLE_RANGE, START_STARTERS_RANGE, START_VIEWS_MAX } from "./types.ts";
+import { INTENT_LABEL_MAX, START_EXAMPLE_RANGE, START_STARTERS_RANGE, START_VIEWS_MAX, startProfileOf } from "./types.ts";
 
 import {
   CAPABILITY_INTENTS,
@@ -602,9 +602,9 @@ export function knownRelationTypes(
 
 /**
  * The process contract a playbook declares on top of its stages:
- *  - `subjectProfile.statusProperty` is a SELECT property of the subject kind;
- *  - every `stages[].subjectStatus`, `activators[].status` and
- *    `humanOnlyStatuses[]` is one of that property's enum values;
+ *  - it names no `statusProperty`, `onEnd` or `humanOnlyStatuses` (retired);
+ *  - every `stages[].subjectStatus` and `activators[].status` is an option of
+ *    the subject kind's declared lifecycle;
  *  - `onFail.toStage` names a stage (key or name) of the same playbook;
  *  - every `relationToSubject` (playbook- and stage-level outputs) is a
  *    relation the corpus defines, or `none`.
@@ -643,58 +643,55 @@ function checkProcessContract(
   for (const pb of tpl.playbooks || []) {
     const at = `playbooks."${pb.name}"`;
     const kind = pb.subjectProfile?.profileSlug;
-    const statusProperty = pb.subjectProfile?.statusProperty;
 
-    // Resolve the lifecycle vocabulary (null = no status property to check against).
-    let statuses: Set<string> | null = null;
-    if (statusProperty !== undefined) {
-      if (!kind) {
+    // Retired from the catalog (One model decision 4, plan §11 row 8): the
+    // process follows the kind's declared lifecycle, an end moves nothing by
+    // default (6 Nov), and a status no stage owns is derived, not listed.
+    const raw = pb as unknown as Record<string, unknown>;
+    const subjectRaw = (pb.subjectProfile ?? {}) as Record<string, unknown>;
+    for (const [field, present] of [
+      ["subjectProfile.statusProperty", subjectRaw.statusProperty !== undefined],
+      ["subjectProfile.onEnd", subjectRaw.onEnd !== undefined],
+      ["onEnd", raw.onEnd !== undefined],
+      ["humanOnlyStatuses", raw.humanOnlyStatuses !== undefined],
+      ["subjectProfile.humanOnlyStatuses", subjectRaw.humanOnlyStatuses !== undefined],
+    ] as const)
+      if (present)
         add(
-          "playbook-status-property-no-subject",
-          `${at}.subjectProfile.statusProperty`,
-          `playbook "${pb.name}" declares statusProperty "${statusProperty}" without a subjectProfile.profileSlug`
+          "playbook-field-retired",
+          `${at}.${field}`,
+          `playbook "${pb.name}" declares ${field} — retired: the process follows the kind's declared lifecycle (a person-only status is \`humanOnly\` on that lifecycle, a status no stage owns is derived, and a session end moves nothing)`
         );
-      } else {
-        const decls = profileDeclarations(kind, tpl, resolveDep, corpus);
-        const prop = decls
-          .flatMap((p) => p.properties ?? [])
-          .find((pr) => pr.slug === statusProperty);
-        if (!prop) {
-          // A kind no declaration in reach carries (unknown kind is reported
-          // by playbook-ref-unknown; don't double-report it here).
-          if (decls.length > 0 || hasCorpus(resolveDep))
-            add(
-              "playbook-status-property-unknown",
-              `${at}.subjectProfile.statusProperty`,
-              `playbook "${pb.name}" statusProperty "${statusProperty}" is not a property of kind "${kind}"`
-            );
-        } else if (
-          prop.inputType !== "select" ||
-          !Array.isArray(prop.enumValues) ||
-          prop.enumValues.length === 0
-        ) {
-          add(
-            "playbook-status-property-not-select",
-            `${at}.subjectProfile.statusProperty`,
-            `playbook "${pb.name}" statusProperty "${kind}.${statusProperty}" must be a select property with enumValues (found inputType "${String(prop.inputType)}")`
-          );
-        } else {
-          statuses = new Set(prop.enumValues);
-        }
+
+    // The lifecycle vocabulary: the kind's DECLARED lifecycle (null = none in
+    // reach to check against).
+    let statuses: Set<string> | null = null;
+    let lifecycleProperty: string | undefined;
+    // A kind no declaration in reach carries is not judged without a corpus
+    // (an unknown kind is reported by playbook-ref-unknown).
+    let judgeable = hasCorpus(resolveDep);
+    if (kind) {
+      const decls = profileDeclarations(kind, tpl, resolveDep, corpus);
+      judgeable ||= decls.length > 0;
+      const declared = decls.find((p) => p.lifecycle !== undefined)?.lifecycle;
+      if (declared) {
+        lifecycleProperty = declared.property;
+        statuses = new Set(declared.options.map((o) => o.key));
       }
     }
     const checkStatus = (rule: string, path: string, value: unknown) => {
-      if (statusProperty === undefined) {
+      if (lifecycleProperty === undefined) {
+        if (!judgeable) return;
         add(
-          `${rule}-no-property`,
+          `${rule}-no-lifecycle`,
           path,
-          `${path} = "${String(value)}" needs subjectProfile.statusProperty — a status is a value OF that property`
+          `${path} = "${String(value)}" needs "${String(kind)}" to declare a lifecycle — a status is a value of the kind's lifecycle property`
         );
       } else if (statuses && !statuses.has(value as string)) {
         add(
           rule,
           path,
-          `${path} = "${String(value)}" is not a value of ${kind}.${statusProperty} (${[...statuses].join(", ")})`
+          `${path} = "${String(value)}" is not a value of ${kind}.${lifecycleProperty} (${[...statuses].join(", ")})`
         );
       }
     };
@@ -745,10 +742,6 @@ function checkProcessContract(
       }
     });
 
-    (pb.humanOnlyStatuses ?? []).forEach((s, i) =>
-      checkStatus("human-only-status-unknown", `${at}.humanOnlyStatuses[${i}]`, s)
-    );
-
     const outputs: Array<{ path: string; rel: unknown; optional: unknown; at: string }> = [
       ...(pb.expectedOutputs ?? []).map((o, i) => ({
         at: `${at}.expectedOutputs[${i}]`,
@@ -946,8 +939,7 @@ function stableJson(v: unknown): string {
  * With a corpus: every template that declares this profile WITH the lifecycle
  * property declares the SAME lifecycle — the pod declares it from whichever
  * template installs first, so two different declarations would make a pod's
- * lifecycle depend on install order. And a playbook binding the kind reads the
- * lifecycle property as its `statusProperty`.
+ * lifecycle depend on install order.
  */
 function checkLifecycleDeclarations(
   tpl: WorkspaceYaml,
@@ -1026,22 +1018,6 @@ function checkLifecycleDeclarations(
         `"${profile.slug}" declares "${other.property}" here ${profile.lifecycle ? "with a different lifecycle than" : "without the lifecycle"} another template declares — the pod keeps whichever installs first, so every declaration must be identical`
       );
   }
-
-  // A playbook moving a kind with a declared lifecycle moves THAT property.
-  for (const pb of tpl.playbooks ?? []) {
-    const kind = pb.subjectProfile?.profileSlug;
-    const statusProperty = pb.subjectProfile?.statusProperty;
-    if (!kind || statusProperty === undefined) continue;
-    const lc = profileDeclarations(kind, tpl, resolveDep, corpus)
-      .map((p) => p.lifecycle)
-      .find((l) => l !== undefined);
-    if (lc && lc.property !== statusProperty)
-      add(
-        "lifecycle-status-property",
-        `playbooks."${pb.name}".subjectProfile.statusProperty`,
-        `playbook "${pb.name}" moves "${kind}.${statusProperty}" but "${kind}"'s lifecycle is "${lc.property}" — a kind has ONE lifecycle`
-      );
-  }
 }
 
 // ── Presentation declarations (entity rendering, decision 8) ────────────────
@@ -1126,12 +1102,65 @@ function checkPresentationDeclarations(
   }
 }
 
+// ── Kanban grouping: the board names the field its columns are ─────────────
+
+/**
+ * A kanban's columns are the values of ONE select property, read by the
+ * renderer from `config.groupByField` (`KanbanAdapter`: `render.groupByField`,
+ * else `properties.status`). Grouped on the kind's lifecycle property it is the
+ * flow board: columns are the states and a drag is the governed status move.
+ * Rules (`view-kanban-group-*`):
+ *  - a `groupBy` (top-level or in config) is never read by the board (the
+ *    install door stores it as `config.groupBy`), so the board silently groups
+ *    by `status`;
+ *  - `config.groupByField` is required;
+ *  - it names a select property (with enumValues) of the scoped kind, when a
+ *    declaration of that kind is in reach (a system kind is not judged).
+ */
+function checkKanbanGrouping(
+  tpl: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  corpus: WorkspaceYaml[] | undefined,
+  add: (rule: string, path: string, message: string) => void
+): void {
+  for (const v of tpl.views ?? []) {
+    if (String(v.type || "").toLowerCase() !== "kanban") continue;
+    const at = `views."${v.name}"`;
+    const dead = v.groupBy !== undefined ? "groupBy" : (v.config as { groupBy?: unknown } | undefined)?.groupBy !== undefined ? "config.groupBy" : null;
+    if (dead)
+      add(
+        "view-kanban-group-dead",
+        `${at}.${dead}`,
+        `kanban "${v.name}" declares ${dead} — the board never reads it (it groups by status); write config.groupByField instead`
+      );
+    const field = (v.config as { groupByField?: unknown } | undefined)?.groupByField;
+    if (typeof field !== "string" || !field.trim()) {
+      add("view-kanban-group-missing", `${at}.config.groupByField`, `kanban "${v.name}" names no config.groupByField — its columns would be the values of "status"`);
+      continue;
+    }
+    const kind = v.scopeProfileSlug;
+    if (!kind) continue;
+    const slug = field.includes(".") ? field.split(".").pop()! : field;
+    const decls = profileDeclarations(kind, tpl, resolveDep, corpus);
+    if (decls.length === 0) continue;
+    const prop = decls.flatMap((p) => p.properties ?? []).find((p) => p.slug === slug);
+    if (!prop || prop.inputType !== "select" || !Array.isArray(prop.enumValues) || prop.enumValues.length === 0)
+      add(
+        "view-kanban-group-unknown",
+        `${at}.config.groupByField`,
+        `kanban "${v.name}" groups by "${slug}", which is not a select property of "${kind}" with enumValues`
+      );
+  }
+}
+
 // ── Intent: what a space produces (object-first homes H0) ───────────────────
 
 /**
- * `meta.intent = { label, produces: [{ profile }] }` names what the space
- * PRODUCES, in order; no `produces` makes it a library. Rules:
+ * `meta.intent = { label, primary, produces: [{ profile }] }` names what the
+ * space PRODUCES, in order; no `produces` makes it a library. Rules:
  *  - `label` is a non-empty string of at most {@link INTENT_LABEL_MAX} chars;
+ *  - a space that produces names its ONE `primary` output, one of `produces`;
+ *    a library names none (`intent-primary-*`);
  *  - each `profile` is declared by this template or by a template in its
  *    dependency closure (a role/kind it depends on), and is named once;
  *  - each produced profile DECLARES a lifecycle (in one of those
@@ -1162,16 +1191,42 @@ function checkIntent(
     return;
   }
   if (!intent || typeof intent !== "object" || Array.isArray(intent)) {
-    add("intent-shape", "meta.intent", "meta.intent must be { label, produces?: [{ profile }] }");
+    add("intent-shape", "meta.intent", "meta.intent must be { label, primary?, produces?: [{ profile }] }");
     return;
   }
-  const { label, produces } = intent as { label?: unknown; produces?: unknown };
+  const { label, produces, primary } = intent as { label?: unknown; produces?: unknown; primary?: unknown };
   if (typeof label !== "string" || !label.trim() || label.trim().length > INTENT_LABEL_MAX)
     add(
       "intent-label",
       "meta.intent.label",
       `meta.intent.label must be a non-empty string of at most ${INTENT_LABEL_MAX} characters (got ${JSON.stringify(label)})`
     );
+  // One primary output per producing space (One model decision 3): the home
+  // leads with its flow, so it is named, and it is one of what the space
+  // produces (the rest are its operational kinds). A library has no flow.
+  const producedSlugs = Array.isArray(produces)
+    ? produces.map((e) => (e as { profile?: unknown } | null)?.profile).filter((s): s is string => typeof s === "string")
+    : [];
+  if (primary !== undefined && (typeof primary !== "string" || !primary.trim()))
+    add("intent-shape", "meta.intent.primary", `meta.intent.primary must be a profile slug (got ${JSON.stringify(primary)})`);
+  else if (primary === undefined && producedSlugs.length > 0)
+    add(
+      "intent-primary-missing",
+      "meta.intent.primary",
+      `"${tpl.meta.slug}" produces ${producedSlugs.join(", ")} but names no meta.intent.primary — name the ONE output its main flow produces`
+    );
+  else if (primary !== undefined && producedSlugs.length === 0)
+    add(
+      "intent-primary-library",
+      "meta.intent.primary",
+      `meta.intent.primary "${primary}" on a library — a space with no produces has no flow; list "${primary}" in produces or drop primary`
+    );
+  else if (primary !== undefined && !producedSlugs.includes(primary as string))
+    add(
+      "intent-primary-not-produced",
+      "meta.intent.primary",
+      `meta.intent.primary "${primary}" is not in meta.intent.produces (${producedSlugs.join(", ")}) — the primary is one of what the space produces`
+    );
   if (produces === undefined) return;
   if (!Array.isArray(produces)) {
     add("intent-shape", "meta.intent.produces", "meta.intent.produces must be a list of { profile }");
@@ -1248,14 +1303,24 @@ function checkStart(
   const shapeOk =
     !!st && typeof st === "object" && !Array.isArray(st) &&
     Number.isInteger(st.order) && st.order > 0 && isStr(st.label) && isStr(st.promise) &&
-    strList(st.suggestFor) && isStr(st.profile) && strList(st.views) && strList(st.starters) &&
+    strList(st.suggestFor) && (st.profile === undefined || isStr(st.profile)) && strList(st.views) && strList(st.starters) &&
     Array.isArray(st.example) && st.example.every((e: any) => e && isStr(e.title) && (e.values === undefined || (typeof e.values === "object" && e.values !== null && !Array.isArray(e.values)))) &&
     !!fs && isStr(fs.title) && isStr(fs.goal);
   if (!shapeOk) {
-    add("start-shape", "meta.start", "meta.start must be { order (int ≥ 1), label, promise, suggestFor[], profile, views[], example[{ title, values? }], firstSession{ title, goal }, starters[] }");
+    add("start-shape", "meta.start", "meta.start must be { order (int ≥ 1), label, promise, suggestFor[], profile?, views[], example[{ title, values? }], firstSession{ title, goal }, starters[] }");
     return;
   }
   const start = st as import("./types.ts").TemplateStart;
+  // One source: the start is about the space's primary output unless it names
+  // another kind; naming the primary again is a second copy that can drift.
+  const primary = tpl.meta.intent?.primary;
+  if (start.profile !== undefined && start.profile === primary)
+    add("start-profile-redundant", "meta.start.profile", `meta.start.profile repeats meta.intent.primary "${primary}" — omit it (the start defaults to the primary output)`);
+  const profile = startProfileOf(tpl.meta);
+  if (!profile) {
+    add("start-profile-missing", "meta.profile", `meta.start names no kind and "${tpl.meta.slug}" declares no meta.intent.primary to default to`);
+    return;
+  }
   if (start.label.trim().length > INTENT_LABEL_MAX)
     add("start-label", "meta.start.label", `meta.start.label must be at most ${INTENT_LABEL_MAX} characters (got ${JSON.stringify(start.label)})`);
   const [exMin, exMax] = START_EXAMPLE_RANGE;
@@ -1276,26 +1341,26 @@ function checkStart(
       return;
     }
     const scope = [view.scopeProfileSlug, ...(view.scopeProfileSlugs ?? [])].filter(Boolean);
-    if (!scope.includes(start.profile))
-      add("start-views-scope", at, `view "${slug}" is not scoped to "${start.profile}" (scope: ${scope.join(", ") || "none"})`);
+    if (!scope.includes(profile))
+      add("start-views-scope", at, `view "${slug}" is not scoped to "${profile}" (scope: ${scope.join(", ") || "none"})`);
   });
 
   // Profile + example against the declarations in the closure.
   const closure = [...collectDependencyClosure(tpl, resolveDep)];
   const sources = [tpl, ...closure.map(resolveDep).filter((t): t is WorkspaceYaml => !!t)];
-  const decls = sources.flatMap((t) => (t.profiles ?? []).filter((p) => p.slug === start.profile));
+  const decls = sources.flatMap((t) => (t.profiles ?? []).filter((p) => p.slug === profile));
   if (decls.length === 0) {
     if (!closure.some((d) => !resolveDep(d)))
-      add("start-profile-unknown", "meta.start.profile", `"${start.profile}" is neither declared by "${tpl.meta.slug}" nor by a template it depends on`);
+      add("start-profile-unknown", "meta.profile", `"${profile}" is neither declared by "${tpl.meta.slug}" nor by a template it depends on`);
   } else {
     const props = new Map(decls.flatMap((p) => p.properties ?? []).map((p) => [p.slug, p] as const));
     start.example.forEach((row, i) => {
       for (const [key, value] of Object.entries(row.values ?? {})) {
         const at = `meta.start.example[${i}].values.${key}`;
         const prop = props.get(key);
-        if (!prop) add("start-example-property", at, `"${key}" is not a property of "${start.profile}"`);
+        if (!prop) add("start-example-property", at, `"${key}" is not a property of "${profile}"`);
         else if (prop.enumValues?.length && !prop.enumValues.includes(value as string))
-          add("start-example-enum", at, `${JSON.stringify(value)} is not one of ${start.profile}.${key}: ${prop.enumValues.join(", ")}`);
+          add("start-example-enum", at, `${JSON.stringify(value)} is not one of ${profile}.${key}: ${prop.enumValues.join(", ")}`);
       }
     });
   }
@@ -2117,6 +2182,7 @@ export function validateTemplate(
   checkSharedRoleReferences(tpl, resolveDepFrom(opts), add);
   checkStageDomains(tpl, resolveDepFrom(opts), add);
   checkProcessContract(tpl, resolveDepFrom(opts), opts.corpus, add);
+  checkKanbanGrouping(tpl, resolveDepFrom(opts), opts.corpus, add);
   checkLifecycleDeclarations(tpl, resolveDepFrom(opts), opts.corpus, add);
   checkPresentationDeclarations(tpl, resolveDepFrom(opts), opts.corpus, add);
   checkIntent(tpl, resolveDepFrom(opts), add);