lightflow-engine 0.2.9 → 0.2.12

package/BENCHMARKS.md

@@ -156,6 +156,10 @@ 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 |
 
 ### What changed per version (all perf-neutral by design)
 
@@ -178,6 +182,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
 

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/metadata.js

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

package/dist/compat/workflow.js

@@ -9,7 +9,7 @@
  */
 import { createHash } from "node:crypto";
 import { step, registerStep, } from "../index.js";
-import { current } from "../index.js";
+import { getCurrent } from "../index.js";
 export { FatalError, CancelledError, sleep } from "../index.js";
 export { getWorkflowMetadata } from "../compat/metadata.js";
 // Vercel exports the step-aware fetch under both names; entry-agents
@@ -23,7 +23,7 @@ export { workflowFetch } from "../compat/fetch.js";
  * terminal done marker.
  */
 export function getWritable() {
-    const ctx = current;
+    const ctx = getCurrent();
     if (!ctx)
         throw new Error("getWritable() outside a workflow");
     const underlying = {
@@ -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;
@@ -102,7 +102,7 @@ type Ctx = {
     chunks: string[];
     now: () => number;
 };
-export declare let current: Ctx | null;
+export declare function getCurrent(): Ctx | null;
 export declare function getWorkflowMetadata(): {
     runId: string;
 };

package/dist/index.js

@@ -39,28 +39,29 @@ export function registerWorkflow(id, fn) {
 export function registerStep(id, fn) {
     steps.set(id, fn);
 }
-export let current = globalThis.__lightflowCurrent ?? null;
-if (!globalThis.__lightflowCurrent) {
-    globalThis.__lightflowCurrent = null;
+// Cross-bundle execution context: Next.js may execute the engine and workflow
+// code from different module instances of this file. `current` must be visible
+// across all of them, so it lives on globalThis and is read via getCurrent().
+export function getCurrent() {
+    return globalThis.__lightflowCurrent ?? null;
 }
-// Keep the live binding in sync: `current` assignments below must write both.
 function setCurrent(v) {
-    current = v;
     globalThis.__lightflowCurrent = v;
 }
-// Rewrite plain assignments on `current` below to setCurrent(...)
 export function getWorkflowMetadata() {
-    if (!current)
+    const ctx = getCurrent();
+    if (!ctx)
         throw new Error("getWorkflowMetadata() outside a workflow");
-    return { runId: current.runId };
+    return { runId: ctx.runId };
 }
 /* ------------------------------------------------------------------ */
 /* The step id: derived from call order, so replay is deterministic    */
 /* ------------------------------------------------------------------ */
 function nextStepKey() {
-    if (!current)
+    const ctx = getCurrent();
+    if (!ctx)
         throw new Error("steps can only be called inside a workflow");
-    return `step:${current.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 (!current)
+    const ctx = getCurrent();
+    if (!ctx)
         return fn(); // plain call outside a workflow
-    const ctx = current;
     const key = nextStepKey();
     ctx.stepCalls += 1;
     // Replay: memoized result for this call position? (O(1) map lookup)
@@ -163,11 +164,11 @@ async function maybeSnapshot(ctx) {
 }
 /** Durable sleep. Accepts milliseconds or an absolute Date. */
 export async function sleep(until) {
-    if (!current) {
+    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 = current;
     const wakeAt = until instanceof Date ? until.getTime() : ctx.now() + until;
     const key = `sleep:${ctx.sleepCalls}`;
     ctx.sleepCalls += 1;
@@ -192,8 +193,8 @@ export class SuspendSignal {
 }
 /** Ordered output stream for a run. Chunks are persisted and replayable. */
 export function getWritable() {
-    const ctx = current;
-    if (!current)
+    const ctx = getCurrent();
+    if (!ctx)
         throw new Error("getWritable() outside a workflow");
     return {
         async write(chunk) {
@@ -273,8 +274,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 +333,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);
@@ -377,7 +377,7 @@ export class Engine {
                 return p;
             },
         };
-        const prev = current;
+        const prev = getCurrent();
         setCurrent(ctx);
         try {
             const output = await fn(...args);
@@ -401,6 +401,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 +538,23 @@ export class CancelledError extends Error {
 export function defineHook() {
     return {
         async create() {
-            if (!current)
+            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:${current.hookCalls}`;
-            current.hookCalls += 1;
-            await current.store.createHook?.(current.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 (!current)
+    const ctx = getCurrent();
+    if (!ctx)
         throw new Error("hooks only inside a workflow");
-    const existing = await current.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]);

package/package.json

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