lightflow-engine 0.2.2 → 0.2.4

package/dist/src/compat/api.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Vercel Workflow compat — `workflow/api` module surface.
+ *
+ * Differences from our core Engine API:
+ *  - start(fn, args): takes the workflow FUNCTION (not an id); returns the
+ *    run handle directly (not a promise).
+ *  - getRun(runId): returns the handle synchronously; `status` is a Promise;
+ *    status includes "pending" and "cancelled".
+ *  - getReadable({ startIndex }): chunk-indexed resumable stream with
+ *    getTailIndex().
+ *  - run.cancel(), run.returnValue.
+ */
+import { Engine, type Store } from "../index.js";
+export type VercelRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+export type VercelRun = {
+    runId: string;
+    /** 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'
+     *  startStopMonitor re-awaits it in a 150ms poll loop. */
+    readonly status: Promise<VercelRunStatus>;
+    returnValue: Promise<unknown>;
+    getReadable<T = unknown>(opts?: {
+        startIndex?: number;
+    }): ReadableStream<T> & {
+        getTailIndex(): Promise<number>;
+    };
+    cancel(): Promise<void>;
+};
+/** Configure the compat layer with a store/engine (call once at boot). */
+export declare function initWorkflowApi(store: Store, engine?: Engine): void;
+export declare function getEngine(): Engine;
+export declare function start(fn: (...args: never[]) => Promise<unknown>, args: unknown[]): Promise<VercelRun>;
+export declare function getRun(runId: string): VercelRun;

package/dist/src/compat/fetch.d.ts

@@ -0,0 +1 @@
+export declare function workflowFetch(input: string, init?: RequestInit): Promise<Response>;

package/dist/src/compat/metadata.d.ts

@@ -0,0 +1,3 @@
+export declare function getWorkflowMetadata(): {
+    workflowRunId: string;
+};

package/dist/src/compat/next.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Vercel Workflow compat — `workflow/next` surface.
+ *
+ * Vercel's withWorkflow wraps the Next.js config to enable the directive
+ * compiler ("use workflow" / "use step"). lightflow's runtime does not need
+ * a bundler transform: directives are inert strings, workflow functions are
+ * registered explicitly by start(), and "use step" functions can be wrapped
+ * with step() from compat/workflow for durability.
+ *
+ * This drop-in is an identity wrapper so next.config.ts keeps working
+ * unchanged:
+ *   import { withWorkflow } from "workflow/next";
+ * + import { withWorkflow } from "lightflow-engine/compat/next";
+ */
+export declare function withWorkflow<T extends Record<string, unknown>>(config: T): T;

package/dist/src/compat/workflow.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Vercel Workflow compatibility layer — `workflow` module surface.
+ *
+ * Drop-in for entry-agents-style code: same named exports, same shapes.
+ * Directive notes:
+ *  - "use workflow" / "use step" are inert strings at runtime. This layer
+ *    makes directly-called "use step" functions durable via the companion
+ *    webpack loader (workflow/next) or explicit step() wrappers.
+ */
+export { FatalError, CancelledError, sleep } from "../index.js";
+export { getWorkflowMetadata } from "../compat/metadata.js";
+export { workflowFetch } from "../compat/fetch.js";
+/**
+ * Vercel's getWritable returns a web-standard WritableStream whose writes
+ * are durable chunk events. Ours maps 1:1: every writer.write(chunk) is a
+ * memoized chunk event keyed by call position; writer.close() emits the
+ * terminal done marker.
+ */
+export declare function getWritable<T = unknown>(): WritableStream<T>;
+/** Auto-registration id for a workflow function (stable per code site). */
+export declare function workflowIdFor(fn: (...a: unknown[]) => Promise<unknown>): string;
+/**
+ * makeStep — turns a plain async function into a durable step callable.
+ *
+ * Entry's "use step" functions take arguments; lightflow's step() takes a
+ * thunk. makeStep wraps both: the returned function is a drop-in for the
+ * original (same signature), but each call becomes a memoized, retrying,
+ * replayable step keyed by call position. Outside a workflow it degrades
+ * to a plain call, so tests and non-durable paths keep working.
+ */
+export declare function makeStep<A extends unknown[], R>(fn: (...args: A) => Promise<R>, opts?: {
+    retries?: number;
+}): (...args: A) => Promise<R>;

package/dist/src/index.d.ts

