lightflow-engine 0.2.10 → 0.2.13

package/BENCHMARKS.md

@@ -156,6 +156,11 @@ same Postgres (16, local) and the same harness (200 runs x 5 steps @ conc 20;
 | 0.2.4 | 456.1 | 2,280 | 8,280 |
 | 0.2.5 | 459.1 | 2,295 | 9,068 |
 | 0.2.6 | 494.9–525.1 | 2,474–2,626 | 8,379–9,737 |
+| 0.2.7 | 416.0 | 2,080 | 9,180 |
+| 0.2.8 | 455.2 | 2,276 | 8,695 |
+| 0.2.9 | 474.1 | 2,371 | 9,008 |
+| 0.2.10 | 455.3 | 2,277 | 9,368 |
+| 0.2.12 | 457.0 | 2,285 | 9,943 |
 
 ### What changed per version (all perf-neutral by design)
 
@@ -178,6 +183,14 @@ same Postgres (16, local) and the same harness (200 runs x 5 steps @ conc 20;
   resolved the package root, but the types were broken).
 - **0.2.6** — `export { workflowFetch as fetch }` (entry imports both
   names), `WorkflowFn` accepts typed args, `run.exists: true`.
+- **0.2.7** — lazy `returnValue` on run handles: no unhandled rejection
+  when a status-only handle outlives a failed run. Added
+  `test/compat-runtime.ts` (makeStep args+retries, FatalError, ghost runs).
+- **0.2.8–0.2.10** — cross-bundle runtime state for Next.js: engine/store,
+  workflow/step registries, and the execution context moved to globalThis
+  because instrumentation and route handlers load as separate module
+  instances. Found by a live end-to-end Entry chat run; zero measurable
+  cost (globalThis lookup vs module global).
 
 ### Spread notes
 
@@ -197,3 +210,13 @@ ln -s <path-to>/lightflow/node_modules <dir>/node_modules
 PKG=<dir> LIGHTFLOW_PG_URL=postgres://... BENCH_N=200 RN=5 npx tsx bench-pkg.mts
 PKG=<dir> LIGHTFLOW_PG_URL=postgres://... BENCH_N=50 RN=400 npx tsx bench-pkg.mts
 ```
+
+### 0.2.12 — bug-fix release (cancel/reaper/chunk)
+
+- **cancel is terminal**: `cancel()` now writes `status='cancelled'` + flag atomically; `finishRun` refuses to overwrite a cancelled run (was: racing replay resurrected the run as completed/failed). `RunStatus` gains `"cancelled"`.
+- **Lease-aware stale reaper**: `staleRuns` only reaps runs whose lease expired — a run inside a long step is no longer double-executed.
+- **Stream close marker**: `close()` uses a monotonic chunk index (was `ctx.writes`, which could collide and silently drop the done marker → hanging stream).
+- **O(1) nextChunkIndex**: `lightflow_runs.chunk_count` counter replaces a full chunk scan per write — long-run steps/s 9,368 → ~9,900.
+- Tidy: single `getCurrent()` per call site (was double call + `!`).
+
+Short: 200×5 conc 20 → **457 runs/s / 2,285 steps/s** (within noise of 0.2.9/0.2.10). Long: 50×400 → **9,943 steps/s** (best recorded).

package/dist/compat/api.js

@@ -40,6 +40,8 @@ function makeRunHandle(runId) {
             return "pending";
         if (row.status === "completed")
             return "completed";
+        if (row.status === "cancelled")
+            return "cancelled";
         if (row.status === "failed") {
             return row.output?.error === "cancelled"
                 ? "cancelled"

package/dist/compat/workflow.js

@@ -51,10 +51,14 @@ export function getWritable() {
             const already = [...ctx.memo.values()].some((e) => e.type === "chunk" && e.payload?.done === true);
             if (already)
                 return;
+            // Monotonic chunk index — using ctx.writes here could collide with a
+            // real chunk's index and the unique-index no-op would silently drop
+            // the done marker (stream never terminates).
+            const index = await ctx.store.nextChunkIndex(ctx.runId);
             ctx.seq += 1;
             ctx.append({
                 runId: ctx.runId, seq: ctx.seq, type: "chunk",
-                payload: { value: null, done: true, key: "close", index: ctx.writes },
+                payload: { value: null, done: true, key: "close", index },
                 createdAt: ctx.now(),
             });
         },

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export declare class FatalError extends Error {
     readonly fatal = true;
     constructor(message: string);
 }
-export type RunStatus = "running" | "completed" | "failed";
+export type RunStatus = "running" | "completed" | "failed" | "cancelled";
 export type StepEvent = {
     runId: string;
     seq: number;
@@ -49,6 +49,7 @@ export interface Store {
     isCancelled?(runId: string): Promise<boolean>;
     /** Next monotonic chunk index (max+1), atomic per run. */
     nextChunkIndex?(runId: string): Promise<number>;
+    pruneEvents?(runId: string, beforeSeq: number): Promise<void>;
     /** Run lease: claim (atomically) / release before executing a replay. */
     claimRun?(runId: string, leaseMs?: number): Promise<{
         ok: boolean;

package/dist/index.js

@@ -48,19 +48,20 @@ export function getCurrent() {
 function setCurrent(v) {
     globalThis.__lightflowCurrent = v;
 }
-// Rewrite plain assignments on `current` below to setCurrent(...)
 export function getWorkflowMetadata() {
-    if (!getCurrent())
+    const ctx = getCurrent();
+    if (!ctx)
         throw new Error("getWorkflowMetadata() outside a workflow");
-    return { runId: getCurrent().runId };
+    return { runId: ctx.runId };
 }
 /* ------------------------------------------------------------------ */
 /* The step id: derived from call order, so replay is deterministic    */
 /* ------------------------------------------------------------------ */
 function nextStepKey() {
-    if (!getCurrent())
+    const ctx = getCurrent();
+    if (!ctx)
         throw new Error("steps can only be called inside a workflow");
-    return `step:${getCurrent().stepCalls}`;
+    return `step:${ctx.stepCalls}`;
 }
 /* ------------------------------------------------------------------ */
 /* Public API inside a workflow                                        */
@@ -70,9 +71,9 @@ function nextStepKey() {
  * the function body is NOT re-executed.
  */
 export async function step(fn) {
-    if (!getCurrent())
-        return fn(); // plain call outside a workflow
     const ctx = getCurrent();
+    if (!ctx)
+        return fn(); // plain call outside a workflow
     const key = nextStepKey();
     ctx.stepCalls += 1;
     // Replay: memoized result for this call position? (O(1) map lookup)
@@ -160,14 +161,18 @@ async function maybeSnapshot(ctx) {
         runId: ctx.runId, seq: ctx.seq, type: "snapshot",
         payload: { memo }, createdAt: ctx.now(),
     });
+    // Folded events below the snapshot are dead weight — drop them so the log
+    // stays O(recent activity), not O(total steps). Chunks are kept (stream
+    // replay reads them); run_completed (seq 0) is protected by beforeSeq > 0.
+    await ctx.store.pruneEvents?.(ctx.runId, ctx.seq - 1);
 }
 /** Durable sleep. Accepts milliseconds or an absolute Date. */
 export async function sleep(until) {
-    if (!getCurrent()) {
+    const ctx = getCurrent();
+    if (!ctx) {
         const ms = until instanceof Date ? until.getTime() - Date.now() : until;
         return new Promise((r) => setTimeout(r, Math.max(0, ms)));
     }
-    const ctx = getCurrent();
     const wakeAt = until instanceof Date ? until.getTime() : ctx.now() + until;
     const key = `sleep:${ctx.sleepCalls}`;
     ctx.sleepCalls += 1;
@@ -193,7 +198,7 @@ export class SuspendSignal {
 /** Ordered output stream for a run. Chunks are persisted and replayable. */
 export function getWritable() {
     const ctx = getCurrent();
-    if (!getCurrent())
+    if (!ctx)
         throw new Error("getWritable() outside a workflow");
     return {
         async write(chunk) {
@@ -273,8 +278,7 @@ export class Engine {
             getReadable: () => this.readable(runId),
             /** Entry calls this to kill a duplicate stream (route.ts:172). */
             cancel: async () => {
-                await this.store.cancel?.(runId);
-                await this.store.setStatus(runId, "failed", { error: "cancelled" });
+                await this.store.cancel?.(runId); // terminal: cancelled=true + status='cancelled'
             },
         };
     }
@@ -333,7 +337,7 @@ export class Engine {
         if (claim && !claim.ok)
             return;
         if (claim?.cancelled) {
-            await this.store.setStatus(runId, "failed", { error: "cancelled" });
+            await this.store.setStatus(runId, "cancelled", { error: "cancelled" });
             return;
         }
         const log = await this.store.getEvents(runId);
@@ -401,6 +405,11 @@ export class Engine {
             };
             if (err instanceof CancelledError)
                 return fail("cancelled");
+            if (await this.store.isCancelled?.(runId)) {
+                // A concurrent cancel() already wrote the terminal status — don't
+                // resurrect it as 'failed'.
+                return;
+            }
             if (err instanceof FatalError)
                 return fail(err.message);
             return fail(err instanceof Error ? err.message : String(err));
@@ -533,21 +542,23 @@ export class CancelledError extends Error {
 export function defineHook() {
     return {
         async create() {
-            if (!getCurrent())
+            const ctx = getCurrent();
+            if (!ctx)
                 throw new Error("hooks only inside a workflow");
             const token = `hook_${randomUUID().replace(/-/g, "").slice(0, 20)}`;
-            const key = `hook:${getCurrent().hookCalls}`;
-            getCurrent().hookCalls += 1;
-            await getCurrent().store.createHook?.(getCurrent().runId, token, key);
+            const key = `hook:${ctx.hookCalls}`;
+            ctx.hookCalls += 1;
+            await ctx.store.createHook?.(ctx.runId, token, key);
             return { token };
         },
     };
 }
 /** Await a previously created hook until an external caller resolves it. */
 export async function hookResult(token) {
-    if (!getCurrent())
+    const ctx = getCurrent();
+    if (!ctx)
         throw new Error("hooks only inside a workflow");
-    const existing = await getCurrent().store.getHook?.(token);
+    const existing = await ctx.store.getHook?.(token);
     if (existing && existing.payload?.resolved) {
         return existing.payload.value;
     }

package/dist/pg-store.js

@@ -63,6 +63,10 @@ export async function createPostgresStore(url, opts = {}) {
       resolved  BOOLEAN NOT NULL DEFAULT false,
       created_at BIGINT NOT NULL
     );
+  `);
+    // Stream chunk counter: O(1) nextChunkIndex without scanning all chunks.
+    await pool.query(`
+    ALTER TABLE lightflow_runs ADD COLUMN IF NOT EXISTS chunk_count INTEGER NOT NULL DEFAULT 0;
   `);
     // Durable timers: expression index matching the dueTimers query exactly
     // (bigint cast on the payload value, partial on pending timers).
