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

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, trust-gated extension loading, and memory or database persistence.
+State-machine and transition-flow workflow runtime with pluggable action runners, guard runners, trust-gated extension loading, memory or database persistence, and rich observability.
 
 ## What It Provides
 
@@ -13,37 +13,145 @@ State-machine and transition-flow workflow runtime with pluggable action runners
 
 The package exposes:
 
+### Runners & Host
+
 | Export | Purpose |
 |--------|---------|
 | `WorkflowService` | High-level loader and runner for both workflow kinds |
 | `StateMachineDriver` | Direct state-machine execution |
 | `TransitionFlowDriver` | Direct transition-flow execution |
 | `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 |
+| `createDefaultWorkflowEngineHost()` | Creates a host with built-in `note`, `shell`, `event.emit`, `always`, `never`, and `action-ok` capabilities |
+
+### Built-in Actions & Guards
+
+| Export | Purpose |
+|--------|---------|
+| `NoteActionRunner` | Records a note in result data and emits `workflow.hitl.note` |
+| `ShellActionRunner` | Shell command backed by `@gobing-ai/ts-runtime` `ProcessExecutor` |
+| `EventEmitActionRunner` | Emits `workflow.custom` events for user-defined observability |
+| `always` guard | Always passes |
+| `never` guard | Always rejects |
+| `action-ok` guard | Passes when the last action succeeded (`lastActionResult?.ok === true`) |
+
+### Persistence
+
+| Export | Purpose |
+|--------|---------|
 | `MemoryWorkflowPersistenceAdapter` | In-memory persistence for tests and short-lived runs |
 | `DbWorkflowPersistenceAdapter` | DB-backed persistence over `@gobing-ai/ts-db` |
-| `applyWorkflowEngineSchema()` | Installs the package-owned DB schema |
-| `WORKFLOW_ENGINE_SCHEMA_SQL` | Raw SQL DDL for the workflow engine tables |
+| `applyWorkflowEngineSchema()` | Installs the package-owned DB schema (idempotent; safe to call before every write) |
+| `WORKFLOW_ENGINE_SCHEMA_SQL` | Raw SQL DDL for the 5 workflow engine tables |
+
+### Configuration & Validation
+
+| Export | Purpose |
+|--------|---------|
 | `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 |
+
+### Extensions
+
+| Export | Purpose |
+|--------|---------|
+| `loadWorkflowExtensionsIntoHost()` | Trust-gated extension module loading for actions and guards |
 | `WorkflowExtensionRef` / `LoadWorkflowExtensionsOptions` / `WorkflowExtensionKind` | Extension loading types |
