@gobing-ai/ts-dual-workflow-engine 0.2.1

package/dist/schema.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+/** Zod schema for workflow action definitions. */
+export const ActionDefSchema = z.object({
+    kind: z.string().min(1),
+    options: z.record(z.string(), z.unknown()).optional(),
+});
+/** Zod schema for workflow guard definitions. */
+export const GuardDefSchema = z.object({
+    kind: z.string().min(1),
+    options: z.record(z.string(), z.unknown()).optional(),
+});
+/** 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(),
+    })),
+});
+/** 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(),
+    })),
+});
+/** Zod schema for either supported workflow definition shape. */
+export const WorkflowDefSchema = z.union([StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema]);

package/dist/service.d.ts

@@ -0,0 +1,17 @@
+import type { WorkflowEngineHost } from './host';
+import type { WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunResult } from './types';
+/** High-level workflow service for loading, running, and listing persisted workflow runs. */
+export declare class WorkflowService {
+    private readonly host;
+    private readonly persistence;
+    constructor(host: WorkflowEngineHost, persistence: WorkflowPersistenceAdapter);
+    /** Load a workflow file and validate it. */
+    load(path: string): Promise<WorkflowDef>;
+    /** Run an already-loaded workflow definition. */
+    run(workflow: WorkflowDef, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    /** Load and run a workflow file. */
+    runFile(path: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    /** List persisted workflow runs. */
+    listRuns(): Promise<readonly import("./types").WorkflowRunRecord[]>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE9G,6FAA6F;AAC7F,qBAAa,eAAe;IAEpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,IAAI,EAAE,kBAAkB,EACxB,WAAW,EAAE,0BAA0B;IAG5D,4CAA4C;IACtC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI9C,iDAAiD;IAC3C,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAU9F,oCAAoC;IAC9B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzF,oCAAoC;IAC9B,QAAQ;CAGjB"}

package/dist/service.js

@@ -0,0 +1,31 @@
+import { loadWorkflowDef } from './config.js';
+import { StateMachineDriver } from './state-machine.js';
+import { TransitionFlowDriver } from './transition-flow.js';
+/** High-level workflow service for loading, running, and listing persisted workflow runs. */
+export class WorkflowService {
+    host;
+    persistence;
+    constructor(host, persistence) {
+        this.host = host;
+        this.persistence = persistence;
+    }
+    /** Load a workflow file and validate it. */
+    async load(path) {
+        return await loadWorkflowDef(path);
+    }
+    /** Run an already-loaded workflow definition. */
+    async run(workflow, options = {}) {
+        if (workflow.kind === 'transition-flow') {
+            return await new TransitionFlowDriver({ host: this.host, persistence: this.persistence }).run(workflow, options);
+        }
+        return await new StateMachineDriver({ host: this.host, persistence: this.persistence }).run(workflow, options);
+    }
+    /** Load and run a workflow file. */
+    async runFile(path, options = {}) {
+        return await this.run(await this.load(path), options);
+    }
+    /** List persisted workflow runs. */
+    async listRuns() {
+        return await this.persistence.listRuns();
+    }
+}

package/dist/state-machine.d.ts

@@ -0,0 +1,18 @@
+import type { WorkflowEngineHost } from './host';
+import type { StateMachineWorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunResult } from './types';
+/** Dependencies required by the state-machine driver. */
+export interface StateMachineDriverOptions {
+    readonly host: WorkflowEngineHost;
+    readonly persistence: WorkflowPersistenceAdapter;
+}
+/** State-machine workflow driver with an R7 single control function. */
+export declare class StateMachineDriver {
+    private readonly options;
+    constructor(options: StateMachineDriverOptions);
+    /** Run a state-machine workflow to completion or failure. */
+    run(workflow: StateMachineWorkflowDef, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    private runActions;
+    private done;
+    private fail;
+}
+//# sourceMappingURL=state-machine.d.ts.map

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

@@ -0,0 +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"}

package/dist/state-machine.js

@@ -0,0 +1,123 @@
+import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import { FSMError } from './errors.js';
+import { mergeVars, resolveTemplates } from './variables.js';
+/** State-machine workflow driver with an R7 single control function. */
+export class StateMachineDriver {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Run a state-machine workflow to completion or failure. */
+    async run(workflow, options = {}) {
+        const runId = options.runId ?? crypto.randomUUID();
+        const startedAt = new Date().toISOString();
+        const mode = 'state-machine';
+        await this.options.persistence.createRun(runRecord(runId, workflow.name, mode, startedAt, options.metadata));
+        const states = new Map(workflow.states.map((state) => [state.id, state]));
+        const terminal = new Set(workflow.terminalStates ?? []);
+        const vars = mergeVars(workflow.vars, options.vars);
+        const env = allowedEnv(workflow.env?.allow ?? [], options.env ?? getProcessEnv());
+        let current = states.get(workflow.initialState);
+        let transitionsTaken = 0;
+        let lastActionResult;
+        const iterationBound = workflow.iterationBound ?? 50;
+        if (current === undefined)
+            throw new FSMError(`Initial state "${workflow.initialState}" is not declared`);
+        while (true) {
+            // 1. Persist current state snapshot before work starts.
+            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);
+            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.
+            if (lastActionResult?.terminal === true) {
+                return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+            }
+            // 4. Stop when the current state is terminal or has no outbound transitions.
+            const outbound = workflow.transitions.filter((transition) => transition.from === current?.id);
+            if (terminal.has(current.id) || outbound.length === 0) {
+                return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+            }
+            // 5. Evaluate transition guards in declaration order and pick the first passing transition.
+            const nextTransition = await firstPassingTransition(outbound, this.options.host, {
+                runId,
+                current: current.id,
+                vars,
+                lastActionResult,
+            });
+            if (nextTransition === undefined) {
+                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);
+            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.
+            transitionsTaken += 1;
+            await this.options.persistence.saveTransition(runId, current.id, nextTransition.to, nextTransition.trigger ?? null);
+            if (transitionsTaken > iterationBound) {
+                return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, 'iteration-bound-exceeded');
+            }
+            const nextState = states.get(nextTransition.to);
+            if (nextState === undefined)
+                throw new FSMError(`Transition target "${nextTransition.to}" is not declared`);
+            current = nextState;
+        }
+    }
+    async runActions(actions, workflowName, stateId, runId, vars, env, options) {
+        let last;
+        for (const action of actions) {
+            const resolved = resolveTemplates(action.options ?? {}, {
+                vars,
+                env,
+                builtins: { workflow: workflowName, state: stateId, runId },
+            });
+            last = await this.options.host.runAction(action.kind, resolved, {
+                runId,
+                workdir: options.workdir,
+                stateOrNodeId: stateId,
+                vars,
+                env,
+                metadata: options.metadata,
+            });
+            if (!last.ok || last.terminal === true)
+                return last;
+        }
+        return last;
+    }
+    async done(runId, workflowName, mode, finalState, transitionsTaken) {
+        await this.options.persistence.savePhase(runId, finalState, 'done');
+        await this.options.persistence.finalizeRun(runId, 'done', new Date().toISOString());
+        return { runId, workflowName, mode, status: 'done', finalState, transitionsTaken };
+    }
+    async fail(runId, workflowName, mode, finalState, transitionsTaken, reason = 'failed') {
+        await this.options.persistence.savePhase(runId, finalState, 'failed');
+        await this.options.persistence.finalizeRun(runId, 'failed', new Date().toISOString());
+        return { runId, workflowName, mode, status: 'failed', finalState, transitionsTaken, reason };
+    }
+}
+async function firstPassingTransition(transitions, host, context) {
+    for (const transition of transitions) {
+        if (transition.guard === undefined)
+            return transition;
+        if (await host.evaluateGuard(transition.guard.kind, transition.guard.options ?? {}, context))
+            return transition;
+    }
+    return undefined;
+}
+function allowedEnv(names, source) {
+    return Object.fromEntries(names.flatMap((name) => (source[name] === undefined ? [] : [[name, source[name]]])));
+}
+function runRecord(runId, workflowName, mode, startedAt, metadata) {
+    return {
+        id: runId,
+        workflow_name: workflowName,
+        mode,
+        status: 'running',
+        started_at: startedAt,
+        completed_at: null,
+        metadata_json: JSON.stringify(metadata ?? {}),
+    };
+}

package/dist/transition-flow.d.ts

@@ -0,0 +1,17 @@
+import type { WorkflowEngineHost } from './host';
+import type { TransitionFlowWorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunResult } from './types';
+/** Dependencies required by the transition-flow driver. */
+export interface TransitionFlowDriverOptions {
+    readonly host: WorkflowEngineHost;
+    readonly persistence: WorkflowPersistenceAdapter;
+}
+/** Transition-flow workflow driver with an R7 single control function. */
+export declare class TransitionFlowDriver {
+    private readonly options;
+    constructor(options: TransitionFlowDriverOptions);
+    /** Run a transition-flow workflow to completion or failure. */
+    run(workflow: TransitionFlowWorkflowDef, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    private done;
+    private fail;
+}
+//# sourceMappingURL=transition-flow.d.ts.map

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

@@ -0,0 +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"}

package/dist/transition-flow.js

@@ -0,0 +1,114 @@
+import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import { mergeVars, resolveTemplates } from './variables.js';
+/** Transition-flow workflow driver with an R7 single control function. */
+export class TransitionFlowDriver {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Run a transition-flow workflow to completion or failure. */
+    async run(workflow, options = {}) {
+        const runId = options.runId ?? crypto.randomUUID();
+        const startedAt = new Date().toISOString();
+        const mode = 'transition-flow';
+        await this.options.persistence.createRun(runRecord(runId, workflow.name, mode, startedAt, options.metadata));
+        const nodes = new Map(workflow.nodes.map((node) => [node.id, node]));
+        const terminal = new Set(workflow.terminalNodes ?? []);
+        const vars = mergeVars(workflow.vars, options.vars);
+        const env = allowedEnv(workflow.env?.allow ?? [], options.env ?? getProcessEnv());
+        let current = nodes.get(workflow.initialNode);
+        let transitionsTaken = 0;
+        let lastActionResult;
+        const iterationBound = workflow.iterationBound ?? 50;
+        if (current === undefined) {
+            throw new Error(`Initial node "${workflow.initialNode}" is not declared`);
+        }
+        while (true) {
+            // 1. Persist current node snapshot before action execution.
+            await this.options.persistence.saveWorkflowState(runId, current.id, { transitionsTaken });
+            await this.options.persistence.savePhase(runId, current.id, 'running');
+            // 2. Execute the node action when one is configured.
+            if (current.action !== undefined) {
+                const resolved = resolveTemplates(current.action.options ?? {}, {
+                    vars,
+                    env,
+                    builtins: { workflow: workflow.name, node: current.id, runId },
+                });
+                lastActionResult = await this.options.host.runAction(current.action.kind, resolved, {
+                    runId,
+                    workdir: options.workdir,
+                    stateOrNodeId: current.id,
+                    vars,
+                    env,
+                    metadata: options.metadata,
+                });
+                if (!lastActionResult.ok) {
+                    return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, lastActionResult.error);
+                }
+                if (lastActionResult.terminal === true) {
+                    return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+                }
+            }
+            // 3. Stop when the node is terminal or no outgoing edge exists.
+            const outbound = workflow.edges.filter((edge) => edge.from === current?.id);
+            if (terminal.has(current.id) || outbound.length === 0) {
+                return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+            }
+            // 4. Evaluate edge conditions in declaration order and pick the first passing edge.
+            const edge = await firstPassingEdge(outbound, this.options.host, {
+                runId,
+                current: current.id,
+                vars,
+                lastActionResult,
+            });
+            if (edge === undefined) {
+                return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, 'no-passing-edge');
+            }
+            // 5. Persist the edge transition.
+            transitionsTaken += 1;
+            await this.options.persistence.saveTransition(runId, current.id, edge.to, edge.condition?.kind ?? null);
+            // 6. Enforce the iteration bound after taking the transition.
+            if (transitionsTaken > iterationBound) {
+                return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, 'iteration-bound-exceeded');
+            }
+            // 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`);
+            current = nextNode;
+        }
+    }
+    async done(runId, workflowName, mode, finalState, transitionsTaken) {
+        await this.options.persistence.savePhase(runId, finalState, 'done');
+        await this.options.persistence.finalizeRun(runId, 'done', new Date().toISOString());
+        return { runId, workflowName, mode, status: 'done', finalState, transitionsTaken };
+    }
+    async fail(runId, workflowName, mode, finalState, transitionsTaken, reason = 'failed') {
+        await this.options.persistence.savePhase(runId, finalState, 'failed');
+        await this.options.persistence.finalizeRun(runId, 'failed', new Date().toISOString());
+        return { runId, workflowName, mode, status: 'failed', finalState, transitionsTaken, reason };
+    }
+}
+async function firstPassingEdge(edges, host, context) {
+    for (const edge of edges) {
+        if (edge.condition === undefined)
+            return edge;
+        if (await host.evaluateGuard(edge.condition.kind, edge.condition.options ?? {}, context))
+            return edge;
+    }
+    return undefined;
+}
+function allowedEnv(names, source) {
+    return Object.fromEntries(names.flatMap((name) => (source[name] === undefined ? [] : [[name, source[name]]])));
+}
+function runRecord(runId, workflowName, mode, startedAt, metadata) {
+    return {
+        id: runId,
+        workflow_name: workflowName,
+        mode,
+        status: 'running',
+        started_at: startedAt,
+        completed_at: null,
+        metadata_json: JSON.stringify(metadata ?? {}),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+/** Workflow execution status persisted for runs and phases. */
+export type WorkflowStatus = 'running' | 'done' | 'failed';
+/** Runtime variables and user variables available to workflow definitions. */
+export type Vars = Record<string, string>;
+/** Environment allowlist carried by a workflow definition. */
+export interface Env {
+    readonly allow?: readonly string[];
+}
+/** Workflow action definition executed by a host action runner. */
+export interface ActionDef {
+    readonly kind: string;
+    readonly options?: Record<string, unknown>;
+}
+/** Guard predicate definition used by state-machine transitions and transition-flow edges. */
+export interface GuardDef {
+    readonly kind: string;
+    readonly options?: Record<string, unknown>;
+}
+/** One state in a state-machine workflow. */
+export interface StateDef {
+    readonly id: string;
+    readonly onEnter?: readonly ActionDef[];
+    readonly onExit?: readonly ActionDef[];
+}
+/** One transition in a state-machine workflow. */
+export interface TransitionDef {
+    readonly from: string;
+    readonly to: string;
+    readonly trigger?: string;
+    readonly guard?: GuardDef;
+}
+/** State-machine workflow definition. */
+export interface StateMachineWorkflowDef {
+    readonly kind?: 'state-machine';
+    readonly name: string;
+    readonly initialState: string;
+    readonly terminalStates?: readonly string[];
+    readonly iterationBound?: number;
+    readonly vars?: Vars;
+    readonly env?: Env;
+    readonly states: readonly StateDef[];
+    readonly transitions: readonly TransitionDef[];
+}
+/** Transition-flow node definition. */
+export interface FlowNodeDef {
+    readonly id: string;
+    readonly type?: 'action' | 'gate' | 'parallel' | 'decision';
+    readonly action?: ActionDef;
+}
+/** Transition-flow edge definition. */
+export interface FlowEdgeDef {
+    readonly from: string;
+    readonly to: string;
+    readonly condition?: GuardDef;
+}
+/** Transition-flow workflow definition. */
+export interface TransitionFlowWorkflowDef {
+    readonly kind: 'transition-flow';
+    readonly name: string;
+    readonly initialNode: string;
+    readonly terminalNodes?: readonly string[];
+    readonly iterationBound?: number;
+    readonly vars?: Vars;
+    readonly env?: Env;
+    readonly nodes: readonly FlowNodeDef[];
+    readonly edges: readonly FlowEdgeDef[];
+}
+/** Discriminated workflow definition union. */
+export type WorkflowDef = StateMachineWorkflowDef | TransitionFlowWorkflowDef;
+/** Action execution context passed to action runners. */
+export interface ActionRunContext {
+    readonly runId: string;
+    readonly workdir?: string;
+    readonly stateOrNodeId: string;
+    readonly vars: Vars;
+    readonly env: Record<string, string>;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Result of a single action execution. */
+export interface ActionResult {
+    readonly ok: boolean;
+    readonly data?: Record<string, unknown>;
+    readonly error?: string;
+    readonly terminal?: boolean;
+}
+/** Action runner implementation registered in the workflow host. */
+export interface ActionRunner {
+    readonly kind: string;
+    execute(options: Record<string, unknown>, context: ActionRunContext): Promise<ActionResult>;
+}
+/** Guard evaluation context. */
+export interface GuardContext {
+    readonly runId: string;
+    readonly current: string;
+    readonly vars: Vars;
+    readonly lastActionResult?: ActionResult;
+}
+/** Guard runner implementation registered in the workflow host. */
+export interface GuardRunner {
+    readonly kind: string;
+    evaluate(options: Record<string, unknown>, context: GuardContext): Promise<boolean>;
+}
+/** Input for running a workflow. */
+export interface WorkflowRunOptions {
+    readonly runId?: string;
+    readonly workdir?: string;
+    readonly vars?: Vars;
+    readonly env?: Record<string, string | undefined>;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Result returned by both driver loops. */
+export interface WorkflowRunResult {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly mode: 'state-machine' | 'transition-flow';
+    readonly status: WorkflowStatus;
+    readonly finalState: string;
+    readonly transitionsTaken: number;
+    readonly reason?: string;
+}
+/** Persisted workflow run record. */
+export interface WorkflowRunRecord {
+    readonly id: string;
+    readonly workflow_name: string;
+    readonly mode: string;
+    readonly status: WorkflowStatus;
+    readonly started_at: string;
+    readonly completed_at: string | null;
+    readonly metadata_json: string;
+}
+/** Persistence adapter implemented by DB-backed and test stores. */
+export interface WorkflowPersistenceAdapter {
+    createRun(record: WorkflowRunRecord): Promise<void>;
+    finalizeRun(runId: string, status: WorkflowStatus, completedAt: string): Promise<void>;
+    savePhase(runId: string, phase: string, status: WorkflowStatus): Promise<void>;
+    saveTransition(runId: string, from: string, to: string, trigger: string | null): Promise<void>;
+    saveWorkflowState(runId: string, state: string, data: Record<string, unknown>): Promise<void>;
+    loadRun(runId: string): Promise<WorkflowRunRecord | undefined>;
+    listRuns(): Promise<readonly WorkflowRunRecord[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/variables.d.ts

@@ -0,0 +1,14 @@
+import type { Vars } from './types';
+/** Runtime context used for workflow variable interpolation. */
+export interface VariableContext {
+    readonly vars: Vars;
+    readonly env: Record<string, string | undefined>;
+    readonly builtins?: Record<string, string | number | undefined>;
+}
+/** Merge workflow vars with caller overrides; caller values win. */
+export declare function mergeVars(workflowVars?: Vars, overrideVars?: Vars): Vars;
+/** Resolve templates inside an unknown options value. */
+export declare function resolveTemplates<T>(value: T, context: VariableContext): T;
+/** Resolve a single template string. */
+export declare function resolveTemplateString(value: string, context: VariableContext): string;
+//# sourceMappingURL=variables.d.ts.map

package/dist/variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../src/variables.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAIpC,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;CACnE;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,YAAY,GAAE,IAAS,EAAE,YAAY,GAAE,IAAS,GAAG,IAAI,CAEhF;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,CAAC,CAgBzE;AAED,wCAAwC;AACxC,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAmBrF"}

package/dist/variables.js

@@ -0,0 +1,45 @@
+import { WorkflowValidationError } from './errors.js';
+const TEMPLATE_REF = /\$\{([^}]+)\}/g;
+/** Merge workflow vars with caller overrides; caller values win. */
+export function mergeVars(workflowVars = {}, overrideVars = {}) {
+    return { ...workflowVars, ...overrideVars };
+}
+/** Resolve templates inside an unknown options value. */
+export function resolveTemplates(value, context) {
+    if (typeof value === 'string') {
+        return resolveTemplateString(value, context);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => resolveTemplates(entry, context));
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            resolveTemplates(entry, context),
+        ]));
+    }
+    return value;
+}
+/** Resolve a single template string. */
+export function resolveTemplateString(value, context) {
+    return value.replace(TEMPLATE_REF, (_match, name) => {
+        if (name.startsWith('vars.')) {
+            const key = name.slice('vars.'.length);
+            const resolved = context.vars[key];
+            if (resolved === undefined)
+                throw new WorkflowValidationError(`Workflow variable "${key}" is not defined`);
+            return resolved;
+        }
+        if (name.startsWith('env.')) {
+            const key = name.slice('env.'.length);
+            const resolved = context.env[key];
+            if (resolved === undefined)
+                throw new WorkflowValidationError(`Environment variable "${key}" is not defined`);
+            return resolved;
+        }
+        const resolved = context.builtins?.[name];
+        if (resolved === undefined)
+            throw new WorkflowValidationError(`Workflow builtin "${name}" is not defined`);
+        return String(resolved);
+    });
+}