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

package/README.md

@@ -1,4 +1,278 @@
 # @gobing-ai/ts-dual-workflow-engine
 
-Standalone workflow runtime for state-machine and transition-flow workflows. The package owns workflow definitions, validation schemas, variable resolution, action execution, persistence schema, and driver loops.
+State-machine and transition-flow workflow runtime with pluggable action runners, guard runners, and memory or database persistence.
 
+## What It Provides
+
+`ts-dual-workflow-engine` runs declarative workflows in two execution modes:
+
+| Mode | Use When |
+|------|----------|
+| `state-machine` | A run owns one current state and chooses the next state by evaluating ordered transition guards |
+| `transition-flow` | A run moves through nodes and edges in a DAG-like flow, executing node actions as it advances |
+
+The package exposes:
+
+| Export | Purpose |
+|--------|---------|
+| `WorkflowService` | High-level loader and runner for both workflow kinds |
+| `StateMachineDriver` | Direct state-machine execution |
+| `TransitionFlowDriver` | Direct transition-flow execution |
+| `WorkflowEngineHost` | Registry for action runners and guard runners |
+| `MemoryWorkflowPersistenceAdapter` | In-memory persistence for tests and short-lived runs |
+| `DbWorkflowPersistenceAdapter` | DB-backed persistence over `@gobing-ai/ts-db` |
+| `loadWorkflowDef()` / `loadWorkflowDefFromText()` | YAML workflow loading and validation |
+| `applyWorkflowEngineSchema()` | Installs the package-owned DB schema |
+
+## Installation
+
+```bash
+bun add @gobing-ai/ts-dual-workflow-engine @gobing-ai/ts-db
+```
+
+Use `@gobing-ai/ts-db` only when you need durable workflow history. Memory persistence has no database requirement.
+
+## State Machine Example
+
+```ts
+import {
+    MemoryWorkflowPersistenceAdapter,
+    StateMachineDriver,
+    WorkflowEngineHost,
+    type ActionRunner,
+} from '@gobing-ai/ts-dual-workflow-engine';
+
+const captureAction: ActionRunner & { seen: string[] } = {
+    kind: 'capture',
+    seen: [],
+    async execute(options) {
+        this.seen.push(String(options.message ?? ''));
+        return { ok: true };
+    },
+};
+
+const host = new WorkflowEngineHost()
+    .registerAction(captureAction)
+    .registerGuard({ kind: 'always', evaluate: async () => true });
+
+const driver = new StateMachineDriver({
+    host,
+    persistence: new MemoryWorkflowPersistenceAdapter(),
+});
+
+const result = await driver.run(
+    {
+        name: 'approval',
+        initialState: 'draft',
+        terminalStates: ['done'],
+        vars: { message: 'approved' },
+        states: [
+            { id: 'draft', onEnter: [{ kind: 'capture', options: { message: '${vars.message}' } }] },
+            { id: 'done' },
+        ],
+        transitions: [{ from: 'draft', to: 'done', guard: { kind: 'always' } }],
+    },
+    { runId: 'approval-1' },
+);
+
+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.
+
+## Transition Flow Example
+
+```ts
+import {
+    createDefaultWorkflowEngineHost,
+    MemoryWorkflowPersistenceAdapter,
+    WorkflowService,
+} from '@gobing-ai/ts-dual-workflow-engine';
+
+const service = new WorkflowService(
+    createDefaultWorkflowEngineHost(),
+    new MemoryWorkflowPersistenceAdapter(),
+);
+
+const result = await service.run({
+    kind: 'transition-flow',
+    name: 'linear-flow',
+    initialNode: 'start',
+    terminalNodes: ['done'],
+    nodes: [
+        { id: 'start', action: { kind: 'note', options: { message: 'started' } } },
+        { id: 'done' },
+    ],
+    edges: [{ from: 'start', to: 'done' }],
+});
+
+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.
+
+## Load Workflows from YAML
+
+```ts
+import { loadWorkflowDef, WorkflowService } from '@gobing-ai/ts-dual-workflow-engine';
+
+const workflow = await loadWorkflowDef('./workflows/approval.yaml');
+await service.run(workflow, { runId: 'approval-1' });
+```
+
+`loadWorkflowDef(path)` reads YAML or JSON from disk. File loads honor a top-level `$schema` ref by default, then validate the internal structural schema and semantic references before returning a `WorkflowDef`. The `$schema` value resolves from the bundled package schema (shipped under `node_modules/@gobing-ai/ts-dual-workflow-engine/schemas/`) — no network access; quote the value, since YAML treats a leading `@` as reserved. Relative paths and (opt-in) remote URLs also work; see `@gobing-ai/ts-runtime` → *Structured config*. `loadWorkflowDefFromText(text, source)` handles inline definitions with internal validation only.
+
+### State-machine YAML
+
+`kind: state-machine` is optional because state-machine is the default shape, but including it makes the file easier to scan.
+
+```yaml
+# workflows/approval.yaml
+$schema: "@gobing-ai/ts-dual-workflow-engine/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: approval
+initialState: draft
+terminalStates: [done]
+vars:
+  reviewer: robin
+env:
+  allow: [APP_ENV]
+states:
+  - id: draft
+    onEnter:
+      - kind: note
+        options:
+          message: "review requested by ${vars.reviewer} in ${env.APP_ENV}"
+  - id: approved
+    onEnter:
+      - kind: note
+        options:
+          message: approved
+  - id: done
+transitions:
+  - from: draft
+    to: approved
+    guard:
+      kind: always
+  - from: approved
+    to: done
+```
+
+```ts
+import {
+    createDefaultWorkflowEngineHost,
+    loadWorkflowDef,
+    MemoryWorkflowPersistenceAdapter,
+    WorkflowService,
+} from '@gobing-ai/ts-dual-workflow-engine';
+
+const service = new WorkflowService(
+    createDefaultWorkflowEngineHost(),
+    new MemoryWorkflowPersistenceAdapter(),
+);
+
+const workflow = await loadWorkflowDef('./workflows/approval.yaml');
+const result = await service.run(workflow, {
+    runId: 'approval-1',
+    env: { APP_ENV: 'development' },
+});
+```
+
+### Transition-flow YAML
+
+Transition-flow definitions must declare `kind: transition-flow`.
+
+```yaml
+# workflows/import-file.yaml
+$schema: "@gobing-ai/ts-dual-workflow-engine/schemas/transition-flow-workflow.schema.json"
+kind: transition-flow
+name: import-file
+initialNode: read
+terminalNodes: [done]
+vars:
+  file: events.jsonl
+nodes:
+  - id: read
+    type: action
+    action:
+      kind: note
+      options:
+        message: "reading ${vars.file}"
+  - id: validate
+    type: gate
+  - id: done
+edges:
+  - from: read
+    to: validate
+  - from: validate
+    to: done
+    condition:
+      kind: always
+```
+
+```ts
+const workflow = await loadWorkflowDef('./workflows/import-file.yaml');
+const result = await service.run(workflow, {
+    runId: 'import-1',
+    vars: { file: 'override.jsonl' },
+});
+```
+
+`validateWorkflowDef()` is available when the caller already has an object and only needs validation.
+
+## Variables and Environment
+
+Actions receive resolved template values. The engine supports:
+
+| Template | Source |
+|----------|--------|
+| `${vars.name}` | Workflow vars merged with run vars |
+| `${env.NAME}` | Environment values explicitly allowed by workflow config |
+| `${runId}` | Current run ID |
+| `${workflow}` | Workflow name |
+| `${state}` | Current state or node ID |
+
+```ts
+await service.run(workflow, {
+    vars: { file: 'events.jsonl' },
+    env: { API_TOKEN: process.env.API_TOKEN },
+    metadata: { requestedBy: 'scheduler' },
+});
+```
+
+The workflow definition controls which environment names are visible through `env.allow`.
+
+## DB Persistence
+
+```ts
+import { createDbAdapter } from '@gobing-ai/ts-db';
+import {
+    applyWorkflowEngineSchema,
+    createDefaultWorkflowEngineHost,
+    DbWorkflowPersistenceAdapter,
+    WorkflowService,
+} from '@gobing-ai/ts-dual-workflow-engine';
+
+const db = await createDbAdapter({ driver: 'bun-sqlite', url: './workflow.db' });
+await applyWorkflowEngineSchema(db);
+
+const service = new WorkflowService(
+    createDefaultWorkflowEngineHost(),
+    new DbWorkflowPersistenceAdapter(db),
+);
+```
+
+Use `service.listRuns()` to read persisted run records. The adapter stores run status, phase snapshots, state snapshots, and transitions.
+
+## Error Handling
+
+Validation failures throw `WorkflowValidationError`. Runtime finite-state-machine errors throw `FSMError`. Run failures caused by actions or guards are returned as `WorkflowRunResult` with `status: 'failed'`, preserving the run record.
+
+## Boundary Notes
+
+- The engine executes workflows; it does not provide a scheduler. Use `@gobing-ai/ts-infra` scheduler or an external cron trigger to start runs.
+- Persistence is adapter-based. Downstream apps own DB lifecycle and migration ordering.
+- Action and guard runners are the extension points. Keep domain behavior there, not in workflow parsing.

