@gobing-ai/ts-dual-workflow-engine 0.2.7 → 0.2.9

package/src/config.ts

@@ -1,26 +1,24 @@
-import { getFs } from '@gobing-ai/ts-runtime';
-import { parse } from 'yaml';
+import { loadStructuredConfig, parseYamlObject } from '@gobing-ai/ts-runtime';
 import { WorkflowValidationError } from './errors';
-import { WorkflowDefSchema } from './schema';
+import { StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema } from './schema';
 import type { WorkflowDef } from './types';
 
+export interface WorkflowLoadOptions {
+    /** When true, honor a top-level `$schema` ref. Defaults to true for file loads. */
+    validateSchema?: boolean;
+    /** Optional fetch implementation for remote HTTP(S) schema refs. */
+    fetch?: (input: string) => Promise<Response>;
+}
+
 /** Load a workflow definition from YAML or JSON text. */
 export function loadWorkflowDefFromText(text: string, source = '<inline>'): WorkflowDef {
-    const parsed = source.endsWith('.json') ? JSON.parse(text) : parse(text);
-    const result = WorkflowDefSchema.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,
-        );
-    }
-    validateWorkflowDef(result.data as WorkflowDef);
-    return result.data as WorkflowDef;
+    const parsed = source.endsWith('.json') ? JSON.parse(text) : parseYamlObject(text);
+    return parseWorkflowDef(parsed, source);
 }
 
 /** Load a workflow definition from a filesystem path. */
-export async function loadWorkflowDef(path: string): Promise<WorkflowDef> {
-    return loadWorkflowDefFromText(await getFs().readFile(path), path);
+export async function loadWorkflowDef(path: string, options: WorkflowLoadOptions = {}): Promise<WorkflowDef> {
+    return parseWorkflowDef(await loadStructuredConfig(path, options), path);
 }
 
 /** Validate semantic workflow invariants beyond structural Zod checks. */
@@ -33,25 +31,203 @@ export function validateWorkflowDef(workflow: WorkflowDef): void {
 }
 
 function validateStateMachine(workflow: Extract<WorkflowDef, { kind?: 'state-machine' }>): void {
-    const states = new Set(workflow.states.map((state) => state.id));
+    const errors: string[] = [];
+    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`);
     }
+
+    // Transition endpoints must be declared.
+    type Transition = (typeof workflow.transitions)[number];
+    const outboundByState = new Map<string, Transition[]>();
     for (const transition of workflow.transitions) {
-        if (!states.has(transition.from))
-            throw new WorkflowValidationError(`Transition source "${transition.from}" is not declared`);
-        if (!states.has(transition.to))
-            throw new WorkflowValidationError(`Transition target "${transition.to}" is not declared`);
+        if (!states.has(transition.from)) errors.push(`Transition source "${transition.from}" is not declared`);
+        if (!states.has(transition.to)) 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 validateTransitionFlow(workflow: Extract<WorkflowDef, { kind: 'transition-flow' }>): void {
-    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`);
+function parseWorkflowDef(parsed: unknown, source: string): WorkflowDef {
+    // 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}: ${formatWorkflowIssues(result.error.issues)}`,
+            result.error.issues,
+        );
     }
+    validateWorkflowDef(result.data as WorkflowDef);
+    return result.data as WorkflowDef;
+}
+
+/** Pick the dialect schema by the shape of the input so diagnostics are field-precise. */
+function selectWorkflowSchema(
+    parsed: unknown,
+): typeof StateMachineWorkflowDefSchema | typeof TransitionFlowWorkflowDefSchema {
+    if (parsed !== null && typeof parsed === 'object') {
+        const value = parsed as Record<string, unknown>;
+        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: readonly { path: PropertyKey[]; message: string }[]): string {
+    return issues
+        .map((issue) => {
+            const path = issue.path.map(String).join('.');
+            return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+        })
+        .join('; ');
+}
+
+function validateTransitionFlow(workflow: Extract<WorkflowDef, { kind: 'transition-flow' }>): void {
+    const errors: string[] = [];
+    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<string>();
     for (const edge of workflow.edges) {
-        if (!nodes.has(edge.from)) throw new WorkflowValidationError(`Edge source "${edge.from}" is not declared`);
-        if (!nodes.has(edge.to)) throw new WorkflowValidationError(`Edge target "${edge.to}" is not declared`);
+        if (!nodes.has(edge.from)) errors.push(`Edge source "${edge.from}" is not declared`);
+        if (!nodes.has(edge.to)) 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: readonly string[]): string[] {
+    const seen = new Set<string>();
+    const dupes = new Set<string>();
+    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: WorkflowDef): Record<string, unknown>[] {
+    const optionSets: Record<string, unknown>[] = [];
+    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: readonly Record<string, unknown>[],
+    vars: Record<string, string> | undefined,
+    env: { allow?: readonly string[] } | undefined,
+): string[] {
+    const declaredVars = new Set(Object.keys(vars ?? {}));
+    const allowedEnv = new Set(env?.allow ?? []);
+    const errors: string[] = [];
+    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: WorkflowDef, errors: readonly string[]): void {
+    if (errors.length > 0) {
+        throw new WorkflowValidationError(`Workflow "${workflow.name}" is invalid: ${errors.join('; ')}`, errors);
     }
 }

package/src/schema.ts

@@ -1,5 +1,28 @@
 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),
@@ -13,55 +36,79 @@ export const GuardDefSchema = z.object({
 });
 
 /** Zod schema for state-machine workflow definitions. */
-export const StateMachineWorkflowDefSchema = z.object({
-    kind: z.literal('state-machine').optional(),
-    name: z.string().min(1),
-    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({
-            id: z.string().min(1),
-            onEnter: z.array(ActionDefSchema).optional(),
-            onExit: z.array(ActionDefSchema).optional(),
-        }),
-    ),
-    transitions: z.array(
-        z.object({
-            from: z.string().min(1),
-            to: z.string().min(1),
-            trigger: z.string().optional(),
-            guard: GuardDefSchema.optional(),
-        }),
-    ),
-});
+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: 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(),
+                })
+                .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({
-    kind: z.literal('transition-flow'),
-    name: z.string().min(1),
-    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({
-            id: z.string().min(1),
-            type: z.enum(['action', 'gate', 'parallel', 'decision']).optional(),
-            action: ActionDefSchema.optional(),
-        }),
-    ),
-    edges: z.array(
-        z.object({
-            from: z.string().min(1),
-            to: z.string().min(1),
-            condition: GuardDefSchema.optional(),
-        }),
-    ),
-});
+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: 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(),
+                })
+                .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/src/state-machine.ts

