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

package/README.md

@@ -1,6 +1,6 @@
 # @gobing-ai/ts-dual-workflow-engine
 
-State-machine and transition-flow workflow runtime with pluggable action runners, guard runners, and memory or database persistence.
+State-machine and transition-flow workflow runtime with pluggable action runners, guard runners, trust-gated extension loading, and memory or database persistence.
 
 ## What It Provides
 
@@ -18,11 +18,243 @@ The package exposes:
 | `WorkflowService` | High-level loader and runner for both workflow kinds |
 | `StateMachineDriver` | Direct state-machine execution |
 | `TransitionFlowDriver` | Direct transition-flow execution |
-| `WorkflowEngineHost` | Registry for action runners and guard runners |
+| `WorkflowEngineHost` | Capability registry for action runners and guard runners |
+| `createDefaultWorkflowEngineHost()` | Creates a host with built-in `note`, `shell`, and `always` capabilities |
+| `NoteActionRunner` | Built-in action that records a note in result data |
+| `ShellActionRunner` | Built-in shell action backed by `@gobing-ai/ts-runtime` `ProcessExecutor` |
+| `RunLifecycle` | Shared run bookkeeping: identity, persistence sequencing, OTel spans, structured logging, and optional event bus emission |
 | `MemoryWorkflowPersistenceAdapter` | In-memory persistence for tests and short-lived runs |
 | `DbWorkflowPersistenceAdapter` | DB-backed persistence over `@gobing-ai/ts-db` |
-| `loadWorkflowDef()` / `loadWorkflowDefFromText()` | YAML workflow loading and validation |
 | `applyWorkflowEngineSchema()` | Installs the package-owned DB schema |
