@hasna/workflows 0.1.0 → 0.1.2

package/types/store.d.ts

@@ -0,0 +1,86 @@
+export declare const RUN_STATUSES: readonly ["pending", "running", "completed", "failed", "cancelled", "interrupted"];
+export type RunStatus = (typeof RUN_STATUSES)[number];
+export declare const NODE_STATUSES: readonly ["pending", "running", "completed", "failed", "skipped"];
+export type NodeStatus = (typeof NODE_STATUSES)[number];
+export interface RunRow {
+    id: string;
+    graphName: string;
+    graphVersion: string;
+    status: RunStatus;
+    attempts: number;
+    contextJson: string;
+    resultJson: string | null;
+    error: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface RunNodeRow {
+    id: string;
+    runId: string;
+    nodeId: string;
+    status: NodeStatus;
+    attempts: number;
+    lane: string | null;
+    exitCode: number | null;
+    outputJson: string | null;
+    error: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export interface MemoRow {
+    key: string;
+    graphName: string;
+    nodeId: string;
+    inputHash: string;
+    outputJson: string;
+    hitCount: number;
+    createdAt: string;
+}
+export interface CreateRunInput {
+    graphName: string;
+    graphVersion: string;
+    context?: unknown;
+}
+export interface CreateRunNodeInput {
+    runId: string;
+    nodeId: string;
+    lane?: string;
+}
+export interface WorkflowsStore {
+    close(): void;
+    listTables(): string[];
+    createRun(input: CreateRunInput): RunRow;
+    getRun(id: string): RunRow | undefined;
+    listRuns(opts?: {
+        status?: RunStatus;
+        limit?: number;
+    }): RunRow[];
+    setRunStatus(id: string, status: RunStatus, patch?: {
+        result?: unknown;
+        error?: string | null;
+        startedAt?: string;
+        finishedAt?: string;
+    }): void;
+    /** Persist the run's durable execution state (the engine's cursor + steps). */
+    setRunContext(id: string, context: unknown): void;
+    bumpAttempts(id: string): void;
+    createRunNode(input: CreateRunNodeInput): RunNodeRow;
+    getRunNode(id: string): RunNodeRow | undefined;
+    listRunNodes(runId: string): RunNodeRow[];
+    setRunNodeStatus(id: string, status: NodeStatus, patch?: {
+        exitCode?: number | null;
+        output?: unknown;
+        error?: string | null;
+        startedAt?: string;
+        finishedAt?: string;
+    }): void;
+    bumpAttemptsNode(id: string): void;
+    memoPut(key: string, graphName: string, nodeId: string, inputHash: string, outputJson: string): void;
+    memoGet(key: string): MemoRow | undefined;
+    memoHit(key: string): void;
+    memoList(): MemoRow[];
+    memoClear(): void;
+}
+export declare function openStore(dataDir: string): WorkflowsStore;

package/types/wal.d.ts

@@ -0,0 +1,85 @@
+import type { WorkflowGraph } from "./graph.js";
+export interface ClaimOp {
+    op: "claim_acquired";
+    runId: string;
+    worker: string;
+    expiresAt: string;
+    fencing: number;
+    at: string;
+}
+export interface ReleaseOp {
+    op: "claim_released";
+    runId: string;
+    fencing: number;
+    at: string;
+}
+export interface GraphRegisteredOp {
+    op: "graph_registered";
+    name: string;
+    version: string;
+    graph: WorkflowGraph;
+    at: string;
+}
+export type WalOp = {
+    op: "run_started";
+    runId: string;
+    at: string;
+} | {
+    op: "run_finished";
+    runId: string;
+    status: string;
+    at: string;
+} | {
+    op: "node_started";
+    runId: string;
+    nodeId: string;
+    at: string;
+} | {
+    op: "node_finished";
+    runId: string;
+    nodeId: string;
+    status: string;
+    at: string;
+} | {
+    op: "memo_set";
+    key: string;
+    at: string;
+} | GraphRegisteredOp | ClaimOp | ReleaseOp;
+export interface WalEntry {
+    seq: number;
+    at: string;
+    checksum: string;
+    op: WalOp;
+}
+export interface LiveClaim {
+    worker: string;
+    fencing: number;
+    expiresAtMs: number;
+}
+export interface WalReplay {
+    entries: WalEntry[];
+    /** True when the file contained a torn tail (partial or corrupt line). */
+    torn: boolean;
+    /** True when the torn tail was truncated away. */
+    repaired: boolean;
+    /** Reconstructed live claims from claim_acquired/claim_released pairs. */
+    liveClaims(nowMs?: number): Map<string, LiveClaim>;
+}
+export declare const WAL_FILE_NAME = "session.wal";
+/** The data-dir layout is workflows/ + sessions/ + workflows.db (owner spec):
+ * session WALs live under sessions/, workflow graph files under workflows/. */
+export declare const SESSIONS_DIR_NAME = "sessions";
+export declare class SessionWAL {
+    readonly filePath: string;
+    private constructor();
+    static open(dataDir: string): SessionWAL;
+    static openAt(filePath: string): SessionWAL;
+    /** Append one op and return the persisted entry (seq is 1-based). */
+    append(op: WalOp): WalEntry;
+    private nextSeq;
+    /** Read and verify the whole WAL; truncate the first torn tail. */
+    replay(): WalReplay;
+    close(): void;
+}
+/** Write a fresh (empty) WAL — used by tests and by init. */
+export declare function resetWal(filePath: string): void;