@kylebegeman/pulse 0.3.0

package/README.md

@@ -0,0 +1,1078 @@
+<div align="center">
+
+# Pulse
+
+**Signal-driven workflow engine for multi-tenant applications**
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-12+-4169e1?logo=postgresql&logoColor=white)](https://www.postgresql.org)
+[![Redis](https://img.shields.io/badge/Redis-6+-dc382d?logo=redis&logoColor=white)](https://redis.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[Quick Start](#quick-start) &#8226; [Core Concepts](#core-concepts) &#8226; [API Reference](#api-reference) &#8226; [Examples](#examples) &#8226; [Database Schema](#database-schema)
+
+</div>
+
+---
+
+## Overview
+
+Pulse is a TypeScript library for building event-driven workflow automation. Your application emits **signals**, and the engine matches them to registered **workflows** — scheduling and executing **steps** in sequence with full persistence, observability, and replay support.
+
+```
+Signal  ->  Match  ->  Schedule Steps  ->  Evaluate Conditions  ->  Execute Actions  ->  Record Results
+```
+
+Built for multi-tenant SaaS. Every signal, workflow, and run is scoped to a tenant. The engine runs in-process alongside your application using your existing PostgreSQL database and Redis instance.
+
+### Highlights
+
+- **Signal-driven** — Emit structured events, let the engine match and execute workflows
+- **Multi-tenant** — Every resource is scoped to a tenant out of the box
+- **Parallel execution** — Fan out into concurrent branches with automatic convergence
+- **Cron scheduling** — Trigger workflows on recurring schedules via BullMQ
+- **Replay** — Re-process historical signals with replay-safety controls
+- **Cancellation & retry** — Cancel in-progress runs or retry from the point of failure
+- **Timeline** — Chronological audit trail for every run
+- **Lifecycle hooks** — Observe step and run completion for integrations
+- **Production-hardened** — CAS step claiming, state guards, idempotent migrations
+
+---
+
+## Quick Start
+
+```ts
+import { createEngine } from '@kylebegeman/pulse'
+import { Pool } from 'pg'
+import Redis from 'ioredis'
+
+const engine = createEngine({
+  db: new Pool({ connectionString: process.env.DATABASE_URL }),
+  redis: new Redis(process.env.REDIS_URL),
+})
+
+// Register a trigger, action, and condition
+engine.registerTrigger('heartbeat.missed', {
+  source: 'heartbeat',
+  resourceType: 'service',
+})
+
+engine.registerAction('create_incident', async (ctx) => {
+  const incident = await createIncident({
+    service: ctx.trigger.resourceId,
+    tenant: ctx.tenantId,
+  })
+  ctx.log('Incident created', { incidentId: incident.id })
+  return { success: true, data: { incidentId: incident.id } }
+}, { replaySafe: true })
+
+engine.registerCondition('is_still_failing', async (ctx) => {
+  const status = await checkServiceHealth(ctx.trigger.resourceId)
+  return status === 'unhealthy'
+})
+
+// Run migrations and create a workflow
+await engine.migrate()
+
+await engine.createWorkflow({
+  tenantId: 'workspace_1',
+  name: 'Incident on missed heartbeat',
+  triggerType: 'heartbeat.missed',
+  steps: [
+    { type: 'delay', name: 'wait_5m', delayMs: 5 * 60 * 1000 },
+    { type: 'condition', name: 'is_still_failing' },
+    { type: 'action', name: 'create_incident' },
+  ],
+  config: {},
+  isEnabled: true,
+})
+
+// Start processing and emit signals
+await engine.start()
+
+await engine.emit({
+  tenantId: 'workspace_1',
+  source: 'heartbeat',
+  type: 'heartbeat.missed',
+  resourceType: 'service',
+  resourceId: 'api-server',
+  payload: { lastSeenAt: new Date().toISOString() },
+})
+
+// Graceful shutdown
+await engine.stop()
+```
+
+---
+
+## Installation
+
+Pulse is a private package. Install from GitHub:
+
+```bash
+# package.json
+"@kylebegeman/pulse": "github:mrbagels/pulse"
+
+# or via SSH
+npm install git+ssh://git@github.com:mrbagels/pulse.git
+```
+
+**Peer requirements:**
+
+| Dependency | Purpose |
+|:--|:--|
+| `pg` | PostgreSQL client — engine uses your connection pool |
+| `ioredis` | Redis client — used by BullMQ for job queuing |
+
+---
+
+## Core Concepts
+
+### Signals (Triggers)
+
+A **signal** is a structured event emitted by your application. Every signal includes a tenant, a source system, a type, and optional resource and payload data.
+
+```ts
+await engine.emit({
+  tenantId: 'workspace_1',
+  source: 'heartbeat',
+  type: 'heartbeat.missed',
+  resourceType: 'service',
+  resourceId: 'api-server',
+  environment: 'production',
+  payload: { lastSeenAt: '...' },
+})
+```
+
+Triggers are **registered** to declare their source, expected resource type, and optional Zod payload schema:
+
+```ts
+import { z } from 'zod'
+
+engine.registerTrigger('heartbeat.missed', {
+  source: 'heartbeat',
+  resourceType: 'service',
+  payloadSchema: z.object({
+    lastSeenAt: z.string().datetime(),
+  }),
+})
+```
+
+All emitted signals are persisted to the database for auditing and [replay](#replay).
+
+### Workflows
+
+A **workflow** is a named sequence of steps that runs when a matching signal is emitted. Workflows are stored in the database and scoped to a tenant.
+
+```ts
+await engine.createWorkflow({
+  tenantId: 'workspace_1',
+  name: 'Incident on missed heartbeat',
+  triggerType: 'heartbeat.missed',
+  environmentFilter: 'production',
+  resourceTypeFilter: 'service',
+  steps: [
+    { type: 'delay', name: 'wait_5m', delayMs: 300_000 },
+    { type: 'condition', name: 'is_still_failing' },
+    { type: 'action', name: 'create_incident' },
+  ],
+  config: { severity: 'high' },
+  isEnabled: true,
+})
+```
+
+When a signal is emitted, the engine finds all enabled workflows matching the signal type (and optional filters), creates a **run** for each, and begins scheduling steps. Workflows can be enabled or disabled at runtime:
+
+```ts
+await engine.disableWorkflow('wfd_abc123')
+await engine.enableWorkflow('wfd_abc123')
+```
+
+### Steps
+
+Each workflow contains an ordered list of steps. Steps execute sequentially — each must complete before the next begins.
+
+| Type | Purpose |
+|:--|:--|
+| `action` | Execute a registered handler function |
+| `condition` | Evaluate a boolean to branch or complete early |
+| `delay` | Pause execution for a duration (via BullMQ delayed jobs) |
+| `parallel` | Execute multiple branches concurrently |
+
+#### Action steps
+
+```ts
+engine.registerAction('send_alert', async (ctx) => {
+  await sendSlackMessage(ctx.config.channel, `Alert for ${ctx.trigger.resourceId}`)
+  return { success: true, data: { sent: true } }
+}, { replaySafe: false })
+```
+
+Actions support retry policies and timeouts:
+
+```ts
+{
+  type: 'action',
+  name: 'send_alert',
+  retryPolicy: { maxAttempts: 3, backoffMs: 5000 },
+  timeoutMs: 30_000,
+}
+```
+
+#### Condition steps
+
+```ts
+engine.registerCondition('monitor_still_failing', async (ctx) => {
+  const health = await checkHealth(ctx.trigger.resourceId)
+  return health.status === 'down'
+})
+```
+
+Control what happens when a condition returns `false`:
+
+```ts
+{ type: 'condition', name: 'check', onFalse: 'complete' }  // Default: complete early
+{ type: 'condition', name: 'check', onFalse: 'skip' }      // Skip next step
+{ type: 'condition', name: 'check', onFalse: 3 }            // Skip next N steps
+```
+
+#### Delay steps
+
+```ts
+{ type: 'delay', name: 'wait_5_minutes', delayMs: 5 * 60 * 1000 }
+```
+
+Maximum delay: 30 days. Uses BullMQ delayed jobs for reliability.
+
+#### Parallel steps
+
+Run multiple branches concurrently. All branches must complete before the workflow continues.
+
+```ts
+{
+  type: 'parallel',
+  name: 'notify_all_channels',
+  branches: [
+    [{ type: 'action', name: 'send_email' }, { type: 'action', name: 'log_email_sent' }],
+    [{ type: 'action', name: 'send_slack' }],
+    [{ type: 'action', name: 'send_sms' }],
+  ],
+}
+```
+
+- Branches execute independently via BullMQ jobs
+- Branches can contain any step types
+- If any branch fails, the parallel step fails and the run fails
+- Minimum 2 branches required
+
+### Cron Scheduling
+
+Workflows can run on recurring schedules. When a cron fires, the engine emits a trigger of the workflow's type automatically.
+
+```ts
+await engine.createWorkflow({
+  tenantId: 'workspace_1',
+  name: 'Daily cleanup',
+  triggerType: 'maintenance.cleanup',
+  steps: [{ type: 'action', name: 'cleanup_old_records' }],
+  config: {},
+  isEnabled: true,
+  cronExpression: '0 2 * * *', // Daily at 2:00 AM
+})
+```
+
+Cron jobs use BullMQ repeatable jobs. Enabling/disabling a workflow starts/stops its cron. Standard 5-field format: `minute hour dayOfMonth month dayOfWeek`.
+
+### Handler Context
+
+Every action and condition handler receives a `WorkflowContext`:
+
+```ts
+engine.registerAction('my_action', async (ctx) => {
+  ctx.tenantId   // Current tenant
+  ctx.trigger    // The signal that started this run
+  ctx.run        // Current run state
+  ctx.step       // Current step state
+  ctx.config     // Workflow-level config
+  ctx.isReplay   // True during replay execution
+  ctx.emit(...)  // Emit another signal (workflow chaining)
+  ctx.log(...)   // Write to execution log
+
+  return { success: true }
+})
+```
+
+### Lifecycle Hooks
+
+```ts
+const engine = createEngine({
+  db: pool,
+  redis: redisClient,
+  onStepComplete: (event) => {
+    console.log(`Step ${event.step.stepName}: ${event.step.status}`)
+  },
+  onRunComplete: (event) => {
+    console.log(`Run ${event.run.id}: ${event.status}`)
+  },
+})
+```
+
+Hooks are fire-and-forget — errors in hooks do not affect workflow execution.
+
+### Replay
+
+Re-process a historical signal through the matching pipeline:
+
+```ts
+await engine.replay('trg_abc123')                     // Full replay
+await engine.replay('trg_abc123', { dryRun: true })   // Dry run — skip actions
+```
+
+Actions declare replay safety. Actions with `replaySafe: false` are **skipped** during replay to prevent duplicate side effects.
+
+```ts
+engine.registerAction('create_incident', handler, { replaySafe: true })
+engine.registerAction('send_email', handler, { replaySafe: false })
+```
+
+### Cancel & Retry
+
+**Cancel** an in-progress run:
+
+```ts
+const canceledRun = await engine.cancelRun('run_abc123', 'No longer needed')
+```
+
+Sets status to `canceled`, marks pending steps as `skipped`, removes pending BullMQ jobs.
+
+**Retry** a failed run from the point of failure:
+
+```ts
+const retriedRun = await engine.retryRun('run_abc123')
+```
+
+Resets the failed step to `pending`, sets the run back to `running`, and re-enqueues via BullMQ.
+
+**List** failed runs:
+
+```ts
+const allFailed = await engine.getFailedRuns()
+const tenantFailed = await engine.getFailedRuns('workspace_1')
+```
+
+### Run Timeline
+
+Chronological audit trail for debugging dashboards:
+
+```ts
+const timeline = await engine.getRunTimeline('run_abc123')
+
+for (const entry of timeline) {
+  console.log(`[${entry.timestamp}] ${entry.type}`, entry.detail)
+}
+```
+
+Entry types: `run_created`, `step_scheduled`, `step_started`, `step_completed`, `step_failed`, `step_skipped`, `run_completed`, `run_failed`, `run_canceled`, `log`
+
+---
+
+## API Reference
+
+### `createEngine(config)`
+
+```ts
+import { createEngine } from '@kylebegeman/pulse'
+
+const engine = createEngine({
+  db: pool,                       // Required — pg Pool instance
+  redis: redisClient,             // Required — ioredis instance
+  tablePrefix: 'pulse_',          // Default: 'pulse_'
+  queuePrefix: 'pulse',           // Default: 'pulse'
+  concurrency: 5,                 // Default: 5
+  onStepComplete: (e) => {},      // Optional lifecycle hook
+  onRunComplete: (e) => {},       // Optional lifecycle hook
+})
+```
+
+### Engine Methods
+
+#### Registration
+
+| Method | Description |
+|:--|:--|
+| `registerTrigger(type, registration)` | Register a signal type with source, optional resource type, and optional Zod payload schema |
+| `registerAction(name, handler, options?)` | Register an action handler. Set `replaySafe` in options |
+| `registerCondition(name, handler)` | Register a condition handler returning a boolean |
+
+#### Signals
+
+| Method | Returns | Description |
+|:--|:--|:--|
+| `emit(trigger)` | `TriggerEnvelope` | Emit a signal — persists, matches workflows, creates runs |
+
+#### Lifecycle
+
+| Method | Description |
+|:--|:--|
+| `start()` | Start BullMQ workers and restore cron jobs |
+| `stop()` | Graceful shutdown — waits for active jobs, stops cron |
+
+#### Queries
+
+| Method | Returns | Description |
+|:--|:--|:--|
+| `getRun(runId)` | `WorkflowRun \| null` | Get a run by ID |
+| `getRunSteps(runId)` | `WorkflowStepRun[]` | Get all step runs for a run |
+| `getRunsByTrigger(triggerId)` | `WorkflowRun[]` | Get runs spawned by a trigger |
+| `getTrigger(triggerId)` | `TriggerEnvelope \| null` | Get a persisted trigger |
+
+#### Timeline
+
+| Method | Returns | Description |
+|:--|:--|:--|
+| `getRunTimeline(runId)` | `RunTimelineEntry[]` | Chronological lifecycle view |
+
+#### Cancel & Retry
+
+| Method | Returns | Description |
+|:--|:--|:--|
+| `cancelRun(runId, reason?)` | `WorkflowRun` | Cancel an in-progress run |
+| `retryRun(runId)` | `WorkflowRun` | Retry a failed run from the failed step |
+| `getFailedRuns(tenantId?)` | `WorkflowRun[]` | List failed runs |
+
+#### Replay
+
+| Method | Returns | Description |
+|:--|:--|:--|
+| `replay(triggerId, options?)` | `WorkflowRun[]` | Re-emit a historical trigger |
+
+#### Workflow Management
+
+| Method | Returns | Description |
+|:--|:--|:--|
+| `createWorkflow(definition)` | `WorkflowDefinition` | Create a workflow, schedules cron if applicable |
+| `enableWorkflow(definitionId)` | `void` | Enable a workflow |
+| `disableWorkflow(definitionId)` | `void` | Disable a workflow |
+
+#### Schema
+
+| Method | Description |
+|:--|:--|
+| `migrate()` | Create `pulse_*` tables (idempotent) |
+
+---
+
+## Examples
+
+### Monitoring: Incident on Missed Heartbeat
+
+Wait for a missed heartbeat, verify the service is still down, then create an incident and page on-call.
+
+```ts
+engine.registerTrigger('heartbeat.missed', {
+  source: 'heartbeat',
+  resourceType: 'service',
+})
+
+engine.registerCondition('service_still_down', async (ctx) => {
+  const status = await healthCheck(ctx.trigger.resourceId)
+  return status !== 'healthy'
+})
+
+engine.registerAction('create_incident', async (ctx) => {
+  const incident = await db.incidents.create({
+    tenantId: ctx.tenantId,
+    serviceId: ctx.trigger.resourceId,
+    severity: ctx.config.severity || 'medium',
+  })
+  ctx.log('Incident created', { incidentId: incident.id })
+  return { success: true, data: { incidentId: incident.id } }
+}, { replaySafe: true })
+
+engine.registerAction('notify_oncall', async (ctx) => {
+  await pagerduty.trigger({ service: ctx.trigger.resourceId })
+  return { success: true }
+}, { replaySafe: false })
+
+await engine.createWorkflow({
+  tenantId: 'workspace_1',
+  name: 'Incident on missed heartbeat',
+  triggerType: 'heartbeat.missed',
+  environmentFilter: 'production',
+  steps: [
+    { type: 'delay', name: 'wait_5m', delayMs: 5 * 60 * 1000 },
+    { type: 'condition', name: 'service_still_down' },
+    { type: 'action', name: 'create_incident' },
+    { type: 'action', name: 'notify_oncall' },
+  ],
+  config: { severity: 'high' },
+  isEnabled: true,
+})
+```
+
+### Billing: Trial Expiration
+
+Send a warning email, wait 3 days, then downgrade if the user hasn't upgraded.
+
+```ts
+engine.registerAction('send_trial_warning', async (ctx) => {
+  await emails.send({
+    to: ctx.trigger.payload.email,
+    template: 'trial-expiring',
+    data: { daysLeft: ctx.trigger.payload.daysLeft },
+  })
+  return { success: true }
+}, { replaySafe: false })
+
+engine.registerCondition('has_not_upgraded', async (ctx) => {
+  const sub = await billing.getSubscription(ctx.tenantId)
+  return sub.plan === 'trial'
+})
+
+engine.registerAction('downgrade_to_free', async (ctx) => {
+  await billing.changePlan(ctx.tenantId, 'free')
+  ctx.log('Downgraded to free plan')
+  return { success: true }
+}, { replaySafe: true })
+
+await engine.createWorkflow({
+  tenantId: 'workspace_1',
+  name: 'Trial expiration',
+  triggerType: 'trial.expiring',
+  steps: [
+    { type: 'action', name: 'send_trial_warning' },
+    { type: 'delay', name: 'wait_3_days', delayMs: 3 * 24 * 60 * 60 * 1000 },
+    { type: 'condition', name: 'has_not_upgraded' },
+    { type: 'action', name: 'downgrade_to_free' },
+  ],
+  config: {},
+  isEnabled: true,
+})
+```
+
+### Workflow Chaining
+
+Actions can emit signals, allowing workflows to trigger other workflows.
+
+```ts
+engine.registerAction('attempt_auto_fix', async (ctx) => {
+  const result = await autoRemediate(ctx.trigger.resourceId)
+
+  if (result.fixed) {
+    await ctx.emit({
+      tenantId: ctx.tenantId,
+      source: 'auto-remediation',
+      type: 'service.recovered',
+      resourceType: 'service',
+      resourceId: ctx.trigger.resourceId,
+      payload: { fix: result.action },
+    })
+  }
+
+  return { success: true, data: result }
+}, { replaySafe: true })
+
+// A separate workflow reacts to the recovery signal
+await engine.createWorkflow({
+  tenantId: 'workspace_1',
+  name: 'Auto-close on recovery',
+  triggerType: 'service.recovered',
+  steps: [{ type: 'action', name: 'close_incident' }],
+  config: {},
+  isEnabled: true,
+})
+```
+
+### Parallel: Multi-Channel Notification
+
+Send notifications across multiple channels simultaneously.
+
+```ts
+await engine.createWorkflow({
+  tenantId: 'workspace_1',
+  name: 'Multi-channel alert',
+  triggerType: 'alert.triggered',
+  steps: [
+    {
+      type: 'parallel',
+      name: 'notify_all',
+      branches: [
+        [{ type: 'action', name: 'send_email' }],
+        [{ type: 'action', name: 'send_slack' }],
+        [{ type: 'action', name: 'send_sms' }],
+      ],
+    },
+    { type: 'action', name: 'mark_notified' },
+  ],
+  config: {
+    alertEmail: 'oncall@company.com',
+    slackChannel: '#alerts',
+    phoneNumber: '+1234567890',
+  },
+  isEnabled: true,
+})
+```
+
+### Cron: Daily Cleanup Job
+
+```ts
+await engine.createWorkflow({
+  tenantId: 'workspace_1',
+  name: 'Daily cleanup',
+  triggerType: 'maintenance.cleanup',
+  steps: [
+    { type: 'action', name: 'cleanup_old_records' },
+    { type: 'action', name: 'send_cleanup_report' },
+  ],
+  config: {},
+  isEnabled: true,
+  cronExpression: '0 2 * * *',
+})
+```
+
+### Error Recovery: Retry Failed Runs
+
+```ts
+const failed = await engine.getFailedRuns('workspace_1')
+
+for (const run of failed) {
+  const retried = await engine.retryRun(run.id)
+  console.log(`Retried run ${retried.id}, now ${retried.status}`)
+}
+
+await engine.cancelRun('run_xyz789', 'Superseded by newer deployment')
+```
+
+---
+
+## Runtime Guarantees
+
+### Execution Semantics
+
+Pulse provides **at-least-once** execution. If a worker crashes after an action completes but before the engine records success, the step may execute again on retry. Design actions to be **idempotent** where possible:
+
+```ts
+engine.registerAction('send_email', async (ctx) => {
+  const idempotencyKey = `${ctx.run.id}:${ctx.step.name}`
+  // Use this key with your provider to prevent duplicates
+})
+```
+
+### Step Claiming
+
+Every step is claimed atomically before execution using compare-and-set:
+
+```sql
+UPDATE step_runs SET status = 'running', started_at = NOW()
+WHERE id = $1 AND status IN ('pending', 'scheduled')
+RETURNING *
+```
+
+If two workers pick up the same job, only one successfully claims it. The other silently no-ops.
+
+### State Transitions
+
+Run status changes are guarded by the current status. Invalid transitions are rejected:
+
+```
+pending  ->  running, canceled
+running  ->  waiting, completed, failed, canceled
+waiting  ->  running, canceled
+failed   ->  running (retry)
+```
+
+### Context Accumulation
+
+Each action's return value is stored in the run context keyed by action name:
+
+```ts
+// After "check_status" returns { healthy: true }
+// ctx.run.context.check_status === { healthy: true }
+```
+
+Step names within a workflow must be unique to prevent key collisions.
+
+---
+
+## Database Schema
+
+The engine creates tables with the prefix `pulse_` (configurable). All tables use `TEXT` primary keys with auto-generated IDs. Migrations are idempotent — safe to call on every startup.
+
+```ts
+await engine.migrate()
+```
+
+### `pulse_triggers`
+
+| Column | Type | Description |
+|:--|:--|:--|
+| `id` | `TEXT PK` | Trigger ID (`trg_...`) |
+| `tenant_id` | `TEXT` | Tenant scope |
+| `source` | `TEXT` | Originating system |
+| `type` | `TEXT` | Signal type |
+| `resource_type` | `TEXT` | Resource category |
+| `resource_id` | `TEXT` | Specific resource |
+| `environment` | `TEXT` | Environment scope |
+| `payload` | `JSONB` | Arbitrary event data |
+| `created_at` | `TIMESTAMPTZ` | When emitted |
+
+### `pulse_workflow_definitions`
+
+| Column | Type | Description |
+|:--|:--|:--|
+| `id` | `TEXT PK` | Definition ID |
+| `tenant_id` | `TEXT` | Tenant scope |
+| `name` | `TEXT` | Human-readable name |
+| `description` | `TEXT` | Optional description |
+| `trigger_type` | `TEXT` | Signal type to match |
+| `environment_filter` | `TEXT` | Optional environment filter |
+| `resource_type_filter` | `TEXT` | Optional resource type filter |
+| `steps` | `JSONB` | Ordered step definitions |
+| `config` | `JSONB` | Config passed to handlers |
+| `is_enabled` | `BOOLEAN` | Whether active |
+| `cron_expression` | `TEXT` | Optional cron schedule |
+| `created_at` | `TIMESTAMPTZ` | Creation time |
+| `updated_at` | `TIMESTAMPTZ` | Last update |
+
+### `pulse_workflow_runs`
+
+| Column | Type | Description |
+|:--|:--|:--|
+| `id` | `TEXT PK` | Run ID |
+| `definition_id` | `TEXT FK` | Workflow definition |
+| `tenant_id` | `TEXT` | Tenant scope |
+| `trigger_id` | `TEXT FK` | Signal that started this run |
+| `status` | `TEXT` | `pending` / `running` / `waiting` / `completed` / `failed` / `canceled` |
+| `context` | `JSONB` | Shared run context |
+| `current_step_index` | `INTEGER` | Active step position |
+| `is_replay` | `BOOLEAN` | Whether this is a replay |
+| `definition_snapshot` | `JSONB` | Frozen copy of workflow at run creation |
+| `started_at` | `TIMESTAMPTZ` | When execution began |
+| `completed_at` | `TIMESTAMPTZ` | When completed |
+| `failed_at` | `TIMESTAMPTZ` | When failed |
+| `canceled_at` | `TIMESTAMPTZ` | When canceled |
+| `cancel_reason` | `TEXT` | Cancel reason |
+| `created_at` | `TIMESTAMPTZ` | Creation time |
+| `updated_at` | `TIMESTAMPTZ` | Last update |
+
+### `pulse_workflow_step_runs`
+
+| Column | Type | Description |
+|:--|:--|:--|
+| `id` | `TEXT PK` | Step run ID |
+| `run_id` | `TEXT FK` | Parent workflow run |
+| `tenant_id` | `TEXT` | Tenant scope |
+| `step_index` | `INTEGER` | Position in sequence |
+| `step_type` | `TEXT` | `action` / `condition` / `delay` / `parallel` |
+| `step_name` | `TEXT` | Registered handler name |
+| `status` | `TEXT` | `pending` / `scheduled` / `running` / `completed` / `failed` / `skipped` |
+| `scheduled_for` | `TIMESTAMPTZ` | When to execute (delays) |
+| `started_at` | `TIMESTAMPTZ` | When execution began |
+| `completed_at` | `TIMESTAMPTZ` | When completed |
+| `result` | `JSONB` | Action result data |
+| `error_message` | `TEXT` | Error details |
+| `branch_index` | `INTEGER` | Branch index (parallel) |
+| `parent_step_run_id` | `TEXT` | Parent parallel step |
+| `created_at` | `TIMESTAMPTZ` | Creation time |
+
+### `pulse_execution_logs`
+
+| Column | Type | Description |
+|:--|:--|:--|
+| `id` | `TEXT PK` | Log entry ID |
+| `run_id` | `TEXT FK` | Parent workflow run |
+| `step_run_id` | `TEXT FK` | Associated step |
+| `tenant_id` | `TEXT` | Tenant scope |
+| `level` | `TEXT` | `info` / `warn` / `error` |
+| `message` | `TEXT` | Log message |
+| `data` | `JSONB` | Structured log data |
+| `created_at` | `TIMESTAMPTZ` | When written |
+
+---
+
+## Type Reference
+
+<details>
+<summary><code>TriggerInput</code></summary>
+
+```ts
+interface TriggerInput {
+  tenantId: string
+  source: string
+  type: string
+  resourceType?: string
+  resourceId?: string
+  environment?: string
+  payload?: Record<string, unknown>
+}
+```
+</details>
+
+<details>
+<summary><code>TriggerEnvelope</code></summary>
+
+```ts
+interface TriggerEnvelope extends TriggerInput {
+  id: string
+  createdAt: Date
+}
+```
+</details>
+
+<details>
+<summary><code>TriggerRegistration</code></summary>
+
+```ts
+interface TriggerRegistration {
+  source: string
+  resourceType?: string
+  payloadSchema?: ZodSchema
+}
+```
+</details>
+
+<details>
+<summary><code>WorkflowDefinition</code></summary>
+
+```ts
+interface WorkflowDefinition {
+  id: string
+  tenantId: string
+  name: string
+  description?: string
+  triggerType: string
+  environmentFilter?: string
+  resourceTypeFilter?: string
+  steps: WorkflowStep[]
+  config: Record<string, unknown>
+  isEnabled: boolean
+  cronExpression?: string
+  createdAt: Date
+  updatedAt: Date
+}
+```
+</details>
+
+<details>
+<summary><code>WorkflowStep</code></summary>
+
+```ts
+type StepType = 'action' | 'condition' | 'delay' | 'parallel'
+
+interface WorkflowStep {
+  type: StepType
+  name: string
+  config?: Record<string, unknown>
+  delayMs?: number
+  timeoutMs?: number
+  retryPolicy?: RetryPolicy
+  onFalse?: 'complete' | 'skip' | number
+  branches?: WorkflowStep[][]
+}
+```
+</details>
+
+<details>
+<summary><code>WorkflowRun</code></summary>
+
+```ts
+type WorkflowStatus = 'pending' | 'running' | 'waiting' | 'completed' | 'failed' | 'canceled'
+
+interface WorkflowRun {
+  id: string
+  definitionId: string
+  tenantId: string
+  triggerId: string
+  status: WorkflowStatus
+  context: Record<string, unknown>
+  currentStepIndex: number
+  isReplay: boolean
+  definitionSnapshot: DefinitionSnapshot
+  startedAt?: Date
+  completedAt?: Date
+  failedAt?: Date
+  canceledAt?: Date
+  cancelReason?: string
+  createdAt: Date
+  updatedAt: Date
+}
+```
+</details>
+
+<details>
+<summary><code>WorkflowStepRun</code></summary>
+
+```ts
+type StepStatus = 'pending' | 'scheduled' | 'running' | 'completed' | 'failed' | 'skipped'
+
+interface WorkflowStepRun {
+  id: string
+  runId: string
+  tenantId: string
+  stepIndex: number
+  stepType: StepType
+  stepName: string
+  status: StepStatus
+  scheduledFor?: Date
+  startedAt?: Date
+  completedAt?: Date
+  result?: Record<string, unknown>
+  errorMessage?: string
+  branchIndex?: number
+  parentStepRunId?: string
+  createdAt: Date
+}
+```
+</details>
+
+<details>
+<summary><code>RunTimelineEntry</code></summary>
+
+```ts
+interface RunTimelineEntry {
+  timestamp: Date
+  type:
+    | 'run_created' | 'run_completed' | 'run_failed' | 'run_canceled'
+    | 'step_scheduled' | 'step_started' | 'step_completed'
+    | 'step_failed' | 'step_skipped' | 'log'
+  stepIndex?: number
+  stepName?: string
+  stepType?: string
+  detail?: Record<string, unknown>
+}
+```
+</details>
+
+<details>
+<summary><code>WorkflowContext</code></summary>
+
+```ts
+interface WorkflowContext {
+  tenantId: string
+  trigger: TriggerEnvelope
+  run: WorkflowRun
+  step: WorkflowStepRun
+  config: Record<string, unknown>
+  isReplay: boolean
+  emit: (trigger: TriggerInput) => Promise<TriggerEnvelope>
+  log: (message: string, data?: Record<string, unknown>) => void
+}
+```
+</details>
+
+<details>
+<summary><code>EngineConfig</code></summary>
+
+```ts
+interface EngineConfig {
+  db: Pool
+  redis: unknown
+  tablePrefix?: string     // Default: 'pulse_'
+  queuePrefix?: string     // Default: 'pulse'
+  concurrency?: number     // Default: 5
+  onStepComplete?: LifecycleHook<StepCompleteEvent>
+  onRunComplete?: LifecycleHook<RunCompleteEvent>
+}
+```
+</details>
+
+<details>
+<summary><code>ActionResult</code> / <code>ActionOptions</code> / <code>RetryPolicy</code> / <code>ReplayOptions</code></summary>
+
+```ts
+interface ActionResult {
+  success: boolean
+  data?: Record<string, unknown>
+  error?: string
+}
+
+interface ActionOptions {
+  replaySafe: boolean
+}
+
+interface RetryPolicy {
+  maxAttempts: number   // 1-10
+  backoffMs: number     // 100-300000 ms
+}
+
+interface ReplayOptions {
+  dryRun?: boolean
+}
+```
+</details>
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      Your Application                        │
+│                                                              │
+│   engine.emit({ type: 'heartbeat.missed', ... })             │
+│       │                                                      │
+│       v                                                      │
+│   ┌──────────┐    ┌──────────┐    ┌────────────────────┐     │
+│   │ Registry │    │ Matcher  │--->│    Run Manager      │     │
+│   │          │    │          │    │   (state machine)   │     │
+│   │ triggers │    │ matches  │    │                     │     │
+│   │ actions  │    │ signal   │    │ pending -> running   │     │
+│   │ conds    │    │ to wfs   │    │ -> waiting -> done   │     │
+│   └──────────┘    └──────────┘    └─────────┬──────────┘     │
+│                                             │                │
+│                                             v                │
+│   ┌──────────────────────┐    ┌────────────────────────┐     │
+│   │   Step Scheduler     │    │    Step Executor        │     │
+│   │                      │--->│                         │     │
+│   │ BullMQ delayed jobs  │    │ delay -> cond -> action │     │
+│   │ + parallel branches  │    │ + parallel dispatch     │     │
+│   └──────────────────────┘    └────────────────────────┘     │
+│                                                              │
+│   ┌───────────────┐  ┌──────────────┐  ┌────────────────┐   │
+│   │ Replay Mgr    │  │  Cron Mgr    │  │  Timeline &    │   │
+│   │               │  │              │  │  Exec Logs     │   │
+│   │ re-emit with  │  │ BullMQ       │  │                │   │
+│   │ safety checks │  │ repeatables  │  │ ctx.log()      │   │
+│   └───────────────┘  └──────────────┘  └────────────────┘   │
+│                                                              │
+│   ┌──────────────┐           ┌────────────────┐              │
+│   │  PostgreSQL  │           │     Redis      │              │
+│   │  (your DB)   │           │  (BullMQ jobs) │              │
+│   └──────────────┘           └────────────────┘              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Module Breakdown
+
+| Module | File | Purpose |
+|:--|:--|:--|
+| Engine Factory | `src/index.ts` | `createEngine()` — wires everything together |
+| Types | `src/types.ts` | All TypeScript interfaces and type definitions |
+| Registry | `src/registry.ts` | Trigger, action, and condition registration |
+| Matcher | `src/matcher.ts` | Signal-to-workflow matching, run creation, validation |
+| Run Manager | `src/runs.ts` | Run lifecycle, state machine, timeline, cancel |
+| Scheduler | `src/scheduler.ts` | Step scheduling with BullMQ delayed jobs + parallel |
+| Executor | `src/executor.ts` | Step dispatch — delay, condition, action, parallel |
+| Cron Manager | `src/cron.ts` | Cron scheduling via BullMQ repeatable jobs |
+| Replay | `src/replay.ts` | Trigger persistence and replay support |
+| Queue | `src/queue.ts` | BullMQ queue and worker setup |
+| Logs | `src/logs.ts` | Execution logging and query helpers |
+| Schema | `src/schema/` | Table definitions and migration runner |
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|:--|:--|
+| Node.js | 18+ |
+| PostgreSQL | 12+ |
+| Redis | 6+ |
+| TypeScript | 5.0+ |
+
+---
+
+## License
+
+MIT