@synap-core/workspace-templates 0.9.4 → 0.10.0

package/src/types.ts

@@ -174,6 +174,29 @@ export interface TemplateEntityLink {
   label?: string;
 }
 
+/**
+ * A domain-level relation TYPE definition — a `relation_defs` row, the workspace's
+ * relation vocabulary. Distinct from {@link TemplateEntityLink}, which is a
+ * profile→profile EDGE (and only carries `type` + `label`). A relation def stands
+ * alone: it has no source/target profile pairing and it carries the rich metadata
+ * (`description`, `isDirectional`, `uiHints`) that the entity-link path drops.
+ *
+ * Mirrors `DefaultRelationDef` in synap-backend
+ * `packages/database/src/utils/default-relation-defs.ts` VERBATIM — the door
+ * find-or-creates a `relation_defs` row from each entry (idempotent by
+ * `slug` within the workspace), which is `ensureDefaultRelationDefs`'s body.
+ */
+export interface TemplateRelationDef {
+  slug: string;
+  displayName: string;
+  description?: string;
+  isDirectional?: boolean;
+  uiHints?: {
+    category?: "workflow" | "social" | "reference" | "hierarchy";
+    inverseLabel?: string;
+  };
+}
+
 export interface TemplateSeedEntity {
   profileSlug: string;
   title: string;
@@ -445,6 +468,34 @@ export interface TemplateAutomation {
   status?: "draft" | "active" | "paused";
 }
 
+// ============================================================================
+// Commands — workspace-scoped intelligence commands seeded with the workspace
+//
+// A prompt-template command (the "Default Command Pack") the workspace exposes
+// in its command surface. Mirrors `DefaultCommandDef` in synap-backend
+// `packages/database/src/utils/ensure-default-commands.ts` — the door
+// find-or-creates an `intelligence_commands` row from each entry, idempotent by
+// `title` within the workspace (`ensureDefaultCommands`'s body generalized).
+// ============================================================================
+
+export interface TemplateCommandDerivedInput {
+  name: string;
+  label?: string;
+  /** Mirrors `DerivedInput.type` (text | number | entity | view | choice). */
+  type?: string;
+}
+
+export interface TemplateCommand {
+  title: string;
+  promptTemplate: string;
+  derivedInputs?: TemplateCommandDerivedInput[];
+  /** text | proposal | view */
+  outputMode?: string;
+  canCreateViews?: boolean;
+  /** read_only | propose_writes */
+  permissionsProfile?: string;
+}
+
 // ============================================================================
 // Action placements — template-declarable actions on an entity-detail surface
 //
@@ -694,6 +745,21 @@ export interface WorkspaceYaml {
   /** Schema-level links between entity types */
   entityLinks?: TemplateEntityLink[];
 
+  /**
+   * Domain-level relation TYPE vocabulary seeded into the workspace's
+   * `relation_defs`. Distinct from `entityLinks` (profile→profile edges): a
+   * relation def stands alone and carries `description`/`isDirectional`/`uiHints`.
+   * The `base` template carries the universal defaults. See {@link TemplateRelationDef}.
+   */
+  relationDefs?: TemplateRelationDef[];
+
+  /**
+   * Workspace-scoped intelligence commands (prompt-template "Default Command
+   * Pack") seeded with the workspace. The `base` template carries the universal
+   * pack. See {@link TemplateCommand}.
+   */
+  commands?: TemplateCommand[];
+
   /** Initial data to seed on workspace creation */
   seedEntities?: TemplateSeedEntity[];
 

package/src/validate-flow.ts

@@ -36,9 +36,9 @@
  * `schema/automations.ts`.
  */
 
-// ── Contract constants (mirror @synap/database schema/automations.ts) ─────────
+// ── Contract constants (mirror schema/automations.ts — keep in sync) ──────────
 
-/** The 21 node types — `AutomationNodeBase.type` union (schema/automations.ts). */
+/** The 23 node types — `AutomationNodeBase.type` union (schema/automations.ts). */
 export const FLOW_NODE_TYPES = [
   "trigger",
   "command",
@@ -56,6 +56,8 @@ export const FLOW_NODE_TYPES = [
   "select",
   "claim",
   "messages_query",
+  "runs_query",
+  "proposals_query",
   "switch",
   "skill",
   "capability",
@@ -81,22 +83,73 @@ export const FLOW_OUTPUT_TYPES = [
 /**
  * The known `config.channelType` values for a `channel_message` output. Mirrors
  * the executor's channel_message resolution (automation-executor.ts). The output
- * channel is CONTEXT-DERIVED — a channel_message is valid with `channelId`, OR
- * `channelEntityRef` (an entity-id expression → that entity's internal channel),
- * OR a `channelType` from this set, OR NOTHING (the executor defaults a targetless
- * channel_message to the automation's own run channel). A `channelType` that is
- * PRESENT but not one of these is still a typo → still an error.
+ * channel is now CONTEXT-DERIVED — a channel_message is valid with `channelId`,
+ * OR `channelEntityRef` (an entity-id expression → that entity's internal
+ * channel), OR a `channelType` from this set, OR NOTHING (the executor defaults a
+ * targetless channel_message to the automation's own run channel). A `channelType`
+ * that is PRESENT but not one of these is still a typo → still an error.
  */
+// The executor's channel_message resolution (automation-executor.ts) is the SSOT
+// for these values; config is an untyped Record so there is no compile-time
+// drift guard here — keep this array in sync with the executor by hand.
 export const CHANNEL_MESSAGE_CHANNEL_TYPES = [
   "personal_thread",
   "proactive",
   "subjectEntity",
 ] as const;
 
+/**
+ * Node types a `loop` may dispatch PER ITEM. Mirrors `LOOP_BODY_NODE_TYPES` in
+ * `packages/jobs/src/workers/automation-executor.ts` (the runtime SSOT — the
+ * `switch (childNode.type)` inside the loop body). A loop OWNS the contiguous
+ * chain of these reachable from it; traversal STOPS at any other type
+ * (switch / delay / nested loop / sub_automation / entity_read / …), which runs
+ * ONCE in the main topological pass instead.
+ *
+ * Hand-mirrored: `@synap/api` does not depend on `@synap/jobs`, so there is no
+ * compile-time drift guard here — keep this array in sync with the executor by
+ * hand (same convention as CHANNEL_MESSAGE_CHANNEL_TYPES above).
+ */
+export const LOOP_BODY_NODE_TYPES = [
+  "command",
+  "output",
+  "playbook_run",
+  "messages_query",
+  "runs_query",
+  "proposals_query",
+  "query",
+  "fetch",
+  "transform",
+  "condition",
+  "skill",
+  "capability",
+] as const;
+
+/**
+ * What a loop actually PUTS in scope for its body: `context.loop = { item, index }`
+ * (automation-executor.ts, `case "loop"`). Any other `{{loop.<x>}}` segment
+ * resolves to undefined at runtime.
+ */
+export const LOOP_PROVIDED_BINDINGS = ["item", "index"] as const;
+
 const NODE_TYPE_SET = new Set<string>(FLOW_NODE_TYPES);
+const LOOP_BODY_TYPE_SET = new Set<string>(LOOP_BODY_NODE_TYPES);
+const LOOP_BINDING_SET = new Set<string>(LOOP_PROVIDED_BINDINGS);
 const OUTPUT_TYPE_SET = new Set<string>(FLOW_OUTPUT_TYPES);
 const CHANNEL_TYPE_SET = new Set<string>(CHANNEL_MESSAGE_CHANNEL_TYPES);
 
+// ── Drift guard — NOT compile-time IN THIS COPY ───────────────────────────────
+// The arrays above are hand-mirrored from TS *union types* in the schema. The
+// BACKEND copy carries an `AssertExact` binding that fails `tsc` on drift; THIS
+// package has no `@synap/database` dependency, so that guard cannot live here.
+// Do not assume tsc protects you when editing these arrays — what protects this
+// copy is `validate-flow.drift.test.ts`, which strips comments and therefore
+// could never have caught this paragraph being wrong (it was, until 2026-07-31).
+//
+// ⚠️ If you re-generate this file FROM the backend copy, re-apply this block and
+// de-duplicate the header above: a naive strip of the `AssertExact` CODE leaves
+// its comment behind, asserting a guard that does not exist here.
+
 // ── Result / error types ──────────────────────────────────────────────────────
 
 export interface FlowValidationError {
@@ -479,6 +532,54 @@ export function validateFlowDefinition(
     }
   }
 
+  // ── Loop bindings: `{{loop.*}}` only inside a loop body, only real paths ──────
+  // `context.loop` exists ONLY while a loop dispatches its body and is deleted
+  // right after, so a node OUTSIDE every loop body that reads `{{loop.item.id}}`
+  // resolves it to `undefined` at runtime — a Zod "expected string, received
+  // undefined" at best, a junk entity/relation written with an empty id at worst.
+  // The ownership walk below is the SAME rule the executor applies
+  // (`computeLoopBodyNodeIds`), so a node behind a boundary type (switch, delay,
+  // nested loop, …) or with no edge from the loop at all is correctly reported:
+  // those are exactly the shapes that leak into the main pass.
+  const loopBodyNodeIds = new Set<string>();
+  for (const node of nodes) {
+    if (!nonEmptyString(node.id) || node.type !== "loop") continue;
+    for (const id of collectLoopBody(node.id, nodesById, edges)) {
+      loopBodyNodeIds.add(id);
+    }
+  }
+  for (const node of nodes) {
+    if (!nonEmptyString(node.id)) continue;
+    const refs = collectLoopBindingRefs(node.data);
+    if (refs.length === 0) continue;
+    if (!loopBodyNodeIds.has(node.id)) {
+      errors.push({
+        nodeId: node.id,
+        code: "loop_ref_outside_loop_body",
+        message: `Node "${node.id}" references ${refs
+          .map((r) => `\`{{loop.${r}...}}\``)
+          .join(
+            ", "
+          )} but is not inside a loop body, so there is no item to bind — it would run once with an empty value. Connect it downstream of a loop node with no switch/delay/nested-loop/sub_automation node in between.`,
+      });
+      continue;
+    }
+    const unknown = refs.filter((r) => !LOOP_BINDING_SET.has(r));
+    if (unknown.length > 0) {
+      errors.push({
+        nodeId: node.id,
+        code: "loop_ref_unknown_path",
+        message: `Node "${node.id}" references ${unknown
+          .map((r) => `\`{{loop.${r}}}\``)
+          .join(
+            ", "
+          )}, which a loop does not provide. A loop binds only: ${LOOP_PROVIDED_BINDINGS.map(
+          (b) => `\`loop.${b}\``
+        ).join(", ")}.`,
+      });
+    }
+  }
+
   // ── Acyclic (Kahn's algorithm — mirrors topoSort in automation-executor.ts) ───
   // Only run when edges reference real nodes; dangling edges are already reported
   // and would corrupt the in-degree bookkeeping.
@@ -495,6 +596,84 @@ export function validateFlowDefinition(
   return { valid: errors.length === 0, errors };
 }
 
+/**
+ * The node ids a loop OWNS as its per-item body — the contiguous chain of
+ * LOOP_BODY_NODE_TYPES nodes reachable from it, stopping at any other type.
+ * Mirrors `computeLoopBodyNodeIds` in automation-executor.ts exactly (all
+ * out-edges, handle-agnostic); the `seen` set makes a cyclic graph terminate
+ * (cycles are reported separately).
+ */
+function collectLoopBody(
+  loopNodeId: string,
+  nodesById: Map<string, LooseNode>,
+  edges: LooseEdge[]
+): Set<string> {
+  const body = new Set<string>();
+  const stack: string[] = [];
+  for (const edge of edges) {
+    if (edge.source === loopNodeId && nonEmptyString(edge.target))
+      stack.push(edge.target);
+  }
+  while (stack.length > 0) {
+    const id = stack.pop()!;
+    if (body.has(id)) continue;
+    const node = nodesById.get(id);
+    if (
+      !node ||
+      !nonEmptyString(node.type) ||
+      !LOOP_BODY_TYPE_SET.has(node.type)
+    )
+      continue; // boundary — runs once in the main pass, not per item
+    body.add(id);
+    for (const edge of edges) {
+      if (edge.source === id && nonEmptyString(edge.target))
+        stack.push(edge.target);
+    }
+  }
+  return body;
+}
+
+/**
+ * The FIRST path segment of every `{{loop.<segment>…}}` reference anywhere in a
+ * node's `data` (deep: objects + arrays), deduped. Mirrors
+ * `collectLoopBindingRefs` in automation-executor.ts — including the PRE-PIPE
+ * restriction: an array pipe argument (`{{x | map:{{loop.item.id}}}}`) binds
+ * `loop` per item inside the RESOLVER, a scope that is valid outside any loop
+ * node, so it must not be reported.
+ */
+function collectLoopBindingRefs(data: unknown): string[] {
+  const found = new Set<string>();
+  const walk = (v: unknown): void => {
+    if (typeof v === "string") {
+      const head = v.split("|")[0];
+      const re = /\{\{\s*loop\.([A-Za-z0-9_$]+)/g;
+      let m: RegExpExecArray | null;
+      let matched = false;
+      while ((m = re.exec(head)) !== null) {
+        found.add(m[1]);
+        matched = true;
+      }
+      // The executor's own detector is the LOOSER `/\{\{\s*loop\./` — it fires on
+      // `{{loop.}}` or `{{loop.-x}}`, which this stricter segment pattern does
+      // not. Without this fallback a malformed reference passes save-time
+      // validation and then throws at RUN time, which is exactly the class of
+      // failure the loop rules were added to eliminate. Report it under the
+      // empty segment so it surfaces as `loop_ref_unknown_path`.
+      if (!matched && /\{\{\s*loop\./.test(head)) found.add("");
+      return;
+    }
+    if (Array.isArray(v)) {
+      for (const x of v) walk(x);
+      return;
+    }
+    if (isRecord(v)) {
+      for (const x of Object.values(v)) walk(x);
+    }
+  };
+  walk(data);
+  return [...found];
+}
+
 /**
  * Return the set of node ids that participate in a cycle (empty if acyclic).
  * Kahn's algorithm — the same ordering the executor's `topoSort` relies on; a

package/src/validate.ts

@@ -152,6 +152,11 @@ export const SYSTEM_PROFILES = new Set([
   "research",
   "knowledge",
   "user_observation",
+  // Generated artifact — a workspace-scoped pod system profile
+  // (`ensure-system-profiles.ts`) written by the `base` report automation. It
+  // was simply missing from this hand-maintained list; the flow's
+  // `create-report` node references it, so referential integrity needs it here.
+  "report",
 ]);
 
 // ── Dependency-vocabulary closure (compose vs require semantics) ─────────────
@@ -290,8 +295,27 @@ export function validateTemplate(
         );
     }
   }
-  if (!tpl.profiles || tpl.profiles.length === 0) {
-    add("profiles-required", "profiles", "At least one profile is required");
+  // A template earns validity by declaring a data-schema profile OR by carrying
+  // operational defaults (relation vocabulary / commands / automations). The
+  // `base` template is the latter: pod-wide operational config with no
+  // data-schema profile of its own (its report automation writes the `report`
+  // system profile and reads other system profiles, none declared here). Without
+  // this carve-out a legitimate operational-defaults template fails the gate,
+  // while a data template that forgot its profiles still does (it carries no
+  // operational config either).
+  const carriesOperationalDefaults =
+    (tpl.relationDefs && tpl.relationDefs.length > 0) ||
+    (tpl.commands && tpl.commands.length > 0) ||
+    (tpl.automations && tpl.automations.length > 0);
+  if (
+    (!tpl.profiles || tpl.profiles.length === 0) &&
+    !carriesOperationalDefaults
+  ) {
+    add(
+      "profiles-required",
+      "profiles",
+      "At least one profile is required (or operational defaults: relationDefs / commands / automations)"
+    );
   }
   if (
     tpl.app &&