@gobing-ai/ts-dual-workflow-engine 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-dual-workflow-engine",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "description": "@gobing-ai/ts-dual-workflow-engine — State-machine and transition-flow workflow runtime.",
     "keywords": [
         "typescript",
@@ -48,9 +48,9 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-dual-workflow-engine-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-db": "^0.3.0",
-        "@gobing-ai/ts-runtime": "^0.3.0",
-        "@gobing-ai/ts-utils": "^0.3.0",
+        "@gobing-ai/ts-db": "^0.3.2",
+        "@gobing-ai/ts-infra": "^0.3.2",
+        "@gobing-ai/ts-runtime": "^0.3.2",
         "zod": "^4.1.0"
     },
     "devDependencies": {

package/src/config.ts

@@ -1,8 +1,10 @@
 import { loadStructuredConfig, parseYamlObject } from '@gobing-ai/ts-runtime';
 import { WorkflowValidationError } from './errors';
+import { RUNTIME_BUILTIN_KEYS } from './run-lifecycle';
 import { StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema } from './schema';
 import type { WorkflowDef } from './types';
 
+/** Loading options for {@link loadWorkflowDef}. */
 export interface WorkflowLoadOptions {
     /** When true, honor a top-level `$schema` ref. Defaults to true for file loads. */
     validateSchema?: boolean;
@@ -177,17 +179,12 @@ function collectActionOptions(workflow: WorkflowDef): Record<string, unknown>[]
     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',
-]);
+/**
+ * Reserved template namespaces always available at runtime (not user-declared vars).
+ * Single-sourced from {@link RUNTIME_BUILTIN_KEYS} so the validator can never drift
+ * from the builtins the drivers actually inject at run time.
+ */
+const RUNTIME_TEMPLATE_NAMESPACES = new Set<string>(RUNTIME_BUILTIN_KEYS);
 
 /**
  * Check `${...}` template references inside action options resolve to something:

package/src/events.ts

@@ -0,0 +1,19 @@
+/** Typed event map for workflow-engine run observability. All events prefixed `workflow.`. */
+export type WorkflowEngineEvents = {
+    /** Emitted when a run begins (inside the span). */
+    'workflow.run.started': (data: { workflowName: string; mode: string; runId: string }) => void;
+    /** Emitted when a run completes successfully. */
+    'workflow.run.done': (data: { finalState: string; transitionsTaken: number }) => void;
+    /** Emitted when a run fails. */
+    'workflow.run.failed': (data: { finalState: string; reason: string }) => void;
+    /** Emitted when entering a state or node. */
+    'workflow.node.enter': (data: { node: string; transitionsTaken: number }) => void;
+    /** Emitted on a state/node transition. */
+    'workflow.node.transition': (data: { from: string; to: string; trigger: string | null }) => void;
+    /** Emitted when an action starts executing. */
+    'workflow.action.start': (data: { node: string; kind: string }) => void;
+    /** Emitted when an action finishes executing (success or failure). */
+    'workflow.action.done': (data: { node: string; kind: string; durationMs: number; ok: boolean }) => void;
+    /** Emitted when a non-fatal action failure is continued past (onError: 'continue'). */
+    'workflow.action.failed_continue': (data: { node: string; transitionsTaken: number; error?: string }) => void;
+};

package/src/extensions.ts

