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

package/README.md

@@ -1,4 +1,274 @@
 # @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 = {
+    kind: 'capture',
+    async execute(options) {
+        console.log(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' },
+);
+
+console.log(result.status, result.finalState);
+```
+
+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' }],
+});
+
+console.log(result);
+```
+
+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":"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"}

package/dist/config.js

@@ -1,20 +1,15 @@
-import { getFs } from '@gobing-ai/ts-runtime';
+import { loadStructuredConfig } from '@gobing-ai/ts-runtime';
 import { parse } from 'yaml';
 import { WorkflowValidationError } from './errors.js';
 import { WorkflowDefSchema } 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;
+    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) {
@@ -37,6 +32,14 @@ function validateStateMachine(workflow) {
             throw new WorkflowValidationError(`Transition target "${transition.to}" is not declared`);
     }
 }
+function parseWorkflowDef(parsed, source) {
+    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;
+}
 function validateTransitionFlow(workflow) {
     const nodes = new Set(workflow.nodes.map((node) => node.id));
     if (!nodes.has(workflow.initialNode)) {

package/dist/schema.d.ts

@@ -11,6 +11,7 @@ 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;
     initialState: z.ZodString;
@@ -43,6 +44,7 @@ export declare const StateMachineWorkflowDefSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** 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;
     initialNode: z.ZodString;
@@ -76,6 +78,7 @@ export declare const TransitionFlowWorkflowDefSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** 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;
     initialState: z.ZodString;
@@ -106,6 +109,7 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
     kind: z.ZodLiteral<"transition-flow">;
     name: z.ZodString;
     initialNode: z.ZodString;

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;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"}

package/dist/schema.js

@@ -11,6 +11,7 @@ export const GuardDefSchema = z.object({
 });
 /** Zod schema for state-machine workflow definitions. */
 export const StateMachineWorkflowDefSchema = z.object({
+    $schema: z.string().optional(),
     kind: z.literal('state-machine').optional(),
     name: z.string().min(1),
     initialState: z.string().min(1),
@@ -32,6 +33,7 @@ export const StateMachineWorkflowDefSchema = z.object({
 });
 /** Zod schema for transition-flow workflow definitions. */
 export const TransitionFlowWorkflowDefSchema = z.object({
+    $schema: z.string().optional(),
     kind: z.literal('transition-flow'),
     name: z.string().min(1),
     initialNode: z.string().min(1),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-dual-workflow-engine",
-    "version": "0.2.6",
+    "version": "0.2.8",
     "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,8 +48,8 @@
         "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.6",
-        "@gobing-ai/ts-runtime": "^0.2.6",
+        "@gobing-ai/ts-db": "^0.2.8",
+        "@gobing-ai/ts-runtime": "^0.2.8",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },

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

@@ -0,0 +1,71 @@
+{
+    "$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" },
+        "initialState": { "type": "string" },
+        "terminalStates": { "type": "array", "items": { "type": "string" } },
+        "iterationBound": { "type": "integer" },
+        "vars": { "type": "object", "additionalProperties": { "type": "string" } },
+        "env": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "allow": { "type": "array", "items": { "type": "string" } }
+            }
+        },
+        "states": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id"],
+                "properties": {
+                    "id": { "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" },
+                    "to": { "type": "string" },
+                    "trigger": { "type": "string" },
+                    "guard": { "$ref": "#/$defs/guard" }
+                }
+            }
+        }
+    },
+    "$defs": {
+        "action": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string" },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        },
+        "guard": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string" },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,70 @@
+{
+    "$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" },
+        "initialNode": { "type": "string" },
+        "terminalNodes": { "type": "array", "items": { "type": "string" } },
+        "iterationBound": { "type": "integer" },
+        "vars": { "type": "object", "additionalProperties": { "type": "string" } },
+        "env": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "allow": { "type": "array", "items": { "type": "string" } }
+            }
+        },
+        "nodes": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id"],
+                "properties": {
+                    "id": { "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" },
+                    "to": { "type": "string" },
+                    "condition": { "$ref": "#/$defs/guard" }
+                }
+            }
+        }
+    },
+    "$defs": {
+        "action": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string" },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        },
+        "guard": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string" },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        }
+    }
+}

package/src/config.ts

@@ -1,26 +1,25 @@
-import { getFs } from '@gobing-ai/ts-runtime';
+import { loadStructuredConfig } from '@gobing-ai/ts-runtime';
 import { parse } from 'yaml';
 import { WorkflowValidationError } from './errors';
 import { WorkflowDefSchema } 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;
+    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. */
@@ -45,6 +44,18 @@ function validateStateMachine(workflow: Extract<WorkflowDef, { kind?: 'state-mac
     }
 }
 
+function parseWorkflowDef(parsed: unknown, source: string): WorkflowDef {
+    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;
+}
+
 function validateTransitionFlow(workflow: Extract<WorkflowDef, { kind: 'transition-flow' }>): void {
     const nodes = new Set(workflow.nodes.map((node) => node.id));
     if (!nodes.has(workflow.initialNode)) {

package/src/schema.ts

@@ -14,6 +14,7 @@ export const GuardDefSchema = z.object({
 
 /** Zod schema for state-machine workflow definitions. */
 export const StateMachineWorkflowDefSchema = z.object({
+    $schema: z.string().optional(),
     kind: z.literal('state-machine').optional(),
     name: z.string().min(1),
     initialState: z.string().min(1),
@@ -40,6 +41,7 @@ export const StateMachineWorkflowDefSchema = z.object({
 
 /** Zod schema for transition-flow workflow definitions. */
 export const TransitionFlowWorkflowDefSchema = z.object({
+    $schema: z.string().optional(),
     kind: z.literal('transition-flow'),
     name: z.string().min(1),
     initialNode: z.string().min(1),