@gobing-ai/ts-dual-workflow-engine 0.2.8 → 0.3.0

package/README.md

@@ -42,10 +42,11 @@ import {
     type ActionRunner,
 } from '@gobing-ai/ts-dual-workflow-engine';
 
-const captureAction: ActionRunner = {
+const captureAction: ActionRunner & { seen: string[] } = {
     kind: 'capture',
+    seen: [],
     async execute(options) {
-        console.log(options.message);
+        this.seen.push(String(options.message ?? ''));
         return { ok: true };
     },
 };
@@ -74,7 +75,9 @@ const result = await driver.run(
     { runId: 'approval-1' },
 );
 
-console.log(result.status, result.finalState);
+result.status; // "done"
+result.finalState; // "done"
+captureAction.seen; // ["approved"]
 ```
 
 The driver persists each state snapshot, phase update, transition, and final run status through the configured persistence adapter.
@@ -105,7 +108,8 @@ const result = await service.run({
     edges: [{ from: 'start', to: 'done' }],
 });
 
-console.log(result);
+result.status; // "done"
+result.finalState; // "done"
 ```
 
 The default host includes built-in `note` and `shell` action runners plus an `always` guard. For production systems, register domain-specific runners and keep shell execution explicit.

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IAChC,mFAAmF;IACnF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChD;AAED,yDAAyD;AACzD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,WAAW,CAGtF;AAED,yDAAyD;AACzD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC,CAE3G;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAM/D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IAChC,mFAAmF;IACnF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChD;AAED,yDAAyD;AACzD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,WAAW,CAGtF;AAED,yDAAyD;AACzD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC,CAE3G;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAM/D"}

package/dist/config.js

@@ -1,10 +1,9 @@
-import { loadStructuredConfig } from '@gobing-ai/ts-runtime';
-import { parse } from 'yaml';
+import { loadStructuredConfig, parseYamlObject } from '@gobing-ai/ts-runtime';
 import { WorkflowValidationError } from './errors.js';
-import { WorkflowDefSchema } from './schema.js';
+import { StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema } from './schema.js';
 /** Load a workflow definition from YAML or JSON text. */
 export function loadWorkflowDefFromText(text, source = '<inline>') {
-    const parsed = source.endsWith('.json') ? JSON.parse(text) : parse(text);
+    const parsed = source.endsWith('.json') ? JSON.parse(text) : parseYamlObject(text);
     return parseWorkflowDef(parsed, source);
 }
 /** Load a workflow definition from a filesystem path. */
@@ -21,34 +20,184 @@ export function validateWorkflowDef(workflow) {
     }
 }
 function validateStateMachine(workflow) {
-    const states = new Set(workflow.states.map((state) => state.id));
+    const errors = [];
+    const ids = workflow.states.map((state) => state.id);
+    const states = new Set(ids);
+    const terminals = new Set(workflow.terminalStates ?? []);
+    // Duplicate state ids.
+    for (const id of duplicates(ids))
+        errors.push(`State "${id}" is declared more than once`);
+    // Initial state must be declared and must not be terminal.
     if (!states.has(workflow.initialState)) {
-        throw new WorkflowValidationError(`Initial state "${workflow.initialState}" is not declared`);
+        errors.push(`Initial state "${workflow.initialState}" is not declared`);
     }
+    else if (terminals.has(workflow.initialState)) {
+        errors.push(`Initial state "${workflow.initialState}" must not be a terminal state`);
+    }
+    // Terminal states must be declared.
+    for (const terminal of terminals) {
+        if (!states.has(terminal))
+            errors.push(`Terminal state "${terminal}" is not declared`);
+    }
+    const outboundByState = new Map();
     for (const transition of workflow.transitions) {
         if (!states.has(transition.from))
-            throw new WorkflowValidationError(`Transition source "${transition.from}" is not declared`);
+            errors.push(`Transition source "${transition.from}" is not declared`);
         if (!states.has(transition.to))
-            throw new WorkflowValidationError(`Transition target "${transition.to}" is not declared`);
+            errors.push(`Transition target "${transition.to}" is not declared`);
+        const list = outboundByState.get(transition.from) ?? [];
+        list.push(transition);
+        outboundByState.set(transition.from, list);
     }
+    // Explicit terminal states must not declare outgoing transitions. Note: a state
+    // with NO transitions is treated as an implicit terminal by the driver (it stops
+    // there), so a missing transition is NOT an error; only an *explicit* terminal
+    // that also declares transitions is contradictory.
+    for (const state of workflow.states) {
+        const outbound = outboundByState.get(state.id) ?? [];
+        if (terminals.has(state.id)) {
+            if (outbound.length > 0)
+                errors.push(`Terminal state "${state.id}" must not declare transitions`);
+            continue;
+        }
+        // An unguarded transition is unconditional, so anything after it is dead —
+        // it must be declared last among a state's outgoing transitions.
+        const ungatedIndex = outbound.findIndex((transition) => transition.guard === undefined);
+        if (ungatedIndex !== -1 && ungatedIndex < outbound.length - 1) {
+            errors.push(`State "${state.id}" has an unguarded transition that is not last; later transitions are unreachable`);
+        }
+    }
+    // Template variable references must resolve against declared vars / env allowlist.
+    errors.push(...checkVariableReferences(collectActionOptions(workflow), workflow.vars, workflow.env));
+    throwIfErrors(workflow, errors);
 }
 function parseWorkflowDef(parsed, source) {
-    const result = WorkflowDefSchema.safeParse(parsed);
+    // Parse against the specific dialect schema (not the union) so errors carry the
+    // exact failing field path instead of the union's generic "Invalid input".
+    const schema = selectWorkflowSchema(parsed);
+    const result = schema.safeParse(parsed);
     if (!result.success) {
-        throw new WorkflowValidationError(`Workflow definition failed schema validation for ${source}: ${result.error.issues.map((issue) => issue.message).join('; ')}`, result.error.issues);
+        throw new WorkflowValidationError(`Workflow definition failed schema validation for ${source}: ${formatWorkflowIssues(result.error.issues)}`, result.error.issues);
     }
     validateWorkflowDef(result.data);
     return result.data;
 }
