@gobing-ai/ts-dual-workflow-engine 0.3.11 → 0.3.14

package/src/persistence.ts

@@ -1,7 +1,7 @@
 import type { DbAdapter } from '@gobing-ai/ts-db';
 import { RunCollisionError } from './errors';
 import { WORKFLOW_ENGINE_SCHEMA_SQL } from './schema-sql';
-import type { WorkflowPersistenceAdapter, WorkflowRunRecord, WorkflowStatus } from './types';
+import type { ActionRedactor, WorkflowPersistenceAdapter, WorkflowRunRecord, WorkflowStatus } from './types';
 
 /** Apply workflow-engine-owned schema to a database adapter. */
 export async function applyWorkflowEngineSchema(db: DbAdapter): Promise<void> {
@@ -95,6 +95,49 @@ export class DbWorkflowPersistenceAdapter implements WorkflowPersistenceAdapter
         );
     }
 
+    /** Insert a running action row. Returns the row id for later finalization. */
+    async saveActionStart(runId: string, node: string, kind: string): Promise<string> {
+        const id = crypto.randomUUID();
+        const now = Date.now();
+        await this.db.run(
+            `INSERT INTO action_runs (id, run_id, node, kind, status, started_at, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+            id,
+            runId,
+            node,
+            kind,
+            'running',
+            new Date(now).toISOString(),
+            now,
+            now,
+        );
+        return id;
+    }
+
+    /** Finalize an action row with duration, ok flag, and optional redacted result. */
+    async saveActionFinalize(
+        actionId: string,
+        status: WorkflowStatus,
+        durationMs: number,
+        ok: boolean,
+        result?: unknown,
+        _redactor?: ActionRedactor,
+    ): Promise<void> {
+        const now = Date.now();
+        await this.db.run(
+            `UPDATE action_runs
+             SET status = ?, duration_ms = ?, ok = ?, result_json = ?, completed_at = ?, updated_at = ?
+             WHERE id = ?`,
+            status,
+            durationMs,
+            ok ? 1 : 0,
+            result !== undefined ? JSON.stringify(result) : null,
+            new Date(now).toISOString(),
+            now,
+            actionId,
+        );
+    }
+
     /** Load a single run by id. */
     async loadRun(runId: string): Promise<WorkflowRunRecord | undefined> {
         await applyWorkflowEngineSchema(this.db);
@@ -128,6 +171,50 @@ export class MemoryWorkflowPersistenceAdapter implements WorkflowPersistenceAdap
         if (run !== undefined) this.runs.set(runId, { ...run, status, completed_at: completedAt });
     }
 
+    readonly actionRuns: Array<{
+        id: string;
+        runId: string;
+        node: string;
+        kind: string;
+        status: WorkflowStatus;
+        durationMs: number | null;
+        ok: number | null;
+        resultJson: string | null;
+    }> = [];
+
+    /** Insert a running action row. */
+    async saveActionStart(runId: string, node: string, kind: string): Promise<string> {
+        const id = crypto.randomUUID();
+        this.actionRuns.push({
+            id,
+            runId,
+            node,
+            kind,
+            status: 'running',
+            durationMs: null,
+            ok: null,
+            resultJson: null,
+        });
+        return id;
+    }
+
+    /** Finalize an action row. */
+    async saveActionFinalize(
+        actionId: string,
+        status: WorkflowStatus,
+        durationMs: number,
+        ok: boolean,
+        result?: unknown,
+        _redactor?: ActionRedactor,
+    ): Promise<void> {
+        const row = this.actionRuns.find((a) => a.id === actionId);
+        if (row === undefined) return;
+        row.status = status;
+        row.durationMs = durationMs;
+        row.ok = ok ? 1 : 0;
+        row.resultJson = result !== undefined ? JSON.stringify(result) : null;
+    }
+
     /** Save one phase/state execution record. */
     async savePhase(runId: string, phase: string, status: WorkflowStatus): Promise<void> {
         this.phases.push({ runId, phase, status });

package/src/run-lifecycle.ts

@@ -108,8 +108,18 @@ export class RunLifecycle {
             async () => {
                 await lifecycle.persistence.createRun(lifecycle.runRecord(options.metadata));
                 lifecycle.logger.info('workflow run started');
-                addSpanEvent('workflow.run.started', { workflowName, mode, runId });
-                void lifecycle.events?.emit('workflow.run.started', { workflowName, mode, runId });
+                addSpanEvent('workflow.run.started', {
+                    workflowName,
+                    mode,
+                    runId,
+                    dryRun: options.dryRun ?? false,
+                });
+                void lifecycle.events?.emit('workflow.run.started', {
+                    workflowName,
+                    mode,
+                    runId,
+                    dryRun: options.dryRun ?? false,
+                });
                 return await loop(lifecycle);
             },
             { attributes: { 'workflow.name': workflowName, 'workflow.mode': mode, 'workflow.run_id': runId } },
@@ -120,15 +130,33 @@ export class RunLifecycle {
     async enter(stateOrNodeId: string, transitionsTaken: number): Promise<void> {
         await this.persistence.saveWorkflowState(this.runId, stateOrNodeId, { transitionsTaken });
         await this.persistence.savePhase(this.runId, stateOrNodeId, 'running');
-        addSpanEvent('workflow.node.enter', { node: stateOrNodeId, transitionsTaken });
-        void this.events?.emit('workflow.node.enter', { node: stateOrNodeId, transitionsTaken });
+        addSpanEvent('workflow.node.enter', {
+            runId: this.runId,
+            node: stateOrNodeId,
+            transitionsTaken,
+        });
+        void this.events?.emit('workflow.node.enter', {
+            runId: this.runId,
+            node: stateOrNodeId,
+            transitionsTaken,
+        });
     }
 
     /** Persist a transition and emit its observability event. */
     async recordTransition(from: string, to: string, trigger: string | null): Promise<void> {
         await this.persistence.saveTransition(this.runId, from, to, trigger);
-        addSpanEvent('workflow.node.transition', { from, to, ...(trigger === null ? {} : { trigger }) });
-        void this.events?.emit('workflow.node.transition', { from, to, trigger });
+        addSpanEvent('workflow.node.transition', {
+            runId: this.runId,
+            from,
+            to,
+            ...(trigger === null ? {} : { trigger }),
+        });
+        void this.events?.emit('workflow.node.transition', {
+            runId: this.runId,
+            from,
+            to,
+            trigger,
+        });
     }
 
     /** Finalize the run as succeeded and return its result. */
@@ -136,8 +164,8 @@ export class RunLifecycle {
         await this.persistence.savePhase(this.runId, finalState, 'done');
         await this.persistence.finalizeRun(this.runId, 'done', new Date().toISOString());
         this.logger.info('workflow run done', { finalState, transitionsTaken });
-        addSpanEvent('workflow.run.done', { finalState, transitionsTaken });
-        void this.events?.emit('workflow.run.done', { finalState, transitionsTaken });
+        addSpanEvent('workflow.run.done', { runId: this.runId, finalState, transitionsTaken });
+        void this.events?.emit('workflow.run.done', { runId: this.runId, finalState, transitionsTaken });
         return this.result('done', finalState, transitionsTaken);
     }
 
@@ -145,32 +173,40 @@ export class RunLifecycle {
     async fail(finalState: string, transitionsTaken: number, reason = 'failed'): Promise<WorkflowRunResult> {
         await this.persistence.savePhase(this.runId, finalState, 'failed');
         await this.persistence.finalizeRun(this.runId, 'failed', new Date().toISOString());
-        addSpanEvent('workflow.run.failed', { finalState, reason });
-        void this.events?.emit('workflow.run.failed', { finalState, reason });
+        addSpanEvent('workflow.run.failed', { runId: this.runId, finalState, reason });
+        void this.events?.emit('workflow.run.failed', { runId: this.runId, finalState, reason });
         this.logger.warn('workflow run failed', { finalState, transitionsTaken, reason });
         return this.result('failed', finalState, transitionsTaken, reason);
     }
 
     /** Emit action-level observability before a host action is invoked. */
     actionStart(stateOrNodeId: string, kind: string): void {
-        addSpanEvent('workflow.action.start', { node: stateOrNodeId, kind });
-        void this.events?.emit('workflow.action.start', { node: stateOrNodeId, kind });
+        addSpanEvent('workflow.action.start', { runId: this.runId, node: stateOrNodeId, kind });
+        void this.events?.emit('workflow.action.start', { runId: this.runId, node: stateOrNodeId, kind });
     }
 
     /** Emit action-level observability after a host action settles. */
     actionDone(stateOrNodeId: string, kind: string, durationMs: number, ok: boolean): void {
-        addSpanEvent('workflow.action.done', { node: stateOrNodeId, kind, durationMs, ok });
-        void this.events?.emit('workflow.action.done', { node: stateOrNodeId, kind, durationMs, ok });
+        addSpanEvent('workflow.action.done', { runId: this.runId, node: stateOrNodeId, kind, durationMs, ok });
+        void this.events?.emit('workflow.action.done', {
+            runId: this.runId,
+            node: stateOrNodeId,
+            kind,
+            durationMs,
+            ok,
+        });
     }
 
     /** Log and trace a non-fatal action failure for the 'continue' error policy (ADR-013 observability seam). */
     warnActionFailed(stateOrNodeId: string, transitionsTaken: number, error?: string): void {
         addSpanEvent('workflow.action.failed_continue', {
+            runId: this.runId,
             node: stateOrNodeId,
             transitionsTaken,
             ...(error === undefined ? {} : { error }),
         });
         void this.events?.emit('workflow.action.failed_continue', {
+            runId: this.runId,
             node: stateOrNodeId,
             transitionsTaken,
             ...(error === undefined ? {} : { error }),
@@ -178,6 +214,27 @@ export class RunLifecycle {
         this.logger.warn('action failed (continuing)', { node: stateOrNodeId, transitionsTaken, error });
     }
 
+    /** Emit a guard evaluation result (fired for every guard, including rejected). */
+    guardEvaluated(from: string, to: string, kind: string, passed: boolean): void {
+        void this.events?.emit('workflow.guard.evaluated', {
+            runId: this.runId,
+            from,
+            to,
+            kind,
+            passed,
+        });
+    }
+
+    /** Emit when an interactive HITL prompt is presented. */
+    hitlAsk(node: string, kind: string, message: string): void {
+        void this.events?.emit('workflow.hitl.ask', { runId: this.runId, node, kind, message });
+    }
+
+    /** Emit when an interactive HITL prompt resolves. */
+    hitlResponse(node: string, ok: boolean): void {
+        void this.events?.emit('workflow.hitl.response', { runId: this.runId, node, ok });
+    }
+
     private result(
         status: WorkflowStatus,
         finalState: string,

package/src/schema-sql.ts

@@ -1,4 +1,4 @@
-/** SQL DDL for the dual-workflow engine's persistent schema — runs, phase_runs, transition_runs, and workflow_states tables. */
+/** SQL DDL for the dual-workflow engine's persistent schema — runs, phase_runs, transition_runs, workflow_states, and action_runs tables. */
 export const WORKFLOW_ENGINE_SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS runs (
     id TEXT PRIMARY KEY,
@@ -36,7 +36,6 @@ CREATE TABLE IF NOT EXISTS transition_runs (
     updated_at INTEGER NOT NULL DEFAULT 0,
     FOREIGN KEY (run_id) REFERENCES runs(id)
 );
-
 CREATE TABLE IF NOT EXISTS workflow_states (
     id TEXT PRIMARY KEY,
     run_id TEXT NOT NULL,
@@ -46,4 +45,20 @@ CREATE TABLE IF NOT EXISTS workflow_states (
     updated_at INTEGER NOT NULL DEFAULT 0,
     FOREIGN KEY (run_id) REFERENCES runs(id)
 );
+
+CREATE TABLE IF NOT EXISTS action_runs (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    node TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    status TEXT NOT NULL,
+    duration_ms INTEGER,
+    ok INTEGER,
+    result_json TEXT,
+    started_at TEXT,
+    completed_at TEXT,
+    created_at INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0,
+    FOREIGN KEY (run_id) REFERENCES runs(id)
+);
 `.trim();

package/src/state-machine.ts

@@ -88,12 +88,18 @@ export class StateMachineDriver {
             }
 
             // 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,
-            });
+            const nextTransition = await firstPassingTransition(
+                outbound,
+                this.options.host,
+                {
+                    runId,
+                    current: current.id,
+                    vars,
+                    lastActionResult,
+                },
+                lifecycle,
+            );
+
             if (nextTransition === undefined) {
                 return await lifecycle.fail(current.id, transitionsTaken, 'no-passing-transition');
             }
