lightflow-engine 0.1.3 → 0.2.0

package/BENCHMARKS.md

@@ -0,0 +1,158 @@
+# lightflow — Benchmarks
+
+All numbers measured locally on the dev machine: Node 22, Postgres 16,
+localhost socket (no network hop). Reproduce with:
+
+```bash
+npm run build
+export LIGHTFLOW_PG_URL=postgres://user:***@localhost:5432/lightflow
+node dist/test/bench.js          # short-workflow throughput
+node dist/test/bench-long.mjs    # long-workflow throughput (RN=<steps>)
+node --test dist/test/race.js    # concurrency correctness
+```
+
+Benchmarks live in [`test/bench.ts`](test/bench.ts) and
+[`test/bench-long.mjs`](test/bench-long.mjs). SQL-statement counts come from
+`pg_stat_statements`.
+
+---
+
+## v0.1.0 — baseline
+
+The starting point: advisory-locked, statement-per-concern persistence.
+
+| Metric | Value |
+|---|---|
+| Runs / sec (200 runs × 5 steps, conc 20) | **184** |
+| Steps / sec | **922** |
+| SQL statements per event append | 5 (BEGIN, advisory lock, max(seq), INSERT, COMMIT) |
+| Advisory lock avg time in hot path | **7.8 ms** (40× every other query) |
+| `writable.write` | re-fetches full event log per write |
+| Racing resumes | can double-execute a memoized step (latent) |
+| `wakeAt` timer index | present but **silently unused** (text/bigint cast mismatch) |
+| Worker timer wake | ~4 queries + full event-log fetch per due timer |
+| Replay memo lookup | O(n) linear scan → O(n²) replay |
+
+---
+
+## v0.1.1 — event-append round
+
+**Focus: per-event write cost.** Profiled with `pg_stat_statements`, then:
+
+- `appendEvent` fast path: single `INSERT … ON CONFLICT DO NOTHING` (caller
+  supplies seq; the `(run_id, seq)` unique constraint arbitrates races).
+  Advisory lock only on rare collisions.
+- **Run lease** (`claimed_until`): atomic claim/release around each replay —
+  concurrent `resume()` calls can no longer re-execute a memoized step.
+- Dropped `step_started` events (replay never reads them).
+- `writable.write` uses the in-memory replay log, not a re-fetch.
+- `createRun`: single CTE round trip. `waitFor`: adaptive poll 5→250 ms.
+
+| Metric | v0.1.0 | v0.1.1 | Δ |
+|---|---|---|---|
+| Runs / sec (200×5, conc 20) | 184 | **456–556** | **~2.7×** |
+| Steps / sec | 922 | **~2,300–2,800** | **~2.7×** |
+| SQL per event append | 5 | 1 | −80% |
+| Advisory lock in hot path | every event | removed | — |
+| Double-execution under 20 racing resumes | possible | **0 in 200 races** | fixed |
+
+Sustained (500 runs × 10 steps, conc 100): **445 runs/s, 4,450 steps/s**.
+
+---
+
+## v0.1.2 — replay & timer round
+
+**Focus: replay cost and timer dispatch.** Researched Temporal's "replay
+debt", PgQue's notify pattern, and Absurd's minimal-query design, then:
+
+- **O(1) replay memo**: event log indexed once into a `Map` at replay start.
+- **Fixed the timer index**: expression index on `((payload->>'wakeAt')::bigint)`.
+- **`dueTimers` anti-join** against `sleep_completed` (returns key too) —
+  worker completes a timer in 2 queries instead of ~4 + full-log fetch.
+- **Adaptive worker poll** (50 ms → configured, backs off when idle) plus an
+  optional LISTEN/NOTIFY wakeup nudge (lossy; polling remains authoritative).
+
+| Metric | v0.1.1 | v0.1.2 | Δ |
+|---|---|---|---|
+| Steps / sec, 400-step workflows (50 runs) | 8,230 | **9,070** | +10% |
+| Runs / sec, 100-step workflows (50 runs) | — | 65 (6,470 steps/s) | new |
+| Queries per timer wake | ~4 + full log fetch | 2 | −60%+ |
+| Replay memo lookup | O(n) | O(1) | — |
+| Worker idle poll floor | 500 ms fixed | 50 ms adaptive + notify | — |
+
+---
+
+## v0.1.3 — compaction & client round
+
+**Focus: replay-from-scratch cost, client overhead, polling waste.**
+
+- **Snapshot compaction** (the Temporal `ContinueAsNew` problem, designed out):
+  every 200 completed steps, memoized state folds into a single `snapshot`
+  event; replay resumes from the latest snapshot instead of seq 0. A 700-step
+  run mid-way through sleeps and resumes correctly through snapshots.
+- **pg pipelining** (`pg >= 8.23`, one option): queries batch per connection —
+  biggest wins under concurrency and on networked Postgres.
+- **Zero-poll `returnValue`**: in-process callers await a deferred promise;
+  the DB is only polled by cross-process callers (adaptive 5→250 ms).
+
+| Metric | v0.1.2 | v0.1.3 |
+|---|---|---|
+| Runs / sec, 500×10 @ conc 100 | — | **497** |
+| Steps / sec, 400-step workflows | 9,070 | 8,956–10,658* |
+| Steps / sec, 600-step workflows | — | 10,055 |
+| `returnValue` DB polls (same process) | every 5–250 ms | **0** |
+| Replay cost for an old run | O(total events) | O(events since snapshot) |
+
+\* range across runs; the long-workflow number varies with how many
+snapshots land before each resume.
+
+---
+
+## v0.1.4 — round-trip & fsync round
+
+**Focus: query-count per run and the commit durability dial.**
+
+- **Merged control round trips**: `claimRun` returns the cancelled flag with
+  the lease; new `finishRun` writes terminal status and releases the lease in
+  one UPDATE. Control queries per run: 6 → 4.
+- **Pipelined step appends**: consecutive `step_completed` events share one
+  flush (buffered in `ctx.inflight`, awaited at suspension/terminal/snapshot
+  boundaries). Verified: 700-step sleep-resume path stays correct.
+- **Opt-in async commit** (`sessionOptions: { synchronous_commit: 'off' }`):
+  documented tradeoff — the last few transactions may be lost on a server
+  crash (never corruption). Off by default; durability remains the default.
+
+| Metric | v0.1.3 | v0.1.4 | Δ |
+|---|---|---|---|
+| Runs / sec (200×5, conc 20) | 437–480 | **502–512** | +8% |
+| Runs / sec (500×10, conc 100) | 497 | **503–512** | +2% |
+| Steps / sec (400-step) | 8,956 | **9,017–9,939** | +5% |
+| Steps / sec (400-step, async commit opt-in) | — | **11,004** | +23% vs durable |
+| Control queries per run | 6 | 4 | −33% |
+
+---
+
+## Reproducing
+
+`test/bench.ts` honours `BENCH_N` (runs), `BENCH_M` (steps per run),
+`BENCH_CONC` (in-flight). `bench-long.mjs` honours `RN` (steps) and runs 50
+sequential-ish workflows through `start()` + terminal-poll.
+
+Every version's table above was produced on the same machine and database,
+so cross-version rows are directly comparable.
+
+## v0.2.0 — compat layer (perf-neutral)
+
+Focus: Vercel Workflow drop-in compat (`lightflow-engine/compat/*`).
+No perf regression vs v0.1.4 — two real bugs found and fixed along the way:
+post-resume chunk loss (chunk keys now include the durable-timer position)
+and chunks vanishing from streams after snapshot compaction (live chunks
+now fold into snapshots).
+
+| Scenario | v0.1.4 | v0.2.0 |
+|---|---|---|
+| 200 runs x 5 steps, conc 20 (runs/s) | 502–512 | 504.5 |
+| 50 runs x 400 steps durable (steps/s) | 9,939 | 9,062–10,600 |
+
+Verdict: perf-neutral within noise. Compat test (7/7) exercises the full
+entry-agents surface end-to-end.