package/dist/config.d.ts

@@ -1,8 +1,14 @@
 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 declare function loadWorkflowDefFromText(text: string, source?: string): WorkflowDef;
 /** Load a workflow definition from a filesystem path. */
-export declare function loadWorkflowDef(path: string): Promise<WorkflowDef>;
+export declare function loadWorkflowDef(path: string, options?: WorkflowLoadOptions): Promise<WorkflowDef>;
 /** Validate semantic workflow invariants beyond structural Zod checks. */
 export declare function validateWorkflowDef(workflow: WorkflowDef): void;
 //# sourceMappingURL=config.d.ts.map

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,yDAAyD;AACzD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,WAAW,CAWtF;AAED,yDAAyD;AACzD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAExE;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,20 +1,14 @@
-import { getFs } 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 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);
-    return result.data;
+    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) {
-    return loadWorkflowDefFromText(await getFs().readFile(path), path);
+export async function loadWorkflowDef(path, options = {}) {
+    return parseWorkflowDef(await loadStructuredConfig(path, options), path);
 }
 /** Validate semantic workflow invariants beyond structural Zod checks. */
 export function validateWorkflowDef(workflow) {
@@ -26,26 +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 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`);
+function parseWorkflowDef(parsed, source) {
+    // 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);
+    return result.data;
+}
+/** 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

@@ -11,8 +11,11 @@ export declare const GuardDefSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Zod schema for state-machine workflow definitions. */
 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>;
@@ -22,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>>;
@@ -30,21 +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>;
@@ -54,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";
@@ -64,20 +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>;
@@ -87,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>>;
@@ -95,19 +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>;
@@ -117,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";
@@ -127,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuBxC,CAAC;AAEH,2DAA2D;AAC3D,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsB1C,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"}