@vaudience/aigentflow-flow-validator 0.23.0 → 0.25.0

package/PARITY.md

@@ -6,6 +6,45 @@ discipline for keeping the two in sync.
 
 **Tracks AIgentFlow flow schema: `v2.831.0`** (`SPEC_VERSION` in [`src/spec/aigentflow-spec.json`](./src/spec/aigentflow-spec.json)), which adds the rule `unknown_function_operation` and a clearer `unknown_executor_scheme` message (package 0.23.0, below). Earlier: the rule `flow_data_key_reserved` (package 0.22.0). Earlier: the `here` executor scheme, the `strict_templates` flow key and the rule `template_default_piped` (package 0.21.0). Earlier: the warning `compliance_residency_unenforced` (package 0.20.0). `orchestrator.region` / `orchestrator.enforce_region` (package 0.19.0). Earlier: the AigentChat executor was removed (package 0.18.0). Earlier additions: the `examples:` block (package 0.17.0), `server_owned_query_key` (package 0.15.1) from the AIgentFlow release after v2.790.0, `credential_endpoint_unpaired` (package 0.15.2) from AIgentFlow v2.793.0 and the release after it, and `display_name_too_long` (package 0.15.3) from AIgentFlow v2.802.0.
 
+> package 0.25.0 — **the `atlas://` executor scheme and seven rules**. `atlas` becomes a known
+> scheme (no `unknown_executor_scheme` warning). The URL form is `atlas://<provider>/<resource>`:
+> provider `agent` has the single resource `run`, provider `capability` takes a capability reference
+> as its resource. Seven new **errors**, all with the step as `field` (a loop sub-step reports its
+> sub-step path and the composite `parent.child` step id):
+> `atlas_operation_unknown` (any other provider, or `agent` with a resource other than `run`);
+> `atlas_agent_missing` (an agent run whose `query.agent` is absent, empty or not a string);
+> `atlas_agent_not_literal` (`query.agent` contains `{{`: the agent is always written out, never
+> computed from input); `atlas_capabilities_not_literal` (a string entry of `query.capabilities`
+> contains `{{`); `atlas_prompt_missing` and `atlas_prompt_both` (an agent run takes exactly one of
+> `query.prompt` and `query.prompt_template`; an empty string counts as absent);
+> `atlas_capability_ref_invalid` (the reference fails `^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$`).
+> Templates in `prompt`, in `inputs` values and in a capability's `args` are fine. A templated
+> executor is skipped, an unparsable URL stays `invalid_executor_url`'s, and the scheme match is
+> exact (`ATLAS://` is a known scheme but gets none of these rules). The shape check runs first, so
+> a reference containing a character outside letters, digits, `_`, `-` and `/` (for example a dot
+> or colon) is reported as `invalid_executor_url` and never reaches the reference pattern.
+> `specVersion` is unchanged (`2.831.0`). Module: `validators/executors.ts`; spec block
+> `atlasExecutor`. Gates: thirteen `invalid-atlas-*` / `valid-atlas-*` fixtures (the valid ones
+> forbid every atlas code and `unknown_executor_scheme`), shared byte for byte with the Go port, and
+> `test/v0250-atlas-executor.test.ts`. On the 227 bundled example flows both ports report no new
+> findings.
+
+> package 0.24.0 — **`potential_infinite_loop` fires only on a cycle with no way out**, in step
+> with the reference. It used to fire on every cycle reachable from the start step, so a deliberate
+> ask-again loop (a step that routes back until a condition sends it onward) carried a warning that
+> told the author nothing. The reference now computes the strongly connected sets (Tarjan) over
+> `next.default` and `next.conditions[].goto` edges reachable from start (markers `null` /
+> `orchestrator` and unknown steps are not followed; `end` is an ordinary step) and warns once when
+> a cyclic set (more than one step, or a self-loop) has no exit. A member leaves the set when it has
+> no `next`, its `next` has `parallel` (a fan-out is treated as an exit, not guessed at), its
+> `next.default` is empty (when no condition matches the flow ends), or any default or condition
+> target is `null`, `orchestrator` or a step outside the set. Code and severity are unchanged; the
+> message now ends "a cycle of steps has no way out" and the suggestion asks for a `next.conditions`
+> branch that leaves the cycle. It cannot prove an exit ever fires; that is undecidable from the
+> YAML. Module: `validators/connectivity.ts`. Gates: ten `valid-cycle-*` / `warn-cycle-*` fixtures
+> (the valid ones use `forbidWarningCodes`, the only way to assert a false-positive risk), shared
+> byte for byte with the Go port. On the 227 bundled example flows both ports report 0 findings.
+
 > package 0.23.0 — **`unknown_function_operation`**, in step with the reference (AIgentFlow
 > v2.831.0; `specVersion` 2.831.0). One new **error**: a step or loop sub-step whose executor
 > is `function://<a>/<b>` where `<a>/<b>` is not one of the 32 registered built-ins. Before