package/README.md

@@ -149,6 +149,27 @@ Kill-and-resume is a first-class path, not an edge case. The engine includes a
 **reaper** that resumes runs wedged in `running` — a failure mode we hit in
 other engines and designed out here.
 
+## Vercel Workflow drop-in compat
+
+lightflow ships a compatibility layer mirroring the exact Vercel Workflow
+API surface (`start(fn, args)`, sync `getRun()`, `run.status` Promise,
+`run.getReadable({ startIndex })` + `getTailIndex()`, `run.cancel()`,
+`run.returnValue`, `getWritable()` as a web `WritableStream`,
+`getWorkflowMetadata()`, `sleep(Date)`, `FatalError`, `withWorkflow`).
+See [COMPAT.md](./COMPAT.md) for the 3-step swap guide and honest
+differences list.
+
+```ts
+import { createPostgresStore } from "lightflow-engine/pg";
+import { Engine } from "lightflow-engine";
+import { initWorkflowApi } from "lightflow-engine/compat/api";
+
+const store = await createPostgresStore(process.env.LIGHTFLOW_PG_URL!);
+const engine = new Engine(store, { pollMs: 50 });
+await engine.startWorker();
+initWorkflowApi(store, engine);
+```
+
 ## Benchmarks
 
 Full before/after numbers for every version live in [BENCHMARKS.md](BENCHMARKS.md).