@@ -0,0 +1,189 @@
+/**
+ * lightflow — a durable workflow engine, from scratch.
+ *
+ * Implements every primitive Entry's workflows rely on:
+ *   - "use workflow"  deterministic orchestration, replayed from an event log
+ *   - "use step"      at-least-once, memoized side effects
+ *   - sleep(ms | Date) durable timers (survive process death)
+ *   - getWritable()    ordered, resumable output stream
+ *   - start() / getRun()  start, resume by id, await returnValue
+ *   - FatalError       non-retryable failure
+ *   - getWorkflowMetadata()  run id inside a workflow
+ *
+ * Design goals that fix the two defects found in world-postgres:
+ *   1. All timestamps are epoch milliseconds (integer). No naive/UTC skew.
+ *   2. No spec-version coupling: events are plain JSON rows with a schema
+ *      version integer that the engine upgrades itself.
+ */
+export declare class FatalError extends Error {
+    readonly fatal = true;
+    constructor(message: string);
+}
+export type RunStatus = "running" | "completed" | "failed";
+export type StepEvent = {
+    runId: string;
+    seq: number;
+    type: "step_started" | "step_completed" | "step_failed" | "sleep_created" | "sleep_completed" | "chunk" | "run_completed" | "run_failed" | "snapshot";
+    payload: unknown;
+    createdAt: number;
+};
+export interface Store {
+    createRun(runId: string, name: string, input: unknown): Promise<void>;
+    getRun(runId: string): Promise<{
+        status: RunStatus;
+        output?: unknown;
+    } | null>;
+    appendEvent(e: StepEvent): Promise<void>;
+    getEvents(runId: string): Promise<StepEvent[]>;
+    /** Durable timers due at or before `now`. */
+    dueTimers(now: number): Promise<{
+        runId: string;
+        seq: number;
+        key: string;
+    }[]>;
+    claimDue(now: number): Promise<boolean>;
+    /** Runs still 'running' with no activity since `cutoff` (epoch ms). */
+    staleRuns?(cutoff: number): Promise<string[]>;
+    /** Mark a run cancelled. Ignored once terminal. */
+    cancel?(runId: string): Promise<void>;
+    isCancelled?(runId: string): Promise<boolean>;
+    /** Next monotonic chunk index (max+1), atomic per run. */
+    nextChunkIndex?(runId: string): Promise<number>;
+    /** Run lease: claim (atomically) / release before executing a replay. */
+    claimRun?(runId: string, leaseMs?: number): Promise<{
+        ok: boolean;
+        cancelled: boolean;
+    }>;
+    releaseRun?(runId: string): Promise<void>;
+    /** Terminal status + lease release in one round trip. */
+    finishRun?(runId: string, status: RunStatus, output?: unknown): Promise<void>;
+    /** Optional LISTEN/NOTIFY wakeup nudge for workers. */
+    notifyWake?(): Promise<void>;
+    /** Optional dedicated LISTEN client factory (pg Pool or Client). */
+    getListenClient?(): {
+        query(sql: string): Promise<unknown>;
+        on(event: "notification", cb: () => void): void;
+        release?(): void;
+    };
+    /** Hooks: durable external callbacks a workflow can await. */
+    createHook?(runId: string, token: string, key: string): Promise<void>;
+    resolveHook?(token: string, payload: unknown): Promise<string | null>;
+    getHook?(token: string): Promise<{
+        runId: string;
+        payload: unknown;
+    } | null>;
+    setStatus(runId: string, status: RunStatus, output?: unknown): Promise<void>;
+}
+type WorkflowFn = (...args: unknown[]) => 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 = {
+    runId: string;
+    seq: number;
+    /** deterministic call position counters — these form the replay key */
+    stepCalls: number;
+    sleepCalls: number;
+    writes: number;
+    hookCalls: number;
+    store: Store;
+    log: StepEvent[];
+    /** O(1) memo lookup: "type:key" -> event (built once at replay start) */
+    memo: Map<string, StepEvent>;
+    /** steps completed during the current execution (for snapshot trigger) */
+    completedNow: number;
+    /** results of steps completed this execution: key -> value */
+    freshResults: Map<string, unknown>;
+    /** in-flight append promises: flushed at suspension points / run end */
+    inflight: Promise<void>[];
+    /** appends an event, pipelining it with others already in flight */
+    append(e: StepEvent): Promise<void>;
+    /** index of events already consumed during replay */
+    cursor: number;
+    chunks: string[];
+    now: () => number;
+};
+export declare let current: Ctx | null;
+export declare function getWorkflowMetadata(): {
+    runId: string;
+};
+/**
+ * Run a side effect durably. On replay the memoized result is returned and
+ * the function body is NOT re-executed.
+ */
+export declare function step<T>(fn: () => Promise<T>): Promise<T>;
+/** Durable sleep. Accepts milliseconds or an absolute Date. */
+export declare function sleep(until: number | Date): Promise<void>;
+export declare class SuspendSignal {
+    readonly key: string;
+    readonly wakeAt: number;
+    constructor(key: string, wakeAt: number);
+}
+/** Ordered output stream for a run. Chunks are persisted and replayable. */
+export declare function getWritable<T = string>(): {
+    write(chunk: T): Promise<void>;
+    close(): Promise<void>;
+};
+export declare class Engine {
+    private readonly store;
+    private readonly opts;
+    /** In-process run completions: runId -> deferred. Avoids polling entirely. */
+    private readonly local;
+    private defer;
+    constructor(store: Store, opts?: {
+        stepRetries?: number;
+        pollMs?: number;
+        staleRunMs?: number;
+    });
+    start(workflowId: string, args: unknown[]): Promise<{
+        runId: string;
+    }>;
+    getRun(runId: string): Promise<{
+        runId: string;
+        status: RunStatus;
+        returnValue: Promise<unknown>;
+        getReadable: () => ReadableStream<any>;
+        /** Entry calls this to kill a duplicate stream (route.ts:172). */
+        cancel: () => Promise<void>;
+    }>;
+    private waitFor;
+    private readable;
+    /** Execute (or resume) a run. Racing resumes are arbitrated by a lease. */
+    run(runId: string, workflowId: string, args: unknown[]): Promise<void>;
+    private workerStopped;
+    private listenClient?;
+    /** Signal the worker loop to exit after its current poll cycle. */
+    stopWorker(): void;
+    /** Worker loop: resume runs whose timers are due. Resolves when stopWorker() is called. */
+    startWorker(onError?: (e: unknown) => void): Promise<void>;
+    /**
+     * Built-in reaper: resume 'running' runs with no event activity in the
+     * last `staleMs`. Fixes the orphaned-run failure mode found in testing
+     * world-postgres (a run wedged in 'running' forever).
+     */
+    private reapStale;
+    resume(runId: string): Promise<void>;
+}
+/**
+ * Cancel a run (Entry's route.ts calls getRun(id).cancel() to kill duplicate
+ * streams). Terminal runs ignore this.
+ */
+export declare class CancelledError extends Error {
+    constructor(runId: string);
+}
+/** Create a durable hook a workflow can await; resolve it from outside. */
+export declare function defineHook<T = unknown>(): {
+    create(): Promise<{
+        token: string;
+    }>;
+};
+/** Await a previously created hook until an external caller resolves it. */
+export declare function hookResult<T>(token: string): Promise<T>;
+/** Durable fetch: memoized per step position, like any other side effect. */
+export declare function workflowFetch(input: string, init?: RequestInit): Promise<Response>;
+/**
+ * Durable loop: executes body(i) for i in [0, n). Each iteration is guarded by
+ * a durable timer barrier; completed iterations are skipped on replay, so a
+ * resumed run continues where it stopped instead of restarting.
+ */
+export declare function hashId(s: string): string;
+export {};

