lightflow-engine 0.1.0

package/dist/src/pg-store.js

@@ -0,0 +1,194 @@
+/**
+ * Postgres-backed store for lightflow.
+ *
+ * Two tables only. All times are BIGINT epoch milliseconds — no timestamp
+ * columns, so no timezone ambiguity (the bug that cost hours in world-postgres).
+ */
+import pg from "pg";
+export async function createPostgresStore(url) {
+    const pool = new pg.Pool({ connectionString: url, max: 20 });
+    await pool.query(`
+    CREATE TABLE IF NOT EXISTS lightflow_runs (
+      run_id     TEXT PRIMARY KEY,
+      name       TEXT NOT NULL,
+      status     TEXT NOT NULL DEFAULT 'running',
+      input      JSONB NOT NULL,
+      output     JSONB,
+      created_at BIGINT NOT NULL,
+      updated_at BIGINT NOT NULL
+    );
+  `);
+    await pool.query(`
+    CREATE TABLE IF NOT EXISTS lightflow_events (
+      id          BIGSERIAL PRIMARY KEY,
+      run_id      TEXT NOT NULL REFERENCES lightflow_runs(run_id) ON DELETE CASCADE,
+      seq         INTEGER NOT NULL,
+      type        TEXT NOT NULL,
+      payload     JSONB NOT NULL,
+      created_at  BIGINT NOT NULL,
+      UNIQUE (run_id, seq)
+    );
+  `);
+    await pool.query(`
+    CREATE INDEX IF NOT EXISTS lightflow_events_run_idx
+      ON lightflow_events (run_id, seq);
+  `);
+    // Cancellation flag (Entry cancels duplicate streams).
+    await pool.query(`
+    ALTER TABLE lightflow_runs ADD COLUMN IF NOT EXISTS cancelled BOOLEAN NOT NULL DEFAULT false;
+  `);
+    // Durable hooks: an external caller resolves a token, the workflow wakes.
+    await pool.query(`
+    CREATE TABLE IF NOT EXISTS lightflow_hooks (
+      token     TEXT PRIMARY KEY,
+      run_id    TEXT NOT NULL,
+      key       TEXT NOT NULL,
+      payload   JSONB,
+      resolved  BOOLEAN NOT NULL DEFAULT false,
+      created_at BIGINT NOT NULL
+    );
+  `);
+    await pool.query(`
+    CREATE INDEX IF NOT EXISTS lightflow_events_timer_idx
+      ON lightflow_events ((payload->>'wakeAt'))
+      WHERE type = 'sleep_created';
+  `);
+    // Exactly-once chunks: one row per (run, write index) AND one per (run,
+    // call-position key). The key index is what makes a replayed write a
+    // harmless no-op even when two replays race.
+    await pool.query(`
+    CREATE UNIQUE INDEX IF NOT EXISTS lightflow_events_chunk_unique
+      ON lightflow_events (run_id, (payload->>'index'))
+      WHERE type = 'chunk';
+  `);
+    await pool.query(`
+    CREATE UNIQUE INDEX IF NOT EXISTS lightflow_events_chunk_key_unique
+      ON lightflow_events (run_id, (payload->>'key'))
+      WHERE type = 'chunk' AND payload->>'key' IS NOT NULL;
+  `);
+    return {
+        async createRun(runId, name, input) {
+            const now = Date.now();
+            await pool.query(`INSERT INTO lightflow_runs (run_id, name, status, input, created_at, updated_at)
+         VALUES ($1,$2,'running',$3,$4,$4) ON CONFLICT (run_id) DO NOTHING`, [runId, name, JSON.stringify(input), now]);
+            await pool.query(`INSERT INTO lightflow_events (run_id, seq, type, payload, created_at)
+         VALUES ($1,0,'run_completed',$2,$3) ON CONFLICT DO NOTHING`, [runId, JSON.stringify({ name, args: input }), now]);
+        },
+        async getRun(runId) {
+            const r = await pool.query(`SELECT status, output FROM lightflow_runs WHERE run_id=$1`, [runId]);
+            if (r.rowCount === 0)
+                return null;
+            return { status: r.rows[0].status, output: r.rows[0].output };
+        },
+        async appendEvent(e) {
+            if (e.type === "chunk") {
+                // Exactly-once by write key, decided INSIDE the advisory lock so two
+                // racing replays cannot both pass the check-then-insert window.
+                const c = await pool.connect();
+                try {
+                    await c.query("BEGIN");
+                    await c.query("SELECT pg_advisory_xact_lock(hashtext($1))", [e.runId]);
+                    const key = e.payload.key;
+                    if (key) {
+                        const dup = await c.query(`SELECT 1 FROM lightflow_events
+               WHERE run_id=$1 AND type='chunk' AND payload->>'key'=$2 LIMIT 1`, [e.runId, key]);
+                        if (dup.rowCount) {
+                            await c.query("COMMIT");
+                            return;
+                        }
+                    }
+                    const r = await c.query(`SELECT COALESCE(max(seq),-1)+1 AS seq FROM lightflow_events WHERE run_id=$1`, [e.runId]);
+                    await c.query(`INSERT INTO lightflow_events (run_id, seq, type, payload, created_at)
+             VALUES ($1,$2,$3,$4,$5)
+             ON CONFLICT (run_id, (payload->>'index')) WHERE type='chunk' DO NOTHING`, [e.runId, r.rows[0].seq, e.type, JSON.stringify(e.payload), e.createdAt]);
+                    await c.query("COMMIT");
+                }
+                catch (err) {
+                    await c.query("ROLLBACK").catch(() => { });
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (!/duplicate key value/.test(msg))
+                        throw err;
+                    // duplicate chunk from a replayed tick: expected, ignore
+                }
+                finally {
+                    c.release();
+                }
+                return;
+            }
+            const c = await pool.connect();
+            try {
+                await c.query("BEGIN");
+                await c.query("SELECT pg_advisory_xact_lock(hashtext($1))", [e.runId]);
+                const r = await c.query(`SELECT COALESCE(max(seq),-1)+1 AS seq FROM lightflow_events WHERE run_id=$1`, [e.runId]);
+                await c.query(`INSERT INTO lightflow_events (run_id, seq, type, payload, created_at)
+           VALUES ($1,$2,$3,$4,$5) ON CONFLICT (run_id, seq) DO NOTHING`, [e.runId, r.rows[0].seq, e.type, JSON.stringify(e.payload), e.createdAt]);
+                await c.query("COMMIT");
+            }
+            catch (err) {
+                await c.query("ROLLBACK").catch(() => { });
+                throw err;
+            }
+            finally {
+                c.release();
+            }
+        },
+        async getEvents(runId) {
+            const r = await pool.query(`SELECT run_id, seq, type, payload, created_at FROM lightflow_events
+         WHERE run_id=$1 ORDER BY seq ASC`, [runId]);
+            return r.rows.map((x) => ({
+                runId: x.run_id, seq: x.seq, type: x.type,
+                payload: x.payload, createdAt: Number(x.created_at),
+            }));
+        },
+        async dueTimers(now) {
+            const r = await pool.query(`SELECT run_id, seq FROM lightflow_events
+         WHERE type='sleep_created' AND (payload->>'wakeAt')::bigint <= $1`, [now]);
+            return r.rows.map((x) => ({ runId: x.run_id, seq: x.seq }));
+        },
+        async claimDue() { return false; },
+        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]);
+            return Number(r.rows[0].n);
+        },
+        async staleRuns(cutoff) {
+            const r = await pool.query(`SELECT run_id FROM lightflow_runs
+         WHERE status='running' AND updated_at < $1`, [cutoff]);
+            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()]);
+        },
+        async isCancelled(runId) {
+            const r = await pool.query(`SELECT cancelled FROM lightflow_runs WHERE run_id=$1`, [runId]);
+            return r.rowCount ? Boolean(r.rows[0].cancelled) : false;
+        },
+        async createHook(runId, token, key) {
+            await pool.query(`INSERT INTO lightflow_hooks (token, run_id, key, resolved, created_at)
+         VALUES ($1,$2,$3,false,$4) ON CONFLICT (token) DO NOTHING`, [token, runId, key, Date.now()]);
+        },
+        async resolveHook(token, payload) {
+            const r = await pool.query(`UPDATE lightflow_hooks SET resolved=true, payload=$2
+         WHERE token=$1 RETURNING run_id`, [token, JSON.stringify(payload)]);
+            return r.rowCount ? r.rows[0].run_id : null;
+        },
+        async getHook(token) {
+            const r = await pool.query(`SELECT run_id, payload, resolved FROM lightflow_hooks WHERE token=$1`, [token]);
+            if (!r.rowCount)
+                return null;
+            return {
+                runId: r.rows[0].run_id,
+                payload: { ...(r.rows[0].payload ?? {}), resolved: Boolean(r.rows[0].resolved) },
+            };
+        },
+        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()]);
+        },
+    };
+}
+export async function applyTimezoneGuard(url) {
+    // Belt and braces: even though we store BIGINT, ensure the session TZ is UTC.
+    const pool = new pg.Pool({ connectionString: url, max: 2 });
+    await pool.query(`SET timezone = 'UTC'`);
+    await pool.end();
+}

package/dist/test/coverage.js

@@ -0,0 +1,107 @@
+/**
+ * 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/drain.js

@@ -0,0 +1,21 @@
+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.js

@@ -0,0 +1,115 @@
+/**
+ * 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/resume-all.js

@@ -0,0 +1,14 @@
+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.js

@@ -0,0 +1,12 @@
+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.js

@@ -0,0 +1,46 @@
+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.js

@@ -0,0 +1,157 @@
+/**
+ * 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);
+});