package/dist/src/compat/api.js

@@ -0,0 +1,157 @@
+/**
+ * Vercel Workflow compat — `workflow/api` module surface.
+ *
+ * Differences from our core Engine API:
+ *  - start(fn, args): takes the workflow FUNCTION (not an id); returns the
+ *    run handle directly (not a promise).
+ *  - getRun(runId): returns the handle synchronously; `status` is a Promise;
+ *    status includes "pending" and "cancelled".
+ *  - getReadable({ startIndex }): chunk-indexed resumable stream with
+ *    getTailIndex().
+ *  - run.cancel(), run.returnValue.
+ */
+import { Engine, registerWorkflow } from "../index.js";
+import { workflowIdFor } from "./workflow.js";
+let sharedEngine = null;
+let sharedStore = null;
+/** Configure the compat layer with a store/engine (call once at boot). */
+export function initWorkflowApi(store, engine) {
+    sharedStore = store;
+    sharedEngine = engine ?? new Engine(store);
+}
+export function getEngine() {
+    if (!sharedEngine) {
+        throw new Error("workflow/api not initialized — call initWorkflowApi(store) at startup");
+    }
+    return sharedEngine;
+}
+/**
+ * Register a workflow function under a stable id and start it. Mirrors
+ * Vercel's start(workflowFn, args).
+ */
+export async function start(fn, args) {
+    const engine = getEngine();
+    const id = workflowIdFor(fn);
+    registerWorkflow(id, fn);
+    const { runId } = await engine.start(id, args);
+    return makeRunHandle(runId);
+}
+export function getRun(runId) {
+    return makeRunHandle(runId);
+}
+function makeRunHandle(runId) {
+    const engine = getEngine();
+    const store = sharedStore;
+    let cachedStatus = null;
+    const statusPromise = (async () => {
+        if (cachedStatus)
+            return cachedStatus;
+        const deadline = Date.now() + 10 * 60_000;
+        let delay = 5;
+        let seenRow = false;
+        while (Date.now() < deadline) {
+            const row = await store.getRun(runId);
+            if (row) {
+                seenRow = true;
+                if (row.status === "completed") {
+                    cachedStatus = "completed";
+                    return cachedStatus;
+                }
+                if (row.status === "failed") {
+                    // cancelled runs are 'failed' with error 'cancelled'
+                    cachedStatus =
+                        row.output?.error === "cancelled"
+                            ? "cancelled" : "failed";
+                    return cachedStatus;
+                }
+            }
+            await new Promise((r) => setTimeout(r, delay));
+            delay = seenRow ? Math.min(delay * 1.6, 250) : 5;
+        }
+        throw new Error(`run status timeout: ${runId}`);
+    })();
+    const handle = {
+        runId,
+        status: statusPromise,
+        returnValue: (async () => (await engine.getRun(runId)).returnValue)(),
+        getReadable(opts) {
+            const startIndex = opts?.startIndex ?? 0;
+            let sent = startIndex;
+            let closed = false;
+            const collectChunks = async () => {
+                // Chunks can live in two places: the latest snapshot memo
+                // (compaction folds pre-snapshot chunks) and as raw events after
+                // it. Merge, dedupe by key, and order by chunk index.
+                const events = await store.getEvents(runId);
+                const byKey = new Map();
+                for (const e of events) {
+                    if (e.type === "snapshot") {
+                        const memo = e.payload.memo ?? {};
+                        for (const [k, v] of Object.entries(memo)) {
+                            if (!k.startsWith("chunk:"))
+                                continue;
+                            const p = v;
+                            byKey.set(p.key, p);
+                        }
+                    }
+                    else if (e.type === "chunk") {
+                        const p = e.payload;
+                        byKey.set(p.key, p);
+                    }
+                }
+                return [...byKey.values()].sort((a, b) => a.index - b.index);
+            };
+            const stream = new ReadableStream({
+                async pull(controller) {
+                    if (closed) {
+                        controller.close();
+                        return;
+                    }
+                    const chunks = await collectChunks();
+                    const hasDone = chunks.some((c) => c.done);
+                    // chunks carry a monotonic `index`; entries after startIndex
+                    for (const c of chunks) {
+                        const p = c;
+                        if (p.done) {
+                            closed = true;
+                            controller.close();
+                            return;
+                        }
+                        if (p.index < startIndex)
+                            continue;
+                        if (p.index >= sent) {
+                            controller.enqueue(p.value);
+                            sent = p.index + 1;
+                        }
+                    }
+                    if (hasDone) {
+                        closed = true;
+                        controller.close();
+                        return;
+                    }
+                    const row = await store.getRun(runId);
+                    if (row && row.status !== "running") {
+                        closed = true;
+                        controller.close();
+                    }
+                },
+            });
+            stream.getTailIndex = async () => {
+                const chunks = await collectChunks();
+                let max = -1;
+                for (const c of chunks) {
+                    if (c.done)
+                        return max;
+                    if (typeof c.index === "number" && c.index > max)
+                        max = c.index;
+                }
+                return max;
+            };
+            return stream;
+        },
+        async cancel() {
+            await (await engine.getRun(runId)).cancel();
+        },
+    };
+    return handle;
+}