-function validateTransitionFlow(workflow) {
-    const nodes = new Set(workflow.nodes.map((node) => node.id));
-    if (!nodes.has(workflow.initialNode)) {
-        throw new WorkflowValidationError(`Initial node "${workflow.initialNode}" is not declared`);
+/** Pick the dialect schema by the shape of the input so diagnostics are field-precise. */
+function selectWorkflowSchema(parsed) {
+    if (parsed !== null && typeof parsed === 'object') {
+        const value = parsed;
+        if (value.kind === 'transition-flow' || 'nodes' in value || 'edges' in value || 'initialNode' in value) {
+            return TransitionFlowWorkflowDefSchema;
+        }
     }
+    return StateMachineWorkflowDefSchema;
+}
+/** Render Zod issues as `path: message` fragments so the offending field is obvious. */
+function formatWorkflowIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = issue.path.map(String).join('.');
+        return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join('; ');
+}
+function validateTransitionFlow(workflow) {
+    const errors = [];
+    const ids = workflow.nodes.map((node) => node.id);
+    const nodes = new Set(ids);
+    // Duplicate node ids.
+    for (const id of duplicates(ids))
+        errors.push(`Node "${id}" is declared more than once`);
+    // Initial node must be declared.
+    if (!nodes.has(workflow.initialNode))
+        errors.push(`Initial node "${workflow.initialNode}" is not declared`);
+    // Edge endpoints must be declared; duplicate from→to edges are ambiguous.
+    const seenEdges = new Set();
     for (const edge of workflow.edges) {
         if (!nodes.has(edge.from))
-            throw new WorkflowValidationError(`Edge source "${edge.from}" is not declared`);
+            errors.push(`Edge source "${edge.from}" is not declared`);
         if (!nodes.has(edge.to))
-            throw new WorkflowValidationError(`Edge target "${edge.to}" is not declared`);
+            errors.push(`Edge target "${edge.to}" is not declared`);
+        const key = `${edge.from}→${edge.to}`;
+        if (seenEdges.has(key))
+            errors.push(`Duplicate edge "${key}"`);
+        seenEdges.add(key);
+    }
+    // Template variable references must resolve.
+    errors.push(...checkVariableReferences(collectActionOptions(workflow), workflow.vars, workflow.env));
+    throwIfErrors(workflow, errors);
+}
+/** Return the ids that appear more than once, in first-seen order. */
+function duplicates(ids) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const id of ids) {
+        if (seen.has(id))
+            dupes.add(id);
+        seen.add(id);
+    }
+    return [...dupes];
+}
+/** Gather every action `options` object across a workflow's states/nodes for template scanning. */
+function collectActionOptions(workflow) {
+    const optionSets = [];
+    const actions = workflow.kind === 'transition-flow'
+        ? workflow.nodes.flatMap((node) => (node.action ? [node.action] : []))
+        : workflow.states.flatMap((state) => [...(state.onEnter ?? []), ...(state.onExit ?? [])]);
+    for (const action of actions) {
+        if (action.options)
+            optionSets.push(action.options);
+    }
+    return optionSets;
+}
+/** Reserved template namespaces always available at runtime (not user-declared vars). */
+const RUNTIME_TEMPLATE_NAMESPACES = new Set([
+    'workflow',
+    'runId',
+    'task',
+    'state',
+    'node',
+    'iteration',
+    'run',
+    'runtime',
+]);
+/**
+ * Check `${...}` template references inside action options resolve to something:
+ * a declared `vars.X`, an env-allowlisted `env.X`, or a reserved runtime namespace.
+ */
+function checkVariableReferences(optionSets, vars, env) {
+    const declaredVars = new Set(Object.keys(vars ?? {}));
+    const allowedEnv = new Set(env?.allow ?? []);
+    const errors = [];
+    const reference = /\$\{([^}]+)\}/g;
+    for (const options of optionSets) {
+        for (const value of Object.values(options)) {
+            if (typeof value !== 'string')
+                continue;
+            for (const match of value.matchAll(reference)) {
+                const expr = (match[1] ?? '').trim();
+                const [namespace, name] = expr.includes('.') ? expr.split('.', 2) : [expr, undefined];
+                if (namespace === 'vars') {
+                    if (name !== undefined && !declaredVars.has(name)) {
+                        errors.push(`Unknown variable reference "\${${expr}}" (no var "${name}" declared)`);
+                    }
+                }
+                else if (namespace === 'env') {
+                    if (name !== undefined && !allowedEnv.has(name)) {
+                        errors.push(`Env reference "\${${expr}}" is not in env.allow`);
+                    }
+                }
+                else if (namespace !== undefined && !RUNTIME_TEMPLATE_NAMESPACES.has(namespace)) {
+                    errors.push(`Unknown template reference "\${${expr}}"`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+/** Throw a single aggregated validation error when any invariant failed. */
+function throwIfErrors(workflow, errors) {
+    if (errors.length > 0) {
+        throw new WorkflowValidationError(`Workflow "${workflow.name}" is invalid: ${errors.join('; ')}`, errors);
     }
 }

package/dist/schema.d.ts

@@ -14,6 +14,8 @@ export declare const StateMachineWorkflowDefSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     kind: z.ZodOptional<z.ZodLiteral<"state-machine">>;
     name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
     initialState: z.ZodString;
     terminalStates: z.ZodOptional<z.ZodArray<z.ZodString>>;
     iterationBound: z.ZodOptional<z.ZodNumber>;
@@ -23,6 +25,7 @@ export declare const StateMachineWorkflowDefSchema: z.ZodObject<{
     }, z.core.$strip>>;
     states: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         onEnter: z.ZodOptional<z.ZodArray<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -31,22 +34,25 @@ export declare const StateMachineWorkflowDefSchema: z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>>;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     transitions: z.ZodArray<z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         trigger: z.ZodOptional<z.ZodString>;
         guard: z.ZodOptional<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /** Zod schema for transition-flow workflow definitions. */
 export declare const TransitionFlowWorkflowDefSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     kind: z.ZodLiteral<"transition-flow">;
     name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
     initialNode: z.ZodString;
     terminalNodes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     iterationBound: z.ZodOptional<z.ZodNumber>;
@@ -56,6 +62,7 @@ export declare const TransitionFlowWorkflowDefSchema: z.ZodObject<{
     }, z.core.$strip>>;
     nodes: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodEnum<{
             action: "action";
             gate: "gate";
@@ -66,21 +73,24 @@ export declare const TransitionFlowWorkflowDefSchema: z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     edges: z.ZodArray<z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         condition: z.ZodOptional<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /** Zod schema for either supported workflow definition shape. */
 export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     kind: z.ZodOptional<z.ZodLiteral<"state-machine">>;
     name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
     initialState: z.ZodString;
     terminalStates: z.ZodOptional<z.ZodArray<z.ZodString>>;
     iterationBound: z.ZodOptional<z.ZodNumber>;
@@ -90,6 +100,7 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strip>>;
     states: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         onEnter: z.ZodOptional<z.ZodArray<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -98,20 +109,23 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>>;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     transitions: z.ZodArray<z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         trigger: z.ZodOptional<z.ZodString>;
         guard: z.ZodOptional<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>, z.ZodObject<{
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     kind: z.ZodLiteral<"transition-flow">;
     name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
     initialNode: z.ZodString;
     terminalNodes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     iterationBound: z.ZodOptional<z.ZodNumber>;
@@ -121,6 +135,7 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strip>>;
     nodes: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodEnum<{
             action: "action";
             gate: "gate";
@@ -131,14 +146,15 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     edges: z.ZodArray<z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
         condition: z.ZodOptional<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>]>;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;iBAG1B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,yDAAyD;AACzD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwBxC,CAAC;AAEH,2DAA2D;AAC3D,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuB1C,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAA4E,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;iBAG1B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,yDAAyD;AACzD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmC7B,CAAC;AAEd,2DAA2D;AAC3D,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkC/B,CAAC;AAEd,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAA4E,CAAC"}

package/dist/schema.js

@@ -1,4 +1,23 @@
 import { z } from 'zod';
+/** Identifier names reserved for runtime template namespaces; not allowed as user vars. */
+const RESERVED_VAR_NAMES = new Set(['task', 'state', 'node', 'iteration', 'run', 'runtime']);
+/** Valid identifier pattern for variable and env names. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** User variables: identifier-keyed string map; reserved runtime names are rejected. */
+const VarsSchema = z.record(z.string(), z.string()).superRefine((vars, ctx) => {
+    for (const key of Object.keys(vars)) {
+        if (!IDENTIFIER.test(key)) {
+            ctx.addIssue({ code: 'custom', message: `Invalid variable name "${key}" (must be a valid identifier)` });
+        }
+        if (RESERVED_VAR_NAMES.has(key)) {
+            ctx.addIssue({ code: 'custom', message: `Variable name "${key}" is reserved for runtime use` });
+        }
+    }
+});
+/** Environment allowlist: identifier-named env vars exposed to templates. */
+const EnvSchema = z.object({
+    allow: z.array(z.string().regex(IDENTIFIER, 'env.allow entries must be valid identifiers')).optional(),
+});
 /** Zod schema for workflow action definitions. */
 export const ActionDefSchema = z.object({
     kind: z.string().min(1),
@@ -10,47 +29,69 @@ export const GuardDefSchema = z.object({
     options: z.record(z.string(), z.unknown()).optional(),
 });
 /** Zod schema for state-machine workflow definitions. */
-export const StateMachineWorkflowDefSchema = z.object({
+export const StateMachineWorkflowDefSchema = z
+    .object({
     $schema: z.string().optional(),
     kind: z.literal('state-machine').optional(),
     name: z.string().min(1),
+    // Optional, behavior-free document version tag (accepted for forward/backward compat).
+    version: z.string().optional(),
+    description: z.string().optional(),
     initialState: z.string().min(1),
     terminalStates: z.array(z.string().min(1)).optional(),
     iterationBound: z.number().int().positive().optional(),
-    vars: z.record(z.string(), z.string()).optional(),
-    env: z.object({ allow: z.array(z.string()).optional() }).optional(),
-    states: z.array(z.object({
+    vars: VarsSchema.optional(),
+    env: EnvSchema.optional(),
+    states: z.array(z
+        .object({
         id: z.string().min(1),
+        description: z.string().optional(),
         onEnter: z.array(ActionDefSchema).optional(),
         onExit: z.array(ActionDefSchema).optional(),
-    })),
-    transitions: z.array(z.object({
+    })
+        .strict()),
+    transitions: z.array(z
+        .object({
         from: z.string().min(1),
         to: z.string().min(1),
+        description: z.string().optional(),
         trigger: z.string().optional(),
         guard: GuardDefSchema.optional(),
-    })),
-});
+    })
+        .strict()),
+})
+    .strict();
 /** Zod schema for transition-flow workflow definitions. */
-export const TransitionFlowWorkflowDefSchema = z.object({
+export const TransitionFlowWorkflowDefSchema = z
+    .object({
     $schema: z.string().optional(),
     kind: z.literal('transition-flow'),
     name: z.string().min(1),
+    // Optional, behavior-free document version tag (accepted for forward/backward compat).
+    version: z.string().optional(),
+    description: z.string().optional(),
     initialNode: z.string().min(1),
     terminalNodes: z.array(z.string().min(1)).optional(),
     iterationBound: z.number().int().positive().optional(),
-    vars: z.record(z.string(), z.string()).optional(),
-    env: z.object({ allow: z.array(z.string()).optional() }).optional(),
-    nodes: z.array(z.object({
+    vars: VarsSchema.optional(),
+    env: EnvSchema.optional(),
+    nodes: z.array(z
+        .object({
         id: z.string().min(1),
+        description: z.string().optional(),
         type: z.enum(['action', 'gate', 'parallel', 'decision']).optional(),
         action: ActionDefSchema.optional(),
-    })),
-    edges: z.array(z.object({
+    })
+        .strict()),
+    edges: z.array(z
+        .object({
         from: z.string().min(1),
         to: z.string().min(1),
+        description: z.string().optional(),
         condition: GuardDefSchema.optional(),
-    })),
-});
+    })
+        .strict()),
+})
+    .strict();
 /** Zod schema for either supported workflow definition shape. */
 export const WorkflowDefSchema = z.union([StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema]);

package/dist/state-machine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAGR,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAElB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAGjB,yDAAyD;AACzD,MAAM,WAAW,yBAAyB;IACtC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;CACpD;AAED,wEAAwE;AACxE,qBAAa,kBAAkB;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,yBAAyB;IAE/D,6DAA6D;IACvD,GAAG,CAAC,QAAQ,EAAE,uBAAuB,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YA4G5F,UAAU;YA6BV,IAAI;YAYJ,IAAI;CAYrB"}
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAGR,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAElB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAGjB,yDAAyD;AACzD,MAAM,WAAW,yBAAyB;IACtC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;CACpD;AAED,wEAAwE;AACxE,qBAAa,kBAAkB;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,yBAAyB;IAE/D,6DAA6D;IACvD,GAAG,CAAC,QAAQ,EAAE,uBAAuB,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YA8G5F,UAAU;YA8BV,IAAI;YAYJ,IAAI;CAYrB"}

package/dist/state-machine.js

@@ -28,7 +28,7 @@ export class StateMachineDriver {
             await this.options.persistence.saveWorkflowState(runId, current.id, { transitionsTaken });
             await this.options.persistence.savePhase(runId, current.id, 'running');
             // 2. Execute this state's on-enter actions in declaration order.
-            lastActionResult = await this.runActions(current.onEnter ?? [], workflow.name, current.id, runId, vars, env, options);
+            lastActionResult = await this.runActions(current.onEnter ?? [], workflow.name, current.id, runId, vars, env, options, transitionsTaken);
             if (lastActionResult?.ok === false)
                 return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, lastActionResult.error);
             // 3. Stop immediately when an action explicitly declares terminal success.
@@ -51,7 +51,7 @@ export class StateMachineDriver {
                 return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, 'no-passing-transition');
             }
             // 6. Execute this state's on-exit actions before changing state.
-            const exitResult = await this.runActions(current.onExit ?? [], workflow.name, current.id, runId, vars, env, options);
+            const exitResult = await this.runActions(current.onExit ?? [], workflow.name, current.id, runId, vars, env, options, transitionsTaken);
             if (exitResult?.ok === false)
                 return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, exitResult.error);
             // 7. Persist transition and move to the target state.
@@ -66,13 +66,13 @@ export class StateMachineDriver {
             current = nextState;
         }
     }
-    async runActions(actions, workflowName, stateId, runId, vars, env, options) {
+    async runActions(actions, workflowName, stateId, runId, vars, env, options, transitionsTaken) {
         let last;
         for (const action of actions) {
             const resolved = resolveTemplates(action.options ?? {}, {
                 vars,
                 env,
-                builtins: { workflow: workflowName, state: stateId, runId },
+                builtins: runtimeBuiltins(workflowName, stateId, runId, transitionsTaken),
             });
             last = await this.options.host.runAction(action.kind, resolved, {
                 runId,
@@ -98,6 +98,19 @@ export class StateMachineDriver {
         return { runId, workflowName, mode, status: 'failed', finalState, transitionsTaken, reason };
     }
 }
+/** Built-in bare template values available to state-machine action options. */
+function runtimeBuiltins(workflowName, stateId, runId, transitionsTaken) {
+    return {
+        workflow: workflowName,
+        runId,
+        task: workflowName,
+        state: stateId,
+        node: stateId,
+        iteration: transitionsTaken,
+        run: runId,
+        runtime: 'state-machine',
+    };
+}
 async function firstPassingTransition(transitions, host, context) {
     for (const transition of transitions) {
         if (transition.guard === undefined)

package/dist/transition-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transition-flow.d.ts","sourceRoot":"","sources":["../src/transition-flow.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAER,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,EAElB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAGjB,2DAA2D;AAC3D,MAAM,WAAW,2BAA2B;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;CACpD;AAED,0EAA0E;AAC1E,qBAAa,oBAAoB;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,2BAA2B;IAEjE,+DAA+D;IACzD,GAAG,CAAC,QAAQ,EAAE,yBAAyB,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YA8F9F,IAAI;YAYJ,IAAI;CAYrB"}
+{"version":3,"file":"transition-flow.d.ts","sourceRoot":"","sources":["../src/transition-flow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAER,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,EAElB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAGjB,2DAA2D;AAC3D,MAAM,WAAW,2BAA2B;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;CACpD;AAED,0EAA0E;AAC1E,qBAAa,oBAAoB;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,2BAA2B;IAEjE,+DAA+D;IACzD,GAAG,CAAC,QAAQ,EAAE,yBAAyB,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YA8F9F,IAAI;YAYJ,IAAI;CAYrB"}

package/dist/transition-flow.js

@@ -1,4 +1,5 @@
 import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import { FSMError } from './errors.js';
 import { mergeVars, resolveTemplates } from './variables.js';
 /** Transition-flow workflow driver with an R7 single control function. */
 export class TransitionFlowDriver {
@@ -21,7 +22,7 @@ export class TransitionFlowDriver {
         let lastActionResult;
         const iterationBound = workflow.iterationBound ?? 50;
         if (current === undefined) {
-            throw new Error(`Initial node "${workflow.initialNode}" is not declared`);
+            throw new FSMError(`Initial node "${workflow.initialNode}" is not declared`);
         }
         while (true) {
             // 1. Persist current node snapshot before action execution.
@@ -32,7 +33,7 @@ export class TransitionFlowDriver {
                 const resolved = resolveTemplates(current.action.options ?? {}, {
                     vars,
                     env,
-                    builtins: { workflow: workflow.name, node: current.id, runId },
+                    builtins: runtimeBuiltins(workflow.name, current.id, runId, transitionsTaken),
                 });
                 lastActionResult = await this.options.host.runAction(current.action.kind, resolved, {
                     runId,
@@ -74,7 +75,7 @@ export class TransitionFlowDriver {
             // 7. Move to the target node and repeat.
             const nextNode = nodes.get(edge.to);
             if (nextNode === undefined)
-                throw new Error(`Edge target "${edge.to}" is not declared`);
+                throw new FSMError(`Edge target "${edge.to}" is not declared`);
             current = nextNode;
         }
     }
@@ -89,6 +90,19 @@ export class TransitionFlowDriver {
         return { runId, workflowName, mode, status: 'failed', finalState, transitionsTaken, reason };
     }
 }
+/** Built-in bare template values available to transition-flow action options. */
+function runtimeBuiltins(workflowName, nodeId, runId, transitionsTaken) {
+    return {
+        workflow: workflowName,
+        runId,
+        task: workflowName,
+        state: nodeId,
+        node: nodeId,
+        iteration: transitionsTaken,
+        run: runId,
+        runtime: 'transition-flow',
+    };
+}
 async function firstPassingEdge(edges, host, context) {
     for (const edge of edges) {
         if (edge.condition === undefined)