@bitclaw/jobs 1.5.0 → 2.1.0

package/README.md

@@ -1,18 +1,6 @@
 # @bitclaw/jobs
 
-SQLite-backed background job queue for Bun. Features priority ordering, retries with backoff, cron scheduling, job dependencies, batch processing, rate limiting, and a dead-letter table.
-
-## Features
-
-- **Typed** Generic `JobQueue<TMap>` with per-type payload validation
-- **Priority** Jobs ordered by priority DESC then created_at ASC
-- **Retries** Configurable `maxRetries` with automatic dead-letter after exhaustion
-- **Dependencies** Blocked jobs auto-unblock when all dependencies complete
-- **Batches** Group jobs, track progress, fire `then`/`finally` callbacks on completion
-- **Cron** 5-field cron parser with `nextCronOccurrence` and overlap control
-- **Scheduler** Persistent `schedules` table with upsert semantics and cleanup
-- **Rate Limiter** In-memory sliding window per-worker throttling
-- **Worker** `setTimeout`-based poll loop with graceful shutdown and per-job timeout
+SQLite-backed background job queue for Bun. Typed generics, multi-process lease safety, priority aging, middleware pipeline, workflow engine with saga compensation, and zero runtime dependencies.
 
 ## Installation
 
@@ -20,6 +8,36 @@ SQLite-backed background job queue for Bun. Features priority ordering, retries
 bun add @bitclaw/jobs
 ```
 
+Requires Bun ≥ 1.3.0. Uses `bun:sqlite` — no native build step, no extra packages.
+
+## Feature Overview
+
+| Feature | Details |
+|---|---|
+| **Typed payloads** | `JobQueue<TMap>` — per-type payload inference, no `any` |
+| **Priority + aging** | Jobs ordered by priority DESC; workers can boost old jobs per minute |
+| **Retries + backoff** | `exponential`, `fixed`, `jitter`, `fibonacci`; `retryIf` predicate to skip retries |
+| **Dead-letter** | Exhausted jobs moved to `failed_jobs`, retryable via `retryFailedJob` |
+| **Dependencies** | Blocked jobs auto-unblock when all deps complete |
+| **Multi-process safety** | Lease column (`claimed_until`) prevents double-claim across processes |
+| **Lease renewal** | Long-running handlers call `ctx.renewLease()` to extend their claim |
+| **Batches** | Group jobs, track progress, fire `then`/`finally` callbacks on completion |
+| **Cron scheduler** | 5-field cron parser, persistent `schedules` table, overlap control |
+| **Rate limiter** | Per-worker sliding-window throttle (`maxRate`) |
+| **Middleware** | Onion-style `queue.use(fn)` wraps all executions (logging, OTel, timing) |
+| **Job graph API** | `getJobGraph(id)` traverses dependency DAG via recursive CTE |
+| **Dedup** | `uniqueKey` + `dedup: 'ignore' | 'replace'` — state-aware, key reusable after completion |
+| **TTL** | `expireAt` — expired jobs silently skipped and purgeable |
+| **Result storage** | Handler return value persisted; `getJobResult<T>(id)` to read it |
+| **Webhook on completion** | `onComplete: { url }` fires a detached POST after job finishes |
+| **Typed events** | `queue.on('job:done' | 'job:failed' | 'job:dead' | ...)` |
+| **Pause / resume** | `worker.pause()` / `worker.resume()` — in-flight job finishes, no new claims |
+| **Admin handler** | `queue.mountAdminHandler()` returns a zero-dep `Request → Response` handler |
+| **Workflow engine** | `WorkflowEngine` — typed DAG of steps, saga compensation, restart-safe `reconcile()` |
+| **OpenTelemetry** | `createOtelMiddleware(tracer)` — zero-dep, structural tracer interface |
+
+---
+
 ## Quick Start
 
 ```typescript
@@ -27,58 +45,364 @@ import { JobQueue } from '@bitclaw/jobs'
 
 type AppJobs = {
   'email:send': { to: string; subject: string }
+  'report:generate': { type: string }
 }
 
 const queue = new JobQueue<AppJobs>('./jobs.db')
-queue.add('email:send', { to: 'user@test.com', subject: 'Hello' })
-```
 
-## Worker
+// Enqueue
+queue.add('email:send', { to: 'user@example.com', subject: 'Welcome' })
 
-```typescript
+// Worker
 const worker = queue.createWorker({
   type: 'email:send',
   handler: async (job, ctx) => {
     ctx.reportProgress(50)
-    await sendEmail(job.data.to, job.data.subject)
+    await sendEmail(job.data)
+    return { sent: true }          // stored in job.result
   },
   pollIntervalMs: 1000,
-  maxRate: { count: 10, windowMs: 1000 }
+  maxRate: { count: 20, windowMs: 1000 }
 })
 
 worker.start()
