@sweny-ai/core 0.1.160 → 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/main.d.ts

@@ -17,3 +17,6 @@ export declare function workflowExportAction(name: string): void;
 export declare function workflowValidateAction(file: string, options: {
     json?: boolean;
 }): void;
+export declare function workflowUpgradeAction(file: string, options: {
+    dryRun?: boolean;
+}): void;

package/dist/cli/main.js

@@ -19,6 +19,7 @@ import { configuredSkills, configuredSkillsWithDiagnostics } from "../skills/cus
 import { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "../mcp.js";
 import { loadAdditionalContext } from "../templates.js";
 import { loadAndValidateWorkflow } from "../loader.js";
+import { upgradeWorkflowFile } from "./workflow-upgrade.js";
 import { validateRuntimeInput } from "../inputs.js";
 import { mergeDryRunIntoInput, parseInputFlag, parseRunBudgetFlags, parseSpendFlags } from "./workflow-input.js";
 import { stringify as stringifyYaml } from "yaml";
@@ -725,6 +726,8 @@ export function loadWorkflowFile(filePath, knownSkills) {
     if (!result.ok) {
         throw new Error(`Invalid workflow file:\n${result.errors.map((e) => `  ${e.message}`).join("\n")}`);
     }
+    for (const w of result.warnings ?? [])
+        console.error(chalk.yellow(`  \u26A0 ${w}`));
     return result.workflow;
 }
 export async function workflowRunAction(file, options) {
@@ -1122,7 +1125,10 @@ export function workflowValidateAction(file, options) {
     const result = loadAndValidateWorkflow(file);
     // Missing skill env is a warning here, not a failure: `run` is where it blocks.
     const warnings = result.ok
-        ? skillEnvWarnings(result.workflow, process.env, builtinSkills.concat(configuredSkills(process.env, process.cwd())))
+        ? [
+            ...(result.warnings ?? []),
+            ...skillEnvWarnings(result.workflow, process.env, builtinSkills.concat(configuredSkills(process.env, process.cwd()))),
+        ]
         : [];
     if (options.json) {
         const errs = result.ok ? [] : result.errors;
@@ -1149,6 +1155,29 @@ workflowCmd
     .description("Validate a workflow YAML or JSON file")
     .option("--json", "Output result as JSON")
     .action(workflowValidateAction);
+export function workflowUpgradeAction(file, options) {
+    const result = upgradeWorkflowFile(file, { dryRun: options.dryRun });
+    if (result.status === "error") {
+        console.error(chalk.red(`  \u2717 ${result.message}`));
+        process.exit(1);
+        return;
+    }
+    if (result.status === "current") {
+        console.log(chalk.green(`  \u2713 ${file} is already at spec_version "${result.version}"`));
+        return;
+    }
+    const verb = result.status === "dry-run" ? "Would upgrade" : "Upgraded";
+    console.log(chalk.green(`  \u2713 ${verb} ${file}: spec_version "${result.from}" -> "${result.to}"`));
+    for (const step of result.steps)
+        console.log(chalk.dim(`    - ${step}`));
+    if (result.status === "dry-run")
+        console.log(chalk.dim("    (dry run, file not changed)"));
+}
+workflowCmd
+    .command("upgrade <file>")
+    .description("Rewrite a workflow file at the current spec version (comments are kept where possible)")
+    .option("--dry-run", "Show what would change without writing the file")
+    .action(workflowUpgradeAction);
 const workflowRunCmd = workflowCmd
     .command("run [file]")
     .description(WORKFLOW_RUN_DESCRIPTION)

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/cli/workflow-upgrade.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `sweny workflow upgrade <file> [--dry-run]`
+ *
+ * Rewrites a workflow file at the current spec version by running the same
+ * migration chain the loader applies in memory.
+ *
+ * Comment preservation (YAML): the file is edited as a YAML document, not
+ * re-serialized from scratch. Comments, blank lines, key order and quoting on
+ * everything a migration did not touch are kept. NOT preserved: a comment
+ * attached to a value a migration replaced or removed, the original position of
+ * keys a migration renamed (they are added at the end of their map), and
+ * formatting of arrays whose length a migration changed (rewritten whole).
+ * JSON files carry no comments and are rewritten with 2-space indentation.
+ */
+import { type MigrationConfig } from "../migrations.js";
+export type UpgradeResult = {
+    status: "error";
+    message: string;
+} | {
+    status: "current";
+    version: number;
+} | {
+    status: "upgraded" | "dry-run";
+    from: number;
+    to: number;
+    /** Migration descriptions applied, in order. Empty when only `spec_version` was stamped. */
+    steps: string[];
+    /** The full text that was (or, for dry-run, would be) written. */
+    content: string;
+};
+export interface UpgradeOptions {
+    dryRun?: boolean;
+    migration?: MigrationConfig;
+}
+export declare function upgradeWorkflowFile(filePath: string, options?: UpgradeOptions): UpgradeResult;

package/dist/cli/workflow-upgrade.js

@@ -0,0 +1,139 @@
+/**
+ * `sweny workflow upgrade <file> [--dry-run]`
+ *
+ * Rewrites a workflow file at the current spec version by running the same
+ * migration chain the loader applies in memory.
+ *
+ * Comment preservation (YAML): the file is edited as a YAML document, not
+ * re-serialized from scratch. Comments, blank lines, key order and quoting on
+ * everything a migration did not touch are kept. NOT preserved: a comment
+ * attached to a value a migration replaced or removed, the original position of
+ * keys a migration renamed (they are added at the end of their map), and
+ * formatting of arrays whose length a migration changed (rewritten whole).
+ * JSON files carry no comments and are rewritten with 2-space indentation.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isMap, parseDocument } from "yaml";
+import { DEFAULT_MIGRATION_CONFIG, migrateWorkflow } from "../migrations.js";
+import { validateParsed } from "../loader.js";
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function withoutSpecVersion(obj) {
+    const copy = { ...obj };
+    delete copy.spec_version;
+    return copy;
+}
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Apply the difference old -> next onto the YAML document, touching only what changed. */
+function applyDiff(doc, at, old, next) {
+    if (sameJson(old, next))
+        return;
+    if (isPlainObject(old) && isPlainObject(next)) {
+        for (const key of Object.keys(old)) {
+            if (!(key in next))
+                doc.deleteIn([...at, key]);
+        }
+        for (const key of Object.keys(next)) {
+            if (key in old)
+                applyDiff(doc, [...at, key], old[key], next[key]);
+            else
+                doc.setIn([...at, key], next[key]);
+        }
+        return;
+    }
+    if (Array.isArray(old) && Array.isArray(next) && old.length === next.length) {
+        next.forEach((item, i) => applyDiff(doc, [...at, i], old[i], item));
+        return;
+    }
+    if (at.length === 0)
+        doc.contents = doc.createNode(next);
+    else
+        doc.setIn(at, next);
+}
+function setSpecVersion(doc, version) {
+    const root = doc.contents;
+    if (!isMap(root))
+        return;
+    if (root.has("spec_version")) {
+        root.set("spec_version", version);
+        return;
+    }
+    // Insert as the first key. A comment sitting directly above the old first key
+    // is the file's header comment; carry it onto the new pair so it stays on top.
+    const first = root.items[0];
+    const pair = doc.createPair("spec_version", version);
+    const firstKey = first?.key;
+    if (firstKey && firstKey.commentBefore) {
+        pair.key.commentBefore = firstKey.commentBefore;
+        firstKey.commentBefore = undefined;
+    }
+    root.items.unshift(pair);
+}
+export function upgradeWorkflowFile(filePath, options = {}) {
+    const config = options.migration ?? DEFAULT_MIGRATION_CONFIG;
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        return { status: "error", message: `Could not read "${filePath}": ${err instanceof Error ? err.message : err}` };
+    }
+    const isYaml = [".yaml", ".yml"].includes(path.extname(filePath).toLowerCase());
+    let doc;
+    let raw;
+    try {
+        if (isYaml) {
+            doc = parseDocument(content);
+            if (doc.errors.length > 0)
+                throw doc.errors[0];
+            raw = doc.toJS();
+        }
+        else {
+            raw = JSON.parse(content);
+        }
+    }
+    catch (err) {
+        return { status: "error", message: `Could not parse "${filePath}": ${err instanceof Error ? err.message : err}` };
+    }
+    if (!isPlainObject(raw))
+        return { status: "error", message: `Expected a workflow object in "${filePath}"` };
+    const migrated = migrateWorkflow(raw, config);
+    if (!migrated.ok)
+        return { status: "error", message: migrated.message };
+    const versionText = String(migrated.to);
+    if (migrated.applied.length === 0 && raw.spec_version === versionText) {
+        return { status: "current", version: migrated.to };
+    }
+    // Never write a file that would not load.
+    const check = validateParsed(migrated.workflow, { migration: config });
+    if (!check.ok) {
+        return {
+            status: "error",
+            message: `The upgraded workflow is not valid, so "${filePath}" was left unchanged:\n${check.errors
+                .map((e) => `  ${e.message}`)
+                .join("\n")}`,
+        };
+    }
+    let out;
+    if (doc) {
+        applyDiff(doc, [], withoutSpecVersion(raw), withoutSpecVersion(migrated.workflow));
+        setSpecVersion(doc, versionText);
+        out = doc.toString();
+    }
+    else {
+        out = JSON.stringify({ spec_version: versionText, ...withoutSpecVersion(migrated.workflow) }, null, 2) + "\n";
+    }
+    if (!options.dryRun)
+        fs.writeFileSync(filePath, out, "utf-8");
+    return {
+        status: options.dryRun ? "dry-run" : "upgraded",
+        from: migrated.from,
+        to: migrated.to,
+        steps: migrated.applied.map((m) => m.description),
+        content: out,
+    };
+}

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,8 +43,12 @@ 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";
+export type { Migration, MigrationConfig, MigrateResult } from "./migrations.js";
 export { validateRuntimeInput, summarizeInputShape } from "./inputs.js";
 export { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "./mcp.js";
 export type { ProviderContextOptions, SkillMcpOptions } from "./mcp.js";

package/dist/index.js

@@ -43,10 +43,13 @@ 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.
 export { loadAndValidateWorkflow, validateParsed } from "./loader.js";
+export { CURRENT_SPEC_VERSION, MIGRATIONS, migrateWorkflow } from "./migrations.js";
 // Workflow input validation
 export { validateRuntimeInput, summarizeInputShape } from "./inputs.js";
 // MCP auto-injection

package/dist/loader.d.ts

@@ -11,15 +11,18 @@
  */
 import type { Workflow } from "./types.js";
 import { type WorkflowError } from "./schema.js";
+import { type MigrationConfig } from "./migrations.js";
 /** Structural/schema error. `code` is present only for structural errors. */
 export interface LoaderError {
     message: string;
-    code?: WorkflowError["code"] | "IO" | "PARSE" | "SCHEMA";
+    code?: WorkflowError["code"] | "IO" | "PARSE" | "SCHEMA" | "SPEC_VERSION";
     nodeId?: string;
 }
 export type LoaderResult = {
     ok: true;
     workflow: Workflow;
+    /** Non-fatal notes, e.g. the one-line "migrated in memory" warning. */
+    warnings?: string[];
 } | {
     ok: false;
     errors: LoaderError[];
@@ -27,6 +30,10 @@ export type LoaderResult = {
 export interface LoaderOptions {
     /** Optional set of known skill IDs for UNKNOWN_SKILL validation. */
     knownSkills?: Set<string>;
+    /** Spec version + migration registry. Defaults to the built-in one; tests inject their own. */
+    migration?: MigrationConfig;
+    /** Path shown in the migration warning. Set by loadAndValidateWorkflow. */
+    filePath?: string;
 }
 /**
  * Load a workflow YAML or JSON file, parse with the canonical Zod schema,

package/dist/loader.js

@@ -14,6 +14,7 @@ import * as path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { ZodError } from "zod";
 import { workflowZ, validateWorkflow, preflightLegacyVerify } from "./schema.js";
+import { DEFAULT_MIGRATION_CONFIG, migrateWorkflow, migrationWarning, } from "./migrations.js";
 /**
  * Load a workflow YAML or JSON file, parse with the canonical Zod schema,
  * and run structural validation. All three phases contribute to `errors`.
@@ -36,7 +37,7 @@ export function loadAndValidateWorkflow(filePath, options = {}) {
         const msg = err instanceof Error ? err.message : String(err);
         return { ok: false, errors: [{ message: `Could not parse "${filePath}": ${msg}`, code: "PARSE" }] };
     }
-    return validateParsed(raw, options);
+    return validateParsed(raw, { ...options, filePath: options.filePath ?? filePath });
 }
 /**
  * Validate an already-parsed workflow object (e.g. from a marketplace fetch
@@ -47,6 +48,15 @@ export function validateParsed(raw, options = {}) {
         const kind = raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw;
         return { ok: false, errors: [{ message: `Expected a workflow object, got ${kind}`, code: "SCHEMA" }] };
     }
+    // Apply spec_version migrations in memory (older versions), or refuse a
+    // version newer than this build supports. Runs first so a migration can
+    // reshape a file before the checks below see it.
+    const migrated = migrateWorkflow(raw, options.migration ?? DEFAULT_MIGRATION_CONFIG);
+    if (!migrated.ok) {
+        return { ok: false, errors: [{ message: migrated.message, code: "SPEC_VERSION" }] };
+    }
+    raw = migrated.workflow;
+    const warnings = migrated.applied.length > 0 ? [migrationWarning(migrated.from, migrated.to, options.filePath)] : [];
     // Detect legacy `verify:` blocks (renamed to `eval:` in v0.2.0) before the
     // Zod parse. workflowZ is intentionally non-strict at the top level, so a
     // top-level `verify:` would be silently STRIPPED instead of surfacing the
@@ -83,5 +93,5 @@ export function validateParsed(raw, options = {}) {
             errors: structural.map((e) => ({ message: e.message, code: e.code, nodeId: e.nodeId })),
         };
     }
-    return { ok: true, workflow: parsed };
+    return warnings.length > 0 ? { ok: true, workflow: parsed, warnings } : { ok: true, workflow: parsed };
 }

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/migrations.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Workflow spec versioning and migrations.
+ *
+ * Every workflow file carries an optional top-level `spec_version` (a string
+ * holding a positive integer, e.g. "1"). A file without the field is version 1:
+ * that is what every file written before the field existed means.
+ *
+ * Breaking spec changes bump CURRENT_SPEC_VERSION and add one entry to
+ * MIGRATIONS: a pure function from the raw (unvalidated) vN object to the raw
+ * vN+1 object. The loader applies the chain in memory so old files keep
+ * running; `sweny workflow upgrade <file>` writes the result back to disk.
+ *
+ * Adding a migration: see `__tests__/migrations.test.ts` for the harness
+ * (registry validity check plus a chain test to copy).
+ */
+/** A raw, not-yet-validated workflow object as parsed from YAML or JSON. */
+export type RawWorkflow = Record<string, unknown>;
+export interface Migration {
+    /** Version this migration reads. */
+    from: number;
+    /** Version it produces. Always `from + 1`. */
+    to: number;
+    /** One line shown by `sweny workflow upgrade`. */
+    description: string;
+    /** Pure: must not mutate its input. Returns the next-version object. */
+    migrate: (raw: RawWorkflow) => RawWorkflow;
+}
+/** The spec version this build of sweny reads natively. */
+export declare const CURRENT_SPEC_VERSION = 1;
+/**
+ * Ordered registry, one entry per version step. Empty while v1 is current.
+ * Append only; never edit a shipped migration.
+ */
+export declare const MIGRATIONS: readonly Migration[];
+export interface MigrationConfig {
+    current: number;
+    migrations: readonly Migration[];
+}
+export declare const DEFAULT_MIGRATION_CONFIG: MigrationConfig;
+export type MigrateError = {
+    code: "INVALID_VERSION" | "TOO_NEW" | "MIGRATION_FAILED";
+    message: string;
+};
+export type MigrateResult = {
+    ok: true;
+    /** The (possibly migrated) object. `spec_version` is a string when it was declared or migrated. */
+    workflow: RawWorkflow;
+    /** Version the file declared (1 when absent). */
+    from: number;
+    /** Version of `workflow` after migration. */
+    to: number;
+    /** Whether the input declared `spec_version`. */
+    declared: boolean;
+    /** Migrations applied, in order. Empty when the file is already current. */
+    applied: Migration[];
+} | ({
+    ok: false;
+} & MigrateError);
+/** Throws if a registry is not an unbroken chain of single steps ending at `current`. */
+export declare function assertRegistryValid(config: MigrationConfig): void;
+export declare function migrateWorkflow(raw: RawWorkflow, config?: MigrationConfig): MigrateResult;
+/** The single warning the loader emits when it migrated in memory. */
+export declare function migrationWarning(from: number, to: number, filePath?: string): string;