flingit 0.0.63 → 0.0.65

package/node_modules/flingflow/test/context.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { buildContext } from "../src/context.js";
+import { MemoryEventStore } from "../src/store-memory.js";
+import type { EventStore } from "../src/store.js";
+import type { WorkflowConfig } from "../src/types.js";
+import { noSim } from "./fixtures.js";
+
+const TEST_CONFIG: WorkflowConfig = { maxAttempts: 5, initialBackoffMS: 1000, backoffMultiplier: 2, maxBackoffMS: 60_000, stepTimeoutMS: 300_000 };
+
+describe("buildContext", () => {
+  let store: EventStore;
+
+  beforeEach(async () => {
+    store = new MemoryEventStore();
+    (await store.initialize())._unsafeUnwrap();
+  });
+
+  it("provides initial writes in scratchpad", async () => {
+    const { ctx } = (await buildContext(store, "run-1", "wf-1", "start", { userId: 42 }, noSim))._unsafeUnwrap();
+    expect(await ctx.get("userId")).toBe(42);
+    expect(ctx.workflowId).toBe("wf-1");
+    expect(ctx.runId).toBe("run-1");
+    expect(ctx.step).toBe("start");
+  });
+
+  it("reads scratchpad from step_completed events", async () => {
+    (await store.appendBatch([
+      { run_id: "run-1", workflow_id: "wf-1", seq: 0, event_type: "workflow_created", payload: { workflowName: "test", writes: {}, config: TEST_CONFIG }, created_at: 1000 },
+      { run_id: "run-1", workflow_id: "wf-1", seq: 1, event_type: "step_started", payload: { step: "start", attempt: 1 }, created_at: 1001 },
+      { run_id: "run-1", workflow_id: "wf-1", seq: 2, event_type: "step_completed", payload: { step: "start", writes: { user: { name: "Alice" } }, next_step: "two" }, created_at: 1002 },
+    ], noSim))._unsafeUnwrap();
+
+    const { ctx } = (await buildContext(store, "run-1", "wf-1", "two", {}, noSim))._unsafeUnwrap();
+    expect(await ctx.get("user")).toEqual({ name: "Alice" });
+  });
+
+  it("later writes override earlier ones", async () => {
+    (await store.appendBatch([
+      { run_id: "run-1", workflow_id: "wf-1", seq: 0, event_type: "workflow_created", payload: { workflowName: "test", writes: {}, config: TEST_CONFIG }, created_at: 1000 },
+      { run_id: "run-1", workflow_id: "wf-1", seq: 1, event_type: "step_started", payload: { step: "start", attempt: 1 }, created_at: 1001 },
+      { run_id: "run-1", workflow_id: "wf-1", seq: 2, event_type: "step_completed", payload: { step: "start", writes: { val: "old" }, next_step: "two" }, created_at: 1002 },
+      { run_id: "run-1", workflow_id: "wf-1", seq: 3, event_type: "step_started", payload: { step: "two", attempt: 1 }, created_at: 1003 },
+      { run_id: "run-1", workflow_id: "wf-1", seq: 4, event_type: "step_completed", payload: { step: "two", writes: { val: "new" }, next_step: "three" }, created_at: 1004 },
+    ], noSim))._unsafeUnwrap();
+
+    const { ctx } = (await buildContext(store, "run-1", "wf-1", "three", {}, noSim))._unsafeUnwrap();
+    expect(await ctx.get("val")).toBe("new");
+  });
+
+  it("returns undefined for missing keys", async () => {
+    const { ctx } = (await buildContext(store, "run-1", "wf-1", "start", {}, noSim))._unsafeUnwrap();
+    expect(await ctx.get("nonexistent")).toBeUndefined();
+  });
+
+  it("buffers writes without persisting", async () => {
+    const { ctx, getPendingWrites } = (await buildContext(store, "run-1", "wf-1", "start", {}, noSim))._unsafeUnwrap();
+    ctx.set("key1", "value1");
+    ctx.set("key2", "value2");
+
+    expect(getPendingWrites()).toEqual({ key1: "value1", key2: "value2" });
+    // Store should have no events
+    const events = (await store.getAllEvents("run-1", noSim))._unsafeUnwrap();
+    expect(events).toHaveLength(0);
+  });
+
+  it("pending writes are readable via get", async () => {
+    const { ctx } = (await buildContext(store, "run-1", "wf-1", "start", {}, noSim))._unsafeUnwrap();
+    ctx.set("myKey", 123);
+    expect(await ctx.get("myKey")).toBe(123);
+  });
+
+  it("pending writes override scratchpad values", async () => {
+    (await store.appendBatch([
+      { run_id: "run-1", workflow_id: "wf-1", seq: 0, event_type: "workflow_created", payload: { workflowName: "test", writes: {}, config: TEST_CONFIG }, created_at: 1000 },
+      { run_id: "run-1", workflow_id: "wf-1", seq: 1, event_type: "step_started", payload: { step: "start", attempt: 1 }, created_at: 1001 },
+      { run_id: "run-1", workflow_id: "wf-1", seq: 2, event_type: "step_completed", payload: { step: "start", writes: { x: "from-store" }, next_step: "two" }, created_at: 1002 },
+    ], noSim))._unsafeUnwrap();
+
+    const { ctx } = (await buildContext(store, "run-1", "wf-1", "two", {}, noSim))._unsafeUnwrap();
+    expect(await ctx.get("x")).toBe("from-store");
+    ctx.set("x", "overridden");
+    expect(await ctx.get("x")).toBe("overridden");
+  });
+
+  it("empty scratchpad when no step_completed events exist", async () => {
+    (await store.append({
+      run_id: "run-1", workflow_id: "wf-1", seq: 0, event_type: "workflow_created",
+      payload: { workflowName: "test", writes: {}, config: TEST_CONFIG }, created_at: 1000,
+    }, noSim))._unsafeUnwrap();
+
+    const { ctx } = (await buildContext(store, "run-1", "wf-1", "start", {}, noSim))._unsafeUnwrap();
+    expect(await ctx.get("anything")).toBeUndefined();
+  });
+});