package/dist/cli.js

@@ -463,6 +463,7 @@ var aigentflow_spec_default = {
     "ai",
     "aiv",
     "async",
+    "atlas",
     "browser",
     "chart",
     "db",
@@ -1006,6 +1007,49 @@ var aigentflow_spec_default = {
       "utils/parse-date"
     ]
   },
+  atlasExecutor: {
+    $comment: "atlas://<provider>/<resource>: calls into the Atlas platform. Providers are agent (the one resource is run) and capability (the resource is a capability reference). All findings are ERRORS, field = the step (loop sub-steps use the composite step id and the sub-step path). Templated executors, unparsable URLs and other schemes are skipped. A literal agent and literal capabilities keep a step from being steered by data: query.agent and every string in query.capabilities may not contain templateActionOpen, while prompt, inputs and capability args may. A message format takes the quoted step id first.",
+    scheme: "atlas",
+    providerAgent: "agent",
+    providerCapability: "capability",
+    agentResource: "run",
+    capabilityRefPattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
+    operationUnknown: {
+      code: "atlas_operation_unknown",
+      messageFormat: "step %s uses %s, which is not an Atlas operation. The providers are agent (resource run) and capability (resource: a capability reference).",
+      suggestion: "Use atlas://agent/run or atlas://capability/<capability-ref>."
+    },
+    agentMissing: {
+      code: "atlas_agent_missing",
+      messageFormat: "step %s runs an Atlas agent but query.agent is missing or empty.",
+      suggestion: "Set query.agent to the agent to run, written out as a literal such as @acme/reporter."
+    },
+    agentNotLiteral: {
+      code: "atlas_agent_not_literal",
+      messageFormat: "step %s computes query.agent from a template. The agent must be a fixed literal, never derived from input.",
+      suggestion: "Write the agent out as a literal such as @acme/reporter. Data may go into the prompt or the inputs instead."
+    },
+    capabilitiesNotLiteral: {
+      code: "atlas_capabilities_not_literal",
+      messageFormat: "step %s computes an entry of query.capabilities from a template. Capabilities must be fixed literals, never derived from input.",
+      suggestion: "Write each capability out as a literal. Data may go into the prompt or the inputs instead."
+    },
+    promptMissing: {
+      code: "atlas_prompt_missing",
+      messageFormat: "step %s runs an Atlas agent with neither query.prompt nor query.prompt_template.",
+      suggestion: "Set exactly one of query.prompt or query.prompt_template."
+    },
+    promptBoth: {
+      code: "atlas_prompt_both",
+      messageFormat: "step %s sets both query.prompt and query.prompt_template.",
+      suggestion: "Keep exactly one of query.prompt or query.prompt_template."
+    },
+    capabilityRefInvalid: {
+      code: "atlas_capability_ref_invalid",
+      messageFormat: "step %s uses atlas://capability/%s, which is not a valid capability reference.",
+      suggestion: "A capability reference starts with a letter or digit and continues with letters, digits and _ . : - up to 128 characters in all."
+    }
+  },
   flowDataReservedKeys: {
     $comment: "flow_data_key_reserved (ERROR, no loop demotion): a key of the top-level data: map that names engine state. data: is seeded into the mission's .data namespace, where the engine keeps its own bookkeeping, so a flow declaring such a key would forge it. Matching is exact and case-sensitive. A key is reserved when it is one of exact (each with its reason), or starts with one of prefixes (checked in order, first wins; each with its reason). The finding's field is fieldFormat with the key; the message is messageFormat with the key (JSON-quoted, as Go's %q) then the reason; the suggestion is verbatim. Findings are sorted by key. Reference: FlowDataKeyReservation, validateFlowDataKeysAreNotReserved (aigentflow#247 review).",
     code: "flow_data_key_reserved",
@@ -2129,6 +2173,21 @@ var FUNCTION_OPERATIONS = {
   operations: new Set(aigentflow_spec_default.functionOperations.operations),
   sorted: aigentflow_spec_default.functionOperations.operations
 };
+var atlas = aigentflow_spec_default.atlasExecutor;
+var ATLAS_EXECUTOR = {
+  scheme: atlas.scheme,
+  providerAgent: atlas.providerAgent,
+  providerCapability: atlas.providerCapability,
+  agentResource: atlas.agentResource,
+  capabilityRefPattern: new RegExp(atlas.capabilityRefPattern),
+  operationUnknown: atlas.operationUnknown,
+  agentMissing: atlas.agentMissing,
+  agentNotLiteral: atlas.agentNotLiteral,
+  capabilitiesNotLiteral: atlas.capabilitiesNotLiteral,
+  promptMissing: atlas.promptMissing,
+  promptBoth: atlas.promptBoth,
+  capabilityRefInvalid: atlas.capabilityRefInvalid
+};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
@@ -2192,6 +2251,51 @@ function checkExecutor(executor, field, stepID, issues) {
   }
   checkFunctionOperation(executor, field, stepID, templated, issues);
 }