@@ -54,6 +54,7 @@ export class StateMachineDriver {
                 vars,
                 env,
                 options,
+                transitionsTaken,
             );
             if (lastActionResult?.ok === false)
                 return await this.fail(
@@ -103,6 +104,7 @@ export class StateMachineDriver {
                 vars,
                 env,
                 options,
+                transitionsTaken,
             );
             if (exitResult?.ok === false)
                 return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, exitResult.error);
@@ -139,13 +141,14 @@ export class StateMachineDriver {
         vars: Record<string, string>,
         env: Record<string, string>,
         options: WorkflowRunOptions,
+        transitionsTaken: number,
     ): Promise<ActionResult | undefined> {
         let last: ActionResult | undefined;
         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,
@@ -186,6 +189,25 @@ export class StateMachineDriver {
     }
 }
 
+/** Built-in bare template values available to state-machine action options. */
+function runtimeBuiltins(
+    workflowName: string,
+    stateId: string,
+    runId: string,
+    transitionsTaken: number,
+): Record<string, string | number> {
+    return {
+        workflow: workflowName,
+        runId,
+        task: workflowName,
+        state: stateId,
+        node: stateId,
+        iteration: transitionsTaken,
+        run: runId,
+        runtime: 'state-machine',
+    };
+}
+
 async function firstPassingTransition(
     transitions: StateMachineWorkflowDef['transitions'],
     host: WorkflowEngineHost,

package/src/transition-flow.ts

@@ -1,4 +1,5 @@
 import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import { FSMError } from './errors';
 import type { WorkflowEngineHost } from './host';
 import type {
     ActionResult,
@@ -37,7 +38,7 @@ export class TransitionFlowDriver {
         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) {
@@ -50,7 +51,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,
@@ -110,7 +111,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`);
+            if (nextNode === undefined) throw new FSMError(`Edge target "${edge.to}" is not declared`);
             current = nextNode;
         }
     }
@@ -141,6 +142,25 @@ export class TransitionFlowDriver {
     }
 }
 
+/** Built-in bare template values available to transition-flow action options. */
+function runtimeBuiltins(
+    workflowName: string,
+    nodeId: string,
+    runId: string,
+    transitionsTaken: number,
+): Record<string, string | number> {
+    return {
+        workflow: workflowName,
+        runId,
+        task: workflowName,
+        state: nodeId,
+        node: nodeId,
+        iteration: transitionsTaken,
+        run: runId,
+        runtime: 'transition-flow',
+    };
+}
+
 async function firstPassingEdge(
     edges: TransitionFlowWorkflowDef['edges'],
     host: WorkflowEngineHost,

package/src/types.ts

@@ -24,6 +24,8 @@ export interface GuardDef {
 /** One state in a state-machine workflow. */
 export interface StateDef {
     readonly id: string;
+    /** Optional human description of what this state does. */
+    readonly description?: string;
     readonly onEnter?: readonly ActionDef[];
     readonly onExit?: readonly ActionDef[];
 }
@@ -32,6 +34,8 @@ export interface StateDef {
 export interface TransitionDef {
     readonly from: string;
     readonly to: string;
+    /** Optional human description of when/why this transition is taken. */
+    readonly description?: string;
     readonly trigger?: string;
     readonly guard?: GuardDef;
 }
@@ -40,6 +44,10 @@ export interface TransitionDef {
 export interface StateMachineWorkflowDef {
     readonly kind?: 'state-machine';
     readonly name: string;
+    /** Optional behavior-free document version tag. */
+    readonly version?: string;
+    /** Optional human description of the workflow's purpose. */
+    readonly description?: string;
     readonly initialState: string;
     readonly terminalStates?: readonly string[];
     readonly iterationBound?: number;
@@ -52,6 +60,8 @@ export interface StateMachineWorkflowDef {
 /** Transition-flow node definition. */
 export interface FlowNodeDef {
     readonly id: string;
+    /** Optional human description of what this node does. */
+    readonly description?: string;
     readonly type?: 'action' | 'gate' | 'parallel' | 'decision';
     readonly action?: ActionDef;
 }
@@ -60,6 +70,8 @@ export interface FlowNodeDef {
 export interface FlowEdgeDef {
     readonly from: string;
     readonly to: string;
+    /** Optional human description of when/why this edge is taken. */
+    readonly description?: string;
     readonly condition?: GuardDef;
 }
 
@@ -67,6 +79,10 @@ export interface FlowEdgeDef {
 export interface TransitionFlowWorkflowDef {
     readonly kind: 'transition-flow';
     readonly name: string;
+    /** Optional behavior-free document version tag. */
+    readonly version?: string;
+    /** Optional human description of the workflow's purpose. */
+    readonly description?: string;
     readonly initialNode: string;
     readonly terminalNodes?: readonly string[];
     readonly iterationBound?: number;