-// ... later
-await worker.stop()
 ```
 
+---
+
+## Retries and Backoff
+
+```typescript
+queue.add('email:send', data, {
+  maxRetries: 5,
+  backoff: { type: 'exponential', delayMs: 1000 }
+  // types: 'exponential' | 'fixed' | 'jitter' | 'fibonacci'
+})
+
+// Skip retries for permanent errors
+queue.createWorker({
+  type: 'email:send',
+  handler: async job => { /* ... */ },
+  retryIf: (err, job) => !(err instanceof ValidationError)
+})
+```
+
+---
+
+## Dependencies
+
+```typescript
+const depA = queue.add('data:fetch', { source: 'api' })
+const depB = queue.add('data:fetch', { source: 'db' })
+
+// Blocked until both depA and depB complete
+queue.add('report:generate', { type: 'combined' }, {
+  dependsOn: [depA, depB]
+})
+```
+
+---
+
+## Multi-Process Lease Safety
+
+Two workers against the same DB file cannot claim the same job. `pollAndClaim` atomically sets `claimed_until`. If a worker crashes mid-job, any other worker reclaims after lease expiry.
+
+```typescript
+// Default lease: 5 minutes. Override per worker:
+queue.createWorker({
+  type: 'server:provision',
+  handler: async (job, ctx) => {
+    await longStep()
+    ctx.renewLease()   // extend before expiry
+    await anotherStep()
+  },
+  leaseMs: 600_000    // 10 min
+})
+```
+
+---
+
+## Middleware
+
+```typescript
+// Logging
+queue.use(async (job, next) => {
+  console.info(`[job] ${job.type} #${job.id} start`)
+  const result = await next()
+  console.info(`[job] ${job.type} #${job.id} done`)
+  return result
+})
+
+// Multiple middlewares run in registration order (onion)
+queue.use(timingMiddleware)
+queue.use(loggingMiddleware)
+// execution: timing → logging → handler → logging → timing
+```
+
+---
+
+## OpenTelemetry
+
+No peer dependency. Pass any OTel-compatible tracer — the interface is structural.
+
+```typescript
+import { trace } from '@opentelemetry/api'
+import { createOtelMiddleware } from '@bitclaw/jobs/otel'
+
+const tracer = trace.getTracer('my-app', '1.0.0')
+queue.use(createOtelMiddleware(tracer))
+```
+
+Each job execution becomes a span named `job.<type>` with attributes:
+
+| Attribute | Value |
+|---|---|
+| `job.id` | numeric job ID |
+| `job.type` | type string |
+| `job.priority` | priority |
+| `job.retry` | retry count at execution time |
+| `job.error` | error message (failure only) |
+
+---
+
+## Priority Aging
+
+Prevents starvation of low-priority jobs under sustained high-priority load.
+
+```typescript
+queue.createWorker({
+  type: 'email:send',
+  handler: async job => { /* ... */ },
+  aging: {
+    boostPerMinute: 10,  // +10 priority per minute of wait
+    maxBoost: 100        // cap
+  }
+})
+```
+
+---
+
+## Job Graph API
+
+```typescript
+const nodes = queue.getJobGraph(rootJobId)
+// nodes: Array<{ id, type, status, result, dependsOn: number[], dependents: number[] }>
+```
+
+Traverses the full dependency DAG (ancestors + descendants) via SQLite recursive CTE.
+
+---
+
+## Deduplication
+
+```typescript
+// Ignore: silently re-uses existing pending job
+queue.add('report:generate', data, { uniqueKey: 'daily-2026-06-27', dedup: 'ignore' })
+
+// Replace: updates data on existing pending job
+queue.add('report:generate', freshData, { uniqueKey: 'daily-2026-06-27', dedup: 'replace' })
+
+// Cancel pending job by key
+queue.cancelByUniqueKey('report:generate', 'daily-2026-06-27')
+```
+
+---
+
+## Result Storage
+
+```typescript
+const id = queue.add('data:process', payload)
+
+// In handler — return value is stored automatically
+queue.createWorker({
+  type: 'data:process',
+  handler: async job => {
+    return { count: 42, processed: true }
+  }
+})
+
+// Read later
+const result = queue.getJobResult<{ count: number; processed: boolean }>(id)
+```
+
+---
+
+## Typed Events
+
+```typescript
+queue.on('job:done',     job => console.info('done', job.id))
+queue.on('job:failed',   (job, err) => console.warn('retry', err))
+queue.on('job:dead',     (job, err) => alert.send(err))
+queue.on('job:progress', (job, pct) => ws.send({ id: job.id, pct }))
+queue.on('batch:complete', batch => notify(batch.id))
+
+const unsub = queue.on('job:done', cb)
+unsub()   // remove listener
+```
+
+---
+
+## Workflow Engine
+
+Typed DAG of steps where each step is a real job. Dependencies handled by the existing `job_dependencies` mechanism — no separate scheduler. Saga compensation runs in reverse topological order if any step fails permanently.
+
+```typescript
+import { WorkflowEngine } from '@bitclaw/jobs'
+
+const engine = new WorkflowEngine(queue)
+
+const { instanceId, jobIds } = engine
+  .workflow('order-flow')
+  .step('charge',    'payment:charge',   { amount: 100 })
+  .step('provision', 'server:provision', { serverId: 'srv-1' }, { dependsOn: ['charge'] })
+  .step('notify',    'email:welcome',    { userId: 'u1' },      { dependsOn: ['provision'] })
+  .onFail('charge', {
+    compensate: 'payment:refund',
+    compensateData: { amount: 100, reason: 'provision-failed' }
+  })
+  .run()
+
+// Reconcile on startup — resumes any interrupted workflows
+engine.reconcile()
+
+// Read a step's result from within a dependent handler
+const chargeResult = engine.getStepResult<ChargeResult>(instanceId, 'charge')
+
+// Query executions
+engine.listExecutions({ status: 'running', name: 'order-flow' })
+engine.getExecution(instanceId)
+```
+
+**Saga semantics:** `onFail(stepName, { compensate, compensateData })` registers a compensation job for a step that completed successfully. If a later step fails permanently, `reconcile()` enqueues compensation jobs (in reverse topological order) for all completed steps that registered one, then transitions the execution to `compensating`. When all compensation jobs finish, the execution is marked `failed`.
+
+**Restart safety:** Call `engine.reconcile()` on boot. It finds all `running`/`compensating` executions and advances their state without re-running completed steps.
+
+---
+
 ## Cron Scheduler
 
 ```typescript
 import { Scheduler } from '@bitclaw/jobs'
 
 const scheduler = new Scheduler(queue)