+| `WORKFLOW_ENGINE_SCHEMA_SQL` | Raw SQL DDL for the workflow engine tables |
+| `loadWorkflowDef()` / `loadWorkflowDefFromText()` | YAML/JSON workflow loading and validation |
+| `validateWorkflowDef()` | Semantic invariant checking beyond Zod schema |
+| `loadWorkflowExtensionsIntoHost()` | Trust-gated extension module loading for actions and guards |
+| `mergeVars()` / `resolveTemplates()` / `resolveTemplateString()` | Variable merging and `${...}` template resolution |
+| `resolveOnErrorPolicy()` | Resolves effective `OnErrorPolicy` from action, workflow default, and run options |
+| `OnErrorPolicy` | Type: `'fail' | 'continue'` — action error-handling strategy |
+| `allowedEnv()` / `runtimeBuiltins()` | Environment allowlist projection and built-in template injection |
+| `StateMachineWorkflowDefSchema` / `TransitionFlowWorkflowDefSchema` / `WorkflowDefSchema` | Zod schemas for workflow definition validation |
+| `ActionDefSchema` / `GuardDefSchema` | Zod schemas for action and guard definitions |
+| `FSMError` / `WorkflowValidationError` / `RunCollisionError` | Structured error classes |
+| `WorkflowExtensionRef` / `LoadWorkflowExtensionsOptions` / `WorkflowExtensionKind` | Extension loading types |
+| `ActionRunner` / `GuardRunner` / `WorkflowDef` / `WorkflowRunResult` … | Type-only exports for all domain types |
+| `WorkflowEngineEvents` | Typed event map for workflow-engine observability. All events prefixed `workflow.` — see [Observability](#observability) |
+
+## Architecture
+
+### Component Relationships
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   WorkflowService                     │
+│  load(path) → WorkflowDef                            │
+│  run(WorkflowDef, options) → WorkflowRunResult       │
+│  listRuns() → WorkflowRunRecord[]                    │
+└──────────────┬───────────────────────┬───────────────┘
+               │ dispatches on          │
+               │ workflow.kind          │
+       ┌───────▼───────┐       ┌───────▼───────┐
+       │ StateMachine  │       │ TransitionFlow│
+       │   Driver      │       │   Driver      │
+       └───────┬───────┘       └───────┬───────┘
+               │                       │
+               │  both delegate to     │
+               │                       │
+       ┌───────▼───────────────────────▼───────┐
+       │           RunLifecycle                 │
+       │  • run identity (runId)                │
+       │  • persistence (createRun, savePhase,  │
+       │    saveTransition, finalizeRun)        │
+       │  • OTel span + structured logging      │
+       └───────────────┬───────────────────────┘
+                       │
+          ┌────────────┼────────────┐
+          ▼            ▼            ▼
+   ┌──────────┐ ┌──────────┐ ┌──────────┐
+   │Persistence│ │  Host    │ │ Variables│
+   │ Adapter  │ │ (actions │ │ (merge,  │
+   │ (memory  │ │ + guards)│ │ resolve) │
+   │  or DB)  │ │          │ │          │
+   └──────────┘ └──────────┘ └──────────┘
+```
+
+### State-Machine Step Execution
+The state-machine driver runs a loop until reaching a terminal state, failure, or iteration bound. Each iteration:
+
+1. Persists the state snapshot and marks its phase `running`
+2. Executes the state's `onEnter` actions in declaration order
+3. Checks for early termination (action `terminal: true` or terminal state with no outbound transitions)
+4. Evaluates transition guards in declaration order; picks the first passing one
+5. Executes the state's `onExit` actions
+6. Persists the transition and moves to the target state
+
+If an action fails and the resolved `onError` policy is `'fail'` (default), the run stops immediately with
+`status: 'failed'`. When `'continue'`, a non-fatal warning is logged via `RunLifecycle.warnActionFailed()`
+and the run advances to the next guard evaluation or transition.
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant SM as StateMachineDriver
+    participant RL as RunLifecycle
+    participant P as PersistenceAdapter
+    participant H as WorkflowEngineHost
+
+    Caller->>SM: run(workflow, options)
+    SM->>RL: RunLifecycle.run(name, mode, deps, options, loop)
+
+    rect rgb(240, 248, 255)
+        Note over RL,P: RunLifecycle bootstrap
+        RL->>RL: generate runId (or use caller-provided)
+        RL->>P: createRun(runRecord)
+        P-->>RL: ok
+        RL->>SM: invoke loop(lifecycle)
+
+        loop Each state
+            SM->>RL: enter(stateId, transitionsTaken)
+            RL->>P: saveWorkflowState(stateId, data)
+            RL->>P: savePhase(stateId, 'running')
+
+            alt state has onEnter actions
+                SM->>SM: resolveTemplates(action.options)
+                SM->>SM: runtimeBuiltins(workflow, state, runId, n, mode)
+                SM->>H: runAction(kind, resolvedOptions, context)
+                H-->>SM: ActionResult { ok, terminal?, error? }
+                alt action failed
+                    SM->>RL: fail(stateId, n, error)
+                    RL->>P: savePhase(stateId, 'failed')
+                    RL->>P: finalizeRun(runId, 'failed')
+                    RL-->>SM: WorkflowRunResult { status: 'failed' }
+                    SM-->>Caller: failed result
+                else action marked terminal
+                    SM->>RL: done(stateId, n)
+                    RL->>P: savePhase(stateId, 'done')
+                    RL->>P: finalizeRun(runId, 'done')
+                    RL-->>SM: WorkflowRunResult { status: 'done' }
+                    SM-->>Caller: done result
+                end
+            end
+
+            alt terminal state or no outbound transitions
+                SM->>RL: done(stateId, n)
+                RL->>P: savePhase(stateId, 'done')
+                RL->>P: finalizeRun(runId, 'done')
+                RL-->>SM: WorkflowRunResult { status: 'done' }
+                SM-->>Caller: done result
+            end
+
+            SM->>H: evaluateGuard(guard.kind, guard.options, context)
+            H-->>SM: true | false
+            alt no guard passes
+                SM->>RL: fail(stateId, n, 'no-passing-transition')
+                RL-->>SM: failed result
+                SM-->>Caller: failed result
+            end
+
+            alt state has onExit actions
+                SM->>H: runAction(kind, resolvedOptions, context)
+                H-->>SM: ActionResult
+            end
+
+            SM->>RL: recordTransition(from, to, trigger)
+            RL->>P: saveTransition(runId, from, to, trigger)
+            SM->>SM: transitionsTaken += 1
+
+            alt iteration bound exceeded
+                SM->>RL: fail(stateId, n, 'iteration-bound-exceeded')
+                RL-->>SM: failed result
+                SM-->>Caller: failed result
+            end
+        end
+    end
+```
+
+### Transition-Flow Step Execution
+
+The transition-flow driver iterates through nodes and edges until reaching a terminal node, failure, or iteration bound. Each iteration:
+
+1. Persists the node snapshot and marks its phase `running`
+2. Executes the node's action (if configured)
+3. Checks for early termination (action `terminal: true` or terminal node with no outgoing edges)
+4. Evaluates edge conditions in declaration order; picks the first passing edge (or unconditionally follows an edge with no condition)
+5. Persists the edge transition and moves to the target node
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant TF as TransitionFlowDriver
+    participant RL as RunLifecycle
+    participant P as PersistenceAdapter
+    participant H as WorkflowEngineHost
+
+    Caller->>TF: run(workflow, options)
+    TF->>RL: RunLifecycle.run(name, mode, deps, options, loop)
+
+    rect rgb(255, 248, 240)
+        Note over RL,P: RunLifecycle bootstrap
+        RL->>RL: generate runId (or use caller-provided)
+        RL->>P: createRun(runRecord)
+        P-->>RL: ok
+        RL->>TF: invoke loop(lifecycle)
+
+        loop Each node
+            TF->>RL: enter(nodeId, transitionsTaken)
+            RL->>P: saveWorkflowState(nodeId, data)
+            RL->>P: savePhase(nodeId, 'running')
+
+            alt node has action
+                TF->>TF: resolveTemplates(action.options)
+                TF->>TF: runtimeBuiltins(workflow, node, runId, n, mode)
+                TF->>H: runAction(kind, resolvedOptions, context)
+                H-->>TF: ActionResult { ok, terminal?, error? }
+                alt action failed
+                    TF->>RL: fail(nodeId, n, error)
+                    RL->>P: savePhase(nodeId, 'failed')
+                    RL->>P: finalizeRun(runId, 'failed')
+                    RL-->>TF: WorkflowRunResult { status: 'failed' }
+                    TF-->>Caller: failed result
+                else action marked terminal
+                    TF->>RL: done(nodeId, n)
+                    RL->>P: savePhase(nodeId, 'done')
+                    RL->>P: finalizeRun(runId, 'done')
+                    RL-->>TF: WorkflowRunResult { status: 'done' }
+                    TF-->>Caller: done result
+                end
+            end
+
+            alt terminal node or no outgoing edges
+                TF->>RL: done(nodeId, n)
+                RL->>P: savePhase(nodeId, 'done')
+                RL->>P: finalizeRun(runId, 'done')
+                RL-->>TF: WorkflowRunResult { status: 'done' }
+                TF-->>Caller: done result
+            end
+
+            alt edge has condition
+                TF->>H: evaluateGuard(condition.kind, condition.options, context)
+                H-->>TF: true | false
+                alt no condition passes
+                    TF->>RL: fail(nodeId, n, 'no-passing-edge')
+                    RL-->>TF: failed result
+                    TF-->>Caller: failed result
+                end
+            else edge is unconditional
+                Note over TF: proceed immediately
+            end
+
+            TF->>RL: recordTransition(from, to, trigger)
+            RL->>P: saveTransition(runId, from, to, trigger)
+            TF->>TF: transitionsTaken += 1
+
+            alt iteration bound exceeded
+                TF->>RL: fail(nodeId, n, 'iteration-bound-exceeded')
+                RL-->>TF: failed result
+                TF-->>Caller: failed result
+            end
+        end
+    end
+```
 
 ## Installation
 
@@ -78,6 +310,29 @@ const result = await driver.run(
 result.status; // "done"
 result.finalState; // "done"
 captureAction.seen; // ["approved"]
+
+// A workflow with error resilience — non-fatal failures log and continue.
+const host2 = new WorkflowEngineHost()
+    .registerAction(failableAction)
+    .registerGuard({ kind: 'always', evaluate: async () => true });
+
+const resilientDriver = new StateMachineDriver({
+    host: host2,
+    persistence: new MemoryWorkflowPersistenceAdapter(),
+});
+
+const resilientResult = await resilientDriver.run({
+    name: 'resilient-approval',
+    initialState: 'draft',
+    terminalStates: ['done'],
+    defaultOnError: 'continue', // workflow-level default
+    states: [
+        { id: 'draft', onEnter: [{ kind: 'audit', onError: 'fail' }] }, // overrides to fail-fast for audits
+        { id: 'done' },
+    ],
+    transitions: [{ from: 'draft', to: 'done', guard: { kind: 'always' } }],
+});
+
 ```
 
 The driver persists each state snapshot, phase update, transition, and final run status through the configured persistence adapter.
@@ -233,7 +488,11 @@ Actions receive resolved template values. The engine supports:
 | `${env.NAME}` | Environment values explicitly allowed by workflow config |
 | `${runId}` | Current run ID |
 | `${workflow}` | Workflow name |
-| `${state}` | Current state or node ID |
+| `${state}` / `${node}` | Current state or node ID |
+| `${task}` | Workflow name (alias) |
+| `${iteration}` | Current transition count |
+| `${run}` | Run ID (alias) |
+| `${runtime}` | Execution mode (`state-machine` or `transition-flow`) |
 
 ```ts
 await service.run(workflow, {
@@ -267,12 +526,254 @@ const service = new WorkflowService(
 
 Use `service.listRuns()` to read persisted run records. The adapter stores run status, phase snapshots, state snapshots, and transitions.
 
+## Custom Actions and Guards
+
+Register domain-specific runners directly on the host:
+
+```ts
+import { WorkflowEngineHost } from '@gobing-ai/ts-dual-workflow-engine';
+
+const host = new WorkflowEngineHost();
+
+// Custom action
+host.registerAction({
+  kind: 'send-email',
+  async execute(options, context) {
+    await mailer.send(String(options.to), String(options.subject));
+    return { ok: true };
+  },
+});
+
+// Custom guard
+host.registerGuard({
+  kind: 'isBusinessHours',
+  async evaluate() {
+    const hour = new Date().getHours();
+    return hour >= 9 && hour < 17;
+  },
+});
+```
+
+Registered actions and guards are available to any workflow definition by their `kind` string. Internally, the host uses `CapabilityRegistry` from `@gobing-ai/ts-runtime/plugin` to track registrations with origin metadata (`'builtin'`, `'extension'`, or `'core'`).
+
+## Extension Loading
+
+For modules that bundle multiple actions and/or guards together, use the trust-gated extension loader. Each extension module must export an object with a string `name` and an `actions[]` and/or `guards[]` array:
+
+```ts
+// my-extension.ts — extension module (compiled separately or in-project)
+export default {
+  name: 'my-workflow-extensions',
+  actions: [
+    {
+      kind: 'audit-log',
+      async execute(options) {
+        console.log('AUDIT', options.event);
+        return { ok: true };
+      },
+    },
+  ],
+  guards: [
+    {
+      kind: 'feature-flag',
+      async evaluate(options) {
+        return featureFlags.isEnabled(String(options.flag));
+      },
+    },
+  ],
+};
+```
+
+```ts
+import {
+  loadWorkflowExtensionsIntoHost,
+  WorkflowEngineHost,
+} from '@gobing-ai/ts-dual-workflow-engine';
+
+const host = new WorkflowEngineHost();
+
+await loadWorkflowExtensionsIntoHost(
+  host,
+  [{ kind: 'actions', absPath: '/path/to/my-extension.ts', sourceName: 'my-config' }],
+  {
+    allowExtensions: true,        // required — disabled by default
+    moduleLoader: (absPath) => import(absPath),
+  },
+);
+```
+
+Each entry in `actions[]` is registered via `host.registerAction(..., 'extension')`; entries in `guards[]` are registered via `host.registerGuard(..., 'extension')`. When a ref has `kind: 'actions'`, only the module's `actions[]` entries are registered; `guards[]` entries in the same module are ignored (and vice versa).
+
+Override warnings are emitted through an optional `logger.warn` callback when an extension replaces a built-in capability:
+
+```ts
+await loadWorkflowExtensionsIntoHost(host, refs, {
+  allowExtensions: true,
+  moduleLoader: (absPath) => import(absPath),
+  logger: { warn: (msg) => console.warn(msg) },
+});
+```
+
+### Security
+
+**Extension modules execute arbitrary code.** The trust gate is fail-closed:
+
+- `allowExtensions` defaults to `false`. When refs are present and loading is not explicitly allowed, the loader throws **before any import** — a declared extension is never silently dropped.
+- Extension paths are validated at load time; `..` traversal is rejected.
+- The caller controls the `moduleLoader` function. Tests use a stub; production callers use `(absPath) => import(absPath)`. The loader itself has no ambient code-loading capability.
+
+## Zod Schemas
+
+The package exports Zod schemas for programmatic validation:
+
+```ts
+import { StateMachineWorkflowDefSchema, WorkflowDefSchema } from '@gobing-ai/ts-dual-workflow-engine';
+
+// Parse and validate an unknown object as a state-machine workflow
+const workflow = StateMachineWorkflowDefSchema.parse(rawObject);
+
+// Parse and validate as either workflow kind
+const def = WorkflowDefSchema.parse(rawObject);
+```
+
+`WorkflowDefSchema` is a `z.union` of `StateMachineWorkflowDefSchema` and `TransitionFlowWorkflowDefSchema`. `ActionDefSchema` and `GuardDefSchema` validate individual action/guard definitions.
+
+## Variable Utilities
+
+Low-level template resolution is available for callers that build workflow-adjacent tooling:
+
+```ts
+import { mergeVars, resolveTemplates, resolveTemplateString, runtimeBuiltins } from '@gobing-ai/ts-dual-workflow-engine';
+
+// Merge workflow-level vars with per-run overrides
+const vars = mergeVars({ file: 'default.jsonl' }, { file: 'override.jsonl' });
+// { file: 'override.jsonl' }
+
+// Resolve templates in an options object
+const resolved = resolveTemplates(
+  { message: 'Hello ${vars.name}', count: '${iteration}' },
+  { vars: { name: 'Robin' }, env: {}, builtins: { iteration: 3 } },
+);
+// { message: 'Hello Robin', count: '3' }
+
+// Single-string resolution
+resolveTemplateString('Run ${runId} in ${runtime}', {
+  vars: {}, env: {},
+  builtins: { runId: 'abc', runtime: 'state-machine' },
+});
+// "Run abc in state-machine"
+```
+
+## Observability
+
+The workflow engine uses a **three-layer observability model** (ADR-015):
+
+| Layer | Tool | Consumer |
+|-------|------|----------|
+| Logs | `getLogger('workflow')` (run-scoped via `child()`) | Human-readable debugging / file output |
+| Traces | `traceAsync('workflow.run')` + `addSpanEvent` per step | Distributed perf correlation (OTel) |
+| Events | `EventBus<WorkflowEngineEvents>` | Programmatic in-process subscription (progress bars, CI dashboards) |
+
+All three layers are **additive** — EventBus does not replace logging or tracing. A consumer who wants a progress bar subscribes to events; a consumer who wants traces attaches an OTel collector; both work independently.
+
+### Event Map
+
+`WorkflowEngineEvents` is a typed event map. All events are prefixed `workflow.`:
+
+| Event | Payload | When |
+|-------|---------|------|
+| `workflow.run.started` | `{ workflowName, mode, runId }` | When a run begins (inside the span) |
+| `workflow.run.done` | `{ finalState, transitionsTaken }` | When a run completes successfully |
+| `workflow.run.failed` | `{ finalState, reason }` | When a run fails |
+| `workflow.node.enter` | `{ node, transitionsTaken }` | When entering a state or node |
+| `workflow.node.transition` | `{ from, to, trigger }` | On a state/node transition |
+| `workflow.action.start` | `{ node, kind }` | When an action starts executing |
+| `workflow.action.done` | `{ node, kind, durationMs, ok }` | When an action finishes (success or failure) |
+| `workflow.action.failed_continue` | `{ node, transitionsTaken, error? }` | When a non-fatal action failure is continued past (`onError: 'continue'`) |
+
+### Usage
+
+Pass an `EventBus` via `WorkflowRunOptions.events`:
+
+```ts
+import { WorkflowService, createDefaultWorkflowEngineHost, MemoryWorkflowPersistenceAdapter } from '@gobing-ai/ts-dual-workflow-engine';
+import { EventBus } from '@gobing-ai/ts-infra';
+import type { WorkflowEngineEvents } from '@gobing-ai/ts-dual-workflow-engine';
+
+const bus = new EventBus<WorkflowEngineEvents>();
+
+bus.on('workflow.action.done', (data) => {
+  console.log(`Action ${data.kind} on ${data.node}: ${data.ok ? 'ok' : 'fail'} (${data.durationMs}ms)`);
+});
+
+bus.on('workflow.run.done', (data) => {
+  console.log(`Run done at ${data.finalState} (${data.transitionsTaken} transitions)`);
+});
+
+const service = new WorkflowService(
+  createDefaultWorkflowEngineHost(),
+  new MemoryWorkflowPersistenceAdapter(),
+);
+
+const result = await service.run(workflow, { events: bus });
+```
+
+### Zero-overhead default
+
+When no `events` option is provided, the engine incurs zero observability overhead — no emit calls, no handler invocations. The event bus is purely opt-in.
+
+### Action-level events
+
+`workflow.action.start` and `workflow.action.done` fire for nodes that have an action configured. A node without an action emits neither. `durationMs` is measured from action start to settlement, and `ok` reflects the action result (`true` for success, `false` for failure).
+
+## RunLifecycle
+
+`RunLifecycle` is the shared bookkeeping layer both drivers delegate to. It manages:
+
+- **Run identity** — generates a `runId` (or honors caller-provided), timestamps, and run record
+- **Persistence sequencing** — `createRun` → `savePhase`/`saveWorkflowState` per step → `finalizeRun` at the end
+- **Observability** — wraps the full run in an OTel span, emits span events, logs each lifecycle event through `@gobing-ai/ts-infra` logger, and optionally emits `WorkflowEngineEvents` via an injected `EventBus` (see [Observability](#observability))
+- **Error resilience** — `warnActionFailed()` logs non-fatal warnings for `onError: 'continue'` actions, using the same structured-logging observability seam as `fail()`
+```ts
+import { RunLifecycle, type RunLifecycleDeps } from '@gobing-ai/ts-dual-workflow-engine';
+
+// Direct usage (typically only for custom driver implementations)
+const result = await RunLifecycle.run(
+  'my-workflow',
+  'state-machine',
+  { persistence: adapter },
+  { runId: 'custom-1' },
+  async (lifecycle) => {
+    await lifecycle.enter('step-1', 0);
+    // ... execute actions ...
+    return await lifecycle.done('step-1', 1);
+  },
+);
+```
+
 ## Error Handling
 
-Validation failures throw `WorkflowValidationError`. Runtime finite-state-machine errors throw `FSMError`. Run failures caused by actions or guards are returned as `WorkflowRunResult` with `status: 'failed'`, preserving the run record.
+| Error Class | When |
+|-------------|------|
+| `WorkflowValidationError` | Definition validation fails (schema, semantics, template references) |
+| `FSMError` | Runtime state-machine driver error (missing state/node, invalid target) |
+| `RunCollisionError` | Duplicate `runId` when creating a new run |
+
+Run failures caused by actions or guards are returned as `WorkflowRunResult` with `status: 'failed'`, preserving the run record — they do not throw.
+
+### Error Policy (`onError`)
+
+Actions, workflow definitions, and `WorkflowRunOptions` accept `onError?: 'fail' | 'continue'`.
+The resolved policy follows precedence `action.onError ?? workflow.defaultOnError ?? runOptions.onError ?? 'fail'`.
+
+- **`'fail'`** (default): the run halts immediately with `status: 'failed'` — today's behavior.
+- **`'continue'`**: logs a structured warning through `RunLifecycle.warnActionFailed()` and advances to the next
+  state, node, guard, or edge evaluation. A node with no outbound edges that fails with `'continue'` still
+  terminates as `done`.
 
 ## Boundary Notes
 
 - The engine executes workflows; it does not provide a scheduler. Use `@gobing-ai/ts-infra` scheduler or an external cron trigger to start runs.
 - Persistence is adapter-based. Downstream apps own DB lifecycle and migration ordering.
 - Action and guard runners are the extension points. Keep domain behavior there, not in workflow parsing.
+- The host's `CapabilityRegistry` tracks the origin (`'builtin'`, `'extension'`, `'core'`) of every registered action and guard — query it with `host.actionOrigin(kind)` / `host.guardOrigin(kind)`.

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 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;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IAChC,mFAAmF;IACnF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChD;AAED,yDAAyD;AACzD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,WAAW,CAGtF;AAED,yDAAyD;AACzD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC,CAE3G;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAM/D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAChC,mFAAmF;IACnF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChD;AAED,yDAAyD;AACzD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,WAAW,CAGtF;AAED,yDAAyD;AACzD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC,CAE3G;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAM/D"}

package/dist/config.js

@@ -1,5 +1,6 @@
 import { loadStructuredConfig, parseYamlObject } from '@gobing-ai/ts-runtime';
 import { WorkflowValidationError } from './errors.js';
+import { RUNTIME_BUILTIN_KEYS } from './run-lifecycle.js';
 import { StateMachineWorkflowDefSchema, TransitionFlowWorkflowDefSchema } from './schema.js';
 /** Load a workflow definition from YAML or JSON text. */
 export function loadWorkflowDefFromText(text, source = '<inline>') {
@@ -150,17 +151,12 @@ function collectActionOptions(workflow) {
     }
     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(RUNTIME_BUILTIN_KEYS);
 /**
  * Check `${...}` template references inside action options resolve to something:
  * a declared `vars.X`, an env-allowlisted `env.X`, or a reserved runtime namespace.

package/dist/events.d.ts

@@ -0,0 +1,49 @@
+/** 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;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,MAAM,MAAM,oBAAoB,GAAG;IAC/B,mDAAmD;IACnD,sBAAsB,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC9F,iDAAiD;IACjD,mBAAmB,EAAE,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACtF,gCAAgC;IAChC,qBAAqB,EAAE,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC9E,6CAA6C;IAC7C,qBAAqB,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAClF,0CAA0C;IAC1C,0BAA0B,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,CAAC;IACjG,+CAA+C;IAC/C,uBAAuB,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,sEAAsE;IACtE,sBAAsB,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACxG,uFAAuF;IACvF,iCAAiC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACjH,CAAC"}