package/dist/src/compat/fetch.js

@@ -0,0 +1,16 @@
+/**
+ * Durable fetch: memoized per step position, like any other side effect.
+ * Mirrors Vercel's workflow fetch(): Response-shaped result.
+ */
+import { step } from "../index.js";
+export async function workflowFetch(input, init) {
+    return step(async () => {
+        const res = await fetch(input, init);
+        return {
+            __lfResponse: true,
+            status: res.status,
+            headers: Object.fromEntries(res.headers.entries()),
+            body: await res.text(),
+        };
+    });
+}

package/dist/src/compat/metadata.js

@@ -0,0 +1,9 @@
+/**
+ * Vercel Workflow compat: getWorkflowMetadata() returns { workflowRunId }.
+ */
+import { current } from "../index.js";
+export function getWorkflowMetadata() {
+    if (!current)
+        throw new Error("getWorkflowMetadata() outside a workflow");
+    return { workflowRunId: current.runId };
+}

package/dist/src/compat/next.js

@@ -0,0 +1,19 @@
+/**
+ * Vercel Workflow compat — `workflow/next` surface.
+ *
+ * Vercel's withWorkflow wraps the Next.js config to enable the directive
+ * compiler ("use workflow" / "use step"). lightflow's runtime does not need
+ * a bundler transform: directives are inert strings, workflow functions are
+ * registered explicitly by start(), and "use step" functions can be wrapped
+ * with step() from compat/workflow for durability.
+ *
+ * This drop-in is an identity wrapper so next.config.ts keeps working
+ * unchanged:
+ *   import { withWorkflow } from "workflow/next";
+ * + import { withWorkflow } from "lightflow-engine/compat/next";
+ */
+export function withWorkflow(config) {
+    // Directives are inert at runtime; nothing to compile. Accepts and
+    // returns the config untouched so existing call sites compose the same.
+    return config;
+}

package/dist/src/compat/workflow.js

