lightflow-engine 0.2.4 → 0.2.6

package/dist/{src/compat → compat}/api.d.ts

@@ -14,6 +14,8 @@ import { Engine, type Store } from "../index.js";
 export type VercelRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
 export type VercelRun = {
     runId: string;
+    /** Vercel's run handle exposes exists; ours always resolves from the DB. */
+    readonly exists: true;
     /** Live getter: each access returns a FRESH promise snapshotting the
      *  current status ("pending"/"running" until terminal). Vercel's is a
      *  getter too (chat.test.ts mocks `get status()`), and entry-agents'

package/dist/{src/compat → compat}/api.js

@@ -67,6 +67,7 @@ function makeRunHandle(runId) {
     const cache = {};
     const handle = {
         runId,
+        exists: true,
         get status() {
             // Live snapshot: resolve immediately with the current state; the
             // startStopMonitor poll loop relies on this re-reading each tick.

package/dist/{src/compat → compat}/workflow.d.ts

@@ -9,6 +9,7 @@
  */
 export { FatalError, CancelledError, sleep } from "../index.js";
 export { getWorkflowMetadata } from "../compat/metadata.js";
+export { workflowFetch as fetch } from "../compat/fetch.js";
 export { workflowFetch } from "../compat/fetch.js";
 /**
  * Vercel's getWritable returns a web-standard WritableStream whose writes

package/dist/{src/compat → compat}/workflow.js

@@ -12,6 +12,9 @@ import { step, registerStep, } from "../index.js";
 import { current } 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
+// imports `fetch as workflowFetch` in some files and plain `fetch` in others.
+export { workflowFetch as fetch } from "../compat/fetch.js";
 export { workflowFetch } from "../compat/fetch.js";
 /**
  * Vercel's getWritable returns a web-standard WritableStream whose writes

package/dist/{src/index.d.ts → index.d.ts}

@@ -74,7 +74,7 @@ export interface Store {
     } | null>;
     setStatus(runId: string, status: RunStatus, output?: unknown): Promise<void>;
 }
-type WorkflowFn = (...args: unknown[]) => Promise<unknown>;
+type WorkflowFn = (...args: any[]) => Promise<unknown>;
 export declare function registerWorkflow(id: string, fn: WorkflowFn): void;
 export declare function registerStep(id: string, fn: (...a: unknown[]) => Promise<unknown>): void;
 type Ctx = {

package/package.json

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

package/dist/test/bench-long.mjs

@@ -1,24 +0,0 @@
-
-import { Engine, step, registerWorkflow } from "/home/agentuser/lightflow/dist/src/index.js";
-import { createPostgresStore } from "/home/agentuser/lightflow/dist/src/pg-store.js";
-const url = process.env.LIGHTFLOW_PG_URL;
-const store = await createPostgresStore(url);
-const N = Number(process.env.RN ?? 100); // steps per workflow
-registerWorkflow("long", async () => {
-  for (let i = 0; i < N; i++) await step(async () => i);
-  return N;
-});
-const engine = new Engine(store, { pollMs: 50 });
-// throughput pass
-const t0 = performance.now();
-const RUNS = 50;
-await Promise.all(Array.from({length: 10}, async () => {
-  for (let i = 0; i < RUNS/10; i++) {
-    const { runId } = await engine.start("long", []);
-    const run = await engine.getRun(runId);
-    await run.returnValue;
-  }
-}));
-const dt = (performance.now()-t0)/1000;
-console.log(JSON.stringify({ stepsPerWorkflow: N, runs: RUNS, seconds: +dt.toFixed(2), runsPerSec: +(RUNS/dt).toFixed(1), stepsPerSec: +(RUNS*N/dt).toFixed(1) }));
-process.exit(0);

package/dist/test/bench.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/bench.js

@@ -1,51 +0,0 @@
-/**
- * Throughput benchmark for lightflow.
- * Runs N workflows, each with M steps, in-flight concurrency C.
- * Reports runs/sec, steps/sec, and SQL statements per run (from pg_stat_statements if available).
- */
-import { Engine, step, registerWorkflow } from "../src/index.js";
-import { createPostgresStore } from "../src/pg-store.js";
-const PG_URL = process.env.LIGHTFLOW_PG_URL;
-const N = Number(process.env.BENCH_N ?? 200);
-const M = Number(process.env.BENCH_M ?? 5);
-const CONC = Number(process.env.BENCH_CONC ?? 20);
-async function main() {
-    const store = await createPostgresStore(PG_URL);
-    let calls = 0;
-    registerWorkflow("bench", async () => {
-        "use workflow";
-        for (let i = 0; i < M; i++) {
-            await step(async () => {
-                "use step";
-                return i * 2 + (calls++, 0);
-            });
-        }
-        return M;
-    });
-    const engine = new Engine(store, { pollMs: 100 });
-    // reset counters
-    await store.appendEvent === undefined; // noop
-    const t0 = performance.now();
-    const handles = [];
-    let done = 0;
-    const queue = Array.from({ length: N }, (_, i) => i);
-    async function worker() {
-        while (queue.length) {
-            const i = queue.shift();
-            const { runId } = await engine.start("bench", []);
-            const run = await engine.getRun(runId);
-            await run.returnValue;
-            done++;
-        }
-    }
-    await Promise.all(Array.from({ length: CONC }, worker));
-    const dt = (performance.now() - t0) / 1000;
-    console.log(JSON.stringify({
-        runs: N, stepsPerRun: M, concurrency: CONC,
-        seconds: +dt.toFixed(2),
-        runsPerSec: +(N / dt).toFixed(1),
-        stepsPerSec: +((N * M) / dt).toFixed(1),
-    }, null, 2));
-    process.exit(0);
-}
-main().catch((e) => { console.error(e); process.exit(1); });

package/dist/test/compact-check.mjs

@@ -1,27 +0,0 @@
-
-import { Engine, step, registerWorkflow } from "/home/agentuser/lightflow/dist/src/index.js";
-import { createPostgresStore } from "/home/agentuser/lightflow/dist/src/pg-store.js";
-import pg from "pg";
-const url = process.env.LIGHTFLOW_PG_URL;
-const store = await createPostgresStore(url);
-const pool = new pg.Pool({ connectionString: url });
-const N = 600;
-let calls = 0;
-registerWorkflow("compact", async () => {
-  const vals = [];
-  for (let i = 0; i < N; i++) vals.push(await step(async () => { calls++; return i; }));
-  return vals.length;
-});
-const engine = new Engine(store);
-const { runId } = await engine.start("compact", []);
-const run = await engine.getRun(runId);
-const ret = await run.returnValue;
-// count events + snapshots
-const evs = await pool.query("SELECT type, count(*) c FROM lightflow_events WHERE run_id=$1 GROUP BY 1", [runId]);
-const snaps = await pool.query("SELECT count(*) c FROM lightflow_events WHERE run_id=$1 AND type='snapshot'", [runId]);
-console.log("result:", ret, "calls:", calls, "snapshots:", snaps.rows[0].c);
-console.log(evs.rows.map(r=>`${r.type}=${r.c}`).join(", "));
-// replay from snapshot: simulate resume on completed run (should be no-op) - measure getEvents size returned
-const log = await store.getEvents(runId);
-console.log("getEvents rows returned (should be << total):", log.length);
-await pool.end(); process.exit(0);

package/dist/test/compat.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/compat.js

@@ -1,87 +0,0 @@
-/**
- * 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 live getter; await terminal state via returnValue
-    await run.returnValue;
-    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"); // live getter reflects cancel
-    await pool.end();
-    engine.stopWorker();
-    await workerPromise;
-});

package/dist/test/coverage.d.ts

@@ -1,6 +0,0 @@
-export declare function coverageWorkflow(opts: {
-    ticks: number;
-    shouldFailFatally: boolean;
-    useHook: boolean;
-}): Promise<Record<string, unknown>>;
-export declare function register(): Promise<void>;

package/dist/test/coverage.js

@@ -1,107 +0,0 @@
-/**
- * Coverage suite: every primitive Entry's workflows use, plus cancel,
- * hooks, retry-then-FatalError, and durable timers — all crash-tested.
- */
-import { Engine, step, sleep, getWritable, FatalError, getWorkflowMetadata, defineHook, workflowFetch, } from "../src/index.js";
-const URL = process.env.LIGHTFLOW_PG_URL;
-export async function coverageWorkflow(opts) {
-    "use workflow";
-    const { runId } = getWorkflowMetadata();
-    const writable = getWritable();
-    const observed = { runId };
-    await writable.write("stage:start;");
-    // 1. step retries a transient error, then succeeds
-    let attempts = 0;
-    const resilient = await step(async () => {
-        attempts += 1;
-        if (attempts < 3)
-            throw new Error("transient");
-        return "ok-after-2-retries";
-    });
-    observed.resilient = resilient;
-    // 2. FatalError is NOT retried and aborts the run
-    let fatalMessage = null;
-    try {
-        await step(async () => { throw new FatalError("hard stop"); });
-    }
-    catch (e) {
-        fatalMessage = e instanceof FatalError ? e.message : "unknown";
-    }
-    observed.fatalMessage = fatalMessage;
-    // 3. durable sleep (Date)
-    for (let i = 0; i < opts.ticks; i += 1) {
-        await sleep(new Date(Date.now() + 700));
-        await writable.write(`stage:tick:${i + 1};`);
-    }
-    observed.ticks = opts.ticks;
-    // 4. durable sleep (ms overload)
-    await sleep(300);
-    observed.sleptMsOverload = true;
-    // 5. hooks
-    if (opts.useHook) {
-        const { token } = await defineHook().create();
-        observed.hookToken = token;
-    }
-    // 6. durable fetch (memoized)
-    try {
-        const r = await workflowFetch("http://127.0.0.1:9/nope");
-        observed.fetchStatus = r.status;
-    }
-    catch (e) {
-        observed.fetchError = e instanceof Error ? e.message : String(e);
-    }
-    await writable.write("stage:done;");
-    await writable.close();
-    return observed;
-}
-export async function register() {
-    const { registerWorkflow } = await import("../src/index.js");
-    registerWorkflow("coverage", coverageWorkflow);
-}
-/* ---------------- runner ---------------- */
-const { createPostgresStore } = await import("../src/pg-store.js");
-const mode = process.argv[2] ?? "run";
-if (mode === "register-only")
-    process.exit(0);
-const store = await createPostgresStore(URL);
-const engine = new Engine(store, { pollMs: 200, staleRunMs: 15_000 });
-await register();
-void engine.startWorker(() => { });
-if (mode === "run") {
-    const { runId } = await engine.start("coverage", [
-        { ticks: Number(process.argv[3] ?? 3), shouldFailFatally: false, useHook: true },
-    ]);
-    console.log("STARTED", runId);
-    const run = await engine.getRun(runId);
-    const rv = await run.returnValue;
-    console.log("RESULT", JSON.stringify(rv));
-    process.exit(0);
-}
-if (mode === "cancel") {
-    const { runId } = await engine.start("coverage", [
-        { ticks: 12, shouldFailFatally: false, useHook: false },
-    ]);
-    await new Promise((r) => setTimeout(r, 1200));
-    const run = await engine.getRun(runId);
-    await run.cancel();
-    const after = await store.getRun(runId);
-    console.log("CANCELLED", JSON.stringify(after));
-    process.exit(0);
-}
-if (mode === "resume") {
-    const runId = process.argv[3];
-    await engine.resume(runId);
-    const row = await store.getRun(runId);
-    console.log("RESUMED", row?.status, JSON.stringify(row?.output));
-    process.exit(0);
-}
-if (mode === "hook") {
-    const runId = process.argv[3];
-    const token = process.argv[4];
-    const target = await store.resolveHook(token, { ok: true });
-    console.log("HOOK_RESOLVED", target);
-    await engine.resume(runId);
-    const row = await store.getRun(runId);
-    console.log("AFTER_HOOK", row?.status, JSON.stringify(row?.output));
-    process.exit(0);
-}

package/dist/test/crash-snap.mjs

@@ -1,22 +0,0 @@
-
-import { Engine, step, registerWorkflow, sleep } from "/home/agentuser/lightflow/dist/src/index.js";
-import { createPostgresStore } from "/home/agentuser/lightflow/dist/src/pg-store.js";
-const url = process.env.LIGHTFLOW_PG_URL;
-const store = await createPostgresStore(url);
-const N = 700;
-registerWorkflow("crashy", async () => {
-  const vals = [];
-  for (let i = 0; i < N; i++) {
-    vals.push(await step(async () => i));
-    if (i === 350) await sleep(120); // suspend mid-run; snapshots exist by now
-  }
-  return vals.length;
-});
-const engine = new Engine(store, { pollMs: 50 });
-const wp = engine.startWorker();
-setTimeout(() => engine.stopWorker(), 60000);
-const { runId } = await engine.start("crashy", []);
-const run = await engine.getRun(runId);
-const ret = await run.returnValue;
-console.log("completed after suspend+resume:", ret, ret === N ? "OK" : "FAIL"); engine.stopWorker();
-process.exit(0);

package/dist/test/dbg.mjs

@@ -1,28 +0,0 @@
-
-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

@@ -1,34 +0,0 @@
-
-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/dist/test/dbg3.mjs

@@ -1,23 +0,0 @@
-
-import { Engine, step, sleep } from "/home/agentuser/lightflow/dist/src/index.js";
-import { createPostgresStore } from "/home/agentuser/lightflow/dist/src/pg-store.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(), 20000);
-const wf = async () => {
-  await sleep(new Date(Date.now() + 300));
-  await step(async () => "x");
-  return "ok";
-};
-const run = await start(wf, []);
-const s1 = await run.status;           // live snapshot (running/pending)
-const s2 = await run.status;           // fresh promise each access
-console.log("live status:", s1, s2);
-const t = await run.status && await (async()=>{ // wait terminal
-  for(;;){ const st = await run.status; if(st!=="running"&&st!=="pending") return st; await new Promise(r=>setTimeout(r,25)); }
-})();
-console.log("terminal:", t);
-process.exit(0);

package/dist/test/drain.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/drain.js

@@ -1,21 +0,0 @@
-import { Engine } from "../src/index.js";
-import { createPostgresStore } from "../src/pg-store.js";
-import { registerAll } from "./workflow-def.js";
-import pg from "pg";
-registerAll();
-const store = await createPostgresStore(process.env.LIGHTFLOW_PG_URL);
-const engine = new Engine(store, { pollMs: 300, staleRunMs: 10_000 });
-const p = new pg.Pool({ connectionString: process.env.LIGHTFLOW_PG_URL });
-// persistent driver: keeps resuming until nothing is running
-void engine.startWorker(() => { });
-const deadline = Date.now() + 9 * 60_000;
-while (Date.now() < deadline) {
-    const rows = await p.query("SELECT run_id FROM lightflow_runs WHERE status='running'");
-    if (rows.rows.length === 0)
-        break;
-    await Promise.all(rows.rows.slice(0, 12).map((r) => engine.resume(r.run_id).catch(() => { })));
-    await new Promise((r) => setTimeout(r, 1200));
-}
-const done = await p.query("SELECT status,count(*) FROM lightflow_runs GROUP BY status");
-console.log("FINAL", JSON.stringify(done.rows));
-process.exit(0);

package/dist/test/entry-parity.d.ts

@@ -1,14 +0,0 @@
-/**
- * Port of Entry's sandbox-lifecycle + chat patterns onto lightflow.
- * Mirrors: lease claim/clear, while(true) wake loop with sleep(Date),
- * getWritable streaming, post-finish persistence, retry/FatalError.
- */
-export type ParityResult = {
-    ok: boolean;
-    runId: string;
-    ticks: number;
-    leaseValue: string | null;
-    chunks: number;
-    persisted: boolean;
-    fatalCaught: boolean;
-};

package/dist/test/entry-parity.js

@@ -1,115 +0,0 @@
-/**
- * Port of Entry's sandbox-lifecycle + chat patterns onto lightflow.
- * Mirrors: lease claim/clear, while(true) wake loop with sleep(Date),
- * getWritable streaming, post-finish persistence, retry/FatalError.
- */
-import { Engine, step, sleep, getWritable, FatalError, getWorkflowMetadata } from "../src/index.js";
-import { createPostgresStore } from "../src/pg-store.js";
-const URL = process.env.LIGHTFLOW_PG_URL ?? "postgres://entry:entry@localhost:5432/entry_lightflow";
-/* ---------- steps (side effects) ---------- */
-async function claimLease(sessionId, value) {
-    "use step";
-    const pg = (await import("pg")).default;
-    const pool = new pg.Pool({ connectionString: process.env.APP_PG_URL, max: 4 });
-    const r = await pool.query(`UPDATE sessions SET lifecycle_run_id=$2 WHERE id=$1 AND lifecycle_run_id IS NULL`, [sessionId, value]);
-    await pool.end();
-    return (r.rowCount ?? 0) > 0;
-}
-async function clearLease(sessionId) {
-    "use step";
-    const pg = (await import("pg")).default;
-    const pool = new pg.Pool({ connectionString: process.env.APP_PG_URL, max: 4 });
-    await pool.query(`UPDATE sessions SET lifecycle_run_id=NULL WHERE id=$1`, [sessionId]);
-    await pool.end();
-}
-async function persistsFinish(runId, chatId, durationMs) {
-    "use step";
-    const pg = (await import("pg")).default;
-    const pool = new pg.Pool({ connectionString: process.env.APP_PG_URL, max: 4 });
-    await pool.query(`INSERT INTO workflow_runs (id, chat_id, session_id, user_id, status, started_at, finished_at, total_duration_ms)
-     VALUES ($1,$2,'selftest-session','selftest-user','completed',now(),now(),$3)
-     ON CONFLICT (id) DO NOTHING`, [runId, chatId, Math.round(durationMs)]);
-    await pool.end();
-    return true;
-}
-async function flakyStep() {
-    "use step";
-    throw new Error("transient failure");
-}
-/* ---------- the workflow ---------- */
-async function parityWorkflow(opts) {
-    "use workflow";
-    const { runId } = getWorkflowMetadata();
-    const writable = getWritable();
-    const started = Date.now();
-    let fatalCaught = false;
-    await writable.write("stage:start;");
-    // --- retry semantics: transient error retried, FatalError not
-    try {
-        await step(flakyStep);
-    }
-    catch (e) {
-        if (e instanceof FatalError)
-            fatalCaught = true;
-        else
-            fatalCaught = true; // engine treats unknown as non-fatal retry-then-fail
-    }
-    const lease = `lrun-${runId}`;
-    const claimed = await step(() => claimLease(opts.sessionId, lease));
-    await writable.write(`stage:lease:${claimed};`);
-    // --- durable timer loop (mirrors sandbox-lifecycle's while(true))
-    for (let i = 0; i < opts.ticks; i += 1) {
-        await sleep(new Date(Date.now() + 1000));
-        await writable.write(`stage:tick:${i + 1};`);
-    }
-    const persisted = await step(() => persistsFinish(runId, opts.chatId, Date.now() - started));
-    await step(() => clearLease(opts.sessionId));
-    await writable.write("stage:done;");
-    await writable.close();
-    return {
-        ok: true, runId, ticks: opts.ticks,
-        leaseValue: claimed ? lease : null,
-        chunks: 3 + opts.ticks, persisted, fatalCaught,
-    };
-}
-/* ---------- runner ---------- */
-async function main() {
-    const store = await createPostgresStore(URL);
-    const engine = new Engine(store, { pollMs: 300 });
-    const { registerWorkflow } = await import("../src/index.js");
-    registerWorkflow("entry-parity", parityWorkflow);
-    void engine.startWorker((e) => console.error("[worker]", e));
-    const mode = process.argv[2] ?? "run";
-    const ticks = Number(process.argv[3] ?? 3);
-    if (mode === "run") {
-        const { runId } = await engine.start("entry-parity", [
-            { sessionId: "selftest-session", chatId: "selftest-chat", ticks },
-        ]);
-        console.log("STARTED", runId);
-        const run = await engine.getRun(runId);
-        const chunks = [];
-        const reader = run.getReadable().getReader();
-        const dec = new TextDecoder();
-        try {
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                chunks.push(dec.decode(value));
-            }
-        }
-        catch { /* closed */ }
-        const rv = await run.returnValue;
-        console.log("CHUNKS", JSON.stringify(chunks));
-        console.log("RESULT", JSON.stringify(rv));
-        process.exit(0);
-    }
-    if (mode === "resume") {
-        const runId = process.argv[4];
-        await engine.resume(runId);
-        const row = await store.getRun(runId);
-        console.log("RESUMED", runId, JSON.stringify(row));
-        process.exit(0);
-    }
-}
-void main().catch((e) => { console.error(e); process.exit(1); });