@@ -228,9 +232,11 @@ export async function createPostgresStore(url, opts = {}) {
         },
         /** Terminal status + lease release in one round trip. */
         async finishRun(runId, status, output) {
+            // A cancelled run is terminal: the cancel path already wrote the final
+            // status, and a still-running replay must not resurrect it.
             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()]);
+         WHERE run_id=$1 AND cancelled=false`, [runId, status, output === undefined ? null : JSON.stringify(output), Date.now()]);
         },
         /** LISTEN/NOTIFY wakeup support: re-poll immediately on notify. */
         async notifyWake() {
@@ -252,17 +258,25 @@ export async function createPostgresStore(url, opts = {}) {
             };
         },
         async nextChunkIndex(runId) {
-            const r = await pool.query(`SELECT COALESCE(max((payload->>'index')::int),-1)+1 AS n
-         FROM lightflow_events WHERE run_id=$1 AND type='chunk'`, [runId]);
+            // Atomic fetch-and-increment on the run row: O(1), race-free across
+            // replays (the chunk-key unique index still guards duplicates).
+            const r = await pool.query(`UPDATE lightflow_runs SET chunk_count=chunk_count+1, updated_at=$2
+         WHERE run_id=$1 RETURNING chunk_count-1 AS n`, [runId, Date.now()]);
             return Number(r.rows[0].n);
         },
         async staleRuns(cutoff) {
+            // Only runs whose lease has EXPIRED are orphaned. A run inside a long
+            // (>staleMs) step still holds a live lease and must not be double-run.
             const r = await pool.query(`SELECT run_id FROM lightflow_runs