+
 scheduler.register('daily-report', 'report:generate', '0 2 * * *', {
-  data: { type: 'daily' }
+  data: { type: 'daily' },
+  timezone: 'America/New_York',
+  overlap: false   // skip if previous run still processing
+})
+
+scheduler.start()   // ticks every 60s by default
+await scheduler.stop()
+```
+
+---
+
+## Admin Handler
+
+Zero-dependency `Request → Response` handler. Mount in any framework.
+
+```typescript
+// TanStack Start / Hono / bare Bun.serve
+const adminHandler = queue.mountAdminHandler('/admin/jobs')
+
+// Routes:
+// GET  /admin/jobs/stats
+// GET  /admin/jobs/jobs
+// GET  /admin/jobs/jobs/:id
+// GET  /admin/jobs/jobs/:id/graph
+// POST /admin/jobs/jobs/:id/cancel
+// POST /admin/jobs/jobs/:id/force-retry
+// GET  /admin/jobs/failed
+// POST /admin/jobs/failed/:id/retry
+// POST /admin/jobs/failed/retry-by-type
+// GET  /admin/jobs/jobs/types
+```
+
+---
+
+## Batch Processing
+
+```typescript
+const { batchId, jobIds } = queue.addBatch('nightly-sync', [
+  { type: 'user:sync', data: { userId: 'u1' } },
+  { type: 'user:sync', data: { userId: 'u2' } }
+], {
+  thenType: 'report:generate',
+  thenData: { trigger: 'batch-done' }
 })
-scheduler.start() // ticks every 60s by default
+
+const batch = queue.getBatch(batchId)
+// { totalJobs: 2, pendingJobs: 1, failedJobs: 0, ... }
 ```
 
+---
+
 ## Subpath Exports
 
 ```typescript
