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

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/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(