@@ -145,6 +151,10 @@ export class StateMachineDriver {
         lifecycle: RunLifecycle,
         defaultOnError: OnErrorPolicy | undefined,
     ): Promise<RunActionsOutcome> {
+        if (options.dryRun) {
+            return { outcome: 'completed', result: undefined };
+        }
+
         let last: ActionResult | undefined;
         for (const action of actions) {
             const resolved = resolveTemplates(action.options ?? {}, {
@@ -152,6 +162,7 @@ export class StateMachineDriver {
                 env,
                 builtins: runtimeBuiltins(workflowName, stateId, runId, transitionsTaken, 'state-machine'),
             });
+            const actionId = await this.options.persistence.saveActionStart(runId, stateId, action.kind);
             const actionStartMs = Date.now();
             lifecycle.actionStart(stateId, action.kind);
             try {
@@ -165,7 +176,15 @@ export class StateMachineDriver {
                     events: options.events,
                 });
             } finally {
-                lifecycle.actionDone(stateId, action.kind, Date.now() - actionStartMs, last?.ok ?? false);
+                const durationMs = Date.now() - actionStartMs;
+                lifecycle.actionDone(stateId, action.kind, durationMs, last?.ok ?? false);
+                void this.options.persistence.saveActionFinalize(
+                    actionId,
+                    last?.ok !== false ? 'done' : 'failed',
+                    durationMs,
+                    last?.ok ?? false,
+                    last,
+                );
             }
             if (last.terminal === true) return { outcome: 'terminal', result: last };
             if (!last.ok) {
@@ -188,10 +207,13 @@ async function firstPassingTransition(
     transitions: StateMachineWorkflowDef['transitions'],
     host: WorkflowEngineHost,
     context: Parameters<WorkflowEngineHost['evaluateGuard']>[2],
+    lifecycle: RunLifecycle,
 ): Promise<StateMachineWorkflowDef['transitions'][number] | undefined> {
     for (const transition of transitions) {
         if (transition.guard === undefined) return transition;
-        if (await host.evaluateGuard(transition.guard.kind, transition.guard.options ?? {}, context)) return transition;
+        const passed = await host.evaluateGuard(transition.guard.kind, transition.guard.options ?? {}, context);
+        lifecycle.guardEvaluated(context.current, transition.to, transition.guard.kind, passed);
+        if (passed) return transition;
     }
     return undefined;
 }

package/src/transition-flow.ts

@@ -55,13 +55,18 @@ export class TransitionFlowDriver {
             // 1. Persist current node snapshot before action execution.
             await lifecycle.enter(current.id, transitionsTaken);
 
-            // 2. Execute the node action when one is configured.
-            if (current.action !== undefined) {
+            // 2. Execute the node action when one is configured (skipped in dry-run).
+            if (options.dryRun) {
+                if (current.action !== undefined) {
+                    lastActionResult = undefined;
+                }
+            } else if (current.action !== undefined) {
                 const resolved = resolveTemplates(current.action.options ?? {}, {
                     vars,
                     env,
                     builtins: runtimeBuiltins(workflow.name, current.id, runId, transitionsTaken, 'transition-flow'),
                 });
+                const actionId = await this.options.persistence.saveActionStart(runId, current.id, current.action.kind);
                 const actionStartMs = Date.now();
                 lifecycle.actionStart(current.id, current.action.kind);
                 try {
@@ -75,11 +80,14 @@ export class TransitionFlowDriver {
                         events: options.events,
                     });
                 } finally {
-                    lifecycle.actionDone(
-                        current.id,
-                        current.action.kind,
-                        Date.now() - actionStartMs,
+                    const durationMs = Date.now() - actionStartMs;
+                    lifecycle.actionDone(current.id, current.action.kind, durationMs, lastActionResult?.ok ?? false);
+                    void this.options.persistence.saveActionFinalize(
+                        actionId,
+                        lastActionResult?.ok !== false ? 'done' : 'failed',
+                        durationMs,
                         lastActionResult?.ok ?? false,
+                        lastActionResult,
                     );
                 }
                 if (lastActionResult.setVars) vars = mergeSetVars(vars, lastActionResult.setVars);
@@ -102,12 +110,17 @@ export class TransitionFlowDriver {
             }
 
             // 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,
-            });
+            const edge = await firstPassingEdge(
+                outbound,
+                this.options.host,
+                {
+                    runId,
+                    current: current.id,
+                    vars,
+                    lastActionResult,
+                },
+                lifecycle,
+            );
             if (edge === undefined) {
                 return await lifecycle.fail(current.id, transitionsTaken, 'no-passing-edge');
             }
@@ -133,10 +146,13 @@ async function firstPassingEdge(
     edges: TransitionFlowWorkflowDef['edges'],
     host: WorkflowEngineHost,
     context: Parameters<WorkflowEngineHost['evaluateGuard']>[2],
+    lifecycle: RunLifecycle,
 ): Promise<TransitionFlowWorkflowDef['edges'][number] | undefined> {
     for (const edge of edges) {
         if (edge.condition === undefined) return edge;
-        if (await host.evaluateGuard(edge.condition.kind, edge.condition.options ?? {}, context)) return edge;
+        const passed = await host.evaluateGuard(edge.condition.kind, edge.condition.options ?? {}, context);
+        lifecycle.guardEvaluated(context.current, edge.to, edge.condition.kind, passed);
+        if (passed) return edge;
     }
     return undefined;
 }

package/src/types.ts

@@ -160,6 +160,8 @@ export interface WorkflowRunOptions {
     readonly events?: EventBus<WorkflowEngineEvents>;
     /** Run-level error policy override. Lowest precedence; action-level wins. */
     readonly onError?: OnErrorPolicy;
+    /** Validate the definition and walk the transition graph without executing actions. */
+    readonly dryRun?: boolean;
 }
 
 /** Result returned by both driver loops. */
@@ -184,6 +186,23 @@ export interface WorkflowRunRecord {
     readonly metadata_json: string;
 }
 
+/** Persisted action run record — one row per action executed in a workflow run. */
+export interface ActionRunRecord {
+    readonly id: string;
+    readonly run_id: string;
+    readonly node: string;
+    readonly kind: string;
+    readonly status: WorkflowStatus;
+    readonly duration_ms: number | null;
+    readonly ok: number | null;
+    readonly result_json: string | null;
+    readonly started_at: string | null;
+    readonly completed_at: string | null;
+}
+
+/** Optional redaction hook: given action options, return sanitized options for persistence. */
+export type ActionRedactor = (kind: string, options: Record<string, unknown>) => Record<string, unknown>;
+
 /** Persistence adapter implemented by DB-backed and test stores. */
 export interface WorkflowPersistenceAdapter {
     createRun(record: WorkflowRunRecord): Promise<void>;
@@ -191,6 +210,17 @@ export interface WorkflowPersistenceAdapter {
     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>;
+    /** Two-phase action persistence: insert a running row at action start. Returns the action row id. */
+    saveActionStart(runId: string, node: string, kind: string): Promise<string>;
+    /** Finalize an action row with duration, ok, result. */
+    saveActionFinalize(
+        actionId: string,
+        status: WorkflowStatus,
+        durationMs: number,
+        ok: boolean,
+        result?: unknown,
+        redactor?: ActionRedactor,
+    ): Promise<void>;
     loadRun(runId: string): Promise<WorkflowRunRecord | undefined>;
     listRuns(): Promise<readonly WorkflowRunRecord[]>;
 }