@@ -0,0 +1,71 @@
+/**
+ * Vercel Workflow compatibility layer — `workflow` module surface.
+ *
+ * Drop-in for entry-agents-style code: same named exports, same shapes.
+ * Directive notes:
+ *  - "use workflow" / "use step" are inert strings at runtime. This layer
+ *    makes directly-called "use step" functions durable via the companion
+ *    webpack loader (workflow/next) or explicit step() wrappers.
+ */
+import { createHash } from "node:crypto";
+import { current } from "../index.js";
+export { FatalError, CancelledError, sleep } from "../index.js";
+export { getWorkflowMetadata } from "../compat/metadata.js";
+export { workflowFetch } from "../compat/fetch.js";
+/**
+ * Vercel's getWritable returns a web-standard WritableStream whose writes
+ * are durable chunk events. Ours maps 1:1: every writer.write(chunk) is a
+ * memoized chunk event keyed by call position; writer.close() emits the
+ * terminal done marker.
+ */
+export function getWritable() {
+    const ctx = current;
+    if (!ctx)
+        throw new Error("getWritable() outside a workflow");
+    const underlying = {
+        async write(chunk) {
+            // Mirror of engine getWritable().write but through ctx.append.
+            // Key includes the durable-timer position so a post-resume write
+            // can never collide with (and be skipped against) a pre-timer chunk.
+            const key = `w:${ctx.sleepCalls}:${ctx.writes}`;
+            const already = ctx.memo.has(`chunk:${key}`);
+            ctx.writes += 1;
+            if (already)
+                return;
+            const index = await ctx.store.nextChunkIndex(ctx.runId);
+            ctx.seq += 1;
+            const payload = { value: chunk, index, key };
+            ctx.append({
+                runId: ctx.runId, seq: ctx.seq, type: "chunk",
+                payload, createdAt: ctx.now(),
+            });
+            // Record in the live memo so snapshot compaction folds it.
+            ctx.memo.set(`chunk:${key}`, { runId: ctx.runId, seq: ctx.seq,
+                type: "chunk", payload, createdAt: ctx.now() });
+        },
+        async close() {
+            const already = [...ctx.memo.values()].some((e) => e.type === "chunk" && e.payload?.done === true);
+            if (already)
+                return;
+            ctx.seq += 1;
+            ctx.append({
+                runId: ctx.runId, seq: ctx.seq, type: "chunk",
+                payload: { value: null, done: true, key: "close", index: ctx.writes },
+                createdAt: ctx.now(),
+            });
+        },
+    };
+    return new WritableStream({
+        async write(chunk) { await underlying.write(chunk); },
+        async close() { await underlying.close(); },
+        async abort() { },
+    });
+}
+/** Auto-registration id for a workflow function (stable per code site). */
+export function workflowIdFor(fn) {
+    const named = fn.name;
+    if (named && named !== "anonymous")
+        return named;
+    return "wf_" + createHash("sha256")
+        .update(String(fn).slice(0, 512)).digest("hex").slice(0, 16);
+}

package/dist/src/index.js