-import { JobQueue }       from '@bitclaw/jobs'
-import { JobWorker }      from '@bitclaw/jobs/worker'
-import { JobQueue }       from '@bitclaw/jobs/queue'
-import { Scheduler }      from '@bitclaw/jobs/scheduler'
-import { parseCron }      from '@bitclaw/jobs/cron'
-import { initializeSchema } from '@bitclaw/jobs/schema'
-import { SlidingWindowRateLimiter } from '@bitclaw/jobs/rate-limiter'
+import { JobQueue, WorkflowEngine }  from '@bitclaw/jobs'
+import { createOtelMiddleware }       from '@bitclaw/jobs/otel'
+import { WorkflowBuilder }           from '@bitclaw/jobs/workflow'
+import { Scheduler }                 from '@bitclaw/jobs/scheduler'
+import { parseCron }                 from '@bitclaw/jobs/cron'
+import { initializeSchema }          from '@bitclaw/jobs/schema'
+import { SlidingWindowRateLimiter }  from '@bitclaw/jobs/rate-limiter'
+import { JobWorker }                 from '@bitclaw/jobs/worker'
 ```
 
+---
+
+## Competitor Comparison
+
+Analysis against every actively-maintained SQLite job queue as of 2026-06.
+
+| Feature | **@bitclaw/jobs** | bunqueue | plainjob | workmatic | liteq (Go) | apalis-sqlite (Rust) |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| Typed generics | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Priority ordering | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Priority aging (starvation prevention) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Exponential / jitter / fibonacci backoff | ✅ | ✅ (exp only) | ✅ (exp only) | ❌ | ✅ (fixed) | ✅ (exp only) |
+| `retryIf` predicate | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Dead-letter table | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
+| Job dependencies (DAG) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Job graph API (recursive CTE) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Multi-process lease safety | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
+| Lease renewal (`ctx.renewLease`) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Dedup (ignore + replace) | ✅ | ✅ (ignore) | ❌ | ✅ (ignore) | ❌ | ❌ |
+| Job TTL / `expireAt` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Result storage | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| Typed events | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Middleware pipeline | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| OpenTelemetry helper | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Pause / resume per worker | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Webhook on completion | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Batch processing | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
+| Cron scheduler | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
+| Admin HTTP handler | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| Workflow engine | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Saga compensation | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Restart-safe reconcile | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Concurrency per worker | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Rate limiting per worker | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Zero runtime dependencies | ✅ | ✅ | ✅ | ❌ | n/a | n/a |
+
+**Key differentiators:**
+
+- **Only queue with a workflow engine.** `WorkflowEngine` composes real jobs into typed DAGs with saga compensation and restart-safe reconciliation. Competitors require external orchestrators (Temporal, Inngest) for this.
+- **Only queue with middleware.** `queue.use(fn)` enables logging, tracing, and auth-checking without modifying job handlers. Every other queue buries these concerns inside worker configuration.
+- **Only queue with lease renewal.** Long-running jobs (provisioning, ML inference) can extend their claim without crashing. Competitors force you to size `leaseMs` conservatively.
+- **Only queue with priority aging.** High-throughput workloads can starve low-priority jobs indefinitely. Aging prevents it.
+- **Only queue with `retryIf`.** Permanent errors (bad config, invalid input) should not consume retry budget. All others retry blindly.
+- **Job graph API.** `getJobGraph(id)` returns the full dependency graph via recursive CTE — useful for admin UIs and debugging complex pipelines. No competitor exposes this.
+- **OTel helper.** `createOtelMiddleware(tracer)` instruments all job executions with zero library coupling. No peer dependency — the tracer interface is structural.
+
+---
+
 ## Testing
 
 ```bash
 bun test
 ```
 
-118 tests across 7 files.
+204 tests across 9 files.

package/dist/index.d.ts

@@ -2,11 +2,14 @@ export type { ParsedCron } from './cron';
 export { cronMatches, nextCronOccurrence, parseCron } from './cron';
 export type { JobQueueEventMap } from './events';
 export { JobQueueEmitter } from './events';
+export type { OtelSpan, OtelTracer } from './otel';
+export { createOtelMiddleware } from './otel';
 export { JobQueue } from './queue';
 export { SlidingWindowRateLimiter } from './rate-limiter';
 export { Scheduler } from './scheduler';
 export { applyPragmas, initializeSchema } from './schema';
-export type { AddJobOptions, AddScheduleOptions, BackoffConfig, BatchOptions, FailedJob, Job, JobBatch, JobContext, JobGraphNode, JobMap, JobStats, JobStatus, ListJobsOptions, MiddlewareFn, PaginatedResult, PurgeOptions, RateLimit, Schedule, WorkerOptions } from './types';
+export type { AddJobOptions, AddScheduleOptions, BackoffConfig, BatchOptions, FailedJob, Job, JobBatch, JobContext, JobGraphNode, JobMap, JobStats, JobStatus, ListJobsOptions, MiddlewareFn, PaginatedResult, PurgeOptions, RateLimit, Schedule, WorkerOptions, WorkflowExecution, WorkflowExecutionStatus, WorkflowReconcileResult, WorkflowRunResult } from './types';
 export { NonRetryableError } from './types';
 export { JobWorker } from './worker';
+export { WorkflowBuilder, WorkflowEngine } from './workflow';
 //# 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":"AAGA,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC1D,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,SAAS,EACT,GAAG,EACH,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,MAAM,EACN,QAAQ,EACR,SAAS,EACT,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,aAAa,EACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC1D,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,SAAS,EACT,GAAG,EACH,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,MAAM,EACN,QAAQ,EACR,SAAS,EACT,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,9 +2,11 @@
 // Barrel export for @bitclaw/jobs
 export { cronMatches, nextCronOccurrence, parseCron } from './cron';
 export { JobQueueEmitter } from './events';
+export { createOtelMiddleware } from './otel';
 export { JobQueue } from './queue';
 export { SlidingWindowRateLimiter } from './rate-limiter';
 export { Scheduler } from './scheduler';
 export { applyPragmas, initializeSchema } from './schema';
 export { NonRetryableError } from './types';
 export { JobWorker } from './worker';
+export { WorkflowBuilder, WorkflowEngine } from './workflow';

package/dist/otel.d.ts

@@ -0,0 +1,39 @@
+import type { MiddlewareFn } from './types';
+/**
+ * Minimal interface matching @opentelemetry/api Tracer.
+ * Typed structurally so @bitclaw/jobs stays dependency-free —
+ * pass any OTel-compatible tracer without adding it as a peer dep.
+ */
+export type OtelTracer = {
+    startActiveSpan<T>(name: string, fn: (span: OtelSpan) => T): T;
+};
+export type OtelSpan = {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    recordException(error: unknown): void;
+    end(): void;
+};
+/**
+ * Returns a middleware that wraps every job execution in an OTel span.
+ *
+ * Usage:
+ * ```ts
+ * import { trace } from '@opentelemetry/api'
+ * import { createOtelMiddleware } from '@bitclaw/jobs/otel'
+ *
+ * const tracer = trace.getTracer('my-app')
+ * queue.use(createOtelMiddleware(tracer))
+ * ```
+ *
+ * Each span is named `job.<type>` and carries these attributes:
+ * - `job.id`       — numeric job ID
+ * - `job.type`     — job type string
+ * - `job.priority` — job priority
+ * - `job.retry`    — current retry count
+ * - `job.error`    — error message (only on failure)
+ */
+export declare function createOtelMiddleware(tracer: OtelTracer): MiddlewareFn;
+//# sourceMappingURL=otel.d.ts.map

package/dist/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,CAAC,GAAG,CAAC,CAAC;CAChE,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,GAAG,IAAI,IAAI,CAAC;CACb,CAAC;AAMF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CAqBrE"}

package/dist/otel.js

@@ -0,0 +1,45 @@
+/** SpanStatusCode.OK = 1, SpanStatusCode.ERROR = 2 (OTel spec) */
+const STATUS_OK = 1;
+const STATUS_ERROR = 2;
+/**
+ * Returns a middleware that wraps every job execution in an OTel span.
+ *
+ * Usage:
+ * ```ts
+ * import { trace } from '@opentelemetry/api'
+ * import { createOtelMiddleware } from '@bitclaw/jobs/otel'
+ *
+ * const tracer = trace.getTracer('my-app')
+ * queue.use(createOtelMiddleware(tracer))
+ * ```
+ *
+ * Each span is named `job.<type>` and carries these attributes:
+ * - `job.id`       — numeric job ID
+ * - `job.type`     — job type string
+ * - `job.priority` — job priority
+ * - `job.retry`    — current retry count
+ * - `job.error`    — error message (only on failure)
+ */
+export function createOtelMiddleware(tracer) {
+    return (job, next) => tracer.startActiveSpan(`job.${job.type}`, async (span) => {
+        span.setAttribute('job.id', job.id);
+        span.setAttribute('job.type', job.type);
+        span.setAttribute('job.priority', job.priority);
+        span.setAttribute('job.retry', job.retryCount);
+        try {
+            const result = await next();
+            span.setStatus({ code: STATUS_OK });
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            span.setAttribute('job.error', message);
+            span.recordException(err);
+            span.setStatus({ code: STATUS_ERROR, message });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAwG3C,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAY/C;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAkCnD"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA6H3C,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAY/C;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAoCnD"}

package/dist/schema.js

@@ -90,6 +90,25 @@ CREATE TABLE IF NOT EXISTS schedules (
 const SCHEDULES_NEXT_RUN_INDEX = `
 CREATE INDEX IF NOT EXISTS idx_schedules_next_run
   ON schedules (enabled, next_run_at)`;
+const WORKFLOW_EXECUTIONS_TABLE = `
+CREATE TABLE IF NOT EXISTS workflow_executions (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'running',
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  completed_at TEXT
+)`;
+const WORKFLOW_STEPS_TABLE = `
+CREATE TABLE IF NOT EXISTS workflow_steps (
+  execution_id TEXT NOT NULL REFERENCES workflow_executions(id),
+  step_name TEXT NOT NULL,
+  job_id INTEGER NOT NULL,
+  compensate_type TEXT,
+  compensate_data TEXT,
+  compensate_job_id INTEGER,
+  step_order INTEGER NOT NULL,
+  PRIMARY KEY (execution_id, step_name)
+)`;
 export function applyPragmas(db) {
     if (db.filename !== ':memory:' && db.filename !== '') {
         db.run('PRAGMA journal_mode = WAL');
@@ -112,6 +131,8 @@ export function initializeSchema(db) {
     db.run(FAILED_JOBS_TABLE);
     db.run(SCHEDULES_TABLE);
     db.run(SCHEDULES_NEXT_RUN_INDEX);
+    db.run(WORKFLOW_EXECUTIONS_TABLE);
+    db.run(WORKFLOW_STEPS_TABLE);
     // Migrations for columns added after initial schema creation
     const cols = db.prepare('PRAGMA table_info(jobs)').all();
     if (!cols.some(c => c.name === 'unique_key')) {

package/dist/types.d.ts

@@ -241,4 +241,21 @@ export type AddScheduleOptions = {
     overlap?: boolean;
     maxRetries?: number;
 };
+export type WorkflowExecutionStatus = 'running' | 'completed' | 'compensating' | 'failed';
+export type WorkflowExecution = {
+    readonly id: string;
+    readonly name: string;
+    readonly status: WorkflowExecutionStatus;
+    readonly createdAt: string;
+    readonly completedAt: string | null;
+};
+export type WorkflowRunResult<TStepNames extends string> = {
+    instanceId: string;
+    jobIds: Record<TStepNames, number>;
+};
+export type WorkflowReconcileResult = {
+    completed: number;
+    compensated: number;
+    failed: number;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/workflow.d.ts

@@ -0,0 +1,36 @@
+import type { JobQueue } from './queue';
+import type { AddJobOptions, BackoffConfig, JobMap, WorkflowExecution, WorkflowExecutionStatus, WorkflowReconcileResult, WorkflowRunResult } from './types';
+export type { WorkflowExecution, WorkflowExecutionStatus, WorkflowReconcileResult, WorkflowRunResult };
+type StepStepOptions = Omit<AddJobOptions, 'dependsOn'> & {
+    dependsOn?: string[];
+    backoff?: BackoffConfig;
+};
+export declare class WorkflowBuilder<TMap extends JobMap, TStepNames extends string = never> {
+    private readonly queue;
+    private readonly name;
+    private readonly specs;
+    private readonly compensations;
+    constructor(queue: JobQueue<TMap>, name: string);
+    step<SName extends string, K extends string & keyof TMap>(stepName: SName, jobType: K, data: TMap[K], options?: StepStepOptions): WorkflowBuilder<TMap, TStepNames | SName>;
+    onFail<K extends string & keyof TMap>(stepName: TStepNames, compensation: {
+        compensate: K;
+        compensateData: TMap[K];
+    }): this;
+    run(instanceId?: string): WorkflowRunResult<TStepNames>;
+}
+export declare class WorkflowEngine<TMap extends JobMap> {
+    private readonly queue;
+    constructor(queue: JobQueue<TMap>);
+    workflow<TStepNames extends string = never>(name: string): WorkflowBuilder<TMap, TStepNames>;
+    getExecution(instanceId: string): WorkflowExecution | null;
+    getStepResult<T>(instanceId: string, stepName: string): T | null;
+    listExecutions(opts?: {
+        status?: WorkflowExecutionStatus;
+        name?: string;
+        limit?: number;
+        offset?: number;
+    }): WorkflowExecution[];
+    reconcile(): WorkflowReconcileResult;
+    private reconcileExecution;
+}
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,MAAM,EACN,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EAClB,CAAC;AAEF,KAAK,eAAe,GAAG,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,GAAG;IACxD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB,CAAC;AA6DF,qBAAa,eAAe,CAC1B,IAAI,SAAS,MAAM,EACnB,UAAU,SAAS,MAAM,GAAG,KAAK;IAS/B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IARvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAG1B;gBAGe,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,IAAI,EAAE,MAAM;IAG/B,IAAI,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,EACtD,QAAQ,EAAE,KAAK,EACf,OAAO,EAAE,CAAC,EACV,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,eAAe,GACxB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,KAAK,CAAC;IAY5C,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,EAClC,QAAQ,EAAE,UAAU,EACpB,YAAY,EAAE;QAAE,UAAU,EAAE,CAAC,CAAC;QAAC,cAAc,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;KAAE,GACvD,IAAI;IAQP,GAAG,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,UAAU,CAAC;CA4DxD;AAID,qBAAa,cAAc,CAAC,IAAI,SAAS,MAAM;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC;IAElD,QAAQ,CAAC,UAAU,SAAS,MAAM,GAAG,KAAK,EACxC,IAAI,EAAE,MAAM,GACX,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC;IAIpC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAO1D,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAUhE,cAAc,CACZ,IAAI,GAAE;QACJ,MAAM,CAAC,EAAE,uBAAuB,CAAC;QACjC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ,GACL,iBAAiB,EAAE;IAgCtB,SAAS,IAAI,uBAAuB;IAoBpC,OAAO,CAAC,kBAAkB;CA2F3B"}

package/dist/workflow.js

@@ -0,0 +1,219 @@
+import { nowISO } from './utils';
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function topologicalSort(specs) {
+    const nameToSpec = new Map(specs.map(s => [s.stepName, s]));
+    const visited = new Set();
+    const result = [];
+    const visit = (name) => {
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        const spec = nameToSpec.get(name);
+        if (!spec)
+            throw new Error(`Unknown step '${name}' in dependsOn`);
+        for (const dep of spec.dependsOn)
+            visit(dep);
+        result.push(spec);
+    };
+    for (const spec of specs)
+        visit(spec.stepName);
+    return result;
+}
+function toWorkflowExecution(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        status: row.status,
+        createdAt: row.created_at,
+        completedAt: row.completed_at
+    };
+}
+// ─── WorkflowBuilder ────────────────────────────────────────────────────────
+export class WorkflowBuilder {
+    queue;
+    name;
+    specs = [];
+    compensations = new Map();
+    constructor(queue, name) {
+        this.queue = queue;
+        this.name = name;
+    }
+    step(stepName, jobType, data, options) {
+        this.specs.push({
+            stepName,
+            jobType: jobType,
+            data,
+            dependsOn: (options?.dependsOn ?? []),
+            options: options ?? {},
+            compensation: null
+        });
+        return this;
+    }
+    onFail(stepName, compensation) {
+        this.compensations.set(stepName, {
+            type: compensation.compensate,
+            data: compensation.compensateData
+        });
+        return this;
+    }
+    run(instanceId) {
+        const id = instanceId ?? crypto.randomUUID();
+        const jobIds = {};
+        this.queue.db.transaction(() => {
+            this.queue.db.run(`INSERT INTO workflow_executions (id, name, status, created_at)
+         VALUES (?, ?, 'running', ?)`, [id, this.name, nowISO()]);
+            const sorted = topologicalSort(this.specs);
+            for (let order = 0; order < sorted.length; order++) {
+                const spec = sorted[order];
+                const depJobIds = spec.dependsOn.map(depName => {
+                    const depId = jobIds[depName];
+                    if (depId === undefined)
+                        throw new Error(`Step '${depName}' not enqueued yet — check dependsOn`);
+                    return depId;
+                });
+                const addOpts = {
+                    priority: spec.options.priority,
+                    maxRetries: spec.options.maxRetries,
+                    backoff: spec.options.backoff,
+                    runAt: spec.options.runAt,
+                    uniqueKey: spec.options.uniqueKey,
+                    ...(depJobIds.length > 0 ? { dependsOn: depJobIds } : {})
+                };
+                const jobId = this.queue.add(spec.jobType, spec.data, addOpts);
+                jobIds[spec.stepName] = jobId;
+                const comp = this.compensations.get(spec.stepName) ?? null;
+                this.queue.db.run(`INSERT INTO workflow_steps
+             (execution_id, step_name, job_id, compensate_type, compensate_data, step_order)
+           VALUES (?, ?, ?, ?, ?, ?)`, [
+                    id,
+                    spec.stepName,
+                    jobId,
+                    comp?.type ?? null,
+                    comp ? JSON.stringify(comp.data) : null,
+                    order
+                ]);
+            }
+        })();
+        return { instanceId: id, jobIds: jobIds };
+    }
+}
+// ─── WorkflowEngine ─────────────────────────────────────────────────────────
+export class WorkflowEngine {
+    queue;
+    constructor(queue) {
+        this.queue = queue;
+    }
+    workflow(name) {
+        return new WorkflowBuilder(this.queue, name);
+    }
+    getExecution(instanceId) {
+        const row = this.queue.db
+            .query('SELECT * FROM workflow_executions WHERE id = ?')
+            .get(instanceId);
+        return row ? toWorkflowExecution(row) : null;
+    }
+    getStepResult(instanceId, stepName) {
+        const step = this.queue.db
+            .query('SELECT job_id FROM workflow_steps WHERE execution_id = ? AND step_name = ?')
+            .get(instanceId, stepName);
+        if (!step)
+            return null;
+        return this.queue.getJobResult(step.job_id);
+    }
+    listExecutions(opts = {}) {
+        const conditions = [];
+        const params = [];
+        if (opts.status) {
+            conditions.push('status = ?');
+            params.push(opts.status);
+        }
+        if (opts.name) {
+            conditions.push('name = ?');
+            params.push(opts.name);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const limit = opts.limit ?? 50;
+        const offset = opts.offset ?? 0;
+        const rows = this.queue.db
+            .query(`SELECT * FROM workflow_executions ${where}
+         ORDER BY created_at DESC LIMIT ? OFFSET ?`)
+            .all(...params, limit, offset);
+        return rows.map(toWorkflowExecution);
+    }
+    reconcile() {
+        const stats = {
+            completed: 0,
+            compensated: 0,
+            failed: 0
+        };
+        const running = this.queue.db
+            .query("SELECT * FROM workflow_executions WHERE status IN ('running', 'compensating')")
+            .all();
+        for (const exec of running) {
+            this.reconcileExecution(exec, stats);
+        }
+        return stats;
+    }
+    reconcileExecution(exec, stats) {
+        const steps = this.queue.db
+            .query('SELECT * FROM workflow_steps WHERE execution_id = ? ORDER BY step_order ASC')
+            .all(exec.id);
+        if (exec.status === 'compensating') {
+            // If all comp jobs done (or no comp jobs), mark failed
+            const pendingComp = steps.filter(s => {
+                if (!s.compensate_job_id)
+                    return false;
+                const job = this.queue.getJob(s.compensate_job_id);
+                return job !== null && job.status !== 'done';
+            });
+            if (pendingComp.length === 0) {
+                this.queue.db.run("UPDATE workflow_executions SET status = 'failed', completed_at = ? WHERE id = ?", [nowISO(), exec.id]);
+                stats.failed++;
+            }
+            return;
+        }
+        // Build step status map
+        const stepStatuses = steps.map(step => {
+            const job = this.queue.getJob(step.job_id);
+            if (!job) {
+                // Job deleted from jobs table — check failed_jobs
+                const dead = this.queue.db
+                    .query('SELECT id FROM failed_jobs WHERE original_job_id = ? LIMIT 1')
+                    .get(step.job_id);
+                return { step, status: dead ? 'dead' : 'done' };
+            }
+            return { step, status: job.status };
+        });
+        // Any step dead → start compensation
+        const deadStep = stepStatuses.find(s => s.status === 'dead');
+        if (deadStep) {
+            const stepsWithComp = stepStatuses
+                .filter(s => s.status === 'done' && s.step.compensate_type)
+                .reverse();
+            this.queue.db.transaction(() => {
+                if (stepsWithComp.length > 0) {
+                    this.queue.db.run("UPDATE workflow_executions SET status = 'compensating' WHERE id = ?", [exec.id]);
+                    for (const { step } of stepsWithComp) {
+                        const compData = step.compensate_data
+                            ? JSON.parse(step.compensate_data)
+                            : {};
+                        const compJobId = this.queue.add(step.compensate_type, compData, {});
+                        this.queue.db.run('UPDATE workflow_steps SET compensate_job_id = ? WHERE execution_id = ? AND step_name = ?', [compJobId, exec.id, step.step_name]);
+                    }
+                    stats.compensated++;
+                }
+                else {
+                    // No compensation needed — immediately fail
+                    this.queue.db.run("UPDATE workflow_executions SET status = 'failed', completed_at = ? WHERE id = ?", [nowISO(), exec.id]);
+                    stats.failed++;
+                }
+            })();
+            return;
+        }
+        // All done → mark completed
+        if (stepStatuses.every(s => s.status === 'done')) {
+            this.queue.db.run("UPDATE workflow_executions SET status = 'completed', completed_at = ? WHERE id = ?", [nowISO(), exec.id]);
+            stats.completed++;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitclaw/jobs",
-  "version": "1.5.0",
+  "version": "2.1.0",
   "description": "SQLite-backed background job queue using bun:sqlite",
   "files": [
     "dist",
@@ -38,6 +38,14 @@
     "./scheduler": {
       "types": "./dist/scheduler.d.ts",
       "default": "./dist/scheduler.js"
+    },
+    "./workflow": {
+      "types": "./dist/workflow.d.ts",
+      "default": "./dist/workflow.js"
+    },
+    "./otel": {
+      "types": "./dist/otel.d.ts",
+      "default": "./dist/otel.js"
     }
   },
   "scripts": {