+
+### Runtime
+
+| Export | Purpose |
+|--------|---------|
+| `RunLifecycle` | Shared run bookkeeping: identity, persistence sequencing, OTel spans, structured logging, and optional event bus emission |
+| `mergeVars()` / `mergeSetVars()` | Variable merging with run-override semantics |
+| `resolveTemplates()` / `resolveTemplateString()` | `${...}` template resolution in options objects |
+| `runtimeBuiltins()` | Injects runtime template values (`workflow`, `runId`, `state`, `iteration`, etc.) |
+| `allowedEnv()` | Environment allowlist projection over `process.env` |
+| `resolveOnErrorPolicy()` | Resolves effective `OnErrorPolicy` from action, workflow default, and run options |
+
+### Types & Errors
+
+| Export | Purpose |
+|--------|---------|
+| `WorkflowEngineEvents` | Typed event map — all events prefixed `workflow.` |
+| `OnErrorPolicy` | Type: `'fail' | 'continue'` |
+| `HitlRequest` / `HitlAnswer` / `HitlResponder` | Human-in-the-loop interaction contracts (interfaces only; no implementation) |
+| `FSMError` / `WorkflowValidationError` / `RunCollisionError` | Structured error classes |
 | `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
+## DB Schema
 
-### Component Relationships
+The engine owns 5 tables. `applyWorkflowEngineSchema()` installs them idempotently (all `CREATE TABLE IF NOT EXISTS`). The schema applies every write path (`createRun`, `loadRun`, `listRuns`) so late-schema callers always find the tables.
+
+```mermaid
+erDiagram
+    runs {
+        TEXT id PK "run identifier (caller-provided or auto-generated)"
+        TEXT workflow_name "human-readable workflow name"
+        TEXT mode "'state-machine' or 'transition-flow'"
+        TEXT status "NOT NULL — 'running'|'done'|'failed'"
+        TEXT agent "agent identifier"
+        TEXT started_at "ISO 8601 timestamp"
+        TEXT completed_at "ISO 8601, null until terminal"
+        TEXT metadata_json "JSON object, defaults '{}'"
+        INTEGER created_at "epoch ms"
+        INTEGER updated_at "epoch ms"
+    }
+
+    phase_runs {
+        TEXT id PK "composite key: {runId}:phase:{phase}:{uuid}"
+        TEXT run_id FK "references runs.id"
+        TEXT phase "state or node id"
+        TEXT status "NOT NULL — 'running'|'done'|'failed'"
+        TEXT started_at "ISO 8601, nullable"
+        TEXT completed_at "ISO 8601, nullable"
+        INTEGER created_at "epoch ms"
+        INTEGER updated_at "epoch ms"
+    }
+
+    transition_runs {
+        TEXT id PK "composite key: {runId}:transition:{from}:{to}:{uuid}"
+        TEXT run_id FK "references runs.id"
+        TEXT from_state "source state/node id"
+        TEXT to_state "target state/node id"
+        TEXT trigger "guard kind or null for unconditional"
+        TEXT status "NOT NULL — always 'done'"
+        INTEGER created_at "epoch ms"
+        INTEGER updated_at "epoch ms"
+    }
+
+    workflow_states {
+        TEXT id PK "composite key: {runId}:state:{state}:{uuid}"
+        TEXT run_id FK "references runs.id"
+        TEXT state "state or node id"
+        TEXT data_json "serialized workflow data"
+        INTEGER created_at "epoch ms"
+        INTEGER updated_at "epoch ms"
+    }
+
+    action_runs {
+        TEXT id PK "UUID"
+        TEXT run_id FK "references runs.id"
+        TEXT node "state or node id where the action executed"
+        TEXT kind "action kind string"
+        TEXT status "NOT NULL — 'running'|'done'|'failed'"
+        INTEGER duration_ms "wall-clock ms, populated on finalize"
+        INTEGER ok "1 for success, 0 for failure, null until finalize"
+        TEXT result_json "serialized action result, null for noop"
+        TEXT started_at "ISO 8601, nullable"
+        TEXT completed_at "ISO 8601, nullable"
+        INTEGER created_at "epoch ms"
+        INTEGER updated_at "epoch ms"
+    }
+
+    runs ||--o{ phase_runs : "has"
+    runs ||--o{ transition_runs : "has"
+    runs ||--o{ workflow_states : "has"
+    runs ||--o{ action_runs : "has"
+```
+
+## Architecture
 
 ```
 ┌──────────────────────────────────────────────────────┐
@@ -67,6 +175,7 @@ The package exposes:
        │  • persistence (createRun, savePhase,  │
        │    saveTransition, finalizeRun)        │
        │  • OTel span + structured logging      │
+       │  • event bus emission (opt-in)         │
        └───────────────┬───────────────────────┘
                        │
           ┌────────────┼────────────┐
@@ -80,6 +189,7 @@ The package exposes:
 ```
 
 ### 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`
@@ -310,18 +420,23 @@ 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()
+The driver persists each state snapshot, phase update, transition, and final run status through the configured persistence adapter.
+
+### Error Resilience — `onError: 'continue'`
+
+```ts
+const host = new WorkflowEngineHost()
     .registerAction(failableAction)
     .registerGuard({ kind: 'always', evaluate: async () => true });
 
-const resilientDriver = new StateMachineDriver({
-    host: host2,
+const driver = new StateMachineDriver({
+    host,
     persistence: new MemoryWorkflowPersistenceAdapter(),
 });
 
-const resilientResult = await resilientDriver.run({
+const result = await driver.run({
     name: 'resilient-approval',
     initialState: 'draft',
     terminalStates: ['done'],
@@ -332,11 +447,8 @@ const resilientResult = await resilientDriver.run({
     ],
     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.
-
 ## Transition Flow Example
 
 ```ts
@@ -367,7 +479,7 @@ result.status; // "done"
 result.finalState; // "done"
 ```
 
-The default host includes built-in `note` and `shell` action runners plus an `always` guard. For production systems, register domain-specific runners and keep shell execution explicit.
+The default host includes built-in `note`, `shell`, `event.emit`, `always`, `never`, and `action-ok` capabilities. For production systems, register domain-specific runners and keep shell execution explicit.
 
 ## Load Workflows from YAML
 
@@ -378,7 +490,7 @@ const workflow = await loadWorkflowDef('./workflows/approval.yaml');
 await service.run(workflow, { runId: 'approval-1' });
 ```
 
-`loadWorkflowDef(path)` reads YAML or JSON from disk. File loads honor a top-level `$schema` ref by default, then validate the internal structural schema and semantic references before returning a `WorkflowDef`. The `$schema` value resolves from the bundled package schema (shipped under `node_modules/@gobing-ai/ts-dual-workflow-engine/schemas/`) — no network access; quote the value, since YAML treats a leading `@` as reserved. Relative paths and (opt-in) remote URLs also work; see `@gobing-ai/ts-runtime` → *Structured config*. `loadWorkflowDefFromText(text, source)` handles inline definitions with internal validation only.
+`loadWorkflowDef(path)` reads YAML or JSON from disk. File loads honor a top-level `$schema` ref by default, then validate the internal structural schema and semantic references before returning a `WorkflowDef`. The `$schema` value resolves from the bundled package schema — no network access; quote the value, since YAML treats a leading `@` as reserved. `loadWorkflowDefFromText(text, source)` handles inline definitions with internal validation only.
 
 ### State-machine YAML
 
@@ -524,7 +636,7 @@ const service = new WorkflowService(
 );
 ```
 
-Use `service.listRuns()` to read persisted run records. The adapter stores run status, phase snapshots, state snapshots, and transitions.
+Use `service.listRuns()` to read persisted run records. The adapter stores runs, phase snapshots, transition records, workflow state snapshots, and action runs across 5 tables. Schema is applied idempotently on every write path — late callers always find the tables. `DbWorkflowPersistenceAdapter` throws `RunCollisionError` on duplicate run ids. Corrupt payloads or DB errors during `processOnce()`/poll cycles on a queue consumer (when used with `@gobing-ai/ts-infra`'s `EventBus.createJobHandler()` bridge) are handled gracefully.
 
 ## Custom Actions and Guards
 
@@ -554,7 +666,7 @@ host.registerGuard({
 });
 ```
 
-Registered actions and guards are available to any workflow definition by their `kind` string. Internally, the host uses `CapabilityRegistry` from `@gobing-ai/ts-runtime/extension` to track registrations with origin metadata (`'builtin'`, `'extension'`, or `'core'`).
+Registered actions and guards are available to any workflow definition by their `kind` string. Internally, the host uses `CapabilityRegistry` from `@gobing-ai/ts-runtime/extension` to track registrations with origin metadata (`'builtin'`, `'extension'`, or `'core'`). Query origin with `host.actionOrigin(kind)` / `host.guardOrigin(kind)`.
 
 ## Extension Loading
 
@@ -602,17 +714,7 @@ await loadWorkflowExtensionsIntoHost(
 );
 ```
 
-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) },
-});
-```
+When a ref has `kind: 'actions'`, only the module's `actions[]` entries are registered; `guards[]` 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.
 
 ### Security
 
@@ -624,8 +726,6 @@ await loadWorkflowExtensionsIntoHost(host, refs, {
 
 ## Zod Schemas
 
-The package exports Zod schemas for programmatic validation:
-
 ```ts
 import { StateMachineWorkflowDefSchema, WorkflowDefSchema } from '@gobing-ai/ts-dual-workflow-engine';
 
@@ -666,7 +766,7 @@ resolveTemplateString('Run ${runId} in ${runtime}', {
 
 ## Observability
 
-The workflow engine uses a **three-layer observability model** (ADR-015):
+The workflow engine uses a **three-layer observability model**:
 
 | Layer | Tool | Consumer |
 |-------|------|----------|
@@ -682,59 +782,60 @@ All three layers are **additive** — EventBus does not replace logging or traci
 
 | 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'`) |
-| `workflow.custom` | `{ name, payload }` | Emitted by the builtin `event.emit` action for custom user-defined events |
-| `workflow.hitl.note` | `{ node, message }` | Emitted by the builtin `note` action for workflow-visible annotations |
+| `workflow.run.started` | `{ workflowName, mode, runId, dryRun }` | When a run begins (inside the span) |
+| `workflow.run.done` | `{ runId, finalState, transitionsTaken }` | When a run completes successfully |
+| `workflow.run.failed` | `{ runId, finalState, reason }` | When a run fails |
+| `workflow.node.enter` | `{ runId, node, transitionsTaken }` | When entering a state or node |
+| `workflow.node.transition` | `{ runId, from, to, trigger }` | On a state/node transition |
+| `workflow.action.start` | `{ runId, node, kind }` | When an action starts executing |
+| `workflow.action.done` | `{ runId, node, kind, durationMs, ok }` | When an action finishes (success or failure) |
+| `workflow.action.failed_continue` | `{ runId, node, transitionsTaken, error? }` | When a non-fatal action failure is continued past |
+| `workflow.custom` | `{ name, payload }` | Emitted by the builtin `event.emit` action |
+| `workflow.hitl.note` | `{ runId, node, message }` | Emitted by the builtin `note` action |
+| `workflow.guard.evaluated` | `{ runId, from, to, kind, passed }` | When a guard condition is evaluated (fires for every guard) |
+| `workflow.hitl.ask` | `{ runId, node, kind, message }` | When an interactive HITL prompt is presented |
+| `workflow.hitl.response` | `{ runId, node, ok }` | When a HITL prompt receives a response |
+
+### Compatibility Policy
+
+The event map is a **cross-package public contract**. Policy: **additive-only** — new events allowed, new optional payload fields allowed; never rename, remove, or repurpose an existing event or field.
+
+### Subscriber Contract
+
+Event handlers registered via `EventBus.on()` or `EventBus.once()` **must** be:
+- **Fast** — handlers run synchronously on the emit call path; slow handlers stall the workflow execution
+- **Non-throwing** — handler errors are swallowed by `EventBus`; durable behavior must never depend on event delivery
+- **Best-effort** — the engine emits via `void emit()` (fire-and-forget); async handlers are not awaited
+
+For **durable** audit/history/telemetry, use the persistence layer — every record is written incrementally during the run via direct adapter calls, not through the event bus.
+
 ### 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)`);
+const events = new EventBus<WorkflowEngineEvents>();
+events.on('workflow.action.done', ({ runId, kind, durationMs, ok }) => {
+    console.log(`Action ${kind} in run ${runId}: ${durationMs}ms, ok=${ok}`);
 });
 
-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 });
+await service.run(workflow, { runId: 'r1', events });
 ```
 
-### 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()`
+- **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`
+- **Error resilience** — `warnActionFailed()` logs non-fatal warnings for `onError: 'continue'` actions
+
 ```ts
 import { RunLifecycle, type RunLifecycleDeps } from '@gobing-ai/ts-dual-workflow-engine';
 
@@ -767,7 +868,7 @@ Run failures caused by actions or guards are returned as `WorkflowRunResult` wit
 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.
+- **`'fail'`** (default): the run halts immediately with `status: 'failed'`.
 - **`'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`.
@@ -778,3 +879,4 @@ The resolved policy follows precedence `action.onError ?? workflow.defaultOnErro
 - 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)`.
+- HITL types (`HitlRequest`, `HitlAnswer`, `HitlResponder`) are interfaces only — this package ships no HITL implementation.

package/dist/events.d.ts

@@ -5,35 +5,42 @@ export type WorkflowEngineEvents = {
         workflowName: string;
         mode: string;
         runId: string;
+        dryRun: boolean;
     }) => void;
     /** Emitted when a run completes successfully. */
     'workflow.run.done': (data: {
+        runId: string;
         finalState: string;
         transitionsTaken: number;
     }) => void;
     /** Emitted when a run fails. */
     'workflow.run.failed': (data: {
+        runId: string;
         finalState: string;
         reason: string;
     }) => void;
     /** Emitted when entering a state or node. */
     'workflow.node.enter': (data: {
+        runId: string;
         node: string;
         transitionsTaken: number;
     }) => void;
     /** Emitted on a state/node transition. */
     'workflow.node.transition': (data: {
+        runId: string;
         from: string;
         to: string;
         trigger: string | null;
     }) => void;
     /** Emitted when an action starts executing. */
     'workflow.action.start': (data: {
+        runId: string;
         node: string;
         kind: string;
     }) => void;
     /** Emitted when an action finishes executing (success or failure). */
     'workflow.action.done': (data: {
+        runId: string;
         node: string;
         kind: string;
         durationMs: number;
@@ -41,6 +48,7 @@ export type WorkflowEngineEvents = {
     }) => void;
     /** Emitted when a non-fatal action failure is continued past (onError: 'continue'). */
     'workflow.action.failed_continue': (data: {
+        runId: string;
         node: string;
         transitionsTaken: number;
         error?: string;
@@ -52,8 +60,30 @@ export type WorkflowEngineEvents = {
     }) => void;
     /** Emitted by the builtin `note` action for workflow-visible annotations. */
     'workflow.hitl.note': (data: {
+        runId: string;
+        node: string;
+        message: string;
+    }) => void;
+    /** Emitted when a guard condition is evaluated. Fires for every guard, including rejected ones. */
+    'workflow.guard.evaluated': (data: {
+        runId: string;
+        from: string;
+        to: string;
+        kind: string;
+        passed: boolean;
+    }) => void;
+    /** Emitted when an interactive HITL prompt is presented and the engine waits for input. */
+    'workflow.hitl.ask': (data: {
+        runId: string;
         node: string;
+        kind: string;
         message: string;
     }) => void;
+    /** Emitted when an interactive HITL prompt receives a response. */
+    'workflow.hitl.response': (data: {
+        runId: string;
+        node: string;
+        ok: boolean;
+    }) => void;
 };
 //# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -1 +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;IAC9G,iFAAiF;IACjF,iBAAiB,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,IAAI,CAAC;IACtF,6EAA6E;IAC7E,oBAAoB,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC3E,CAAC"}
+{"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,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC/G,iDAAiD;IACjD,mBAAmB,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrG,gCAAgC;IAChC,qBAAqB,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC7F,6CAA6C;IAC7C,qBAAqB,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACjG,0CAA0C;IAC1C,0BAA0B,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,IAAI,CAAC;IAChH,+CAA+C;IAC/C,uBAAuB,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACvF,sEAAsE;IACtE,sBAAsB,EAAE,CAAC,IAAI,EAAE;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,EAAE,EAAE,OAAO,CAAC;KACf,KAAK,IAAI,CAAC;IACX,uFAAuF;IACvF,iCAAiC,EAAE,CAAC,IAAI,EAAE;QACtC,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,gBAAgB,EAAE,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,CAAC;KAClB,KAAK,IAAI,CAAC;IACX,iFAAiF;IACjF,iBAAiB,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,IAAI,CAAC;IACtF,6EAA6E;IAC7E,oBAAoB,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACvF,mGAAmG;IACnG,0BAA0B,EAAE,CAAC,IAAI,EAAE;QAC/B,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,OAAO,CAAC;KACnB,KAAK,IAAI,CAAC;IACX,2FAA2F;IAC3F,mBAAmB,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACpG,mEAAmE;IACnE,wBAAwB,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAC1F,CAAC"}

package/dist/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,KAAK,gBAAgB,EAAsB,MAAM,iCAAiC,CAAC;AAE5F,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvG,sDAAsD;AACtD,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2D;IACnF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyD;IAEhF,4CAA4C;IAC5C,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,GAAE,gBAA8B,GAAG,IAAI;IAKlF,0CAA0C;IAC1C,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,GAAE,gBAA8B,GAAG,IAAI;IAK/E,0DAA0D;IAC1D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,0DAA0D;IAC1D,WAAW,IAAI,MAAM,EAAE;IAIvB,yDAAyD;IACzD,UAAU,IAAI,MAAM,EAAE;IAItB,mHAAmH;IACnH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIxD,0DAA0D;IAC1D,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIvD,mCAAmC;IAC7B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAOjH,mCAAmC;IAC7B,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;CAI/G;AAED,4FAA4F;AAC5F,wBAAgB,+BAA+B,CAC3C,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,eAAe,CAAA;CAAO,GACpD,kBAAkB,CAepB;AAED,gFAAgF;AAChF,qBAAa,gBAAiB,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,UAAU;IAEvB,kEAAkE;IAC5D,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;CAKrG;AAED,yFAAyF;AACzF,qBAAa,qBAAsB,YAAW,YAAY;IACtD,QAAQ,CAAC,IAAI,gBAAgB;IAEvB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;CAOrG;AAED,kEAAkE;AAClE,qBAAa,iBAAkB,YAAW,YAAY;IAGtC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAF5C,QAAQ,CAAC,IAAI,WAAW;gBAEK,eAAe,EAAE,eAAe;IAE7D;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;CAkBpG"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,KAAK,gBAAgB,EAAsB,MAAM,iCAAiC,CAAC;AAE5F,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvG,sDAAsD;AACtD,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2D;IACnF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyD;IAEhF,4CAA4C;IAC5C,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,GAAE,gBAA8B,GAAG,IAAI;IAKlF,0CAA0C;IAC1C,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,GAAE,gBAA8B,GAAG,IAAI;IAK/E,0DAA0D;IAC1D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,0DAA0D;IAC1D,WAAW,IAAI,MAAM,EAAE;IAIvB,yDAAyD;IACzD,UAAU,IAAI,MAAM,EAAE;IAItB,mHAAmH;IACnH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIxD,0DAA0D;IAC1D,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIvD,mCAAmC;IAC7B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAOjH,mCAAmC;IAC7B,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;CAI/G;AAED,4FAA4F;AAC5F,wBAAgB,+BAA+B,CAC3C,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,eAAe,CAAA;CAAO,GACpD,kBAAkB,CAepB;AAED,gFAAgF;AAChF,qBAAa,gBAAiB,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,UAAU;IAEvB,kEAAkE;IAC5D,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;CASrG;AAED,yFAAyF;AACzF,qBAAa,qBAAsB,YAAW,YAAY;IACtD,QAAQ,CAAC,IAAI,gBAAgB;IAEvB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;CAOrG;AAED,kEAAkE;AAClE,qBAAa,iBAAkB,YAAW,YAAY;IAGtC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAF5C,QAAQ,CAAC,IAAI,WAAW;gBAEK,eAAe,EAAE,eAAe;IAE7D;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;CAkBpG"}

package/dist/host.js

@@ -74,7 +74,11 @@ export class NoteActionRunner {
     /** Execute a no-op note action with observable event emission. */
     async execute(options, context) {
         const message = String(options.message ?? '');
-        void context?.events?.emit('workflow.hitl.note', { node: context.stateOrNodeId, message });
+        void context?.events?.emit('workflow.hitl.note', {
+            runId: context.runId,
+            node: context.stateOrNodeId,
+            message,
+        });
         return { ok: true, data: { message } };
     }
 }

package/dist/index.d.ts

@@ -11,6 +11,6 @@ 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, OnErrorPolicy, StateDef, StateMachineWorkflowDef, TransitionDef, TransitionFlowWorkflowDef, Vars, WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunRecord, WorkflowRunResult, WorkflowStatus, } from './types';
+export type { ActionDef, ActionRedactor, ActionResult, ActionRunContext, ActionRunner, ActionRunRecord, Env, FlowEdgeDef, FlowNodeDef, GuardContext, GuardDef, GuardRunner, OnErrorPolicy, StateDef, StateMachineWorkflowDef, TransitionDef, TransitionFlowWorkflowDef, Vars, WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunRecord, WorkflowRunResult, WorkflowStatus, } from './types';
 export { mergeSetVars, 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,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,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtF,OAAO,EACH,+BAA+B,EAC/B,qBAAqB,EACrB,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,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,eAAe,GACvB,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,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtF,OAAO,EACH,+BAA+B,EAC/B,qBAAqB,EACrB,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,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,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,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,eAAe,GACvB,MAAM,aAAa,CAAC"}

package/dist/persistence.d.ts

@@ -1,5 +1,5 @@
 import type { DbAdapter } from '@gobing-ai/ts-db';
-import type { WorkflowPersistenceAdapter, WorkflowRunRecord, WorkflowStatus } from './types';
+import type { ActionRedactor, WorkflowPersistenceAdapter, WorkflowRunRecord, WorkflowStatus } from './types';
 /** Apply workflow-engine-owned schema to a database adapter. */
 export declare function applyWorkflowEngineSchema(db: DbAdapter): Promise<void>;
 /** SQLite/D1-compatible workflow persistence adapter backed by ts-db. */
@@ -16,6 +16,10 @@ export declare class DbWorkflowPersistenceAdapter implements WorkflowPersistence
     saveTransition(runId: string, from: string, to: string, trigger: string | null): Promise<void>;
     /** Save the latest workflow state snapshot. */
     saveWorkflowState(runId: string, state: string, data: Record<string, unknown>): Promise<void>;
+    /** Insert a running action row. Returns the row id for later finalization. */
+    saveActionStart(runId: string, node: string, kind: string): Promise<string>;
+    /** Finalize an action row with duration, ok flag, and optional redacted result. */
+    saveActionFinalize(actionId: string, status: WorkflowStatus, durationMs: number, ok: boolean, result?: unknown, _redactor?: ActionRedactor): Promise<void>;
     /** Load a single run by id. */
     loadRun(runId: string): Promise<WorkflowRunRecord | undefined>;
     /** List persisted workflow runs. */
@@ -44,6 +48,20 @@ export declare class MemoryWorkflowPersistenceAdapter implements WorkflowPersist
     createRun(record: WorkflowRunRecord): Promise<void>;
     /** Finalize a run with terminal status and timestamp. */
     finalizeRun(runId: string, status: WorkflowStatus, completedAt: string): Promise<void>;
+    readonly actionRuns: Array<{
+        id: string;
+        runId: string;
+        node: string;
+        kind: string;
+        status: WorkflowStatus;
+        durationMs: number | null;
+        ok: number | null;
+        resultJson: string | null;
+    }>;
+    /** Insert a running action row. */
+    saveActionStart(runId: string, node: string, kind: string): Promise<string>;
+    /** Finalize an action row. */
+    saveActionFinalize(actionId: string, status: WorkflowStatus, durationMs: number, ok: boolean, result?: unknown, _redactor?: ActionRedactor): Promise<void>;
     /** Save one phase/state execution record. */
     savePhase(runId: string, phase: string, status: WorkflowStatus): Promise<void>;
     /** Save one transition record. */

package/dist/persistence.d.ts.map

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