-         WHERE status='running' AND updated_at < $1`, [cutoff]);
+         WHERE status='running' AND updated_at < $1 AND claimed_until < $2`, [cutoff, Date.now()]);
             return r.rows.map((x) => x.run_id);
         },
         async cancel(runId) {
-            await pool.query(`UPDATE lightflow_runs SET cancelled=true, updated_at=$2 WHERE run_id=$1`, [runId, Date.now()]);
+            // Terminal in one statement: flag + final status together, so a racing
+            // replay can never observe cancel-flag-without-terminal-status.
+            await pool.query(`UPDATE lightflow_runs
+         SET cancelled=true, status='cancelled', output='{"error":"cancelled"}', claimed_until=0, updated_at=$2
+         WHERE run_id=$1`, [runId, Date.now()]);
         },
         async isCancelled(runId) {
             const r = await pool.query(`SELECT cancelled FROM lightflow_runs WHERE run_id=$1`, [runId]);
@@ -286,6 +300,15 @@ export async function createPostgresStore(url, opts = {}) {
                 payload: { ...(r.rows[0].payload ?? {}), resolved: Boolean(r.rows[0].resolved) },
             };
         },
+        async pruneEvents(runId, beforeSeq) {
+            // Remove events fully folded into the latest snapshot. Chunk events are
+            // KEPT: getReadable/getTailIndex stream chunks from the event log, and
+            // the snapshot memo is not a chunk source. run_completed (seq 0) is
+            // protected by beforeSeq > 0.
+            await pool.query(`DELETE FROM lightflow_events
+         WHERE run_id=$1 AND seq < $2
+           AND type IN ('step_completed','step_failed','sleep_created','sleep_completed')`, [runId, beforeSeq]);
+        },
         async setStatus(runId, status, output) {
             await pool.query(`UPDATE lightflow_runs SET status=$2, output=$3, updated_at=$4 WHERE run_id=$1`, [runId, status, output === undefined ? null : JSON.stringify(output), Date.now()]);
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightflow-engine",
-  "version": "0.2.10",
+  "version": "0.2.13",
   "description": "A tiny durable workflow engine for Node.js and Postgres — with a Vercel Workflow drop-in compat layer.",
   "license": "MIT",
   "type": "module",