+function checkAtlasStep(executor, query, stepField, stepID, issues) {
+  if (executor.includes(TEMPLATE_ACTION_OPEN)) return;
+  const m = EXECUTOR_URL_PATTERN.exec(executor);
+  if (m === null || m[1] !== ATLAS_EXECUTOR.scheme) return;
+  const provider = m[2];
+  const resource = m[3];
+  const quoted = JSON.stringify(stepID);
+  const report = (rule, ...args) => {
+    let message = rule.messageFormat.replace("%s", () => quoted);
+    for (const a of args) message = message.replace("%s", () => a);
+    issues.error({
+      field: stepField,
+      message,
+      code: rule.code,
+      stepId: stepID,
+      suggestion: rule.suggestion
+    });
+  };
+  const q2 = isRecord(query) ? query : {};
+  if (provider === ATLAS_EXECUTOR.providerCapability) {
+    if (!ATLAS_EXECUTOR.capabilityRefPattern.test(resource)) {
+      report(ATLAS_EXECUTOR.capabilityRefInvalid, resource);
+    }
+  } else if (provider === ATLAS_EXECUTOR.providerAgent && resource === ATLAS_EXECUTOR.agentResource) {
+    const agent = q2.agent;
+    if (typeof agent !== "string" || agent === "") {
+      report(ATLAS_EXECUTOR.agentMissing);
+    } else if (agent.includes(TEMPLATE_ACTION_OPEN)) {
+      report(ATLAS_EXECUTOR.agentNotLiteral);
+    }
+    const prompt = q2.prompt;
+    const promptTemplate = q2.prompt_template;
+    const hasPrompt = prompt !== void 0 && prompt !== null && prompt !== "";
+    const hasTemplate = promptTemplate !== void 0 && promptTemplate !== null && promptTemplate !== "";
+    if (!hasPrompt && !hasTemplate) report(ATLAS_EXECUTOR.promptMissing);
+    else if (hasPrompt && hasTemplate) report(ATLAS_EXECUTOR.promptBoth);
+  } else {
+    report(ATLAS_EXECUTOR.operationUnknown, executor);
+    return;
+  }
+  const caps = q2.capabilities;
+  if (Array.isArray(caps) && caps.some((c) => typeof c === "string" && c.includes(TEMPLATE_ACTION_OPEN))) {
+    report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
+  }
+}
 function checkFunctionOperation(executor, field, stepID, templated, issues) {
   if (templated) return;
   const m = EXECUTOR_URL_PATTERN.exec(executor);
@@ -2216,6 +2320,7 @@ function validateExecutors(flow, issues) {
     const executor = issues.stringOf(step, "executor", `steps.${stepID}`);
     if (executor !== null && executor !== "") {
       checkExecutor(executor, `steps.${stepID}.executor`, stepID, issues);
+      checkAtlasStep(executor, step.query, `steps.${stepID}`, stepID, issues);
     }
     const loop = step.loop;
     if (isRecord(loop) && Array.isArray(loop.steps)) {
@@ -2232,6 +2337,7 @@ function validateExecutors(flow, issues) {
             `${stepID}.${subID}`,
             issues
           );
+          checkAtlasStep(subExecutor, subStep.query, subPath, `${stepID}.${subID}`, issues);
         }
       });
     }
