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

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,45 +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)

package/dist/types.d.ts

@@ -19,6 +19,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[];
 }
@@ -26,6 +28,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;
 }
@@ -33,6 +37,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;
@@ -44,6 +52,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;
 }
@@ -51,12 +61,18 @@ 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;
 }
 /** Transition-flow workflow definition. */
 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;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-dual-workflow-engine",
-    "version": "0.2.7",
+    "version": "0.2.9",
     "description": "@gobing-ai/ts-dual-workflow-engine — State-machine and transition-flow workflow runtime.",
     "keywords": [
         "typescript",
@@ -32,6 +32,7 @@
     },
     "files": [
         "dist",
+        "schemas",
         "src",
         "README.md"
     ],
@@ -47,9 +48,9 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-dual-workflow-engine-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-db": "^0.2.7",
-        "@gobing-ai/ts-runtime": "^0.2.7",
-        "yaml": "^2.7.0",
+        "@gobing-ai/ts-db": "^0.2.9",
+        "@gobing-ai/ts-runtime": "^0.2.9",
+        "@gobing-ai/ts-utils": "^0.2.9",
         "zod": "^4.1.0"
     },
     "devDependencies": {

package/schemas/state-machine-workflow.schema.json

@@ -0,0 +1,79 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://raw.githubusercontent.com/gobing-ai/ts-libs/main/packages/dual-workflow-engine/schemas/state-machine-workflow.schema.json",
+    "title": "@gobing-ai/ts-dual-workflow-engine State-machine Workflow",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["name", "initialState", "states", "transitions"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "kind": { "const": "state-machine" },
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string" },
+        "description": { "type": "string" },
+        "initialState": { "type": "string", "minLength": 1 },
+        "terminalStates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "iterationBound": { "type": "integer", "exclusiveMinimum": 0 },
+        "vars": {
+            "type": "object",
+            "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+            "additionalProperties": { "type": "string" }
+        },
+        "env": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "allow": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } }
+            }
+        },
+        "states": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id"],
+                "properties": {
+                    "id": { "type": "string", "minLength": 1 },
+                    "description": { "type": "string" },
+                    "onEnter": { "type": "array", "items": { "$ref": "#/$defs/action" } },
+                    "onExit": { "type": "array", "items": { "$ref": "#/$defs/action" } }
+                }
+            }
+        },
+        "transitions": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["from", "to"],
+                "properties": {
+                    "from": { "type": "string", "minLength": 1 },
+                    "to": { "type": "string", "minLength": 1 },
+                    "description": { "type": "string" },
+                    "trigger": { "type": "string" },
+                    "guard": { "$ref": "#/$defs/guard" }
+                }
+            }
+        }
+    },
+    "$defs": {
+        "action": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        },
+        "guard": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        }
+    }
+}

package/schemas/transition-flow-workflow.schema.json

@@ -0,0 +1,78 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://raw.githubusercontent.com/gobing-ai/ts-libs/main/packages/dual-workflow-engine/schemas/transition-flow-workflow.schema.json",
+    "title": "@gobing-ai/ts-dual-workflow-engine Transition-flow Workflow",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["kind", "name", "initialNode", "nodes", "edges"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "kind": { "const": "transition-flow" },
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string" },
+        "description": { "type": "string" },
+        "initialNode": { "type": "string", "minLength": 1 },
+        "terminalNodes": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "iterationBound": { "type": "integer", "exclusiveMinimum": 0 },
+        "vars": {
+            "type": "object",
+            "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+            "additionalProperties": { "type": "string" }
+        },
+        "env": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "allow": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } }
+            }
+        },
+        "nodes": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id"],
+                "properties": {
+                    "id": { "type": "string", "minLength": 1 },
+                    "description": { "type": "string" },
+                    "type": { "enum": ["action", "gate", "parallel", "decision"] },
+                    "action": { "$ref": "#/$defs/action" }
+                }
+            }
+        },
+        "edges": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["from", "to"],
+                "properties": {
+                    "from": { "type": "string", "minLength": 1 },
+                    "to": { "type": "string", "minLength": 1 },
+                    "description": { "type": "string" },
+                    "condition": { "$ref": "#/$defs/guard" }
+                }
+            }
+        }
+    },
+    "$defs": {
+        "action": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        },
+        "guard": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        }
+    }
+}