flingit 0.0.63 → 0.0.65

package/node_modules/flingflow/README.md

@@ -0,0 +1,679 @@
+# flingflow
+
+A durable execution engine using explicit continuations and event sourcing. Workflows are functions that receive the current step and return a continuation describing what to do next. All state is persisted as an append-only event log in SQLite.
+
+## Install
+
+```
+npm install
+```
+
+## Quick Start
+
+```typescript
+import {
+  Engine,
+  MemoryEventStore,
+  WorkflowRegistry,
+  type Ctx,
+  type Continuation,
+} from "flingflow";
+import { NoSimulationTask } from "determined";
+
+const noSim = new NoSimulationTask("app", false);
+
+// 1. Define a workflow
+const registry = new WorkflowRegistry();
+registry.register({
+  name: "onboarding",
+  fn: async (ctx: Ctx): Promise<Continuation> => {
+    switch (ctx.step) {
+      case "start": {
+        const input = await ctx.get("input");
+        const user = await getUser(input.userId);
+        ctx.set("user", user);
+        return { step: "send-email" };
+      }
+      case "send-email": {
+        const user = await ctx.get("user");
+        await sendWelcomeEmail(user.email);
+        return { done: true, result: { sent: true } };
+      }
+    }
+  },
+});
+
+// 2. Create the engine
+const store = new MemoryEventStore();
+const engine = new Engine({ store, registry });
+(await engine.initialize())._unsafeUnwrap();
+
+// 3. Run a workflow
+const runId = (await engine.createWorkflow("onboarding-wf", "onboarding", { userId: 42 }, noSim))._unsafeUnwrap();
+(await engine.runToCompletion(runId, noSim))._unsafeUnwrap();
+
+// 4. Inspect the event log
+const events = (await store.getAllEvents(runId, noSim))._unsafeUnwrap();
+```
+
+## Design
+
+### Explicit Continuations
+
+Each workflow step is a fresh function invocation. The function receives a `Ctx` with the current step name and a scratchpad for passing data between steps. The original input is available via `ctx.get()` (it is written to the scratchpad at workflow creation). It returns a `Continuation` that either names the next step or marks the workflow as done.
+
+There are no determinism constraints — each step can call `Math.random()`, `Date.now()`, fetch live data, whatever it wants.
+
+### Dual IDs
+
+Each workflow has two distinct IDs:
+
+- **Workflow ID** — user-provided logical identity. Only one active run per workflow ID at a time.
+- **Run ID** — system-generated UUID, globally unique across all runs.
+
+This allows workflows to be restarted (new run ID) while preserving the logical identity (same workflow ID). The `appendIfNoActiveWorkflow` store method enforces the uniqueness constraint atomically.
+
+### Event Sourcing
+
+All state is stored as an immutable, append-only event log. The current state of a workflow is derived from its last event. Concurrent workers coordinate via optimistic concurrency: the unique constraint on `(run_id, seq)` ensures exactly one writer wins per sequence number.
+
+### Error Handling
+
+Framework code never throws. All errors are returned as `neverthrow` `Result` values. Workflow functions throw (caught immediately by the engine). The only exceptions are programming errors (e.g., duplicate workflow registration).
+
+### State Machine
+
+```
+workflow_created → step_started → step_completed → step_started → ... → workflow_completed
+                                 → step_failed   → step_started (retry)
+                                                  → workflow_failed (max attempts / non-retryable)
+```
+
+Valid transitions:
+
+| Last Event | Can Be Followed By |
+|---|---|
+| `workflow_created` | `step_started` |
+| `step_started` | `step_completed`, `step_failed` |
+| `step_completed` (has `next_step`) | `step_started` |
+| `step_completed` (no `next_step`) | `workflow_completed` |
+| `step_failed` (retryable, under max) | `step_started` |
+| `step_failed` (not retryable or at max) | `workflow_failed` |
+| `workflow_completed` | *(terminal)* |
+| `workflow_failed` | *(terminal)* |
+
+---
+
+## API Reference
+
+### Types
+
+#### `Continuation`
+
+Returned by workflow functions to describe what happens next.
+
+```typescript
+type Continuation =
+  | { step: string }              // continue to next step
+  | { done: true; result: unknown }  // workflow complete
+```
+
+#### `Ctx`
+
+The context object passed to every workflow step invocation.
+
+```typescript
+type Ctx = {
+  workflowId: string;                       // user-provided logical workflow identity
+  runId: string;                             // system-generated unique run ID
+  step: string;                              // current step name
+  sim: SimulationTask;                       // simulation task for failpoints/checkpoints
+  get(key: string): Promise<unknown>;        // read from scratchpad
+  set(key: string, value: unknown): void;    // buffer a write to scratchpad
+};
+```
+
+- `get()` checks pending (buffered) writes first, then falls back to persisted scratchpad values. Returns `undefined` for missing keys.
+- `set()` buffers a write in memory. Buffered writes are persisted atomically when the step completes successfully. If the step fails, all buffered writes are discarded.
+- `sim` is the `SimulationTask` from the `determined` package. Workflow functions can pass it to external services for failpoint injection during simulation testing.
+
+#### `WorkflowFn`
+
+```typescript
+type WorkflowFn = (ctx: Ctx) => Promise<Continuation>;
+```
+
+A workflow function. Receives the context for the current step and returns a continuation. Typically implemented as a `switch` on `ctx.step`.
+
+#### `WorkflowEvent`
+
+A discriminated union over `event_type`. Every event has:
+
+```typescript
+{
+  run_id: string;        // system-generated unique run ID
+  workflow_id: string;   // user-provided logical workflow identity
+  seq: number;           // sequence number (0-based, ascending)
+  event_type: string;    // discriminant
+  payload: ...;          // typed per event_type
+  created_at: number;    // epoch ms from the injected Clock
+}
+```
+
+Event types and their payloads:
+
+| `event_type` | Payload Type |
+|---|---|
+| `"workflow_created"` | `{ workflowName: string; writes: Record<string, unknown>; config: { maxAttempts, initialBackoffMS, backoffMultiplier, maxBackoffMS, stepTimeoutMS } }` |
+| `"step_started"` | `{ step: string; attempt: number }` |
+| `"step_completed"` | `{ step: string; writes: Record<string, unknown>; next_step?: string }` |
+| `"step_failed"` | `{ step: string; attempt: number; reason: string; retryable: boolean }` |
+| `"workflow_completed"` | `{ result: unknown }` |
+| `"workflow_failed"` | `{ reason: string; cause: WorkflowFailureCause }` |
+
+#### `ClaimResult`
+
+Returned by `Engine.claimStep()` when a step is successfully claimed.
+
+```typescript
+type ClaimResult = {
+  workflowId: string;     // user-provided workflow ID
+  runId: string;           // system-generated run ID
+  workflowName: string;   // name of the registered workflow definition
+  step: string;           // step name to execute
+  attempt: number;        // attempt number (1-based)
+  seq: number;            // sequence number of the step_started event
+};
+```
+
+---
+
+### `WorkflowRegistry`
+
+Stores workflow definitions by name. Duplicate registration throws.
+
+```typescript
+import { WorkflowRegistry } from "flingflow";
+
+const registry = new WorkflowRegistry();
+```
+
+#### `registry.register(def)`
+
+Register a workflow definition. Throws if `name` is already registered.
+
+```typescript
+registry.register({
+  name: string;               // unique workflow name
+  fn: WorkflowFn;             // the workflow function
+  maxAttempts?: number;        // max attempts per step (default: 5)
+  initialBackoffMS?: number;   // delay after first failure in ms (default: 1000)
+  backoffMultiplier?: number;  // exponential multiplier (default: 2)
+  maxBackoffMS?: number;       // backoff cap in ms (default: 60000)
+  stepTimeoutMS?: number;      // step timeout in ms (default: 300000)
+});
+```
+
+#### `registry.get(name): WorkflowDefinition | undefined`
+
+Look up a workflow by name. Returns `undefined` if not registered.
+
+#### `registry.has(name): boolean`
+
+Check if a workflow name is registered.
+
+#### `WorkflowDefinition`
+
+```typescript
+interface WorkflowDefinition {
+  name: string;
+  fn: WorkflowFn;
+  maxAttempts: number;        // always populated (default: 5)
+  initialBackoffMS: number;   // always populated (default: 1000)
+  backoffMultiplier: number;  // always populated (default: 2)
+  maxBackoffMS: number;       // always populated (default: 60000)
+  stepTimeoutMS: number;      // always populated (default: 300000)
+}
+```
+
+---
+
+### `EventStore` Interface
+
+The persistence abstraction. All methods accept a `SimulationTask` for failpoint injection. Mutation methods return `Result` types; read methods return `Result` wrapping the data or an error.
+
+Event payloads are stored as JSON. This means `undefined` values are silently dropped, `Date` objects become strings, `NaN`/`Infinity` become `null`, and `bigint` values will throw. Keep payloads to JSON-safe primitive types and plain objects/arrays.
+
+```typescript
+interface EventStore {
+  initialize(): Promise<Result<void, Error>>;
+  append(event: WorkflowEvent, sim: SimulationTask): Promise<Result<void, AppendError>>;
+  appendBatch(events: WorkflowEvent[], sim: SimulationTask): Promise<Result<void, AppendError>>;
+  appendIfNoActiveWorkflow(workflowId: string, event: WorkflowEvent, sim: SimulationTask): Promise<Result<void, AppendIfNoActiveError>>;
+  getLastEvent(runId: string, sim: SimulationTask): Promise<Result<WorkflowEvent | null, Error>>;
+  getEvent(runId: string, seq: number, sim: SimulationTask): Promise<Result<WorkflowEvent | null, Error>>;
+  getCompletedEvents(runId: string, sim: SimulationTask): Promise<Result<WorkflowEvent[], Error>>;
+  getAllEvents(runId: string, sim: SimulationTask): Promise<Result<WorkflowEvent[], Error>>;
+  getActiveWorkflows(sim: SimulationTask): Promise<Result<WorkflowEvent[], Error>>;
+}
+```
+
+#### `initialize()`
+
+Create tables/indexes. Must be called before any other method. Returns `Result<void, Error>`.
+
+#### `append(event, sim)`
+
+Insert a single event. Returns `UniqueConstraintError` if `(run_id, seq)` already exists, or `WorkflowIdMismatchError` if the event's `workflow_id` doesn't match existing events for that `run_id`.
+
+#### `appendBatch(events, sim)`
+
+Insert multiple events atomically. If any event conflicts, the entire batch is rolled back. No partial inserts.
+
+#### `appendIfNoActiveWorkflow(workflowId, event, sim)`
+
+Atomically check that no active (non-terminal) run exists for the given `workflowId`, then insert the event. Returns `WorkflowAlreadyActiveError` if an active run exists.
+
+#### `getLastEvent(runId, sim)`
+
+Return the event with the highest `seq` for the given run, or `null` if the run doesn't exist.
+
+#### `getEvent(runId, seq, sim)`
+
+Return a specific event by `(run_id, seq)`, or `null` if not found.
+
+#### `getCompletedEvents(runId, sim)`
+
+Return all `step_completed` events for the run, ordered by `seq DESC` (newest first). Used to reconstruct the scratchpad.
+
+#### `getAllEvents(runId, sim)`
+
+Return all events for the run, ordered by `seq ASC`.
+
+#### `getActiveWorkflows(sim)`
+
+Return the last event for every run whose last event is not `workflow_completed` or `workflow_failed`. Used by recovery to find stuck or timed-out workflows.
+
+#### Error Types
+
+```typescript
+class UniqueConstraintError extends Error {
+  constructor(runId: string, seq: number);
+}
+
+class WorkflowAlreadyActiveError extends Error {
+  public readonly activeRunId: string;
+  constructor(workflowId: string, activeRunId: string);
+}
+
+class WorkflowIdMismatchError extends Error {
+  constructor(runId: string, expected: string, got: string);
+}
+```
+
+---
+
+### `MemoryEventStore`
+
+```typescript
+import { MemoryEventStore } from "flingflow";
+
+const store = new MemoryEventStore();
+(await store.initialize())._unsafeUnwrap();
+```
+
+An in-memory `EventStore` backed by `Map<string, Map<number, string>>`. All payloads are JSON-serialized and deserialized on storage and retrieval to match SQLite behavior and catch serialization bugs early.
+
+Suitable for tests and development. Data is lost when the process exits.
+
+---
+
+### `SqliteEventStore`
+
+```typescript
+import { SqliteEventStore } from "flingflow";
+
+// File-based SQLite
+const store = new SqliteEventStore("/path/to/db.sqlite");
+
+// In-memory SQLite
+const store = new SqliteEventStore(":memory:");
+
+// Bring your own better-sqlite3 Database instance
+import Database from "better-sqlite3";
+const db = new Database(":memory:");
+const store = new SqliteEventStore(db);
+
+(await store.initialize())._unsafeUnwrap();
+```
+
+A `better-sqlite3`-backed `EventStore`. Uses WAL journal mode for better concurrent read performance.
+
+Schema:
+
+```sql
+CREATE TABLE workflow_events (
+  run_id TEXT NOT NULL,
+  workflow_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  event_type TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (run_id, seq)
+);
+
+CREATE INDEX idx_workflow_events_last
+ON workflow_events(run_id, seq DESC);
+
+CREATE INDEX idx_workflow_events_workflow
+ON workflow_events(workflow_id);
+```
+
+#### `store.close()`
+
+Close the underlying SQLite database connection. Only available on `SqliteEventStore`, not on the `EventStore` interface.
+
+---
+
+### `Engine`
+
+The core orchestrator. Creates workflows, claims steps, executes workflow functions, and persists results. All methods return `Result` types — the engine never throws.
+
+```typescript
+import { Engine } from "flingflow";
+
+const engine = new Engine({
+  store: EventStore;               // required
+  registry: WorkflowRegistry;      // required
+  clock?: Clock;                   // default: SystemClock
+  generateId?: () => string;       // default: crypto.randomUUID()
+});
+```
+
+#### `engine.initialize()`
+
+```typescript
+await engine.initialize(): Promise<Result<void, Error>>
+```
+
+Delegates to `store.initialize()`. Call once at startup.
+
+#### `engine.createWorkflow(workflowId, name, writes, sim)`
+
+```typescript
+await engine.createWorkflow(
+  workflowId: string,
+  name: string,
+  writes: Record<string, unknown>,
+  sim: SimulationTask,
+): Promise<Result<string, CreateWorkflowError>>  // returns runId on success
+```
+
+Records a `workflow_created` event at `seq=0` with the provided `writes` as the initial scratchpad. Returns the system-generated `runId`. Does **not** start the first step — the caller drives execution via `executeStep` or `runToCompletion`.
+
+Returns `UnknownWorkflowError` if `name` is not registered. Returns `WorkflowAlreadyActiveError` if an active run already exists for this `workflowId`.
+
+Simulation checkpoints: before and after the store append.
+
+#### `engine.claimStep(runId, sim)`
+
+```typescript
+await engine.claimStep(
+  runId: string,
+  sim: SimulationTask,
+): Promise<Result<ClaimResult | null, Error>>
+```
+
+Reads the last event, computes the next transition using `resolveTransition`, and attempts to insert `step_started`:
+
+- **`start_step`**: inserts `step_started`, returns a `ClaimResult`.
+- **`none`**: returns `null` (step in progress or workflow is terminal).
+- **`complete_workflow`** / **`fail_workflow`**: returns an invariant-violation error (these transitions are unreachable — terminal events are always written atomically with the preceding step event).
+
+If the `step_started` insert fails with `UniqueConstraintError` (another worker won the race), the error is propagated — `executeStep` handles it as contention.
+
+Simulation checkpoints: after reading the last event, after the step_started append.
+
+#### `engine.executeStep(runId, sim)`
+
+```typescript
+await engine.executeStep(
+  runId: string,
+  sim: SimulationTask,
+): Promise<Result<boolean, Error>>
+```
+
+Claims a step, builds the context, runs the workflow function, and commits the result. This is the main single-step execution primitive.
+
+On success: commits `step_completed` (and `workflow_completed` if done) atomically via `appendBatch`.
+
+On failure (workflow function throws):
+- If the error is a `NonRetryableError`, records `step_failed` with `retryable: false`.
+- Otherwise, records `step_failed` with `retryable: true`.
+- If the failure is terminal (non-retryable or at max attempts), writes `step_failed` + `workflow_failed` atomically via `appendBatch`.
+
+Returns `true` if a step was claimed and executed (even if the step itself failed), or if contention occurred (another worker claimed the step — the workflow is still active). Returns `false` if nothing was claimable (workflow is done or no pending transitions).
+
+`UniqueConstraintError` from any store operation (claim contention, recovery overlap) is handled internally and returned as `ok(true)`.
+
+Simulation failpoints: before and after the workflow function call, before the commit append.
+
+#### `engine.runToCompletion(runId, sim)`
+
+```typescript
+await engine.runToCompletion(
+  runId: string,
+  sim: SimulationTask,
+): Promise<Result<void, Error>>
+```
+
+Calls `executeStep` in a loop until it returns `false`. Drives a workflow from its current state to a terminal state (`workflow_completed` or `workflow_failed`).
+
+---
+
+### `runRecovery(config, sim)`
+
+Scans for stuck and timed-out workflows and takes corrective action.
+
+```typescript
+import { runRecovery } from "flingflow";
+
+const result = await runRecovery({
+  store: EventStore;
+  registry: WorkflowRegistry;
+  clock: Clock;
+}, sim: SimulationTask);
+
+const recovered: RecoveryResult[] = result._unsafeUnwrap();
+```
+
+Returns an array of `RecoveryResult` objects describing what was found:
+
+```typescript
+interface RecoveryResult {
+  runId: string;
+  reason: RecoveryReason;
+}
+
+type RecoveryReason =
+  | "timeout"          // step_started exceeded stepTimeoutMS
+  | "stuck_created"    // workflow_created but no step ever started
+  | "stuck_completed"  // step_completed but next step never claimed
+  | "stuck_failed"     // step_failed (retryable) but retry never started
+  | "stuck_terminal";  // step should have been finalized but wasn't
+```
+
+Recovery logic for each active (non-terminal) workflow:
+
+| Last Event State | Action |
+|---|---|
+| `step_started` and elapsed >= `stepTimeoutMS` | Appends `step_failed` with `reason: "timeout"`, `retryable: true`. If at max attempts, also appends `workflow_failed` atomically. |
+| `step_started` and not timed out | Skipped (still in progress) |
+| `workflow_created`, `step_completed`, `step_failed` (retryable) | Reported as stuck (caller should drive via `executeStep`) |
+
+Simulation checkpoints: before `getActiveWorkflows`, per workflow.
+
+Typical usage pattern:
+
+```typescript
+const result = await runRecovery({ store, registry, clock }, noSim);
+if (result.isOk()) {
+  for (const r of result.value) {
+    await engine.executeStep(r.runId, noSim);
+  }
+}
+```
+
+---
+
+### `Clock`
+
+```typescript
+interface Clock {
+  now(): number;  // epoch ms
+}
+```
+
+All `created_at` timestamps on events are set explicitly from `clock.now()`. No SQLite defaults.
+
+#### `SystemClock`
+
+```typescript
+import { SystemClock } from "flingflow";
+const clock = new SystemClock();
+clock.now(); // Date.now()
+```
+
+Uses `Date.now()`. The default clock for `Engine`.
+
+#### `ManualClock`
+
+```typescript
+import { ManualClock } from "flingflow";
+
+const clock = new ManualClock(1000); // initial time: 1000ms
+clock.now();        // 1000
+clock.advance(500); // now() returns 1500
+clock.set(9999);    // now() returns 9999
+```
+
+For testing. Lets you control time to test timeout and recovery logic.
+
+---
+
+### `resolveTransition(lastEvent, maxAttempts)`
+
+```typescript
+import { resolveTransition } from "flingflow";
+
+const result: TransitionResult = resolveTransition(lastEvent, maxAttempts);
+```
+
+The centralized state machine transition function. Used internally by both `Engine.claimStep` and `runRecovery`. Exported for custom orchestration or testing.
+
+```typescript
+type TransitionResult =
+  | { action: "start_step"; step: string; attempt: number }
+  | { action: "complete_workflow" }
+  | { action: "fail_workflow"; reason: string }
+  | { action: "none" };
+```
+
+| Input (`lastEvent.event_type`) | Output |
+|---|---|
+| `workflow_created` | `{ action: "start_step", step: "start", attempt: 1 }` |
+| `step_completed` with `next_step` | `{ action: "start_step", step: next_step, attempt: 1 }` |
+| `step_completed` without `next_step` | `{ action: "complete_workflow" }` |
+| `step_failed`, retryable, `attempt < maxAttempts` | `{ action: "start_step", step, attempt: attempt + 1 }` |
+| `step_failed`, retryable, `attempt >= maxAttempts` | `{ action: "fail_workflow", reason: "max attempts (N) exceeded: ..." }` |
+| `step_failed`, non-retryable | `{ action: "fail_workflow", reason: "..." }` |
+| `step_started`, `workflow_completed`, `workflow_failed` | `{ action: "none" }` |
+
+---
+
+### `buildContext(store, runId, workflowId, step, sim)`
+
+```typescript
+import { buildContext } from "flingflow";
+
+const result = await buildContext(store, runId, workflowId, step, sim);
+const { ctx, getPendingWrites } = result._unsafeUnwrap();
+```
+
+Constructs a `Ctx` for a step execution. Eagerly loads the full scratchpad by scanning the `workflow_created` event's `writes` and all `step_completed` events (newest-first, first match per key wins).
+
+Returns a `Result` containing:
+- `ctx` — the `Ctx` object to pass to the workflow function.
+- `getPendingWrites()` — returns a snapshot of all buffered `ctx.set()` calls as `Record<string, unknown>`. Used by the engine to persist writes on step completion.
+
+---
+
+### Failure Handling
+
+#### Retryable Failures (default)
+
+Any `Error` thrown by a workflow function is recorded as `step_failed` with `retryable: true`. The engine retries with exponential backoff up to `maxAttempts` (default: 5). Backoff formula: attempt 1 = no delay, attempt N delay = min(initialBackoffMS * backoffMultiplier^(N-2), maxBackoffMS).
+
+#### Non-Retryable Failures
+
+Import `NonRetryableError` from flingflow and throw it:
+
+```typescript
+import { NonRetryableError } from "flingflow";
+
+throw new NonRetryableError("invalid input");
+```
+
+The engine records `step_failed` with `retryable: false` and immediately writes `workflow_failed` atomically in the same batch.
+
+#### Max Attempts Exceeded
+
+When a retryable step failure occurs at `attempt >= maxAttempts`, the engine writes `step_failed` + `workflow_failed` atomically via `appendBatch` with reason `"max attempts (N) exceeded: <last error>"`.
+
+---
+
+### Simulation Testing
+
+The engine integrates with the [`determined`](https://www.npmjs.com/package/determined) package for deterministic simulation testing. Every engine and store method accepts a `SimulationTask` parameter.
+
+- **Checkpoints** (`sim.checkpoint()`): placed at I/O boundaries (before/after store reads/writes). Lets `determined` interleave concurrent workers at these points.
+- **Failpoints** (`sim.failpoint()`): placed around workflow function calls and commit operations. Lets `determined` inject failures to test crash recovery.
+
+In production, pass a `NoSimulationTask`. In tests, use `SimulationImpl.runTasks()` to run multiple concurrent workers with controlled interleaving.
+
+```typescript
+import { SimulationImpl, SimpleEntropySource, type TaskSpec } from "determined";
+
+const sim = new SimulationImpl(logger, new SimpleEntropySource(), 0.3);
+
+await sim.runTasks([
+  { name: "worker-1", f: async (task) => { await engine.executeStep(runId, task); } },
+  { name: "worker-2", f: async (task) => { await engine.executeStep(runId, task); } },
+] as const);
+```
+
+---
+
+## File Structure
+
+```
+src/
+  types.ts           — Core types, discriminated union WorkflowEvent, NonRetryableError, re-exports from determined
+  clock.ts           — Clock interface, SystemClock, ManualClock
+  transitions.ts     — resolveTransition() state machine helper
+  store.ts           — EventStore interface, error types (UniqueConstraintError, WorkflowAlreadyActiveError, WorkflowIdMismatchError)
+  store-memory.ts    — In-memory EventStore (JSON round-trips payloads)
+  store-sqlite.ts    — better-sqlite3 EventStore
+  context.ts         — buildContext(): scratchpad loading + buffered writes
+  registry.ts        — WorkflowRegistry + WorkflowDefinition
+  engine.ts          — Engine class: createWorkflow, claimStep, executeStep, runToCompletion
+  recovery.ts        — runRecovery(): timeout detection, stuck workflow recovery
+  index.ts           — Barrel exports
+```
+
+## Spec Deviations
+
+- `workflow_created` payload includes `workflowName` (not in SPEC) — needed to look up the workflow function from the registry. It also includes `config` with the retry/backoff configuration sealed at creation time.
+- `created_at` stored as epoch ms integer (not DATETIME string) — always set from `clock.now()`, never from SQLite defaults.
+- `EventStore` has `getEvent(runId, seq)` — avoids fetching all events when only event 0 is needed.
+- `createWorkflow` does **not** auto-kick the first step (SPEC's trigger endpoint does) — keeps the engine pure and testable; the caller drives execution.