package/dist/test/race.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/race.js

@@ -1,43 +0,0 @@
-/**
- * Concurrency stress: each run is resumed by 20 concurrent resume() calls.
- * Contract: exactly one step_completed, zero step_failed per run — racing
- * replays must never re-execute a memoized step (run-lease arbitration).
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import pg from "pg";
-import { Engine, step, registerWorkflow } from "../src/index.js";
-import { createPostgresStore } from "../src/pg-store.js";
-const PG_URL = process.env.LIGHTFLOW_PG_URL;
-if (!PG_URL)
-    throw new Error("LIGHTFLOW_PG_URL is required");
-test("racing resumes never re-execute a memoized step", async () => {
-    const store = await createPostgresStore(PG_URL);
-    const pool = new pg.Pool({ connectionString: PG_URL });
-    registerWorkflow("race-stress", async () => {
-        "use workflow";
-        return await step(async () => {
-            "use step";
-            await new Promise((r) => setTimeout(r, 5));
-            return "x";
-        });
-    });
-    const engine = new Engine(store);
-    const RUNS = 10, RACERS = 20;
-    for (let i = 0; i < RUNS; i++) {
-        const { runId } = await engine.start("race-stress", []);
-        await Promise.all(Array.from({ length: RACERS }, () => engine.resume(runId).catch(() => { })));
-        // wait for terminal state
-        for (let w = 0; w < 200; w++) {
-            const row = await store.getRun(runId);
-            if (row && row.status !== "running")
-                break;
-            await new Promise((r) => setTimeout(r, 25));
-        }
-        const sc = Number((await pool.query("SELECT count(*) c FROM lightflow_events WHERE run_id=$1 AND type='step_completed'", [runId])).rows[0].c);
-        const sf = Number((await pool.query("SELECT count(*) c FROM lightflow_events WHERE run_id=$1 AND type='step_failed'", [runId])).rows[0].c);
-        assert.equal(sc, 1, `run ${runId}: expected 1 step_completed, got ${sc}`);
-        assert.equal(sf, 0, `run ${runId}: expected 0 step_failed, got ${sf}`);
-    }
-    await pool.end();
-});

package/dist/test/resume-all.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/resume-all.js

@@ -1,14 +0,0 @@
-import { Engine } from "../src/index.js";
-import { createPostgresStore } from "../src/pg-store.js";
-import { registerAll } from "./workflow-def.js";
-import pg from "pg";
-registerAll();
-const store = await createPostgresStore(process.env.LIGHTFLOW_PG_URL);
-const engine = new Engine(store, { pollMs: 200, staleRunMs: 15_000 });
-const p = new pg.Pool({ connectionString: process.env.LIGHTFLOW_PG_URL });
-const rows = await p.query("SELECT run_id FROM lightflow_runs WHERE status='running'");
-console.log("RESUMING", rows.rows.length);
-await Promise.all(rows.rows.map((r) => engine.resume(r.run_id).catch((e) => console.error("ERR", e.message))));
-const done = await p.query("SELECT status,count(*) FROM lightflow_runs GROUP BY status");
-console.log("FINAL", JSON.stringify(done.rows));
-process.exit(0);

package/dist/test/resume.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/resume.js

@@ -1,12 +0,0 @@
-import { Engine } from "../src/index.js";
-import { createPostgresStore } from "../src/pg-store.js";
-const { registerWorkflow } = await import("../src/index.js");
-const { parityWorkflow, registerAll } = await import("./workflow-def.js");
-registerAll();
-const store = await createPostgresStore(process.env.LIGHTFLOW_PG_URL);
-const engine = new Engine(store, { pollMs: 300, staleRunMs: 15000 });
-const runId = process.argv[2];
-await engine.resume(runId);
-const row = await store.getRun(runId);
-console.log("FINAL", row?.status, JSON.stringify(row?.output));
-process.exit(0);

package/dist/test/simulate.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/simulate.js

@@ -1,46 +0,0 @@
-import { Engine } from "../src/index.js";
-import { createPostgresStore } from "../src/pg-store.js";
-import { registerAll } from "./workflow-def.js";
-registerAll();
-const users = Number(process.argv[2] ?? 10);
-const chats = Number(process.argv[3] ?? 3);
-const ticks = Number(process.argv[4] ?? 6);
-const store = await createPostgresStore(process.env.LIGHTFLOW_PG_URL);
-const engine = new Engine(store, { pollMs: 200, staleRunMs: 20_000 });
-void engine.startWorker(() => { });
-const ids = [];
-const t0 = Date.now();
-for (let u = 0; u < users; u += 1) {
-    for (let c = 0; c < chats; c += 1) {
-        const { runId } = await engine.start("entry-parity", [
-            { sessionId: "selftest-session", chatId: `sim-${u}-chat-${c}`, ticks },
-        ]);
-        ids.push(runId);
-    }
-}
-console.log("STARTED", ids.length, "in", Date.now() - t0, "ms");
-// poll to terminal state
-const deadline = Date.now() + 20 * 60_000;
-let done = 0;
-while (Date.now() < deadline) {
-    let completed = 0, running = 0, failed = 0;
-    for (const id of ids) {
-        const r = await store.getRun(id);
-        if (!r)
-            continue;
-        if (r.status === "completed")
-            completed += 1;
-        else if (r.status === "running")
-            running += 1;
-        else
-            failed += 1;
-    }
-    done = completed;
-    console.log(`t+${Math.round((Date.now() - t0) / 1000)}s completed=${completed} running=${running} failed=${failed}`);
-    if (completed + failed === ids.length)
-        break;
-    await new Promise((r) => setTimeout(r, 10_000));
-    void running;
-}
-console.log("DONE", done, "of", ids.length);
-process.exit(0);

package/dist/test/smoke.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test/smoke.js

@@ -1,157 +0,0 @@
-/**
- * CI smoke suite — node:test, runs against a real Postgres (see ci.yml).
- * Uses the real engine API: plain async fns marked "use step" / "use workflow",
- * driven through Engine + createPostgresStore (same pattern as test/entry-parity.ts).
- *
- * The kill-recovery harnesses (simulate/drain/resume/resume-all) stay as
- * manual scripts — SIGKILL harnesses can't run inside node:test.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import pg from "pg";
-import { Engine, step, sleep, getWritable, FatalError, getWorkflowMetadata, registerWorkflow } from "../src/index.js";
-import { createPostgresStore } from "../src/pg-store.js";
-const PG_URL = process.env.LIGHTFLOW_PG_URL;
-if (!PG_URL)
-    throw new Error("LIGHTFLOW_PG_URL is required");
-async function freshStore() {
-    return createPostgresStore(PG_URL);
-}
-async function resetTables() {
-    // Ensure schema exists first (fresh CI database), then clear it.
-    await createPostgresStore(PG_URL);
-    const pool = new pg.Pool({ connectionString: PG_URL });
-    await pool.query("TRUNCATE lightflow_events, lightflow_runs");
-    await pool.end();
-}
-/** Poll until the run leaves "running" (or timeout). */
-async function awaitTerminal(store, runId, timeoutMs = 10_000) {
-    const deadline = Date.now() + timeoutMs;
-    let run = await store.getRun(runId);
-    while (run?.status === "running" && Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, 100));
-        run = await store.getRun(runId);
-    }
-    return run;
-}
-test("step memoizes — the side effect executes exactly once", async () => {
-    await resetTables();
-    const store = await freshStore();
-    let calls = 0;
-    registerWorkflow("smoke-memo", async () => {
-        "use workflow";
-        const memoized = async () => {
-            "use step";
-            calls += 1;
-            return `call-${calls}`;
-        };
-        await step(memoized);
-        return { calls };
-    });
-    const engine = new Engine(store, { pollMs: 100 });
-    const workerPromise = engine.startWorker();
-    try {
-        const { runId } = await engine.start("smoke-memo", []);
-        const run = await awaitTerminal(store, runId);
-        assert.equal(run?.status, "completed");
-        assert.equal(run?.output?.calls, 1);
-    }
-    finally {
-        engine.stopWorker();
-        await workerPromise;
-    }
-});
-test("FatalError is caught as fatal inside the workflow", async () => {
-    await resetTables();
-    const store = await freshStore();
-    registerWorkflow("smoke-fatal", async () => {
-        "use workflow";
-        const bomb = async () => {
-            "use step";
-            throw new FatalError("hard stop");
-        };
-        try {
-            await step(bomb);
-            return { fatalCaught: false };
-        }
-        catch (e) {
-            return { fatalCaught: e instanceof FatalError };
-        }
-    });
-    const engine = new Engine(store, { pollMs: 100 });
-    const workerPromise = engine.startWorker();
-    try {
-        const { runId } = await engine.start("smoke-fatal", []);
-        const run = await awaitTerminal(store, runId);
-        assert.equal(run?.status, "completed");
-        assert.equal(run?.output?.fatalCaught, true);
-    }
-    finally {
-        engine.stopWorker();
-        await workerPromise;
-    }
-});
-test("durable sleep resumes and completes via the worker loop", async () => {
-    await resetTables();
-    const store = await freshStore();
-    registerWorkflow("smoke-sleep", async () => {
-        "use workflow";
-        await sleep(100);
-        return "after-sleep";
-    });
-    const engine = new Engine(store, { pollMs: 50 });
-    const workerPromise = engine.startWorker();
-    try {
-        const { runId } = await engine.start("smoke-sleep", []);
-        const run = await awaitTerminal(store, runId);
-        assert.equal(run?.status, "completed");
-        assert.equal(run?.output, "after-sleep");
-    }
-    finally {
-        engine.stopWorker();
-        await workerPromise;
-    }
-});
-test("streaming chunks are ordered and replayable", async () => {
-    await resetTables();
-    const store = await freshStore();
-    registerWorkflow("smoke-stream", async () => {
-        "use workflow";
-        const writable = getWritable();
-        for (let i = 0; i < 3; i += 1) {
-            await writable.write(`chunk-${i}`);
-            await sleep(50);
-        }
-        await writable.close();
-        return 3;
-    });
-    const engine = new Engine(store, { pollMs: 50 });
-    const workerPromise = engine.startWorker();
-    try {
-        const { runId } = await engine.start("smoke-stream", []);
-        const run = await awaitTerminal(store, runId);
-        assert.equal(run?.status, "completed");
-        const pool = new pg.Pool({ connectionString: PG_URL });
-        const rows = await pool.query(`SELECT payload->>'value' AS val FROM lightflow_events
-       WHERE run_id=$1 AND type='chunk' AND (payload->>'done') IS NULL
-       ORDER BY (payload->>'index')::int`, [runId]);
-        await pool.end();
-        assert.deepEqual(rows.rows.map((r) => r.val), ["chunk-0", "chunk-1", "chunk-2"]);
-    }
-    finally {
-        engine.stopWorker();
-        await workerPromise;
-    }
-});
-test("runId is unique per start", async () => {
-    await resetTables();
-    const store = await freshStore();
-    registerWorkflow("smoke-ids", async () => {
-        "use workflow";
-        return getWorkflowMetadata().runId;
-    });
-    const engine = new Engine(store, { pollMs: 100 });
-    const a = await engine.start("smoke-ids", []);
-    const b = await engine.start("smoke-ids", []);
-    assert.notEqual(a.runId, b.runId);
-});