package/node_modules/flingflow/test/engine.test.ts

@@ -0,0 +1,362 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Engine, UnknownWorkflowError } from "../src/engine.js";
+import { MemoryEventStore } from "../src/store-memory.js";
+import { WorkflowRegistry } from "../src/registry.js";
+import { ManualClock } from "../src/clock.js";
+import { WorkflowAlreadyActiveError, type EventStore } from "../src/store.js";
+import {
+  noSim,
+  singleStepWorkflow,
+  multiStepWorkflow,
+  failingWorkflow,
+  failOnceWorkflow,
+  nonRetryableWorkflow,
+  resetFailOnceCounter,
+} from "./fixtures.js";
+
+describe("Engine", () => {
+  let store: EventStore;
+  let registry: WorkflowRegistry;
+  let clock: ManualClock;
+  let engine: Engine;
+  let idCounter: number;
+
+  beforeEach(async () => {
+    store = new MemoryEventStore();
+    (await store.initialize())._unsafeUnwrap();
+    registry = new WorkflowRegistry();
+    clock = new ManualClock(1000);
+    idCounter = 0;
+
+    engine = new Engine({
+      store,
+      registry,
+      clock,
+      generateId: () => `run-${++idCounter}`,
+    });
+
+    registry.register({ name: "single-step", fn: singleStepWorkflow });
+    registry.register({ name: "multi-step", fn: multiStepWorkflow });
+    registry.register({ name: "always-fails", fn: failingWorkflow, maxAttempts: 3, initialBackoffMS: 0 });
+    registry.register({ name: "fail-once", fn: failOnceWorkflow, maxAttempts: 3, initialBackoffMS: 0 });
+    registry.register({ name: "non-retryable", fn: nonRetryableWorkflow });
+
+    resetFailOnceCounter();
+  });
+
+  describe("createWorkflow", () => {
+    it("creates a workflow_created event", async () => {
+      const result = await engine.createWorkflow("wf-single", "single-step", { value: "hello" }, noSim);
+      expect(result.isOk()).toBe(true);
+      const runId = result._unsafeUnwrap();
+      expect(runId).toBe("run-1");
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      expect(events).toHaveLength(1);
+      expect(events[0].event_type).toBe("workflow_created");
+      expect(events[0].payload).toEqual({ workflowName: "single-step", writes: { value: "hello" }, config: { maxAttempts: 5, initialBackoffMS: 1000, backoffMultiplier: 2, maxBackoffMS: 60_000, stepTimeoutMS: 300_000 } });
+      expect(events[0].seq).toBe(0);
+      expect(events[0].created_at).toBe(1000);
+      expect(events[0].run_id).toBe("run-1");
+      expect(events[0].workflow_id).toBe("wf-single");
+    });
+
+    it("rejects unknown workflow names", async () => {
+      const result = await engine.createWorkflow("wf-unknown", "unknown", {}, noSim);
+      expect(result.isErr()).toBe(true);
+      expect(result._unsafeUnwrapErr()).toBeInstanceOf(UnknownWorkflowError);
+    });
+  });
+
+  describe("claimStep", () => {
+    it("claims the first step after workflow_created", async () => {
+      const runId = (await engine.createWorkflow("wf-multi", "multi-step", { items: ["a", "b"] }, noSim))._unsafeUnwrap();
+      const claim = (await engine.claimStep(runId, noSim))._unsafeUnwrap();
+
+      expect(claim).not.toBeNull();
+      expect(claim!.step).toBe("start");
+      expect(claim!.attempt).toBe(1);
+      expect(claim!.workflowName).toBe("multi-step");
+      expect(claim!.initialWrites).toEqual({ items: ["a", "b"] });
+      expect(claim!.workflowId).toBe("wf-multi");
+      expect(claim!.runId).toBe(runId);
+      expect(claim!.config).toEqual({ maxAttempts: 5, initialBackoffMS: 1000, backoffMultiplier: 2, maxBackoffMS: 60_000, stepTimeoutMS: 300_000 });
+    });
+
+    it("returns null for non-existent workflow", async () => {
+      const claim = (await engine.claimStep("nonexistent", noSim))._unsafeUnwrap();
+      expect(claim).toBeNull();
+    });
+
+    it("returns null when step is already in progress", async () => {
+      const runId = (await engine.createWorkflow("wf-single", "single-step", { value: "x" }, noSim))._unsafeUnwrap();
+      const claim1 = (await engine.claimStep(runId, noSim))._unsafeUnwrap();
+      expect(claim1).not.toBeNull();
+
+      // Second claim should fail (step_started is the last event)
+      const claim2 = (await engine.claimStep(runId, noSim))._unsafeUnwrap();
+      expect(claim2).toBeNull();
+    });
+
+    it("transitions to workflow_failed on non-retryable step_failed", async () => {
+      const runId = (await engine.createWorkflow("wf-nonretry", "non-retryable", {}, noSim))._unsafeUnwrap();
+      (await engine.executeStep(runId, noSim))._unsafeUnwrap();
+
+      // step_failed with retryable=false was recorded
+      // claimStep should transition to workflow_failed
+      const claim = (await engine.claimStep(runId, noSim))._unsafeUnwrap();
+      expect(claim).toBeNull();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      const lastEvent = events[events.length - 1];
+      expect(lastEvent.event_type).toBe("workflow_failed");
+    });
+  });
+
+  describe("executeStep", () => {
+    it("single-step happy path", async () => {
+      const runId = (await engine.createWorkflow("wf-single", "single-step", { value: "test" }, noSim))._unsafeUnwrap();
+      const ran = (await engine.executeStep(runId, noSim))._unsafeUnwrap();
+      expect(ran).toBe(true);
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      expect(events.map(e => e.event_type)).toEqual([
+        "workflow_created",
+        "step_started",
+        "step_completed",
+        "workflow_completed",
+      ]);
+
+      const completed = events.find(e => e.event_type === "workflow_completed");
+      expect((completed!.payload as any).result).toEqual({ value: "processed-test" });
+    });
+
+    it("returns false when nothing to execute", async () => {
+      const runId = (await engine.createWorkflow("wf-single", "single-step", { value: "x" }, noSim))._unsafeUnwrap();
+      (await engine.executeStep(runId, noSim))._unsafeUnwrap();
+
+      // Already completed, nothing more to do
+      const ran = (await engine.executeStep(runId, noSim))._unsafeUnwrap();
+      expect(ran).toBe(false);
+    });
+  });
+
+  describe("runToCompletion", () => {
+    it("multi-step workflow with scratchpad", async () => {
+      const runId = (await engine.createWorkflow("wf-multi", "multi-step", { items: ["a", "b", "c"] }, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      expect(events.map(e => e.event_type)).toEqual([
+        "workflow_created",
+        "step_started",     // start
+        "step_completed",   // start -> process
+        "step_started",     // process
+        "step_completed",   // process -> finish
+        "step_started",     // finish
+        "step_completed",   // finish (done)
+        "workflow_completed",
+      ]);
+
+      const completed = events.find(e => e.event_type === "workflow_completed");
+      expect((completed!.payload as any).result).toEqual({ doubled: 6 });
+    });
+  });
+
+  describe("retries", () => {
+    it("retries on retryable failure", async () => {
+      const runId = (await engine.createWorkflow("wf-failonce", "fail-once", {}, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      expect(events.map(e => e.event_type)).toEqual([
+        "workflow_created",
+        "step_started",     // attempt 1
+        "step_failed",      // transient failure
+        "step_started",     // attempt 2
+        "step_completed",
+        "workflow_completed",
+      ]);
+
+      // Check attempt numbers
+      const starts = events.filter(e => e.event_type === "step_started");
+      expect((starts[0].payload as any).attempt).toBe(1);
+      expect((starts[1].payload as any).attempt).toBe(2);
+    });
+
+    it("max attempts exceeded → workflow_failed", async () => {
+      const runId = (await engine.createWorkflow("wf-alwaysfails", "always-fails", {}, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      const types = events.map(e => e.event_type);
+
+      // 3 attempts (maxAttempts=3), then workflow_failed
+      expect(types).toEqual([
+        "workflow_created",
+        "step_started",    // attempt 1
+        "step_failed",
+        "step_started",    // attempt 2
+        "step_failed",
+        "step_started",    // attempt 3
+        "step_failed",
+        "workflow_failed",
+      ]);
+
+      const failed = events.find(e => e.event_type === "workflow_failed");
+      expect((failed!.payload as any).reason).toContain("max attempts (3) exceeded");
+      expect((failed!.payload as any).cause).toBe("max_attempts_exceeded");
+    });
+
+    it("non-retryable failure → immediate workflow_failed", async () => {
+      const runId = (await engine.createWorkflow("wf-nonretry", "non-retryable", {}, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      expect(events.map(e => e.event_type)).toEqual([
+        "workflow_created",
+        "step_started",
+        "step_failed",
+        "workflow_failed",
+      ]);
+
+      const stepFailed = events.find(e => e.event_type === "step_failed");
+      expect((stepFailed!.payload as any).retryable).toBe(false);
+      expect((stepFailed!.payload as any).reason).toBe("invalid input");
+
+      const wfFailed = events.find(e => e.event_type === "workflow_failed");
+      expect((wfFailed!.payload as any).cause).toBe("non_retryable");
+    });
+  });
+
+  describe("event log validity", () => {
+    it("all events have ascending seq numbers", async () => {
+      const runId = (await engine.createWorkflow("wf-multi", "multi-step", { items: ["a"] }, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      for (let i = 0; i < events.length; i++) {
+        expect(events[i].seq).toBe(i);
+      }
+    });
+
+    it("all events have the same run_id", async () => {
+      const runId = (await engine.createWorkflow("wf-multi", "multi-step", { items: ["a"] }, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      for (const event of events) {
+        expect(event.run_id).toBe(runId);
+      }
+    });
+
+    it("all events have the same workflow_id", async () => {
+      const runId = (await engine.createWorkflow("wf-multi", "multi-step", { items: ["a"] }, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      for (const event of events) {
+        expect(event.workflow_id).toBe("wf-multi");
+      }
+    });
+
+    it("created_at values come from the clock", async () => {
+      clock.set(5000);
+      const runId = (await engine.createWorkflow("wf-single", "single-step", { value: "x" }, noSim))._unsafeUnwrap();
+      clock.advance(100);
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      expect(events[0].created_at).toBe(5000); // workflow_created
+      for (const event of events.slice(1)) {
+        expect(event.created_at).toBe(5100); // all others at clock=5100
+      }
+    });
+
+    it("event trace follows valid state machine transitions", async () => {
+      const runId = (await engine.createWorkflow("wf-failonce", "fail-once", {}, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+      const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+      const validTransitions: Record<string, string[]> = {
+        workflow_created: ["step_started"],
+        step_started: ["step_completed", "step_failed"],
+        step_completed: ["step_started", "workflow_completed"],
+        step_failed: ["step_started", "workflow_failed"],
+      };
+
+      for (let i = 0; i < events.length - 1; i++) {
+        const from = events[i].event_type;
+        const to = events[i + 1].event_type;
+        expect(
+          validTransitions[from],
+          `No valid transitions from ${from}`,
+        ).toBeDefined();
+        expect(
+          validTransitions[from],
+          `Invalid transition: ${from} → ${to} at seq ${i}→${i + 1}`,
+        ).toContain(to);
+      }
+    });
+  });
+
+  describe("workflow ID uniqueness", () => {
+    it("rejects duplicate active workflow ID", async () => {
+      const result1 = await engine.createWorkflow("wf-dup", "single-step", { value: "a" }, noSim);
+      expect(result1.isOk()).toBe(true);
+
+      const result2 = await engine.createWorkflow("wf-dup", "single-step", { value: "b" }, noSim);
+      expect(result2.isErr()).toBe(true);
+      expect(result2._unsafeUnwrapErr()).toBeInstanceOf(WorkflowAlreadyActiveError);
+    });
+
+    it("allows reuse of workflow ID after completion", async () => {
+      const runId1 = (await engine.createWorkflow("wf-reuse", "single-step", { value: "first" }, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId1, noSim))._unsafeUnwrap();
+
+      // Workflow completed, so we can reuse the workflow ID
+      const result2 = await engine.createWorkflow("wf-reuse", "single-step", { value: "second" }, noSim);
+      expect(result2.isOk()).toBe(true);
+    });
+
+    it("allows reuse of workflow ID after failure", async () => {
+      const runId1 = (await engine.createWorkflow("wf-reuse-fail", "non-retryable", {}, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId1, noSim))._unsafeUnwrap();
+
+      // Workflow failed, so we can reuse the workflow ID
+      const result2 = await engine.createWorkflow("wf-reuse-fail", "single-step", { value: "retry" }, noSim);
+      expect(result2.isOk()).toBe(true);
+    });
+
+    it("different workflow IDs coexist", async () => {
+      const result1 = await engine.createWorkflow("wf-a", "single-step", { value: "a" }, noSim);
+      const result2 = await engine.createWorkflow("wf-b", "single-step", { value: "b" }, noSim);
+
+      expect(result1.isOk()).toBe(true);
+      expect(result2.isOk()).toBe(true);
+
+      const runId1 = result1._unsafeUnwrap();
+      const runId2 = result2._unsafeUnwrap();
+      expect(runId1).not.toBe(runId2);
+
+      (await engine.runToCompletion(runId1, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId2, noSim))._unsafeUnwrap();
+
+      const events1 = (await store.getAllEvents(runId1, noSim))._unsafeUnwrap();
+      const events2 = (await store.getAllEvents(runId2, noSim))._unsafeUnwrap();
+      expect(events1[events1.length - 1].event_type).toBe("workflow_completed");
+      expect(events2[events2.length - 1].event_type).toBe("workflow_completed");
+    });
+
+    it("successive runs of same workflow ID get different run IDs", async () => {
+      const runId1 = (await engine.createWorkflow("wf-successive", "single-step", { value: "first" }, noSim))._unsafeUnwrap();
+      (await engine.runToCompletion(runId1, noSim))._unsafeUnwrap();
+
+      const runId2 = (await engine.createWorkflow("wf-successive", "single-step", { value: "second" }, noSim))._unsafeUnwrap();
+
+      expect(runId1).not.toBe(runId2);
+      expect(runId1).toBe("run-1");
+      expect(runId2).toBe("run-2");
+    });
+  });
+});

package/node_modules/flingflow/test/fixtures.ts

@@ -0,0 +1,58 @@
+import { NoSimulationTask } from "determined";
+import { NonRetryableError, type Continuation, type Ctx, type WorkflowFn } from "../src/types.js";
+
+export const noSim = new NoSimulationTask("test", false);
+
+// Single-step workflow that completes immediately
+export const singleStepWorkflow: WorkflowFn = async (ctx: Ctx): Promise<Continuation> => {
+  const value = await ctx.get("value") as string;
+  ctx.set("result", `processed-${value}`);
+  return { done: true, result: { value: `processed-${value}` } };
+};
+
+// Multi-step workflow that uses scratchpad
+export const multiStepWorkflow: WorkflowFn = async (ctx: Ctx): Promise<Continuation> => {
+  switch (ctx.step) {
+    case "start": {
+      const items = await ctx.get("items") as string[];
+      ctx.set("count", items.length);
+      return { step: "process" };
+    }
+    case "process": {
+      const count = await ctx.get("count") as number;
+      ctx.set("doubled", count * 2);
+      return { step: "finish" };
+    }
+    case "finish": {
+      const doubled = await ctx.get("doubled") as number;
+      return { done: true, result: { doubled } };
+    }
+    default:
+      throw new Error(`Unknown step: ${ctx.step}`);
+  }
+};
+
+// Workflow that always fails (retryable)
+export const failingWorkflow: WorkflowFn = async (_ctx: Ctx): Promise<Continuation> => {
+  throw new Error("transient failure");
+};
+
+// Workflow that fails then succeeds on retry
+let failOnceCounter = new Map<string, number>();
+export function resetFailOnceCounter(): void { failOnceCounter = new Map(); }
+
+export const failOnceWorkflow: WorkflowFn = async (ctx: Ctx): Promise<Continuation> => {
+  const key = ctx.runId;
+  const attempts = (failOnceCounter.get(key) ?? 0) + 1;
+  failOnceCounter.set(key, attempts);
+
+  if (attempts === 1) {
+    throw new Error("transient failure");
+  }
+  return { done: true, result: { attempts } };
+};
+
+// Non-retryable failure workflow
+export const nonRetryableWorkflow: WorkflowFn = async (_ctx: Ctx): Promise<Continuation> => {
+  throw new NonRetryableError("invalid input");
+};