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

package/dist/extensions.d.ts

@@ -0,0 +1,60 @@
+import type { Logger } from '@gobing-ai/ts-infra';
+import type { WorkflowEngineHost } from './host';
+/** 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 declare function loadWorkflowExtensionsIntoHost(host: WorkflowEngineHost, refs: readonly WorkflowExtensionRef[], options: LoadWorkflowExtensionsOptions): Promise<void>;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAKlD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAGjD,6GAA6G;AAC7G,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACjC,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,8BAA8B,CAChD,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,SAAS,oBAAoB,EAAE,EACrC,OAAO,EAAE,6BAA6B,GACvC,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/extensions.js

@@ -0,0 +1,85 @@
+import { basenamePath, dirnamePath, SEP } from '@gobing-ai/ts-runtime';
+import { loadExtensionModules } from '@gobing-ai/ts-runtime/plugin';
+import { WorkflowValidationError } from './errors.js';
+/**
+ * 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, refs, options) {
+    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 = refs.map((ref) => ({
+        kind: ref.kind,
+        path: `./${basenamePath(ref.absPath)}`,
+        baseDir: dirnamePath(ref.absPath),
+        sourceName: ref.sourceName,
+    }));
+    const sharedOptions = {
+        allowExtensions: options.allowExtensions,
+        logger: options.logger,
+        moduleLoader: options.moduleLoader,
+    };
+    await loadExtensionModules(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, ref, extension, logger) {
+    const name = extension.name;
+    if (ref.kind === 'actions') {
+        const actions = extension.actions;
+        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;
+        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, kind, capabilityType, sourceName, logger) {
+    const origin = capabilityType === 'action' ? host.actionOrigin(kind) : host.guardOrigin(kind);
+    if (logger && origin === 'builtin') {
+        logger.warn(`"${sourceName}" extension overrides built-in ${capabilityType} "${kind}"`);
+    }
+}

package/dist/index.d.ts

@@ -1,12 +1,15 @@
 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, ShellActionRunner, WorkflowEngineHost, } from './host';
 export { applyWorkflowEngineSchema, DbWorkflowPersistenceAdapter, MemoryWorkflowPersistenceAdapter, } from './persistence';
+export { allowedEnv, RUNTIME_BUILTIN_KEYS, RunLifecycle, type RunLifecycleDeps, runtimeBuiltins, type WorkflowMode, } from './run-lifecycle';
 export { ActionDefSchema, GuardDefSchema, StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema, WorkflowDefSchema, } from './schema';
 export { WORKFLOW_ENGINE_SCHEMA_SQL } from './schema-sql';
 export { WorkflowService } from './service';
 export { StateMachineDriver, type StateMachineDriverOptions } from './state-machine';
 export { TransitionFlowDriver, type TransitionFlowDriverOptions } from './transition-flow';
-export type { ActionDef, ActionResult, ActionRunContext, ActionRunner, Env, FlowEdgeDef, FlowNodeDef, GuardContext, GuardDef, GuardRunner, StateDef, StateMachineWorkflowDef, TransitionDef, TransitionFlowWorkflowDef, Vars, WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunRecord, WorkflowRunResult, WorkflowStatus, } from './types';
-export { mergeVars, resolveTemplateString, resolveTemplates, type VariableContext } from './variables';
+export type { ActionDef, ActionResult, ActionRunContext, ActionRunner, Env, FlowEdgeDef, FlowNodeDef, GuardContext, GuardDef, GuardRunner, OnErrorPolicy, StateDef, StateMachineWorkflowDef, TransitionDef, TransitionFlowWorkflowDef, Vars, WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunRecord, WorkflowRunResult, WorkflowStatus, } from './types';
+export { mergeVars, resolveOnErrorPolicy, resolveTemplateString, resolveTemplates, type VariableContext, } from './variables';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,EACH,+BAA+B,EAC/B,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GACrB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACH,yBAAyB,EACzB,4BAA4B,EAC5B,gCAAgC,GACnC,MAAM,eAAe,CAAC;AACvB,OAAO,EACH,eAAe,EACf,cAAc,EACd,6BAA6B,EAC7B,+BAA+B,EAC/B,iBAAiB,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC3F,YAAY,EACR,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,GAAG,EACH,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,uBAAuB,EACvB,aAAa,EACb,yBAAyB,EACzB,IAAI,EACJ,WAAW,EACX,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAChF,YAAY,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EACH,KAAK,6BAA6B,EAClC,8BAA8B,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EACH,+BAA+B,EAC/B,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GACrB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACH,yBAAyB,EACzB,4BAA4B,EAC5B,gCAAgC,GACnC,MAAM,eAAe,CAAC;AACvB,OAAO,EACH,UAAU,EACV,oBAAoB,EACpB,YAAY,EACZ,KAAK,gBAAgB,EACrB,eAAe,EACf,KAAK,YAAY,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACH,eAAe,EACf,cAAc,EACd,6BAA6B,EAC7B,+BAA+B,EAC/B,iBAAiB,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC3F,YAAY,EACR,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,GAAG,EACH,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,aAAa,EACb,QAAQ,EACR,uBAAuB,EACvB,aAAa,EACb,yBAAyB,EACzB,IAAI,EACJ,WAAW,EACX,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EACH,SAAS,EACT,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,eAAe,GACvB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,10 +1,12 @@
 export { loadWorkflowDef, loadWorkflowDefFromText, validateWorkflowDef } from './config.js';
 export { FSMError, RunCollisionError, WorkflowValidationError } from './errors.js';
+export { loadWorkflowExtensionsIntoHost, } from './extensions.js';
 export { createDefaultWorkflowEngineHost, NoteActionRunner, ShellActionRunner, WorkflowEngineHost, } from './host.js';
 export { applyWorkflowEngineSchema, DbWorkflowPersistenceAdapter, MemoryWorkflowPersistenceAdapter, } from './persistence.js';
+export { allowedEnv, RUNTIME_BUILTIN_KEYS, RunLifecycle, runtimeBuiltins, } from './run-lifecycle.js';
 export { ActionDefSchema, GuardDefSchema, StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema, WorkflowDefSchema, } from './schema.js';
 export { WORKFLOW_ENGINE_SCHEMA_SQL } from './schema-sql.js';
 export { WorkflowService } from './service.js';
 export { StateMachineDriver } from './state-machine.js';
 export { TransitionFlowDriver } from './transition-flow.js';
-export { mergeVars, resolveTemplateString, resolveTemplates } from './variables.js';
+export { mergeVars, resolveOnErrorPolicy, resolveTemplateString, resolveTemplates, } from './variables.js';

package/dist/run-lifecycle.d.ts

@@ -0,0 +1,58 @@
+import { type EventBus, type Logger } from '@gobing-ai/ts-infra';
+import type { WorkflowEngineEvents } from './events';
+import type { WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunResult } 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 declare const RUNTIME_BUILTIN_KEYS: readonly ["workflow", "runId", "task", "state", "node", "iteration", "run", "runtime"];
+/** Built-in bare template values available to action options (state-machine + transition-flow). */
+export declare function runtimeBuiltins(workflowName: string, stateOrNodeId: string, runId: string, transitionsTaken: number, mode: WorkflowMode): Record<(typeof RUNTIME_BUILTIN_KEYS)[number], string | number>;
+/** Project the env allowlist over a source map, dropping unset names. */
+export declare function allowedEnv(names: readonly string[], source?: Record<string, string | undefined>): Record<string, 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 declare class RunLifecycle {
+    private readonly workflowName;
+    private readonly mode;
+    readonly runId: string;
+    private readonly persistence;
+    private readonly events;
+    private readonly logger;
+    private readonly startedAt;
+    private constructor();
+    /**
+     * 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 run(workflowName: string, mode: WorkflowMode, deps: RunLifecycleDeps, options: WorkflowRunOptions, loop: (lifecycle: RunLifecycle) => Promise<WorkflowRunResult>): Promise<WorkflowRunResult>;
+    /** Persist the current state/node snapshot and mark its phase running. */
+    enter(stateOrNodeId: string, transitionsTaken: number): Promise<void>;
+    /** Persist a transition and emit its observability event. */
+    recordTransition(from: string, to: string, trigger: string | null): Promise<void>;
+    /** Finalize the run as succeeded and return its result. */
+    done(finalState: string, transitionsTaken: number): Promise<WorkflowRunResult>;
+    /** Finalize the run as failed and return its result. */
+    fail(finalState: string, transitionsTaken: number, reason?: string): Promise<WorkflowRunResult>;
+    /** Emit action-level observability before a host action is invoked. */
+    actionStart(stateOrNodeId: string, kind: string): void;
+    /** Emit action-level observability after a host action settles. */
+    actionDone(stateOrNodeId: string, kind: string, durationMs: number, ok: boolean): void;
+    /** 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;
+    private result;
+    private runRecord;
+}
+//# sourceMappingURL=run-lifecycle.d.ts.map

package/dist/run-lifecycle.d.ts.map

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

package/dist/run-lifecycle.js

@@ -0,0 +1,149 @@
+import { addSpanEvent, getLogger, traceAsync } from '@gobing-ai/ts-infra';
+import { getProcessEnv } from '@gobing-ai/ts-runtime';
+/** Keys of the runtime builtin namespace, single-sourced for resolver + validator. */
+export const RUNTIME_BUILTIN_KEYS = [
+    'workflow',
+    'runId',
+    'task',
+    'state',
+    'node',
+    'iteration',
+    'run',
+    'runtime',
+];
+/** Built-in bare template values available to action options (state-machine + transition-flow). */
+export function runtimeBuiltins(workflowName, stateOrNodeId, runId, transitionsTaken, mode) {
+    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, source = getProcessEnv()) {
+    return Object.fromEntries(names.flatMap((name) => (source[name] === undefined ? [] : [[name, source[name]]])));
+}
+/**
+ * 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 {
+    workflowName;
+    mode;
+    runId;
+    persistence;
+    events;
+    logger;
+    startedAt;
+    constructor(runId, workflowName, mode, deps) {
+        this.workflowName = workflowName;
+        this.mode = mode;
+        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, mode, deps, options, loop) {
+        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, transitionsTaken) {
+        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, to, trigger) {
+        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, transitionsTaken) {
+        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, transitionsTaken, reason = 'failed') {
+        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, kind) {
+        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, kind, durationMs, ok) {
+        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, transitionsTaken, error) {
+        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 });
+    }
+    result(status, finalState, transitionsTaken, reason) {
+        return {
+            runId: this.runId,
+            workflowName: this.workflowName,
+            mode: this.mode,
+            status,
+            finalState,
+            transitionsTaken,
+            ...(reason === undefined ? {} : { reason }),
+        };
+    }
+    runRecord(metadata) {
+        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/dist/schema-sql.d.ts

@@ -1,2 +1,3 @@
+/** SQL DDL for the dual-workflow engine's persistent schema — runs, phase_runs, transition_runs, and workflow_states tables. */
 export declare const WORKFLOW_ENGINE_SCHEMA_SQL: string;
 //# sourceMappingURL=schema-sql.d.ts.map

package/dist/schema-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-sql.d.ts","sourceRoot":"","sources":["../src/schema-sql.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,QA+C/B,CAAC"}
+{"version":3,"file":"schema-sql.d.ts","sourceRoot":"","sources":["../src/schema-sql.ts"],"names":[],"mappings":"AAAA,gIAAgI;AAChI,eAAO,MAAM,0BAA0B,QA+C/B,CAAC"}

package/dist/schema-sql.js

@@ -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/dist/schema.d.ts

@@ -3,6 +3,10 @@ import { z } from 'zod';
 export declare const ActionDefSchema: z.ZodObject<{
     kind: z.ZodString;
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    onError: z.ZodOptional<z.ZodEnum<{
+        fail: "fail";
+        continue: "continue";
+    }>>;
 }, z.core.$strip>;
 /** Zod schema for workflow guard definitions. */
 export declare const GuardDefSchema: z.ZodObject<{
@@ -19,6 +23,10 @@ export declare const StateMachineWorkflowDefSchema: z.ZodObject<{
     initialState: z.ZodString;
     terminalStates: z.ZodOptional<z.ZodArray<z.ZodString>>;
     iterationBound: z.ZodOptional<z.ZodNumber>;
+    defaultOnError: z.ZodOptional<z.ZodEnum<{
+        fail: "fail";
+        continue: "continue";
+    }>>;
     vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     env: z.ZodOptional<z.ZodObject<{
         allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -29,10 +37,18 @@ export declare const StateMachineWorkflowDefSchema: z.ZodObject<{
         onEnter: z.ZodOptional<z.ZodArray<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            onError: z.ZodOptional<z.ZodEnum<{
+                fail: "fail";
+                continue: "continue";
+            }>>;
         }, z.core.$strip>>>;
         onExit: z.ZodOptional<z.ZodArray<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            onError: z.ZodOptional<z.ZodEnum<{
+                fail: "fail";
+                continue: "continue";
+            }>>;
         }, z.core.$strip>>>;
     }, z.core.$strict>>;
     transitions: z.ZodArray<z.ZodObject<{
@@ -56,6 +72,10 @@ export declare const TransitionFlowWorkflowDefSchema: z.ZodObject<{
     initialNode: z.ZodString;
     terminalNodes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     iterationBound: z.ZodOptional<z.ZodNumber>;
+    defaultOnError: z.ZodOptional<z.ZodEnum<{
+        fail: "fail";
+        continue: "continue";
+    }>>;
     vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     env: z.ZodOptional<z.ZodObject<{
         allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -72,6 +92,10 @@ export declare const TransitionFlowWorkflowDefSchema: z.ZodObject<{
         action: z.ZodOptional<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            onError: z.ZodOptional<z.ZodEnum<{
+                fail: "fail";
+                continue: "continue";
+            }>>;
         }, z.core.$strip>>;
     }, z.core.$strict>>;
     edges: z.ZodArray<z.ZodObject<{
@@ -94,6 +118,10 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
     initialState: z.ZodString;
     terminalStates: z.ZodOptional<z.ZodArray<z.ZodString>>;
     iterationBound: z.ZodOptional<z.ZodNumber>;
+    defaultOnError: z.ZodOptional<z.ZodEnum<{
+        fail: "fail";
+        continue: "continue";
+    }>>;
     vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     env: z.ZodOptional<z.ZodObject<{
         allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -104,10 +132,18 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
         onEnter: z.ZodOptional<z.ZodArray<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            onError: z.ZodOptional<z.ZodEnum<{
+                fail: "fail";
+                continue: "continue";
+            }>>;
         }, z.core.$strip>>>;
         onExit: z.ZodOptional<z.ZodArray<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            onError: z.ZodOptional<z.ZodEnum<{
+                fail: "fail";
+                continue: "continue";
+            }>>;
         }, z.core.$strip>>>;
     }, z.core.$strict>>;
     transitions: z.ZodArray<z.ZodObject<{
@@ -129,6 +165,10 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
     initialNode: z.ZodString;
     terminalNodes: z.ZodOptional<z.ZodArray<z.ZodString>>;
     iterationBound: z.ZodOptional<z.ZodNumber>;
+    defaultOnError: z.ZodOptional<z.ZodEnum<{
+        fail: "fail";
+        continue: "continue";
+    }>>;
     vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     env: z.ZodOptional<z.ZodObject<{
         allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -145,6 +185,10 @@ export declare const WorkflowDefSchema: z.ZodUnion<readonly [z.ZodObject<{
         action: z.ZodOptional<z.ZodObject<{
             kind: z.ZodString;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            onError: z.ZodOptional<z.ZodEnum<{
+                fail: "fail";
+                continue: "continue";
+            }>>;
         }, z.core.$strip>>;
     }, z.core.$strict>>;
     edges: z.ZodArray<z.ZodObject<{

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;AAyBxB,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;iBAG1B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,yDAAyD;AACzD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmC7B,CAAC;AAEd,2DAA2D;AAC3D,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkC/B,CAAC;AAEd,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAA4E,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;;;;;iBAI1B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;iBAGzB,CAAC;AAEH,yDAAyD;AACzD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoC7B,CAAC;AAEd,2DAA2D;AAC3D,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmC/B,CAAC;AAEd,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAA4E,CAAC"}

package/dist/schema.js

@@ -22,6 +22,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. */
 export const GuardDefSchema = z.object({
@@ -40,6 +41,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(z
@@ -73,6 +75,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(z

package/dist/state-machine.d.ts

@@ -11,8 +11,13 @@ export declare class StateMachineDriver {
     constructor(options: StateMachineDriverOptions);
     /** Run a state-machine workflow to completion or failure. */
     run(workflow: StateMachineWorkflowDef, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    private loop;
+    /**
+     * Run a state's actions in order. Returns the last action result (retained even
+     * when a failure was continued past, so downstream guards can inspect it) plus an
+     * `outcome` discriminator: `terminal` (an action declared terminal success),
+     * `fail` (a failure under a 'fail' policy — caller must halt), or `completed`.
+     */
     private runActions;
-    private done;
-    private fail;
 }
 //# sourceMappingURL=state-machine.d.ts.map

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

@@ -1 +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;YA8G5F,UAAU;YA8BV,IAAI;YAYJ,IAAI;CAYrB"}
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,OAAO,KAAK,EAIR,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,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;YAU5F,IAAI;IA6FlB;;;;;OAKG;YACW,UAAU;CA0C3B"}