package/dist/src/pg-store.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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).
+ */
+export type Store = import("../src/index.js").Store;
+export declare function createPostgresStore(url: string, opts?: {
+    sessionOptions?: Record<string, string>;
+}): Promise<Store>;
+export declare function applyTimezoneGuard(url: string): Promise<void>;

package/dist/test/bench.d.ts

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

package/dist/test/compat.d.ts

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

package/dist/test/coverage.d.ts

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

package/dist/test/drain.d.ts

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

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

@@ -0,0 +1,14 @@
+/**
+ * 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/race.d.ts

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

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

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

package/dist/test/resume.d.ts

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

package/dist/test/simulate.d.ts

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

package/dist/test/smoke.d.ts

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

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

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

package/package.json

@@ -1,17 +1,32 @@
 {
   "name": "lightflow-engine",
-  "version": "0.2.2",
-  "description": "A tiny durable workflow engine for Node.js and Postgres \u2014 with a Vercel Workflow drop-in compat layer.",
+  "version": "0.2.4",
+  "description": "A tiny durable workflow engine for Node.js and Postgres — with a Vercel Workflow drop-in compat layer.",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./pg": "./dist/pg-store.js",
-    "./compat/workflow": "./dist/compat/workflow.js",
-    "./compat/api": "./dist/compat/api.js",
-    "./compat/next": "./dist/compat/next.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./pg": {
+      "types": "./dist/pg-store.d.ts",
+      "default": "./dist/pg-store.js"
+    },
+    "./compat/workflow": {
+      "types": "./dist/compat/workflow.d.ts",
+      "default": "./dist/compat/workflow.js"
+    },
+    "./compat/api": {
+      "types": "./dist/compat/api.d.ts",
+      "default": "./dist/compat/api.js"
+    },
+    "./compat/next": {
+      "types": "./dist/compat/next.d.ts",
+      "default": "./dist/compat/next.js"
+    }
   },
   "files": [
     "dist",