@@ -2732,31 +2838,81 @@ function validateConnectivity(flow, issues) {
       });
     }
   }
-  const visited = /* @__PURE__ */ new Set();
-  const recStack = /* @__PURE__ */ new Set();
-  const hasCycle = (stepID) => {
-    if (recStack.has(stepID)) return true;
-    if (visited.has(stepID)) return false;
-    visited.add(stepID);
-    recStack.add(stepID);
-    const step = steps[stepID];
-    if (isRecord(step) && isRecord(step.next)) {
-      const next = step.next;
-      for (const target of cycleTargets(next, `steps.${stepID}.next`, issues)) {
-        if (hasCycle(target)) return true;
-      }
-    }
-    recStack.delete(stepID);
-    return false;
-  };
-  if (hasCycle(start)) {
+  if (cycleWithoutExit(steps, start, issues)) {
     issues.warn({
       field: "steps",
-      message: "Potential infinite loop detected in step flow",
+      message: "Potential infinite loop detected in step flow: a cycle of steps has no way out",
       code: "potential_infinite_loop",
-      suggestion: "Review your step transitions to ensure they eventually terminate"
+      suggestion: "Give one step in the cycle a `next.conditions` branch that leaves it (or end the flow there)"
+    });
+  }
+}
+function cycleEdges(step, stepID, issues) {
+  if (!isRecord(step) || !isRecord(step.next)) return [];
+  const next = step.next;
+  const nextPath = `steps.${stepID}.next`;
+  const out = [];
+  const def = issues.stringOf(next, "default", nextPath);
+  if (def !== null && def !== "") out.push(def);
+  if (Array.isArray(next.conditions)) {
+    next.conditions.forEach((cond, i) => {
+      if (!isRecord(cond)) return;
+      const goto = issues.stringOf(cond, "goto", `${nextPath}.conditions[${i}]`);
+      if (goto !== null && goto !== "") out.push(goto);
     });
   }
+  return out;
+}
+function stepLeavesCycle(steps, stepID, inCycle, issues) {
+  const step = steps[stepID];
+  if (!isRecord(step) || !isRecord(step.next)) return true;
+  const next = step.next;
+  if (next.parallel !== void 0 && next.parallel !== null) return true;
+  const def = issues.stringOf(next, "default", `steps.${stepID}.next`);
+  if (def === null || def === "") return true;
+  for (const target of cycleEdges(step, stepID, issues)) {
+    if (isMarker(target) || !inCycle.has(target)) return true;
+  }
+  return false;
+}
+function cycleWithoutExit(steps, start, issues) {
+  let index = 0;
+  const indices = /* @__PURE__ */ new Map();
+  const low = /* @__PURE__ */ new Map();
+  const onStack = /* @__PURE__ */ new Set();
+  const stack = [];
+  let found = false;
+  const strong = (id) => {
+    indices.set(id, index);
+    low.set(id, index);
+    index++;
+    stack.push(id);
+    onStack.add(id);
+    for (const target of cycleEdges(steps[id], id, issues)) {
+      if (isMarker(target) || !Object.prototype.hasOwnProperty.call(steps, target)) continue;
+      if (!indices.has(target)) {
+        strong(target);
+        low.set(id, Math.min(low.get(id), low.get(target)));
+      } else if (onStack.has(target)) {
+        low.set(id, Math.min(low.get(id), indices.get(target)));
+      }
+    }
+    if (low.get(id) !== indices.get(id)) return;
+    const component = [];
+    for (; ; ) {
+      const top = stack.pop();
+      onStack.delete(top);
+      component.push(top);
+      if (top === id) break;
+    }
+    const inCycle = new Set(component);
+    const cyclic = component.length > 1 || cycleEdges(steps[id], id, issues).includes(id);
+    if (!cyclic) return;
+    if (component.some((member) => stepLeavesCycle(steps, member, inCycle, issues))) return;
+    found = true;
+  };
+  if (Object.prototype.hasOwnProperty.call(steps, start)) strong(start);
+  return found;
 }
 
 // src/validators/nextLogic.ts