package/dist/test/workflow-def.d.ts

@@ -1,6 +0,0 @@
-export declare function parityWorkflow(opts: {
-    sessionId: string;
-    chatId: string;
-    ticks: number;
-}): Promise<unknown>;
-export declare function registerAll(): void;

package/dist/test/workflow-def.js

@@ -1,54 +0,0 @@
-import { registerWorkflow } from "../src/index.js";
-export async function parityWorkflow(opts) {
-    "use workflow";
-    const { step, sleep, getWritable, FatalError, getWorkflowMetadata } = await import("../src/index.js");
-    const { runId } = getWorkflowMetadata();
-    const writable = getWritable();
-    const started = Date.now();
-    let fatalCaught = false;
-    await writable.write("stage:start;");
-    try {
-        await step(async () => { throw new Error("transient"); });
-    }
-    catch {
-        fatalCaught = true;
-    }
-    const lease = `lrun-${runId}`;
-    const claimed = await step(async () => {
-        const pg = (await import("pg")).default;
-        const pool = new pg.Pool({ connectionString: process.env.APP_PG_URL, max: 4 });
-        const r = await pool.query(`UPDATE sessions SET lifecycle_run_id=$2 WHERE id=$1 AND lifecycle_run_id IS NULL`, [opts.sessionId, lease]);
-        await pool.end();
-        return (r.rowCount ?? 0) > 0;
-    });
-    await writable.write(`stage:lease:${claimed};`);
-    for (let i = 0; i < opts.ticks; i += 1) {
-        await sleep(new Date(Date.now() + 1000));
-        await writable.write(`stage:tick:${i + 1};`);
-    }
-    const persisted = await step(async () => {
-        const pg = (await import("pg")).default;
-        const pool = new pg.Pool({ connectionString: process.env.APP_PG_URL, max: 4 });
-        await pool.query(`INSERT INTO workflow_runs (id, chat_id, session_id, user_id, status, started_at, finished_at, total_duration_ms)
-       VALUES ($1,$2,'selftest-session','selftest-user','completed',now(),now(),$3)
-       ON CONFLICT (id) DO NOTHING`, [runId, opts.chatId, Math.round(Date.now() - started)]);
-        await pool.end();
-        return true;
-    });
-    await step(async () => {
-        const pg = (await import("pg")).default;
-        const pool = new pg.Pool({ connectionString: process.env.APP_PG_URL, max: 4 });
-        await pool.query(`UPDATE sessions SET lifecycle_run_id=NULL WHERE id=$1`, [opts.sessionId]);
-        await pool.end();
-    });
-    await writable.write("stage:done;");
-    await writable.close();
-    return {
-        ok: true, runId, ticks: opts.ticks,
-        leaseValue: claimed ? lease : null,
-        persisted, fatalCaught,
-    };
-}
-export function registerAll() {
-    registerWorkflow("entry-parity", parityWorkflow);
-}