@@ -0,0 +1,163 @@
+import type { Logger } from '@gobing-ai/ts-infra';
+import { basenamePath, dirnamePath, SEP } from '@gobing-ai/ts-runtime';
+import type { ExtensionRef, LoadExtensionsOptions } from '@gobing-ai/ts-runtime/plugin';
+import { loadExtensionModules } from '@gobing-ai/ts-runtime/plugin';
+import { WorkflowValidationError } from './errors';
+import type { WorkflowEngineHost } from './host';
+import type { ActionRunner, GuardRunner } from './types';
+
+/** Minimal warning sink accepted for non-fatal extension diagnostics; a full {@link Logger} satisfies it. */
+export type WorkflowExtensionLogger = Pick<Logger, 'warn'>;
+
+/**
+ * Capability kinds a workflow extension module can contribute.
+ *
+ * Only `actions` and `guards` are supported as extension surfaces. Driver,
+ * loader, validator, and formatter registries are explicitly deferred per
+ * ADR-010 and are not extension-loadable.
+ */
+export type WorkflowExtensionKind = 'actions' | 'guards';
+
+/**
+ * A single workflow extension module reference.
+ *
+ * The caller provides a pre-resolved absolute path; the loader adapts it to the
+ * shared `ExtensionRef` format before delegating to the generic core so the
+ * trust guard always governs the module that gets imported.
+ */
+export interface WorkflowExtensionRef {
+    /** Target capability registry. */
+    readonly kind: WorkflowExtensionKind;
+    /** Absolute path to the module to import. */
+    readonly absPath: string;
+    /** Name of the config declaring this extension (for diagnostics). */
+    readonly sourceName: string;
+}
+
+/** Options controlling workflow extension loading. */
+export interface LoadWorkflowExtensionsOptions {
+    /**
+     * Whether to actually import extension modules. Defaults to `false`:
+     * loading arbitrary code is a trust decision the caller must make
+     * explicitly. When refs exist and this is not `true`, loading throws
+     * **before any import**.
+     */
+    readonly allowExtensions?: boolean;
+    /** Optional sink for non-fatal warnings (e.g. built-in overrides). */
+    readonly logger?: WorkflowExtensionLogger;
+    /**
+     * Required module loader seam for tests or embedders with custom import
+     * policy. The shared core has no ambient code-loading capability of its
+     * own; the embedder supplies the import policy.
+     */
+    readonly moduleLoader: (absPath: string) => Promise<Record<string, unknown>>;
+}
+
+/**
+ * Import each extension module behind an explicit trust gate and register
+ * its actions and/or guards on the workflow host.
+ *
+ * Delegates generic loading (gate, path guard, module import, export
+ * validation) to the shared ``loadExtensionModules`` from ts-runtime/plugin,
+ * then routes each capability to ``host.registerAction`` or
+ * ``host.registerGuard`` based on ``ref.kind``.
+ *
+ * @throws When extensions are present but ``allowExtensions`` is not ``true``,
+ *   when a module lacks a valid export shape, or when the module's export
+ *   does not contain entries matching ``ref.kind``.
+ */
+export async function loadWorkflowExtensionsIntoHost(
+    host: WorkflowEngineHost,
+    refs: readonly WorkflowExtensionRef[],
+    options: LoadWorkflowExtensionsOptions,
+): Promise<void> {
+    if (refs.length === 0) return;
+
+    // Enforce relative-path guard before adapting to the shared format.
+    // The shared loader's assertRelativeExtensionPath applies to the derived
+    // (basename) path, which is always clean — this pre-check catches `..`
+    // traversal in the caller-supplied absPath before basename strips it (R6).
+    for (const ref of refs) {
+        const segments = ref.absPath.split(SEP);
+        if (segments.includes('..')) {
+            throw new Error(
+                `extension path "${ref.absPath}" declared by "${ref.sourceName}" must not contain ".." traversal`,
+            );
+        }
+    }
+
+    // Adapt WorkflowExtensionRef → shared ExtensionRef so the generic loader
+    // governs every import.  The shared loader resolves (baseDir, path) ->
+    // absPath internally; we supply dirname/basename so the resolved path
+    // reconstructs the caller's original absPath.  assertRelativeExtensionPath
+    // is satisfied because basenamePath() is always a simple filename.
+    const sharedRefs: ExtensionRef<WorkflowExtensionKind>[] = refs.map((ref) => ({
+        kind: ref.kind,
+        path: `./${basenamePath(ref.absPath)}`,
+        baseDir: dirnamePath(ref.absPath),
+        sourceName: ref.sourceName,
+    }));
+
+    const sharedOptions: LoadExtensionsOptions = {
+        allowExtensions: options.allowExtensions,
+        logger: options.logger,
+        moduleLoader: options.moduleLoader,
+    };
+
+    await loadExtensionModules<WorkflowExtensionKind>(sharedRefs, sharedOptions, async (sharedRef, extension) => {
+        await registerExtensionOnHost(host, sharedRef, extension, options.logger);
+    });
+}
+
+/**
+ * Route extension-exported capabilities to the correct host registry.
+ *
+ * Validates that the module export contains entries matching `ref.kind`
+ * (wrong-kind-for-ref throws ``WorkflowValidationError``), registers each
+ * with origin ``'extension'``, and warns on built-in overrides.
+ */
+async function registerExtensionOnHost(
+    host: WorkflowEngineHost,
+    ref: ExtensionRef<WorkflowExtensionKind>,
+    extension: Record<string, unknown>,
+    logger?: WorkflowExtensionLogger,
+): Promise<void> {
+    const name = extension.name as string;
+
+    if (ref.kind === 'actions') {
+        const actions = extension.actions as readonly ActionRunner[] | undefined;
+        if (!Array.isArray(actions)) {
+            throw new WorkflowValidationError(
+                `"${ref.sourceName}" extension "${name}" is referenced as kind "actions" but does not export an actions[] array`,
+            );
+        }
+        for (const action of actions) {
+            warnIfOverride(host, action.kind, 'action', ref.sourceName, logger);
+            host.registerAction(action, 'extension');
+        }
+    } else {
+        const guards = extension.guards as readonly GuardRunner[] | undefined;
+        if (!Array.isArray(guards)) {
+            throw new WorkflowValidationError(
+                `"${ref.sourceName}" extension "${name}" is referenced as kind "guards" but does not export a guards[] array`,
+            );
+        }
+        for (const guard of guards) {
+            warnIfOverride(host, guard.kind, 'guard', ref.sourceName, logger);
+            host.registerGuard(guard, 'extension');
+        }
+    }
+}
+
+function warnIfOverride(
+    host: WorkflowEngineHost,
+    kind: string,
+    capabilityType: 'action' | 'guard',
+    sourceName: string,
+    logger?: WorkflowExtensionLogger,
+): void {
+    const origin = capabilityType === 'action' ? host.actionOrigin(kind) : host.guardOrigin(kind);
+    if (logger && origin === 'builtin') {
+        logger.warn(`"${sourceName}" extension overrides built-in ${capabilityType} "${kind}"`);
+    }
+}