package/dist/index.cjs

@@ -459,6 +459,7 @@ var aigentflow_spec_default = {
     "ai",
     "aiv",
     "async",
+    "atlas",
     "browser",
     "chart",
     "db",
@@ -988,6 +989,48 @@ var aigentflow_spec_default = {
       "utils/parse-date"
     ]
   },
+  atlasExecutor: {
+    scheme: "atlas",
+    providerAgent: "agent",
+    providerCapability: "capability",
+    agentResource: "run",
+    capabilityRefPattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$",
+    operationUnknown: {
+      code: "atlas_operation_unknown",
+      messageFormat: "step %s uses %s, which is not an Atlas operation. The providers are agent (resource run) and capability (resource: a capability reference).",
+      suggestion: "Use atlas://agent/run or atlas://capability/<capability-ref>."
+    },
+    agentMissing: {
+      code: "atlas_agent_missing",
+      messageFormat: "step %s runs an Atlas agent but query.agent is missing or empty.",
+      suggestion: "Set query.agent to the agent to run, written out as a literal such as @acme/reporter."
+    },
+    agentNotLiteral: {
+      code: "atlas_agent_not_literal",
+      messageFormat: "step %s computes query.agent from a template. The agent must be a fixed literal, never derived from input.",
+      suggestion: "Write the agent out as a literal such as @acme/reporter. Data may go into the prompt or the inputs instead."
+    },
+    capabilitiesNotLiteral: {
+      code: "atlas_capabilities_not_literal",
+      messageFormat: "step %s computes an entry of query.capabilities from a template. Capabilities must be fixed literals, never derived from input.",
+      suggestion: "Write each capability out as a literal. Data may go into the prompt or the inputs instead."
+    },
+    promptMissing: {
+      code: "atlas_prompt_missing",
+      messageFormat: "step %s runs an Atlas agent with neither query.prompt nor query.prompt_template.",
+      suggestion: "Set exactly one of query.prompt or query.prompt_template."
+    },
+    promptBoth: {
+      code: "atlas_prompt_both",
+      messageFormat: "step %s sets both query.prompt and query.prompt_template.",
+      suggestion: "Keep exactly one of query.prompt or query.prompt_template."
+    },
+    capabilityRefInvalid: {
+      code: "atlas_capability_ref_invalid",
+      messageFormat: "step %s uses atlas://capability/%s, which is not a valid capability reference.",
+      suggestion: "A capability reference starts with a letter or digit and continues with letters, digits and _ . : - up to 128 characters in all."
+    }
+  },
   flowDataReservedKeys: {
     code: "flow_data_key_reserved",
     fieldFormat: "data.%s",
@@ -2030,6 +2073,21 @@ var FUNCTION_OPERATIONS = {
   operations: new Set(aigentflow_spec_default.functionOperations.operations),
   sorted: aigentflow_spec_default.functionOperations.operations
 };
+var atlas = aigentflow_spec_default.atlasExecutor;
+var ATLAS_EXECUTOR = {
+  scheme: atlas.scheme,
+  providerAgent: atlas.providerAgent,
+  providerCapability: atlas.providerCapability,
+  agentResource: atlas.agentResource,
+  capabilityRefPattern: new RegExp(atlas.capabilityRefPattern),
+  operationUnknown: atlas.operationUnknown,
+  agentMissing: atlas.agentMissing,
+  agentNotLiteral: atlas.agentNotLiteral,
+  capabilitiesNotLiteral: atlas.capabilitiesNotLiteral,
+  promptMissing: atlas.promptMissing,
+  promptBoth: atlas.promptBoth,
+  capabilityRefInvalid: atlas.capabilityRefInvalid
+};
 
 // src/validators/executors.ts
 var SCHEME_SEPARATOR = "://";
@@ -2093,6 +2151,51 @@ function checkExecutor(executor, field, stepID, issues) {
   }
   checkFunctionOperation(executor, field, stepID, templated, issues);
 }