@@ -34,7 +34,7 @@ export function registerWorkflow(id, fn) {
 export function registerStep(id, fn) {
     steps.set(id, fn);
 }
-let current = null;
+export let current = null;
 export function getWorkflowMetadata() {
     if (!current)
         throw new Error("getWorkflowMetadata() outside a workflow");
@@ -104,7 +104,7 @@ export async function step(fn) {
     }
     ctx.seq += 1;
     ctx.freshResults.set(key, value);
-    await ctx.store.appendEvent({
+    ctx.append({
         runId: ctx.runId, seq: ctx.seq, type: "step_completed",
         payload: { key, value }, createdAt: ctx.now(),
     });
@@ -120,6 +120,7 @@ const SNAPSHOT_MIN_EVENTS = 100;
  * costing replay time and can be pruned later without breaking resumes.
  */
 async function maybeSnapshot(ctx) {
+    await Promise.all(ctx.inflight);
     ctx.completedNow += 1;
     const done = ctx.completedNow +
         [...ctx.memo.values()].filter((e) => e.type === "step_completed").length;
@@ -180,13 +181,12 @@ export function getWritable() {
     const ctx = current;
     if (!current)
         throw new Error("getWritable() outside a workflow");
-    /** Deterministic key: (durable-timer position, writes since it). */
-    const keyFor = () => `${ctx.sleepCalls}:${ctx.writes}`;
     return {
         async write(chunk) {
-            // Memoized by call position (like steps): on replay, a write whose
-            // position was already emitted is skipped, and the loop advances.
-            const key = `w:${ctx.writes}`;
+            // Memoized by deterministic call position: (sleep position, writes
+            // since it). sleepCalls survives a resume so a post-timer write can
+            // never collide with (and be skipped against) a pre-timer chunk.
+            const key = `w:${ctx.sleepCalls}:${ctx.writes}`;
             // Use the replay memo — no per-write re-fetch of the event log.
             const already = ctx.memo.has(`chunk:${key}`);
             ctx.writes += 1;
@@ -194,10 +194,14 @@ export function getWritable() {
                 return;
             const index = await ctx.store.nextChunkIndex(ctx.runId);
             ctx.seq += 1;
+            const payload = { value: chunk, index, key };
             await ctx.store.appendEvent({
                 runId: ctx.runId, seq: ctx.seq, type: "chunk",
-                payload: { value: chunk, index, key }, createdAt: ctx.now(),
+                payload, createdAt: ctx.now(),
             });
+            // Record in the live memo so snapshot compaction folds it.
+            ctx.memo.set(`chunk:${key}`, { runId: ctx.runId, seq: ctx.seq,
+                type: "chunk", payload, createdAt: ctx.now() });
         },
         async close() {
             const already = [...ctx.memo.values()].some((e) => e.type === "chunk" && e.payload?.done === true);
@@ -307,8 +311,13 @@ export class Engine {
         // by the winner, and any newer events it would have seen are picked up
         // by the next resume.
         const claimer = this.store;
-        if (claimer.claimRun && !(await claimer.claimRun(runId)))
+        const claim = await claimer.claimRun?.(runId);
+        if (claim && !claim.ok)
+            return;
+        if (claim?.cancelled) {
+            await this.store.setStatus(runId, "failed", { error: "cancelled" });
             return;
+        }
         const log = await this.store.getEvents(runId);
         // Memo index: one pass over the log, O(1) lookups during replay.
         // A leading 'snapshot' event pre-fills completed step/sleep/chunk state.
@@ -340,26 +349,36 @@ export class Engine {
             runId, seq: log.length ? log.reduce((m, e) => Math.max(m, e.seq), 0) + 1 : 1,
             stepCalls: 0, sleepCalls: 0, hookCalls: 0,
             writes: 0,
-            store: this.store, log, memo, completedNow: 0, freshResults: new Map(), cursor: 0, chunks: [], now: () => Date.now(),
+            store: this.store, log, memo, completedNow: 0, freshResults: new Map(),
+            inflight: [], cursor: 0, chunks: [], now: () => Date.now(),
+            append: (e) => {
+                // Pipelined append: capture the promise; callers only await at
+                // suspension/end, so several step completions share one flush.
+                const p = ctx.store.appendEvent(e).then(() => { ctx.inflight = ctx.inflight.filter(x => x !== p); });
+                ctx.inflight.push(p);
+                return p;
+            },
         };
         const prev = current;
         current = ctx;
         try {
-            if (await this.store.isCancelled?.(runId)) {
-                await this.store.setStatus(runId, "failed", { error: "cancelled" });
-                return;
-            }
             const output = await fn(...args);
-            await this.store.setStatus(runId, "completed", output);
+            await Promise.all(ctx.inflight);
+            await (this.store.finishRun?.(runId, "completed", output)
+                ?? this.store.setStatus(runId, "completed", output));
             this.local.get(runId)?.resolve(output);
         }
         catch (err) {
-            if (err instanceof SuspendSignal)
+            if (err instanceof SuspendSignal) {
+                await Promise.all(ctx.inflight);
                 return; // waiting on a timer
+            }
             const fail = async (error) => {
-                await this.store.setStatus(runId, "failed", {
+                await (this.store.finishRun?.(runId, "failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                }) ?? this.store.setStatus(runId, "failed", {
                     error: error instanceof Error ? error.message : String(error),
-                });
+                }));
                 this.local.get(runId)?.reject(err instanceof Error ? err : new Error(String(err)));
             };
             if (err instanceof CancelledError)

package/dist/src/pg-store.js

@@ -5,10 +5,19 @@
  * columns, so no timezone ambiguity (the bug that cost hours in world-postgres).
  */
 import pg from "pg";
-export async function createPostgresStore(url) {
+export async function createPostgresStore(url, opts = {}) {
     // Pipelining (pg >= 8.23): batch queries on one connection instead of one
     // round trip per query — 1.5-2.4x on multi-query workloads.
     const pool = new pg.Pool({ connectionString: url, max: 20, pipeline: true });
+    if (opts.sessionOptions) {
+        const sets = Object.entries(opts.sessionOptions)
+            .map(([k, v]) => `SET ${k} = ${v === "off" || v === "on" ? v : `'${v}'`}`)
+            .join("; ");
+        // Apply per connection as it opens (pg fires 'connect' per client).
+        pool.on("connect", (client) => {
+            void client.query(sets).catch(() => { });
+        });
+    }
     await pool.query(`
     CREATE TABLE IF NOT EXISTS lightflow_runs (
       run_id     TEXT PRIMARY KEY,
@@ -208,14 +217,21 @@ export async function createPostgresStore(url) {
         async claimDue() { return false; },
         async claimRun(runId, leaseMs = 30_000) {
             const now = Date.now();
+            // One round trip: claim the lease AND read the cancelled flag.
             const r = await pool.query(`UPDATE lightflow_runs SET claimed_until=$2, updated_at=$3
          WHERE run_id=$1 AND claimed_until < $3
-         RETURNING run_id`, [runId, now + leaseMs, now]);
-            return (r.rowCount ?? 0) > 0;
+         RETURNING cancelled`, [runId, now + leaseMs, now]);
+            return { ok: (r.rowCount ?? 0) > 0, cancelled: r.rows[0]?.cancelled === true };
         },
         async releaseRun(runId) {
             await pool.query(`UPDATE lightflow_runs SET claimed_until=0 WHERE run_id=$1 AND claimed_until > 0`, [runId]);
         },
+        /** Terminal status + lease release in one round trip. */
+        async finishRun(runId, status, output) {
+            await pool.query(`UPDATE lightflow_runs
+         SET status=$2, output=$3, claimed_until=0, updated_at=$4
+         WHERE run_id=$1`, [runId, status, output === undefined ? null : JSON.stringify(output), Date.now()]);
+        },
         /** LISTEN/NOTIFY wakeup support: re-poll immediately on notify. */
         async notifyWake() {
             await pool.query(`NOTIFY lightflow_wake`);

package/dist/test/compat.js

@@ -0,0 +1,86 @@
+/**
+ * Drop-in verification: the exact Vercel Workflow surface entry-agents uses,
+ * exercised against lightflow's compat layer:
+ *   start(fn, args) / getRun(id) / run.status (Promise) / run.runId /
+ *   run.returnValue / run.cancel() / run.getReadable({startIndex}) /
+ *   getTailIndex() / getWritable() as WritableStream / getWorkflowMetadata()
+ *   -> { workflowRunId } / sleep(Date) / FatalError.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import pg from "pg";
+import { Engine, step, sleep, FatalError } from "../src/index.js";
+import { createPostgresStore } from "../src/pg-store.js";
+import { initWorkflowApi, start } from "../src/compat/api.js";
+import { getWritable, getWorkflowMetadata } from "../src/compat/workflow.js";
+const PG_URL = process.env.LIGHTFLOW_PG_URL;
+if (!PG_URL)
+    throw new Error("LIGHTFLOW_PG_URL is required");
+test("compat: vercel-style agent chat workflow end-to-end", async () => {
+    const store = await createPostgresStore(PG_URL);
+    const engine = new Engine(store, { pollMs: 25 });
+    initWorkflowApi(store, engine);
+    const workerPromise = engine.startWorker();
+    setTimeout(() => engine.stopWorker(), 60_000);
+    const pool = new pg.Pool({ connectionString: PG_URL });
+    // A workflow shaped like entry-agents' runAgentWorkflow:
+    // - "use step"-style direct calls via step()
+    // - getWritable() as a real WritableStream, written via getWriter()
+    // - getWorkflowMetadata() -> { workflowRunId }
+    // - sleep(new Date(...)) for durable timers
+    // - FatalError for non-retryable failures
+    const runAgentWorkflow = async (opts) => {
+        "use workflow";
+        const { workflowRunId } = getWorkflowMetadata();
+        const writable = getWritable();
+        const writer = writable.getWriter();
+        await step(async () => {
+            await writer.write(`start:${opts.chatId}`);
+        });
+        const answer = await step(async () => `reply-to:${opts.messages.join(",")}`);
+        // mid-run durable timer like sandbox-lifecycle
+        await sleep(new Date(Date.now() + 50));
+        await step(async () => { await writer.write(`chunk:${answer}`); });
+        await step(async () => { await writer.write("done-marker"); });
+        await writer.close();
+        if (opts.messages.includes("boom"))
+            throw new FatalError("nope");
+        return { workflowRunId, answer };
+    };
+    // Vercel-style start(fn, args) — function, not id
+    const run = await start(runAgentWorkflow, [
+        { messages: ["hello", "world"], chatId: "c1" },
+    ]);
+    assert.ok(run.runId.startsWith("lrun_"));
+    // status is a Promise, resolvable to a terminal state
+    const status = await run.status;
+    assert.equal(status, "completed");
+    const ret = (await run.returnValue);
+    assert.equal(ret.answer, "reply-to:hello,world");
+    assert.equal(ret.workflowRunId, run.runId);
+    // getReadable() with startIndex + getTailIndex
+    const readable = run.getReadable({ startIndex: 0 });
+    const tail = await readable.getTailIndex();
+    const parts = [];
+    const reader = readable.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        parts.push(value);
+    }
+    assert.deepEqual(parts, ["start:c1", "chunk:reply-to:hello,world", "done-marker"]);
+    assert.ok(tail >= 1);
+    // resume from startIndex: skipping the first chunk
+    const resumed = run.getReadable({ startIndex: 1 });
+    const rreader = resumed.getReader();
+    const r1 = await rreader.read();
+    assert.equal(r1.value, "chunk:reply-to:hello,world");
+    // cancel semantics: getRun + status + cancel()
+    const dup = await start(runAgentWorkflow, [{ messages: ["x"], chatId: "c2" }]);
+    await dup.cancel();
+    assert.equal(await dup.status, "cancelled");
+    await pool.end();
+    engine.stopWorker();
+    await workerPromise;
+});

package/dist/test/dbg.mjs

@@ -0,0 +1,28 @@
+
+import { Engine, step, sleep, registerWorkflow } from "/home/agentuser/lightflow/dist/src/index.js";
+import { createPostgresStore } from "/home/agentuser/lightflow/dist/src/pg-store.js";
+import { getWritable } from "/home/agentuser/lightflow/dist/src/compat/workflow.js";
+import { initWorkflowApi, start } from "/home/agentuser/lightflow/dist/src/compat/api.js";
+import pg from "pg";
+const url = process.env.LIGHTFLOW_PG_URL;
+const store = await createPostgresStore(url);
+const engine = new Engine(store, { pollMs: 25 });
+initWorkflowApi(store, engine);
+const wp = engine.startWorker();
+setTimeout(() => engine.stopWorker(), 30000);
+const wf = async () => {
+  const wr = getWritable();
+  const writer = wr.getWriter();
+  await step(async () => { await writer.write("A"); });
+  await sleep(new Date(Date.now() + 50));
+  await step(async () => { await writer.write("B"); });
+  await step(async () => { await writer.write("C"); });
+  await writer.close();
+  return "ok";
+};
+const run = await start(wf, []);
+console.log("status:", await run.status);
+const pool = new pg.Pool({ connectionString: url });
+const rows = await pool.query("SELECT seq, payload->>'key' k, payload->>'value' v FROM lightflow_events WHERE type='chunk' ORDER BY seq");
+console.log(rows.rows.map(r=>`${r.k}=${r.v}`).join(" | "));
+await pool.end(); process.exit(0);

package/dist/test/dbg2.mjs

@@ -0,0 +1,34 @@
+
+import { Engine, step, sleep, registerWorkflow } from "/home/agentuser/lightflow/dist/src/index.js";
+import { createPostgresStore } from "/home/agentuser/lightflow/dist/src/pg-store.js";
+import { getWritable } from "/home/agentuser/lightflow/dist/src/compat/workflow.js";
+import { initWorkflowApi, start } from "/home/agentuser/lightflow/dist/src/compat/api.js";
+const store = await createPostgresStore(process.env.LIGHTFLOW_PG_URL);
+const engine = new Engine(store, { pollMs: 25 });
+initWorkflowApi(store, engine);
+const wp = engine.startWorker();
+setTimeout(() => engine.stopWorker(), 60000);
+const wf = async () => {
+  const writer = getWritable().getWriter();
+  for (let i = 0; i < 205; i++) {
+    await step(async () => { await writer.write("c" + i); });
+    if (i === 100) await sleep(new Date(Date.now() + 40));
+  }
+  await writer.close();
+  return "done";
+};
+const run = await start(wf, []);
+console.log("status:", await run.status);
+const readable = run.getReadable({ startIndex: 0 });
+const reader = readable.getReader();
+const parts = [];
+for (;;) { const { done, value } = await reader.read(); if (done) break; parts.push(value); }
+const missing = []; for (let i=0;i<205;i++) if (!parts.includes("c"+i)) missing.push(i); console.log("chunks:", parts.length, "nmissing:", missing.length, "m0:", missing[0], "mLast:", missing[missing.length-1]);
+console.log("tailIndex:", await readable.getTailIndex());
+// resume from index 200
+const r2 = run.getReadable({ startIndex: 200 });
+const rd2 = r2.getReader();
+const p2 = [];
+for (;;) { const { done, value } = await rd2.read(); if (done) break; p2.push(value); }
+console.log("resumed-from-200:", p2.length, p2[0], p2.at(-1));
+process.exit(0);

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "lightflow-engine",
-  "version": "0.1.3",
-  "description": "A tiny durable workflow engine for Node.js and Postgres: steps that run at most once, timers that survive crashes, streams that replay exactly once.",
+  "version": "0.2.0",
+  "description": "A tiny durable workflow engine for Node.js and Postgres \u2014 with a Vercel Workflow drop-in compat layer.",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
-    "./pg": "./dist/pg-store.js"
+    "./pg": "./dist/pg-store.js",
+    "./compat/workflow": "./dist/compat/workflow.js",
+    "./compat/api": "./dist/compat/api.js",
+    "./compat/next": "./dist/compat/next.js"
   },
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "BENCHMARKS.md"
   ],
   "keywords": [
     "workflow",