@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/workflow/validation/crossref.ts

@@ -0,0 +1,410 @@
+/**
+ * Task-kind and cross-task-reference validation — ports
+ * pkg/domain/workflow/validation/crossref.go: recognized task kinds, unique
+ * task names, flow.then / fallback_task / cases[].then / outcomes[].then
+ * reference resolution with did-you-mean suggestions, cycle detection, and
+ * the surface rules the task-config protos cannot declare. Reference checks
+ * read the raw task_config Struct (not the typed config) so the errors
+ * speak the author's own vocabulary. Keep every string in lockstep with the
+ * cloud Java validator.
+ */
+import { enumToJson } from "@bufbuild/protobuf";
+import type { JsonObject, JsonValue } from "@bufbuild/protobuf";
+
+import { WorkflowTaskKind, WorkflowTaskKindSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import type {
+  WorkflowSpec,
+  WorkflowTask,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_pb";
+
+/**
+ * Checks that every task has a recognized, non-zero WorkflowTaskKind —
+ * errors for unspecified (0) or unknown enum values (Go ValidateTaskKinds).
+ */
+export function validateTaskKinds(spec: WorkflowSpec | undefined): string[] {
+  if (spec === undefined || spec.tasks.length === 0) {
+    return [];
+  }
+  const errors: string[] = [];
+  for (const task of spec.tasks) {
+    if (WorkflowTaskKind[task.kind] === undefined || task.kind === 0) {
+      errors.push(
+        `task '${task.name}': unknown or unspecified task kind (value=${task.kind})`,
+      );
+    }
+  }
+  return errors;
+}
+
+/**
+ * Checks that all task-name references point to tasks that exist (Go
+ * ValidateCrossTaskReferences): llm_call/validate fallback_task,
+ * agent_call output.fallback_task, switch_case cases[].then, human_input
+ * outcomes[].then, and flow.then on every task. Also validates unique task
+ * names and detects cycles.
+ */
+export function validateCrossTaskReferences(
+  spec: WorkflowSpec | undefined,
+): string[] {
+  if (spec === undefined || spec.tasks.length === 0) {
+    return [];
+  }
+
+  const errors: string[] = [];
+  const taskNames = buildTaskNameSet(spec.tasks);
+
+  errors.push(...validateUniqueTaskNames(spec.tasks));
+  errors.push(...validateFlowReferences(spec.tasks, taskNames));
+
+  for (const task of spec.tasks) {
+    if (task.taskConfig === undefined) {
+      continue;
+    }
+    errors.push(
+      ...extractAndValidateRefs(task.name, task.kind, task.taskConfig, taskNames),
+    );
+  }
+
+  errors.push(...validateNoCycles(spec.tasks, taskNames));
+
+  return errors;
+}
+
+function buildTaskNameSet(tasks: WorkflowTask[]): Set<string> {
+  const names = new Set<string>();
+  for (const t of tasks) {
+    if (t.name !== "") {
+      names.add(t.name);
+    }
+  }
+  return names;
+}
+
+function validateUniqueTaskNames(tasks: WorkflowTask[]): string[] {
+  const seen = new Map<string, number>();
+  const errors: string[] = [];
+
+  tasks.forEach((task, i) => {
+    if (task.name === "") {
+      return;
+    }
+    const firstIdx = seen.get(task.name);
+    if (firstIdx !== undefined) {
+      errors.push(
+        `duplicate task name "${task.name}" at tasks[${i}]: already defined at tasks[${firstIdx}]`,
+      );
+    }
+    seen.set(task.name, i);
+  });
+
+  return errors;
+}
+
+function validateFlowReferences(
+  tasks: WorkflowTask[],
+  taskNames: Set<string>,
+): string[] {
+  const errors: string[] = [];
+
+  for (const task of tasks) {
+    if (task.flow === undefined || task.flow.then === "") {
+      continue;
+    }
+    const then = task.flow.then;
+    if (then === "end") {
+      continue;
+    }
+    if (!taskNames.has(then)) {
+      const suggestion = suggestSimilar(then, taskNames);
+      let msg = `task '${task.name}' flow.then references unknown task '${then}'`;
+      if (suggestion !== "") {
+        msg += ` (did you mean '${suggestion}'?)`;
+      }
+      errors.push(msg);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Cycle detection over the flow.then graph. Go iterates its task-name map
+ * in random order, so a multi-node cycle's reported rotation varies per
+ * run there; iterating in insertion order here is deterministic and always
+ * one of the rotations Go could emit.
+ */
+function validateNoCycles(
+  tasks: WorkflowTask[],
+  taskNames: Set<string>,
+): string[] {
+  const graph = new Map<string, string>();
+  for (const task of tasks) {
+    if (task.flow === undefined || task.flow.then === "") {
+      continue;
+    }
+    graph.set(task.name, task.flow.then);
+  }
+
+  const visited = new Set<string>();
+  const path = new Set<string>();
+  const pathOrder: string[] = [];
+  const errors: string[] = [];
+
+  const dfs = (node: string): void => {
+    if (path.has(node)) {
+      const startIdx = pathOrder.indexOf(node);
+      const cycleParts = [...pathOrder.slice(startIdx), node];
+      errors.push(`circular dependency detected: ${cycleParts.join(" -> ")}`);
+      return;
+    }
+    if (visited.has(node)) {
+      return;
+    }
+
+    visited.add(node);
+    path.add(node);
+    pathOrder.push(node);
+
+    const next = graph.get(node);
+    if (next !== undefined && next !== "end" && taskNames.has(next)) {
+      dfs(next);
+    }
+
+    path.delete(node);
+    pathOrder.pop();
+  };
+
+  for (const name of taskNames) {
+    if (!visited.has(name)) {
+      dfs(name);
+    }
+  }
+
+  return errors;
+}
+
+function extractAndValidateRefs(
+  taskName: string,
+  kind: WorkflowTaskKind,
+  config: JsonObject,
+  validNames: Set<string>,
+): string[] {
+  const errors: string[] = [];
+  const fields = config;
+
+  switch (kind) {
+    case WorkflowTaskKind.llm_call:
+    case WorkflowTaskKind.validate: {
+      const ref = getStringField(fields, "fallbackTask", "fallback_task");
+      if (ref !== "" && !validNames.has(ref)) {
+        const suggestion = suggestSimilar(ref, validNames);
+        let msg = `task '${taskName}' (${enumToJson(WorkflowTaskKindSchema, kind)}) fallback_task references unknown task '${ref}'`;
+        if (suggestion !== "") {
+          msg += ` (did you mean '${suggestion}'?)`;
+        }
+        errors.push(msg);
+      }
+      break;
+    }
+
+    case WorkflowTaskKind.agent_call: {
+      const output = getStructField(fields, "output");
+      if (output !== undefined) {
+        const ref = getStringField(output, "fallbackTask", "fallback_task");
+        if (ref !== "" && !validNames.has(ref)) {
+          const suggestion = suggestSimilar(ref, validNames);
+          let msg = `task '${taskName}' (agent_call) output.fallback_task references unknown task '${ref}'`;
+          if (suggestion !== "") {
+            msg += ` (did you mean '${suggestion}'?)`;
+          }
+          errors.push(msg);
+        }
+      }
+      break;
+    }
+
+    case WorkflowTaskKind.switch_case: {
+      getListField(fields, "cases").forEach((c, i) => {
+        const caseStruct = structValueOf(c);
+        if (caseStruct === undefined) {
+          return;
+        }
+        const ref = getStringField(caseStruct, "then");
+        if (ref !== "" && ref !== "end" && !validNames.has(ref)) {
+          const suggestion = suggestSimilar(ref, validNames);
+          let msg = `task '${taskName}' (switch_case) cases[${i}].then references unknown task '${ref}'`;
+          if (suggestion !== "") {
+            msg += ` (did you mean '${suggestion}'?)`;
+          }
+          errors.push(msg);
+        }
+      });
+      break;
+    }
+
+    case WorkflowTaskKind.human_input: {
+      getListField(fields, "outcomes").forEach((o, i) => {
+        const outcomeStruct = structValueOf(o);
+        if (outcomeStruct === undefined) {
+          return;
+        }
+        const ref = getStringField(outcomeStruct, "then");
+        if (ref !== "" && ref !== "end" && !validNames.has(ref)) {
+          const suggestion = suggestSimilar(ref, validNames);
+          let msg = `task '${taskName}' (human_input) outcomes[${i}].then references unknown task '${ref}'`;
+          if (suggestion !== "") {
+            msg += ` (did you mean '${suggestion}'?)`;
+          }
+          errors.push(msg);
+        }
+      });
+      break;
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Checks the task-config semantics the config protos cannot declare (Go
+ * ValidateTaskConfigSurfaceRules). Since stigmer#805 armed the declared
+ * rules over strict-unmarshaled typed configs, what remains is genuinely
+ * contextual:
+ *
+ *   - agent_call workspace_entries must use git_repo sources:
+ *     WorkspaceSource's oneof legitimately offers local_path on the session
+ *     surface, but no client is connected to serve one when a workflow task
+ *     fires — a workflow-surface restriction, not a schema fact, so it
+ *     cannot live on the shared proto. (Source presence and git_repo.url's
+ *     HTTPS shape ARE schema facts enforced via the constraints step.)
+ *
+ * Keep the strings in lockstep with the cloud Java validator.
+ */
+export function validateTaskConfigSurfaceRules(
+  spec: WorkflowSpec | undefined,
+): string[] {
+  if (spec === undefined || spec.tasks.length === 0) {
+    return [];
+  }
+
+  const errors: string[] = [];
+  for (const task of spec.tasks) {
+    if (task.kind !== WorkflowTaskKind.agent_call || task.taskConfig === undefined) {
+      continue;
+    }
+    getListField(task.taskConfig, "workspace_entries").forEach((v, i) => {
+      const entry = structValueOf(v);
+      if (entry === undefined) {
+        return;
+      }
+      const source = getStructField(entry, "source");
+      if (source === undefined) {
+        // Absence is the constraints step's required-rule to report.
+        return;
+      }
+      if (getStructField(source, "git_repo") === undefined) {
+        errors.push(
+          `task '${task.name}' (agent_call): workspace_entries[${i}] must use a git_repo source — no client is connected to serve a local_path when a workflow task fires`,
+        );
+      }
+    });
+  }
+  return errors;
+}
+
+/**
+ * The first non-empty string among the given keys (Go getStringField): a
+ * present key with a non-string or empty value falls through to the next.
+ * The stubs surface Struct fields as plain JsonObject, so the readers here
+ * work over plain JSON — the same shapes Go's structpb getters resolve.
+ */
+function getStringField(fields: JsonObject, ...keys: string[]): string {
+  for (const key of keys) {
+    const v = fields[key];
+    if (typeof v === "string" && v !== "") {
+      return v;
+    }
+  }
+  return "";
+}
+
+/**
+ * The struct value of the FIRST present key (Go getStructField returns on
+ * the first hit even when it is not a struct — mirrored).
+ */
+function getStructField(
+  fields: JsonObject,
+  ...keys: string[]
+): JsonObject | undefined {
+  for (const key of keys) {
+    const v = fields[key];
+    if (v !== undefined) {
+      return structValueOf(v);
+    }
+  }
+  return undefined;
+}
+
+function getListField(fields: JsonObject, key: string): JsonValue[] {
+  const v = fields[key];
+  return Array.isArray(v) ? v : [];
+}
+
+function structValueOf(v: JsonValue): JsonObject | undefined {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+    ? v
+    : undefined;
+}
+
+/**
+ * The single closest task name within edit distance 3, or "" (Go
+ * suggestSimilar): candidates are scanned in sorted order and a strictly
+ * smaller distance wins, so ties resolve to the lexicographically first.
+ */
+function suggestSimilar(target: string, names: Set<string>): string {
+  const maxDistance = 3;
+  let bestName = "";
+  let bestDist = maxDistance + 1;
+
+  for (const name of [...names].sort()) {
+    const d = levenshtein(target.toLowerCase(), name.toLowerCase());
+    if (d < bestDist) {
+      bestDist = d;
+      bestName = name;
+    }
+  }
+
+  return bestDist <= maxDistance ? bestName : "";
+}
+
+/**
+ * Two-row Levenshtein distance (Go levenshtein). Byte vs UTF-16 code-unit
+ * comparison is equivalent for the ASCII task names the validator sees.
+ */
+function levenshtein(a: string, b: string): number {
+  const la = a.length;
+  const lb = b.length;
+  if (la === 0) {
+    return lb;
+  }
+  if (lb === 0) {
+    return la;
+  }
+
+  let prev: number[] = new Array<number>(lb + 1);
+  let curr: number[] = new Array<number>(lb + 1);
+  for (let j = 0; j <= lb; j++) {
+    prev[j] = j;
+  }
+
+  for (let i = 1; i <= la; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= lb; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+
+  return prev[lb]!;
+}

package/src/domain/workflow/validation/expression-warnings.ts

@@ -0,0 +1,103 @@
+/**
+ * Expression-mistake warnings — ports
+ * pkg/domain/workflow/validation/expression_warnings.go. Scans all task
+ * configs for expressions referencing $context.env.* — a common authoring
+ * mistake: environment variables are accessed via $env.*, and $context
+ * holds accumulated exported task outputs, not environment variables.
+ */
+import type { JsonObject, JsonValue } from "@bufbuild/protobuf";
+
+import type { WorkflowSpec } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_pb";
+
+export function checkExpressionWarnings(
+  spec: WorkflowSpec | undefined,
+): string[] {
+  if (spec === undefined || spec.tasks.length === 0) {
+    return [];
+  }
+
+  const warnings: string[] = [];
+
+  for (const task of spec.tasks) {
+    if (task.taskConfig === undefined) {
+      continue;
+    }
+
+    for (const envKey of findContextEnvRefs(task.taskConfig)) {
+      warnings.push(
+        `task '${task.name}': expression references '$context.env.${envKey}' which resolves to null. ` +
+          `Environment variables are accessed via '$env.${envKey}', not '$context.env.${envKey}'. ` +
+          "$context holds accumulated task outputs, not environment variables.",
+      );
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Scans a raw task config for strings containing "$context.env." and
+ * returns the env key names referenced (e.g. "NOTIFICATION_DATE"). The
+ * stubs surface Struct fields as plain JsonObject, so the walk is over
+ * plain JSON — the same tree Go's structpb walk resolves.
+ */
+function findContextEnvRefs(s: JsonObject): string[] {
+  const keys: string[] = [];
+  for (const v of Object.values(s)) {
+    keys.push(...findContextEnvRefsInValue(v));
+  }
+  return keys;
+}
+
+function findContextEnvRefsInValue(v: JsonValue): string[] {
+  if (typeof v === "string") {
+    return extractContextEnvKeys(v);
+  }
+  if (Array.isArray(v)) {
+    const keys: string[] = [];
+    for (const elem of v) {
+      keys.push(...findContextEnvRefsInValue(elem));
+    }
+    return keys;
+  }
+  if (typeof v === "object" && v !== null) {
+    return findContextEnvRefs(v);
+  }
+  return [];
+}
+
+/**
+ * Extracts env key names from expressions like
+ * "${ $context.env.NOTIFICATION_DATE }".
+ */
+function extractContextEnvKeys(s: string): string[] {
+  const pattern = "$context.env.";
+  const keys: string[] = [];
+
+  for (;;) {
+    const idx = s.indexOf(pattern);
+    if (idx < 0) {
+      break;
+    }
+    const rest = s.slice(idx + pattern.length);
+    let keyEnd = 0;
+    while (keyEnd < rest.length && isEnvKeyChar(rest.charCodeAt(keyEnd))) {
+      keyEnd++;
+    }
+    if (keyEnd > 0) {
+      keys.push(rest.slice(0, keyEnd));
+    }
+    s = rest.slice(keyEnd);
+  }
+
+  return keys;
+}
+
+function isEnvKeyChar(c: number): boolean {
+  return (
+    (c >= 0x41 && c <= 0x5a) || // A-Z
+    (c >= 0x61 && c <= 0x7a) || // a-z
+    (c >= 0x30 && c <= 0x39) || // 0-9
+    c === 0x5f // _
+  );
+}

package/src/domain/workflow/validation/format-violation.ts

@@ -0,0 +1,61 @@
+/**
+ * Cross-edition violation rendering — ports FormatViolation from
+ * pkg/domain/workflow/validation/task_config_constraints.go. Renders one
+ * protovalidate violation as "<field.path> – <message>", matching the Go
+ * and Cloud Java formatters exactly (en-dash separator, "<message>"
+ * sentinel when the rule is message-level, and [index] / ['key'] subscripts
+ * for repeated/map elements) — see prettyPrint / renderPath in
+ * backend/libs/java/utils/.../ProtoMessageFieldsValidator.java. All three
+ * editions emit identical strings for the same violation at Layer 1
+ * (validateSpec's folded whole-resource pass) and Layer 2 (typed task
+ * configs); the conformance suite pins the exact string (#805). Keep the
+ * formatters in lockstep.
+ *
+ * WATCH ITEM (carried from sub-project #4): the <message> half is
+ * protovalidate's text. Authored CEL messages (what the suite pins) are
+ * identical across editions by construction; protovalidate-es's
+ * library-generated messages for STANDARD rules could drift from
+ * protovalidate-go's — any such divergence surfaces at the conformance
+ * gate and goes to the owner.
+ */
+import type { Violation } from "@bufbuild/protovalidate";
+import { violationToProto } from "@bufbuild/protovalidate";
+
+/** The en-dash separator both peer formatters use. */
+const SEPARATOR = " \u2013 ";
+
+export function formatViolation(violation: Violation): string {
+  // The proto form carries the same FieldPath elements Go's formatter
+  // walks (field name or number, plus the subscript oneof).
+  const [proto] = violationToProto(violation);
+  const message = proto.message ?? "";
+  if (proto.field === undefined) {
+    return `<message>${SEPARATOR}${message}`;
+  }
+
+  const parts: string[] = [];
+  for (const el of proto.field.elements) {
+    // Prefer the field name; fall back to the field number when unknown.
+    let rendered = el.fieldName ?? String(el.fieldNumber ?? "");
+    switch (el.subscript.case) {
+      case "index":
+        rendered += `[${el.subscript.value}]`;
+        break;
+      case "boolKey":
+        rendered += `[${el.subscript.value}]`;
+        break;
+      case "intKey":
+        rendered += `[${el.subscript.value}]`;
+        break;
+      case "uintKey":
+        rendered += `[${el.subscript.value}]`;
+        break;
+      case "stringKey":
+        rendered += `['${el.subscript.value}']`;
+        break;
+    }
+    parts.push(rendered);
+  }
+
+  return parts.join(".") + SEPARATOR + message;
+}

package/src/domain/workflow/validation/human-input-validation.ts

@@ -0,0 +1,93 @@
+/**
+ * Human-input timeout-policy validation — ports
+ * pkg/domain/workflow/validation/human_input_validation.go.
+ * FAIL/APPROVE/DENY need no shape. HUMAN_INPUT_TIMEOUT_ESCALATE carries the
+ * outcome-by-name contract (oss#781): a timeout resolves to the outcome
+ * NAMED "escalate" and follows its `then` branch, so the policy is only
+ * valid when such an outcome exists with `then` set. Fail closed — a gate
+ * whose escalation has nowhere to go must never persist; the runner's
+ * loader carries the same check for hand-written YAML. Whether the `then`
+ * TARGET exists (and the graph stays acyclic) is
+ * validateCrossTaskReferences' job — this rule checks shape, not
+ * reachability, so the layers compose without duplication.
+ *
+ * The rule reads the raw task_config Struct like its siblings so the error
+ * speaks the author's own vocabulary. Strict JSON parsing accepts an enum
+ * by name or by number, so both spellings are checked.
+ */
+import { enumToJson } from "@bufbuild/protobuf";
+import type { JsonValue } from "@bufbuild/protobuf";
+
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import type { WorkflowSpec } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_pb";
+import {
+  HumanInputTimeoutPolicy,
+  HumanInputTimeoutPolicySchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/tasks/human_input_pb";
+
+export function validateHumanInputTimeoutPolicies(
+  spec: WorkflowSpec | undefined,
+): string[] {
+  if (spec === undefined || spec.tasks.length === 0) {
+    return [];
+  }
+
+  const escalate = HumanInputTimeoutPolicy.HUMAN_INPUT_TIMEOUT_ESCALATE;
+  const escalateName = enumToJson(HumanInputTimeoutPolicySchema, escalate);
+
+  const errors: string[] = [];
+  for (const task of spec.tasks) {
+    if (task.kind !== WorkflowTaskKind.human_input || task.taskConfig === undefined) {
+      continue;
+    }
+    const fields = task.taskConfig;
+    const value = fields["on_timeout"];
+    if (value === undefined) {
+      continue;
+    }
+
+    let isEscalate = false;
+    if (typeof value === "string") {
+      isEscalate = value === escalateName;
+    } else if (typeof value === "number") {
+      isEscalate = value === escalate;
+    }
+    if (!isEscalate) {
+      continue;
+    }
+
+    if (!hasEscalateOutcomeWithThen(fields["outcomes"])) {
+      errors.push(
+        `task '${task.name}' (human_input): on_timeout policy ${escalateName} requires an outcome named 'escalate' with 'then' set — the timeout resolves to that outcome and follows its 'then' branch`,
+      );
+    }
+  }
+  return errors;
+}
+
+/**
+ * Whether the raw `outcomes` value carries an outcome named "escalate"
+ * whose `then` is a non-empty string — the shape the escalate timeout
+ * policy resolves to at runtime.
+ */
+function hasEscalateOutcomeWithThen(outcomes: JsonValue | undefined): boolean {
+  if (!Array.isArray(outcomes)) {
+    return false;
+  }
+  for (const entry of outcomes) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      continue;
+    }
+    if (stringValueOf(entry["name"]) !== "escalate") {
+      continue;
+    }
+    if (stringValueOf(entry["then"]) !== "") {
+      return true;
+    }
+  }
+  return false;
+}
+
+function stringValueOf(v: JsonValue | undefined): string {
+  return typeof v === "string" ? v : "";
+}