+function checkAtlasStep(executor, query, stepField, stepID, issues) {
+  if (executor.includes(TEMPLATE_ACTION_OPEN)) return;
+  const m = EXECUTOR_URL_PATTERN.exec(executor);
+  if (m === null || m[1] !== ATLAS_EXECUTOR.scheme) return;
+  const provider = m[2];
+  const resource = m[3];
+  const quoted = JSON.stringify(stepID);
+  const report = (rule, ...args) => {
+    let message = rule.messageFormat.replace("%s", () => quoted);
+    for (const a of args) message = message.replace("%s", () => a);
+    issues.error({
+      field: stepField,
+      message,
+      code: rule.code,
+      stepId: stepID,
+      suggestion: rule.suggestion
+    });
+  };
+  const q2 = isRecord(query) ? query : {};
+  if (provider === ATLAS_EXECUTOR.providerCapability) {
+    if (!ATLAS_EXECUTOR.capabilityRefPattern.test(resource)) {
+      report(ATLAS_EXECUTOR.capabilityRefInvalid, resource);
+    }
+  } else if (provider === ATLAS_EXECUTOR.providerAgent && resource === ATLAS_EXECUTOR.agentResource) {
+    const agent = q2.agent;
+    if (typeof agent !== "string" || agent === "") {
+      report(ATLAS_EXECUTOR.agentMissing);
+    } else if (agent.includes(TEMPLATE_ACTION_OPEN)) {
+      report(ATLAS_EXECUTOR.agentNotLiteral);
+    }
+    const prompt = q2.prompt;
+    const promptTemplate = q2.prompt_template;
+    const hasPrompt = prompt !== void 0 && prompt !== null && prompt !== "";
+    const hasTemplate = promptTemplate !== void 0 && promptTemplate !== null && promptTemplate !== "";
+    if (!hasPrompt && !hasTemplate) report(ATLAS_EXECUTOR.promptMissing);
+    else if (hasPrompt && hasTemplate) report(ATLAS_EXECUTOR.promptBoth);
+  } else {
+    report(ATLAS_EXECUTOR.operationUnknown, executor);
+    return;
+  }
+  const caps = q2.capabilities;
+  if (Array.isArray(caps) && caps.some((c) => typeof c === "string" && c.includes(TEMPLATE_ACTION_OPEN))) {
+    report(ATLAS_EXECUTOR.capabilitiesNotLiteral);
+  }
+}
 function checkFunctionOperation(executor, field, stepID, templated, issues) {
   if (templated) return;
   const m = EXECUTOR_URL_PATTERN.exec(executor);
@@ -2117,6 +2220,7 @@ function validateExecutors(flow, issues) {
     const executor = issues.stringOf(step, "executor", `steps.${stepID}`);
     if (executor !== null && executor !== "") {
       checkExecutor(executor, `steps.${stepID}.executor`, stepID, issues);
+      checkAtlasStep(executor, step.query, `steps.${stepID}`, stepID, issues);
     }
     const loop = step.loop;
     if (isRecord(loop) && Array.isArray(loop.steps)) {
@@ -2133,6 +2237,7 @@ function validateExecutors(flow, issues) {
             `${stepID}.${subID}`,
             issues
           );
+          checkAtlasStep(subExecutor, subStep.query, subPath, `${stepID}.${subID}`, issues);
         }
       });
     }
