@sweny-ai/core 0.1.161 → 0.1.162

package/dist/browser.d.ts

@@ -13,12 +13,14 @@
  *   - `buildWorkflow` / `refineWorkflow` — depend on the Claude interface.
  *   - Testing helpers — `MockClaude`, `createFileSkill` use `node:fs`.
  */
-export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, } from "./types.js";
+export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, EdgeWhen, WhenExpression, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, } from "./types.js";
 export { consoleLogger } from "./types.js";
 export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, } from "./types.js";
 export { github, linear, slack, sentry, datadog, betterstack, notification, supabase, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 export type { SkillValidationResult } from "./skills/index.js";
 export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";
 export type { WorkflowError } from "./schema.js";
+export { isWhenExpression, whenLabel, parseExpression, evaluateExpression, checkExpression, ExpressionSyntaxError, } from "./when.js";
+export type { ExprNode, ExpressionScope, ExpressionResult } from "./when.js";
 export { workflowToFlow, flowToWorkflow, applyExecutionEvent, exportAsTypescript, getSkillCatalog } from "./studio.js";
 export type { FlowNode, SkillNodeData, FlowEdge } from "./studio.js";

package/dist/browser.js

@@ -23,5 +23,7 @@ export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRA
 export { github, linear, slack, sentry, datadog, betterstack, notification, supabase, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 // Schema & validation
 export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";
+// Deterministic `when` expressions (#461). Pure, browser-safe.
+export { isWhenExpression, whenLabel, parseExpression, evaluateExpression, checkExpression, ExpressionSyntaxError, } from "./when.js";
 // Studio adapter
 export { workflowToFlow, flowToWorkflow, applyExecutionEvent, exportAsTypescript, getSkillCatalog } from "./studio.js";

package/dist/cli/run-output.js

@@ -262,7 +262,7 @@ export const WORKFLOW_RUN_OPTIONS = [
     ["-y, --yes", "Skip the batch confirmation prompt (for CI)"],
     [
         "--dry-run",
-        "Run with read-only tools only: write tools, external MCP servers, and shell/file-edit tools are withheld, so nothing is created, posted, or sent. Stops at the first conditional edge. To inspect nodes without running, use --list-nodes.",
+        "Run with read-only tools only: write tools, external MCP servers, and shell/file-edit tools are withheld, so nothing is created, posted, or sent. Stops at the first natural-language conditional edge. To inspect nodes without running, use --list-nodes.",
     ],
     [
         "--stage",

package/dist/executor.js

@@ -16,6 +16,7 @@ import { consoleLogger } from "./types.js";
 import { resolveSources } from "./source-resolver.js";
 import { evaluateAll, aggregateEval } from "./eval/index.js";
 import { evaluateRequires } from "./requires.js";
+import { evaluateExpression, isWhenExpression, parseExpression, whenLabel } from "./when.js";
 import { buildRetryPreamble } from "./retry.js";
 import { resolveExecutionModel } from "./model.js";
 import { buildToolAliases } from "./skills/index.js";
@@ -1118,15 +1119,17 @@ function resolveConfig(skills, overrides, env = process.env) {
  * Returns the next node ID, or null when execution should stop.
  */
 async function advanceFromNode(workflow, currentId, results, input, claude, observer, edgeCounts, logger, trace, abort) {
-    // Dry run path gate: stop at the first conditional routing decision.
+    // Dry run path gate: stop at the first natural-language routing decision.
     // Safety does not depend on this (#380): under dry-run every node already
-    // runs read-only (see execute()). The stop keeps the dry-run path a pure
-    // function of the graph (no LLM route evaluation, so the same workflow
-    // always visits the same nodes) and skips action branches whose output
-    // would only describe writes that cannot happen.
+    // runs read-only (see execute()). The stop keeps dry-run routing free of
+    // model route evaluation, so the path is reproducible from the node outputs
+    // alone. Expression edges (#461) are evaluated by sweny with no model call,
+    // so dry-run follows them: a preview can reach the nodes past a
+    // deterministic branch (still read-only, outputs staged) and stops only
+    // where a model would have to pick the branch.
     if (isDryRunInput(input)) {
         const outEdges = workflow.edges.filter((e) => e.from === currentId);
-        if (outEdges.some((e) => e.when)) {
+        if (outEdges.some((e) => e.when && !isWhenExpression(e.when))) {
             safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: "dry run" }, logger);
             return null;
         }
@@ -1134,7 +1137,7 @@ async function advanceFromNode(workflow, currentId, results, input, claude, obse
     const prevId = currentId;
     const nextId = await resolveNext(workflow, currentId, results, input, claude, observer, edgeCounts, logger, abort);
     if (nextId) {
-        const reason = workflow.edges.find((e) => e.from === prevId && e.to === nextId)?.when ?? "only path";
+        const reason = whenLabel(workflow.edges.find((e) => e.from === prevId && e.to === nextId)?.when) ?? "only path";
         trace.edges.push({ from: prevId, to: nextId, reason });
     }
     return nextId;
@@ -1144,7 +1147,8 @@ async function advanceFromNode(workflow, currentId, results, input, claude, obse
  *
  * - 0 out-edges → terminal (return null)
  * - 1 unconditional edge → follow it
- * - Multiple or conditional → Claude evaluates
+ * - Every conditional edge is an `{ expr }` expression → sweny evaluates them, no model call
+ * - Otherwise multiple or conditional → Claude evaluates
  *
  * Edges with max_iterations are filtered out once exhausted.
  */
@@ -1192,6 +1196,12 @@ async function resolveNext(workflow, current, results, input, claude, observer,
         safeObserve(observer, { type: "route", from: current, to: defaultEdge.to, reason: "only path" }, logger);
         return defaultEdge.to;
     }
+    // Deterministic routing (#461): every conditional out-edge is an expression,
+    // so sweny decides without a model call. validateWorkflow rejects a node
+    // that mixes expression and natural-language edges.
+    if (conditionalEdges.every((e) => isWhenExpression(e.when))) {
+        return resolveByExpressions(workflow, current, results, conditionalEdges, defaultEdge, observer, edgeCounts, logger);
+    }
     // Claude evaluates which condition matches. Include input so conditions
     // can reference workflow-level flags like dryRun, and expose evals so
     // routing edges can read `priorNode.evals.X.pass`.
@@ -1233,7 +1243,7 @@ async function resolveNext(workflow, current, results, input, claude, observer,
     }
     const choices = conditionalEdges.map((e) => ({
         id: e.to,
-        description: e.when,
+        description: whenLabel(e.when),
     }));
     if (defaultEdge) {
         choices.push({ id: defaultEdge.to, description: "None of the above / default path" });
@@ -1306,6 +1316,76 @@ async function resolveNext(workflow, current, results, input, claude, observer,
     }, logger);
     return resolved;
 }
+/**
+ * Pick the out-edge whose `{ expr }` condition is true, with no model call
+ * (#461). Exactly one true edge is taken. None true takes the unconditional
+ * default edge when there is one. Otherwise (no edge true and no default, or
+ * two or more true) it fails closed with a RouteEvaluationError, the same
+ * contract as a failed model route evaluation: sweny never guesses an edge.
+ *
+ * An expression reads only successful nodes' outputs. A missing field, or a
+ * node that did not run or did not succeed, makes that expression false and
+ * is logged as a warning, never a silent true.
+ */
+function resolveByExpressions(workflow, current, results, conditionalEdges, defaultEdge, observer, edgeCounts, logger) {
+    const scope = {};
+    for (const [id, r] of results.entries()) {
+        if (r.status === "success")
+            scope[id] = buildPriorNodeContext(r);
+    }
+    const matched = [];
+    for (const edge of conditionalEdges) {
+        const expr = whenLabel(edge.when);
+        let outcome;
+        try {
+            outcome = evaluateExpression(parseExpression(expr), scope);
+        }
+        catch (err) {
+            // validateWorkflow parses every expression before a run, so this only
+            // fires for a workflow that skipped validation. Fail closed.
+            const msg = err instanceof Error ? err.message : String(err);
+            safeObserve(observer, { type: "route", from: current, to: "(end)", reason: `invalid when expression` }, logger);
+            throw new RouteEvaluationError(current, `invalid when expression on edge '${current}' -> '${edge.to}': ${msg}`);
+        }
+        if (outcome.problem) {
+            logger?.warn(`  route expr: '${current}' -> '${edge.to}' is false: ${outcome.problem} (${expr})`, {
+                node: current,
+                to: edge.to,
+            });
+            safeObserve(observer, {
+                type: "node:warning",
+                node: current,
+                reason: `when expression on edge to '${edge.to}' evaluated false: ${outcome.problem}`,
+                fields: [],
+            }, logger);
+        }
+        if (outcome.value)
+            matched.push({ to: edge.to, expr });
+    }
+    const take = (to, reason) => {
+        if (edgeCounts) {
+            const key = `${current}→${to}`;
+            edgeCounts.set(key, (edgeCounts.get(key) ?? 0) + 1);
+        }
+        safeObserve(observer, { type: "route", from: current, to, reason }, logger);
+        return to;
+    };
+    if (matched.length === 1)
+        return take(matched[0].to, matched[0].expr);
+    if (matched.length === 0 && defaultEdge) {
+        logger?.info(`  route expr: no expression matched for '${current}'; taking default edge '${defaultEdge.to}'`, {
+            node: current,
+        });
+        return take(defaultEdge.to, "no expression matched; default edge");
+    }
+    const why = matched.length === 0
+        ? `no when expression on node '${current}' is true and there is no default (unconditional) edge`
+        : `${matched.length} when expressions on node '${current}' are true (to ${matched.map((m) => m.to).join(", ")}); ` +
+            `exactly one may match`;
+    logger?.error(`  route expr: ${why}; refusing to guess. Terminating the run.`, { node: current });
+    safeObserve(observer, { type: "route", from: current, to: "(end)", reason: why }, logger);
+    throw new RouteEvaluationError(current, `${why}; refusing to guess`);
+}
 /**
  * Validate a workflow definition before execution.
  */

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  * })
  * ```
  */
-export type { Skill, SkillCategory, SkillDefinition, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, Source, ResolvedSource, SourceKind, SourceResolutionMap, WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValidationError, InputValidationResult, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, NodeAccess, NodePermissions, NodePermissionsSpec, SafeOutputType, SafeOutputDeclaration, SafeOutputsPolicy, SafeOutputReceipt, SafeOutputPin, AuthorAssociation, } from "./types.js";
+export type { Skill, SkillCategory, SkillDefinition, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, EdgeWhen, WhenExpression, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, Source, ResolvedSource, SourceKind, SourceResolutionMap, WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValidationError, InputValidationResult, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, NodeAccess, NodePermissions, NodePermissionsSpec, SafeOutputType, SafeOutputDeclaration, SafeOutputsPolicy, SafeOutputReceipt, SafeOutputPin, AuthorAssociation, } from "./types.js";
 export { WORKFLOW_INPUT_TYPES } from "./types.js";
 export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, NODE_ACCESS, TOOL_CLASSES, SAFE_OUTPUT_TYPES, SAFE_OUTPUT_APPLIERS, AUTHOR_ASSOCIATIONS, } from "./types.js";
 export { consoleLogger } from "./types.js";
@@ -43,6 +43,8 @@ export type { SkillValidationResult } from "./skills/index.js";
 export { loadCustomSkills, discoverSkills, configuredSkills } from "./skills/custom-loader.js";
 export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, sourceZ, workflowInputsZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";
 export type { WorkflowError } from "./schema.js";
+export { isWhenExpression, whenLabel, parseExpression, evaluateExpression, checkExpression, ExpressionSyntaxError, } from "./when.js";
+export type { ExprNode, ExpressionScope, ExpressionResult } from "./when.js";
 export { loadAndValidateWorkflow, validateParsed } from "./loader.js";
 export type { LoaderResult, LoaderError, LoaderOptions } from "./loader.js";
 export { CURRENT_SPEC_VERSION, MIGRATIONS, migrateWorkflow } from "./migrations.js";

package/dist/index.js

@@ -43,6 +43,8 @@ export { github, linear, slack, sentry, datadog, notification, supabase, builtin
 export { loadCustomSkills, discoverSkills, configuredSkills } from "./skills/custom-loader.js";
 // Schema & validation
 export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, sourceZ, workflowInputsZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";
+// Deterministic `when` expressions (#461). Pure, browser-safe.
+export { isWhenExpression, whenLabel, parseExpression, evaluateExpression, checkExpression, ExpressionSyntaxError, } from "./when.js";
 // Loader — canonical read → parse → structural-validate pipeline (the path
 // the CLI uses for `workflow run`, `workflow validate`, and `publish`).
 // Node-only: loader.ts imports `node:fs`, so this is NOT mirrored in browser.ts.

package/dist/mermaid.js

@@ -9,6 +9,7 @@
  * (current/success/failed/skipped) and optional execution trace
  * to highlight which edges were taken and show loop iterations.
  */
+import { whenLabel } from "./when.js";
 /**
  * Convert a Workflow to a Mermaid flowchart diagram string.
  *
@@ -102,8 +103,9 @@ export function toMermaid(workflow, options = {}) {
         const takenCount = edgeTakenCounts.get(key) ?? 0;
         // Build label parts
         const labelParts = [];
-        if (edge.when)
-            labelParts.push(edge.when);
+        const when = whenLabel(edge.when);
+        if (when)
+            labelParts.push(when);
         if (edge.max_iterations)
             labelParts.push(`max ${edge.max_iterations}x`);
         // Show how many times this edge was actually followed

package/dist/schema.d.ts

@@ -10,6 +10,7 @@ import { z } from "zod";
 import type { Workflow, WorkflowType } from "./types.js";
 import { sourceZ } from "./sources.js";
 import { workflowInputsZ } from "./inputs.js";
+export { isWhenExpression, whenLabel } from "./when.js";
 export { sourceZ };
 export { workflowInputsZ };
 export declare const jsonSchemaZ: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -1683,17 +1684,27 @@ export declare const nodeZ: z.ZodObject<{
 export declare const edgeZ: z.ZodObject<{
     from: z.ZodString;
     to: z.ZodString;
-    when: z.ZodOptional<z.ZodString>;
+    when: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        expr: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        expr: string;
+    }, {
+        expr: string;
+    }>]>>;
     max_iterations: z.ZodOptional<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     from: string;
     to: string;
-    when?: string | undefined;
+    when?: string | {
+        expr: string;
+    } | undefined;
     max_iterations?: number | undefined;
 }, {
     from: string;
     to: string;
-    when?: string | undefined;
+    when?: string | {
+        expr: string;
+    } | undefined;
     max_iterations?: number | undefined;
 }>;
 /**
@@ -2466,17 +2477,27 @@ export declare const workflowZ: z.ZodObject<{
     edges: z.ZodArray<z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
-        when: z.ZodOptional<z.ZodString>;
+        when: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            expr: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            expr: string;
+        }, {
+            expr: string;
+        }>]>>;
         max_iterations: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         from: string;
         to: string;
-        when?: string | undefined;
+        when?: string | {
+            expr: string;
+        } | undefined;
         max_iterations?: number | undefined;
     }, {
         from: string;
         to: string;
-        when?: string | undefined;
+        when?: string | {
+            expr: string;
+        } | undefined;
         max_iterations?: number | undefined;
     }>, "many">;
     entry: z.ZodString;
@@ -2846,7 +2867,9 @@ export declare const workflowZ: z.ZodObject<{
     edges: {
         from: string;
         to: string;
-        when?: string | undefined;
+        when?: string | {
+            expr: string;
+        } | undefined;
         max_iterations?: number | undefined;
     }[];
     entry: string;
@@ -3021,7 +3044,9 @@ export declare const workflowZ: z.ZodObject<{
     edges: {
         from: string;
         to: string;
-        when?: string | undefined;
+        when?: string | {
+            expr: string;
+        } | undefined;
         max_iterations?: number | undefined;
     }[];
     entry: string;
@@ -3238,7 +3263,9 @@ export declare function parseWorkflow(raw: unknown): {
     edges: {
         from: string;
         to: string;
-        when?: string | undefined;
+        when?: string | {
+            expr: string;
+        } | undefined;
         max_iterations?: number | undefined;
     }[];
     entry: string;
@@ -3290,7 +3317,7 @@ export declare function parseWorkflow(raw: unknown): {
     } | undefined;
 };
 export interface WorkflowError {
-    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "AMBIGUOUS_EDGES" | "UNSUPPORTED_EVAL_POLICY" | "INVALID_INLINE_SKILL" | "EDGE_ITERATIONS_EXCEEDED" | "RETRY_MAX_EXCEEDED" | "PERMISSION_CEILING" | "BUDGET_CEILING" | "OUTPUT_NOT_ALLOWED" | "DUPLICATE_OUTPUT" | "UNSUPPORTED_OUTPUT";
+    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "UNBOUNDED_CYCLE" | "AMBIGUOUS_EDGES" | "UNSUPPORTED_EVAL_POLICY" | "INVALID_INLINE_SKILL" | "EDGE_ITERATIONS_EXCEEDED" | "RETRY_MAX_EXCEEDED" | "PERMISSION_CEILING" | "BUDGET_CEILING" | "OUTPUT_NOT_ALLOWED" | "DUPLICATE_OUTPUT" | "UNSUPPORTED_OUTPUT" | "INVALID_WHEN_EXPRESSION" | "MIXED_EDGE_CONDITIONS";
     message: string;
     nodeId?: string;
 }
@@ -4099,8 +4126,22 @@ export declare const workflowJsonSchema: {
                         readonly minLength: 1;
                     };
                     readonly when: {
-                        readonly type: "string";
-                        readonly description: "Natural language condition, evaluated at runtime by the workflow's harness.";
+                        readonly description: "Condition for taking this edge. A string is natural language, evaluated at runtime by the workflow's harness. An object { expr } is a deterministic expression over prior nodes' declared output fields, evaluated by sweny with no model call.";
+                        readonly oneOf: readonly [{
+                            readonly type: "string";
+                        }, {
+                            readonly type: "object";
+                            readonly required: readonly ["expr"];
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly expr: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly maxLength: 2000;
+                                    readonly description: "Boolean expression: == != < <= > >= in, && || !, exists, string/number/boolean/null literals, and node.field paths to declared output fields.";
+                                };
+                            };
+                        }];
                     };
                     readonly max_iterations: {
                         readonly type: "integer";

package/dist/schema.js

@@ -10,6 +10,9 @@ import { z } from "zod";
 import { AUTHOR_ASSOCIATIONS, CONTEXT_MODES, EVALUATOR_KINDS, EVAL_POLICIES, MCP_TRANSPORTS, NODE_ACCESS, NODE_ON_FAIL, REQUIRES_ON_FAIL, SAFE_OUTPUT_APPLIERS, SAFE_OUTPUT_EXPIRES_PATTERN, SAFE_OUTPUT_MAX_CEILING, SAFE_OUTPUT_STATES, SAFE_OUTPUT_TYPES, SKILL_CATEGORIES, SKILL_ID_MAX_LENGTH, SKILL_ID_PATTERN, TOOL_ACCESS, TOOL_CLASSES, WORKFLOW_TYPES, } from "./types.js";
 import { sourceZ } from "./sources.js";
 import { workflowInputsZ, WORKFLOW_INPUT_TYPES } from "./inputs.js";
+import { checkExpression, isWhenExpression, WHEN_EXPR_MAX_LENGTH } from "./when.js";
+// Studio and other schema-only consumers label edges without importing the root entry.
+export { isWhenExpression, whenLabel } from "./when.js";
 export { sourceZ };
 export { workflowInputsZ };
 // ─── Zod Schemas ─────────────────────────────────────────────────
@@ -330,7 +333,9 @@ export const edgeZ = z
     .object({
     from: z.string().min(1),
     to: z.string().min(1),
-    when: z.string().optional(),
+    // Natural language (the harness picks the edge) or `{ expr }`, a
+    // deterministic expression sweny evaluates itself (#461). One or the other.
+    when: z.union([z.string(), z.object({ expr: z.string().min(1).max(WHEN_EXPR_MAX_LENGTH) }).strict()]).optional(),
     max_iterations: z.number().int().min(1).max(EDGE_MAX_ITERATIONS_CEILING).optional(),
 })
     .strict();
@@ -507,6 +512,68 @@ export function validateWorkflow(workflow, knownSkills) {
             });
         }
     }
+    // Deterministic `when` expressions (#461). Every path must name a declared
+    // output field of the edge's source node or one of its ancestors, so a typo
+    // is a load error rather than a branch that never fires. A node routes on
+    // expressions or on natural language, never both: a mixed node would hand
+    // the expression edges to the model and lose the determinism the author
+    // asked for.
+    const ancestorsCache = new Map();
+    const inAll = new Map();
+    for (const [from, tos] of outAll)
+        for (const to of tos)
+            push(inAll, to, from);
+    const ancestorsOf = (id) => {
+        let seen = ancestorsCache.get(id);
+        if (seen)
+            return seen;
+        seen = new Set([id]);
+        const queue = [id];
+        for (let i = 0; i < queue.length; i++) {
+            for (const from of inAll.get(queue[i]) ?? []) {
+                if (!seen.has(from)) {
+                    seen.add(from);
+                    queue.push(from);
+                }
+            }
+        }
+        ancestorsCache.set(id, seen);
+        return seen;
+    };
+    const outputs = Object.fromEntries(Object.entries(workflow.nodes).map(([id, n]) => [id, n.output]));
+    const conditionKinds = new Map();
+    for (const edge of workflow.edges) {
+        if (!nodeIds.has(edge.from) || !edge.when)
+            continue;
+        const kinds = conditionKinds.get(edge.from) ?? { expr: 0, nl: 0 };
+        conditionKinds.set(edge.from, kinds);
+        if (!isWhenExpression(edge.when)) {
+            kinds.nl++;
+            continue;
+        }
+        kinds.expr++;
+        const problems = checkExpression(edge.when.expr, {
+            from: edge.from,
+            ancestors: ancestorsOf(edge.from),
+            outputs,
+        });
+        for (const problem of problems) {
+            errors.push({
+                code: "INVALID_WHEN_EXPRESSION",
+                message: `Edge "${edge.from}" -> "${edge.to}": ${problem}`,
+                nodeId: edge.from,
+            });
+        }
+    }
+    for (const [from, kinds] of conditionKinds) {
+        if (kinds.expr > 0 && kinds.nl > 0) {
+            errors.push({
+                code: "MIXED_EDGE_CONDITIONS",
+                message: `Node "${from}" mixes expression and natural-language 'when' conditions on its out-edges; use one kind per node (an unconditional default edge is fine with either)`,
+                nodeId: from,
+            });
+        }
+    }
     // Reachability: BFS from entry. Skipped only when the entry is missing
     // (every node would be reported, which is noise). All other diagnostics
     // accumulate so one pass reports every structural problem.
@@ -1299,8 +1366,23 @@ export const workflowJsonSchema = {
                     from: { type: "string", minLength: 1 },
                     to: { type: "string", minLength: 1 },
                     when: {
-                        type: "string",
-                        description: "Natural language condition, evaluated at runtime by the workflow's harness.",
+                        description: "Condition for taking this edge. A string is natural language, evaluated at runtime by the workflow's harness. An object { expr } is a deterministic expression over prior nodes' declared output fields, evaluated by sweny with no model call.",
+                        oneOf: [
+                            { type: "string" },
+                            {
+                                type: "object",
+                                required: ["expr"],
+                                additionalProperties: false,
+                                properties: {
+                                    expr: {
+                                        type: "string",
+                                        minLength: 1,
+                                        maxLength: WHEN_EXPR_MAX_LENGTH,
+                                        description: "Boolean expression: == != < <= > >= in, && || !, exists, string/number/boolean/null literals, and node.field paths to declared output fields.",
+                                    },
+                                },
+                            },
+                        ],
                     },
                     max_iterations: {
                         type: "integer",

package/dist/studio.d.ts

@@ -38,7 +38,7 @@
  *    directly to node highlights. node:enter → glow blue,
  *    tool:call → show tool name, node:exit → green/red.
  */
-import type { Workflow, Node, ExecutionEvent, NodeResult, Skill } from "./types.js";
+import type { Workflow, Node, Edge, ExecutionEvent, NodeResult, Skill } from "./types.js";
 export interface FlowNode {
     id: string;
     type: "skillNode";
@@ -74,7 +74,7 @@ export interface FlowEdge {
     /** Array index of this edge in workflow.edges — used for stable lookups. */
     edgeIndex: number;
     data: {
-        when?: string;
+        when?: Edge["when"];
         max_iterations?: number;
         isConditional: boolean;
     };

package/dist/types.d.ts

@@ -489,12 +489,26 @@ export interface NodeToolFilter {
     /** Skill tool names removed from the node (applied after `allow`). */
     deny?: string[];
 }
+/**
+ * A deterministic edge condition (#461): a boolean expression over prior
+ * nodes' declared output fields, evaluated by sweny with no model call.
+ * Grammar and semantics: `when.ts`.
+ */
+export interface WhenExpression {
+    expr: string;
+}
+/** An edge condition: natural language (model-evaluated) or a `{ expr }` expression. */
+export type EdgeWhen = string | WhenExpression;
 /** An edge connecting two nodes */
 export interface Edge {
     from: string;
     to: string;
-    /** Natural language condition, evaluated at runtime by the workflow's harness. */
-    when?: string;
+    /**
+     * Condition for taking this edge. A string is natural language, evaluated at
+     * runtime by the workflow's harness. `{ expr }` is a deterministic expression
+     * evaluated by sweny with no model call.
+     */
+    when?: EdgeWhen;
     /** Max times this edge can be followed (enables retry loops). Default: unlimited. */
     max_iterations?: number;
 }

package/dist/when.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Deterministic `when` expressions (#461).
+ *
+ * An edge's `when` is either natural language (a model picks the edge at
+ * runtime) or `{ expr: "..." }`, a small boolean expression over prior nodes'
+ * declared output fields that sweny evaluates itself, with no model call.
+ *
+ * Grammar (precedence low to high):
+ *
+ *   expr       := or
+ *   or         := and ( "||" and )*
+ *   and        := unary ( "&&" unary )*
+ *   unary      := "!" unary | comparison
+ *   comparison := operand ( ( "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" ) operand )?
+ *   operand    := literal | list | path | "exists" path | "(" expr ")"
+ *   list       := "[" ( literal ( "," literal )* )? "]"
+ *   literal    := number | 'string' | "string" | true | false | null
+ *   path       := ident ( "." ident )+          (node id, then field, then nested fields)
+ *
+ * Semantics are strict and total. There is no coercion and no truthiness:
+ * `&&`, `||`, `!` and the expression itself need booleans; `<` and friends
+ * need two numbers or two strings; `in` needs a list on the right. A missing
+ * field (undefined, or a node that did not run or did not succeed) or a type
+ * mismatch makes the WHOLE expression false and is reported, so a negation
+ * can never turn a missing field into a silent true. `exists path` is the
+ * one explicit presence test: true when the value is present and not null,
+ * never a warning. `&&` and `||` short-circuit, so `exists a.x && a.x > 0`
+ * is safe.
+ *
+ * Pure module: no I/O, no eval, no Function, browser-safe. Strings in the
+ * routed data are compared as data only; nothing in them is ever parsed.
+ */
+import type { EdgeWhen, JSONSchema, WhenExpression } from "./types.js";
+/** Longest expression source accepted. Routing conditions are short. */
+export declare const WHEN_EXPR_MAX_LENGTH = 2000;
+/** True when an edge `when` is the structured `{ expr }` form. */
+export declare function isWhenExpression(when: unknown): when is WhenExpression;
+/** Human-readable label for a `when`: the NL text or the expression source. */
+export declare function whenLabel(when: EdgeWhen | undefined): string | undefined;
+export type Literal = string | number | boolean | null;
+export type ExprNode = {
+    kind: "literal";
+    value: Literal;
+} | {
+    kind: "list";
+    items: Literal[];
+} | {
+    kind: "path";
+    segments: string[];
+} | {
+    kind: "exists";
+    path: {
+        kind: "path";
+        segments: string[];
+    };
+} | {
+    kind: "not";
+    operand: ExprNode;
+} | {
+    kind: "and" | "or";
+    left: ExprNode;
+    right: ExprNode;
+} | {
+    kind: "cmp";
+    op: CmpOp;
+    left: ExprNode;
+    right: ExprNode;
+};
+export type CmpOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in";
+export declare class ExpressionSyntaxError extends Error {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/**
+ * Parse an expression source into an AST. Throws `ExpressionSyntaxError` on
+ * any syntax problem, including an empty source, an over-long source, or
+ * nesting deeper than the cap.
+ */
+export declare function parseExpression(src: string): ExprNode;
+/**
+ * Per-node data an expression may read, keyed by node id. A node that did not
+ * run or did not succeed is absent, so every path into it reads as missing.
+ */
+export type ExpressionScope = Record<string, Record<string, unknown> | undefined>;
+export interface ExpressionResult {
+    /** The edge is taken only when this is true. */
+    value: boolean;
+    /**
+     * Why the expression was forced false: a missing field or a type mismatch.
+     * Absent when it evaluated normally (to true or false).
+     */
+    problem?: string;
+}
+/**
+ * Evaluate a parsed expression against node outputs. Never throws: a missing
+ * field or a type mismatch yields `{ value: false, problem }`.
+ */
+export declare function evaluateExpression(ast: ExprNode, scope: ExpressionScope): ExpressionResult;
+/**
+ * Check an expression against the workflow it routes. Returns one message per
+ * problem, empty when the expression is valid:
+ *   - the source must parse;
+ *   - every path's node must be the edge's source or one of its ancestors;
+ *   - that node must declare `output.properties`, and the field (and any
+ *     nested field) must be declared there;
+ *   - a literal compared with a declared field must fit its declared type,
+ *     and a string literal compared with an enum field must be in the enum;
+ *   - a field used where a boolean is needed must be declared boolean.
+ */
+export declare function checkExpression(src: string, ctx: {
+    from: string;
+    ancestors: Set<string>;
+    outputs: Record<string, JSONSchema | undefined>;
+}): string[];