package/src/host.ts

@@ -1,36 +1,67 @@
 import { NodeProcessExecutor, type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { type CapabilityOrigin, CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';
 import { WorkflowValidationError } from './errors';
 import type { ActionResult, ActionRunContext, ActionRunner, GuardContext, GuardRunner } from './types';
 
 /** Registry owner for workflow actions and guards. */
 export class WorkflowEngineHost {
-    private readonly actions = new Map<string, ActionRunner>();
-    private readonly guards = new Map<string, GuardRunner>();
+    private readonly actions = new CapabilityRegistry<ActionRunner>('workflow action');
+    private readonly guards = new CapabilityRegistry<GuardRunner>('workflow guard');
 
     /** Register or replace an action runner. */
-    registerAction(action: ActionRunner): this {
-        this.actions.set(action.kind, action);
+    registerAction(action: ActionRunner, origin: CapabilityOrigin = 'extension'): this {
+        this.actions.register(action.kind, action, origin);
         return this;
     }
 
     /** Register or replace a guard runner. */
-    registerGuard(guard: GuardRunner): this {
-        this.guards.set(guard.kind, guard);
+    registerGuard(guard: GuardRunner, origin: CapabilityOrigin = 'extension'): this {
+        this.guards.register(guard.kind, guard, origin);
         return this;
     }
 
+    /** Return true when an action of `kind` is registered. */
+    hasAction(kind: string): boolean {
+        return this.actions.has(kind);
+    }
+
+    /** Return true when a guard of `kind` is registered. */
+    hasGuard(kind: string): boolean {
+        return this.guards.has(kind);
+    }
+
+    /** List registered action kinds in registration order. */
+    listActions(): string[] {
+        return this.actions.list();
+    }
+
+    /** List registered guard kinds in registration order. */
+    listGuards(): string[] {
+        return this.guards.list();
+    }
+
+    /** Origin of a registered action, or undefined if none. Lets 0010 distinguish builtin from extension overrides. */
+    actionOrigin(kind: string): CapabilityOrigin | undefined {
+        return this.actions.getEntry(kind)?.origin;
+    }
+
+    /** Origin of a registered guard, or undefined if none. */
+    guardOrigin(kind: string): CapabilityOrigin | undefined {
+        return this.guards.getEntry(kind)?.origin;
+    }
+
     /** Execute a registered action. */
     async runAction(kind: string, options: Record<string, unknown>, context: ActionRunContext): Promise<ActionResult> {
-        const action = this.actions.get(kind);
-        if (action === undefined) throw new WorkflowValidationError(`Unknown workflow action "${kind}"`);
-        return await action.execute(options, context);
+        // Guard at the host boundary so unknown kinds surface as WorkflowValidationError,
+        // not the shared registry's generic Error (ADR-010 R13).
+        if (!this.actions.has(kind)) throw new WorkflowValidationError(`Unknown workflow action "${kind}"`);
+        return await this.actions.get(kind).execute(options, context);
     }
 
     /** Evaluate a registered guard. */
     async evaluateGuard(kind: string, options: Record<string, unknown>, context: GuardContext): Promise<boolean> {
-        const guard = this.guards.get(kind);
-        if (guard === undefined) throw new WorkflowValidationError(`Unknown workflow guard "${kind}"`);
-        return await guard.evaluate(options, context);
+        if (!this.guards.has(kind)) throw new WorkflowValidationError(`Unknown workflow guard "${kind}"`);
+        return await this.guards.get(kind).evaluate(options, context);
     }
 }
 
@@ -39,14 +70,17 @@ export function createDefaultWorkflowEngineHost(
     options: { processExecutor?: ProcessExecutor } = {},
 ): WorkflowEngineHost {
     const host = new WorkflowEngineHost();
-    host.registerAction(new NoteActionRunner());
-    host.registerAction(new ShellActionRunner(options.processExecutor ?? new NodeProcessExecutor()));
-    host.registerGuard({ kind: 'always', evaluate: async () => true });
-    host.registerGuard({ kind: 'never', evaluate: async () => false });
-    host.registerGuard({
-        kind: 'action-ok',
-        evaluate: async (_options, context) => context.lastActionResult?.ok === true,
-    });
+    host.registerAction(new NoteActionRunner(), 'builtin');
+    host.registerAction(new ShellActionRunner(options.processExecutor ?? new NodeProcessExecutor()), 'builtin');
+    host.registerGuard({ kind: 'always', evaluate: async () => true }, 'builtin');
+    host.registerGuard({ kind: 'never', evaluate: async () => false }, 'builtin');
+    host.registerGuard(
+        {
+            kind: 'action-ok',
+            evaluate: async (_options, context) => context.lastActionResult?.ok === true,
+        },
+        'builtin',
+    );
     return host;
 }
 

package/src/index.ts

@@ -1,5 +1,13 @@
 export { loadWorkflowDef, loadWorkflowDefFromText, validateWorkflowDef } from './config';
 export { FSMError, RunCollisionError, WorkflowValidationError } from './errors';
+export type { WorkflowEngineEvents } from './events';
+export {
+    type LoadWorkflowExtensionsOptions,
+    loadWorkflowExtensionsIntoHost,
+    type WorkflowExtensionKind,
+    type WorkflowExtensionLogger,
+    type WorkflowExtensionRef,
+} from './extensions';
 export {
     createDefaultWorkflowEngineHost,
     NoteActionRunner,
@@ -11,6 +19,14 @@ export {
     DbWorkflowPersistenceAdapter,
     MemoryWorkflowPersistenceAdapter,
 } from './persistence';
+export {
+    allowedEnv,
+    RUNTIME_BUILTIN_KEYS,
+    RunLifecycle,
+    type RunLifecycleDeps,
+    runtimeBuiltins,
+    type WorkflowMode,
+} from './run-lifecycle';
 export {
     ActionDefSchema,
     GuardDefSchema,
@@ -33,6 +49,7 @@ export type {
     GuardContext,
     GuardDef,
     GuardRunner,
+    OnErrorPolicy,
     StateDef,
     StateMachineWorkflowDef,
     TransitionDef,
@@ -45,4 +62,10 @@ export type {
     WorkflowRunResult,
     WorkflowStatus,
 } from './types';
-export { mergeVars, resolveTemplateString, resolveTemplates, type VariableContext } from './variables';
+export {
+    mergeVars,
+    resolveOnErrorPolicy,
+    resolveTemplateString,
+    resolveTemplates,
+    type VariableContext,
+} from './variables';

package/src/run-lifecycle.ts

@@ -0,0 +1,211 @@
+import { addSpanEvent, type EventBus, getLogger, type Logger, traceAsync } from '@gobing-ai/ts-infra';
+import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import type { WorkflowEngineEvents } from './events';
+import type {
+    WorkflowPersistenceAdapter,
+    WorkflowRunOptions,
+    WorkflowRunRecord,
+    WorkflowRunResult,
+    WorkflowStatus,
+} from './types';
+
+/** Workflow dialect carried on every run, span, and persisted record. */
+export type WorkflowMode = WorkflowRunResult['mode'];
+
+/** Keys of the runtime builtin namespace, single-sourced for resolver + validator. */
+export const RUNTIME_BUILTIN_KEYS = [
+    'workflow',
+    'runId',
+    'task',
+    'state',
+    'node',
+    'iteration',
+    'run',
+    'runtime',
+] as const;
+
+/** Built-in bare template values available to action options (state-machine + transition-flow). */
+export function runtimeBuiltins(
+    workflowName: string,
+    stateOrNodeId: string,
+    runId: string,
+    transitionsTaken: number,
+    mode: WorkflowMode,
+): Record<(typeof RUNTIME_BUILTIN_KEYS)[number], string | number> {
+    return {
+        workflow: workflowName,
+        runId,
+        task: workflowName,
+        state: stateOrNodeId,
+        node: stateOrNodeId,
+        iteration: transitionsTaken,
+        run: runId,
+        runtime: mode,
+    };
+}
+
+/** Project the env allowlist over a source map, dropping unset names. */
+export function allowedEnv(
+    names: readonly string[],
+    source: Record<string, string | undefined> = getProcessEnv(),
+): Record<string, string> {
+    return Object.fromEntries(
+        names.flatMap((name) => (source[name] === undefined ? [] : [[name, source[name] as string]])),
+    );
+}
+
+/** Dependencies a driver hands to {@link RunLifecycle}. */
+export interface RunLifecycleDeps {
+    readonly persistence: WorkflowPersistenceAdapter;
+    /** Observability sink; defaults to the shared `workflow` category logger. */
+    readonly logger?: Logger;
+    /** Optional event bus for structured in-process run observability. */
+    readonly events?: EventBus<WorkflowEngineEvents>;
+}
+
+/**
+ * Owns the run-level bookkeeping shared by both drivers: run identity, the
+ * create→phase→finalize persistence sequence, and observability (one OTel span
+ * per run plus structured log lines). The two driver control loops stay
+ * dialect-specific (ADR-006 §7) and call into this for every persistence touch.
+ */
+export class RunLifecycle {
+    readonly runId: string;
+    private readonly persistence: WorkflowPersistenceAdapter;
+    private readonly events: EventBus<WorkflowEngineEvents> | undefined;
+    private readonly logger: Logger;
+    private readonly startedAt: string;
+
+    private constructor(
+        runId: string,
+        private readonly workflowName: string,
+        private readonly mode: WorkflowMode,
+        deps: RunLifecycleDeps,
+    ) {
+        this.runId = runId;
+        this.persistence = deps.persistence;
+        this.events = deps.events;
+        this.startedAt = new Date().toISOString();
+        this.logger = (deps.logger ?? getLogger('workflow')).child({ runId, workflow: workflowName, mode });
+    }
+
+    /**
+     * Create the run record and execute `loop` inside the run's OTel span. The
+     * driver's control loop is the body; it receives this lifecycle to drive
+     * per-step persistence and terminal results.
+     */
+    static async run(
+        workflowName: string,
+        mode: WorkflowMode,
+        deps: RunLifecycleDeps,
+        options: WorkflowRunOptions,
+        loop: (lifecycle: RunLifecycle) => Promise<WorkflowRunResult>,
+    ): Promise<WorkflowRunResult> {
+        const runId = options.runId ?? crypto.randomUUID();
+        const lifecycle = new RunLifecycle(runId, workflowName, mode, deps);
+        return await traceAsync(
+            'workflow.run',
+            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 });
+                return await loop(lifecycle);
+            },
+            { attributes: { 'workflow.name': workflowName, 'workflow.mode': mode, 'workflow.run_id': runId } },
+        );
+    }
+
+    /** Persist the current state/node snapshot and mark its phase running. */
+    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 });
+        this.logger.debug('entered', { 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 });
+        this.logger.debug('transition', { from, to, trigger });
+    }
+
+    /** Finalize the run as succeeded and return its result. */
+    async done(finalState: string, transitionsTaken: number): Promise<WorkflowRunResult> {
+        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 });
+        return this.result('done', finalState, transitionsTaken);
+    }
+
+    /** Finalize the run as failed and return its result. */
+    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 });
+        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 });
+    }
+
+    /** 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 });
+    }
+
+    /** 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', {
+            node: stateOrNodeId,
+            transitionsTaken,
+            ...(error === undefined ? {} : { error }),
+        });
+        void this.events?.emit('workflow.action.failed_continue', {
+            node: stateOrNodeId,
+            transitionsTaken,
+            ...(error === undefined ? {} : { error }),
+        });
+        this.logger.warn('action failed (continuing)', { node: stateOrNodeId, transitionsTaken, error });
+    }
+
+    private result(
+        status: WorkflowStatus,
+        finalState: string,
+        transitionsTaken: number,
+        reason?: string,
+    ): WorkflowRunResult {
+        return {
+            runId: this.runId,
+            workflowName: this.workflowName,
+            mode: this.mode,
+            status,
+            finalState,
+            transitionsTaken,
+            ...(reason === undefined ? {} : { reason }),
+        };
+    }
+
+    private runRecord(metadata: unknown): WorkflowRunRecord {
+        return {
+            id: this.runId,
+            workflow_name: this.workflowName,
+            mode: this.mode,
+            status: 'running',
+            started_at: this.startedAt,
+            metadata_json: JSON.stringify(metadata ?? {}),
+            completed_at: null,
+        };
+    }
+}

package/src/schema-sql.ts

@@ -1,3 +1,4 @@
+/** SQL DDL for the dual-workflow engine's persistent schema — runs, phase_runs, transition_runs, and workflow_states tables. */
 export const WORKFLOW_ENGINE_SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS runs (
     id TEXT PRIMARY KEY,

package/src/schema.ts

@@ -27,6 +27,7 @@ const EnvSchema = z.object({
 export const ActionDefSchema = z.object({
     kind: z.string().min(1),
     options: z.record(z.string(), z.unknown()).optional(),
+    onError: z.enum(['fail', 'continue']).optional(),
 });
 
 /** Zod schema for workflow guard definitions. */
@@ -47,6 +48,7 @@ export const StateMachineWorkflowDefSchema = z
         initialState: z.string().min(1),
         terminalStates: z.array(z.string().min(1)).optional(),
         iterationBound: z.number().int().positive().optional(),
+        defaultOnError: z.enum(['fail', 'continue']).optional(),
         vars: VarsSchema.optional(),
         env: EnvSchema.optional(),
         states: z.array(
@@ -85,6 +87,7 @@ export const TransitionFlowWorkflowDefSchema = z
         initialNode: z.string().min(1),
         terminalNodes: z.array(z.string().min(1)).optional(),
         iterationBound: z.number().int().positive().optional(),
+        defaultOnError: z.enum(['fail', 'continue']).optional(),
         vars: VarsSchema.optional(),
         env: EnvSchema.optional(),
         nodes: z.array(