@@ -2633,31 +2738,81 @@ function validateConnectivity(flow, issues) {
       });
     }
   }
-  const visited = /* @__PURE__ */ new Set();
-  const recStack = /* @__PURE__ */ new Set();
-  const hasCycle = (stepID) => {
-    if (recStack.has(stepID)) return true;
-    if (visited.has(stepID)) return false;
-    visited.add(stepID);
-    recStack.add(stepID);
-    const step = steps[stepID];
-    if (isRecord(step) && isRecord(step.next)) {
-      const next = step.next;
-      for (const target of cycleTargets(next, `steps.${stepID}.next`, issues)) {
-        if (hasCycle(target)) return true;
-      }
-    }
-    recStack.delete(stepID);
-    return false;
-  };
-  if (hasCycle(start)) {
+  if (cycleWithoutExit(steps, start, issues)) {
     issues.warn({
       field: "steps",
-      message: "Potential infinite loop detected in step flow",
+      message: "Potential infinite loop detected in step flow: a cycle of steps has no way out",
       code: "potential_infinite_loop",
-      suggestion: "Review your step transitions to ensure they eventually terminate"
+      suggestion: "Give one step in the cycle a `next.conditions` branch that leaves it (or end the flow there)"
+    });
+  }
+}
+function cycleEdges(step, stepID, issues) {
+  if (!isRecord(step) || !isRecord(step.next)) return [];
+  const next = step.next;
+  const nextPath = `steps.${stepID}.next`;
+  const out = [];
+  const def = issues.stringOf(next, "default", nextPath);
+  if (def !== null && def !== "") out.push(def);
+  if (Array.isArray(next.conditions)) {
+    next.conditions.forEach((cond, i) => {
+      if (!isRecord(cond)) return;
+      const goto = issues.stringOf(cond, "goto", `${nextPath}.conditions[${i}]`);
+      if (goto !== null && goto !== "") out.push(goto);
     });
   }
+  return out;
+}
+function stepLeavesCycle(steps, stepID, inCycle, issues) {
+  const step = steps[stepID];
+  if (!isRecord(step) || !isRecord(step.next)) return true;
+  const next = step.next;
+  if (next.parallel !== void 0 && next.parallel !== null) return true;
+  const def = issues.stringOf(next, "default", `steps.${stepID}.next`);
+  if (def === null || def === "") return true;
+  for (const target of cycleEdges(step, stepID, issues)) {
+    if (isMarker(target) || !inCycle.has(target)) return true;
+  }
+  return false;
+}
+function cycleWithoutExit(steps, start, issues) {
+  let index = 0;
+  const indices = /* @__PURE__ */ new Map();
+  const low = /* @__PURE__ */ new Map();
+  const onStack = /* @__PURE__ */ new Set();
+  const stack = [];
+  let found = false;
+  const strong = (id) => {
+    indices.set(id, index);
+    low.set(id, index);
+    index++;
+    stack.push(id);
+    onStack.add(id);
+    for (const target of cycleEdges(steps[id], id, issues)) {
+      if (isMarker(target) || !Object.prototype.hasOwnProperty.call(steps, target)) continue;
+      if (!indices.has(target)) {
+        strong(target);
+        low.set(id, Math.min(low.get(id), low.get(target)));
+      } else if (onStack.has(target)) {
+        low.set(id, Math.min(low.get(id), indices.get(target)));
+      }
+    }
+    if (low.get(id) !== indices.get(id)) return;
+    const component = [];
+    for (; ; ) {
+      const top = stack.pop();
+      onStack.delete(top);
+      component.push(top);
+      if (top === id) break;
+    }
+    const inCycle = new Set(component);
+    const cyclic = component.length > 1 || cycleEdges(steps[id], id, issues).includes(id);
+    if (!cyclic) return;
+    if (component.some((member) => stepLeavesCycle(steps, member, inCycle, issues))) return;
+    found = true;
+  };
+  if (Object.prototype.hasOwnProperty.call(steps, start)) strong(start);
+  return found;
 }
 
 // src/validators/nextLogic.ts