@multiplier-labs/stepflow 0.3.1 → 0.3.4

package/.codekin/reports/complexity/2026-04-03_complexity-report.md

@@ -0,0 +1,152 @@
+# Complexity Report: stepflow
+
+**Date**: 2026-04-03T20:01:36.000Z
+**Repository**: /srv/repos/stepflow
+**Branch**: main
+**Workflow Run**: ba52b549-8f86-4537-b95d-af7bbe803812
+**Session**: 456e9325-f315-4a53-8b5f-e02d09d44a08
+
+---
+
+Now I have sufficient data to produce the full report.
+
+## Summary
+
+**Overall Complexity Rating: Medium**
+
+The codebase is a TypeScript workflow orchestration library (~8,700 source lines across 19 source files, 14,600 including tests). It is well-structured overall, with clear module boundaries and good separation between execution, storage, scheduling, and events. The main complexity hotspots are: (1) `postgres.ts` at 1,354 lines — a large god class with dual interface implementations, (2) `orchestrator.ts:executeStep` — deeply nested retry/cancellation logic, and (3) an unresolved migration from a legacy `StorageAdapter` interface to a newer `WorkflowStorage` interface that introduces duplicated type hierarchies and dead code paths.
+
+- **Largest file**: `src/storage/postgres.ts` — 1,354 lines
+- **Deepest nesting**: `orchestrator.ts:executeStep` — ~4 levels in the retry/cancellation catch block
+- **Most complex function**: `executeStep` in `orchestrator.ts` — ~185 lines, retry loop, 4 error paths, 5+ storage/event calls per iteration
+
+---
+
+## Largest Files
+
+| File | Lines | Primary Responsibility | Refactor Priority |
+|------|-------|------------------------|-------------------|
+| `src/storage/postgres.ts` | 1,354 | PostgreSQL storage adapter (DDL + CRUD + extended API) | **High** |
+| `src/core/engine.ts` | 692 | WorkflowEngine class (registry, run lifecycle, queue) | Medium |
+| `src/storage/sqlite.ts` | 621 | SQLite storage adapter | Medium |
+| `src/planning/planner.ts` | 576 | Rule-based recipe selection and plan generation | Low |
+| `src/planning/types.ts` | 566 | Planning type definitions | Low |
+| `src/core/orchestrator.ts` | 564 | Workflow + step execution logic | **High** |
+| `src/events/webhook.ts` | 557 | Webhook event transport + SSRF protection | Medium |
+| `src/scheduler/postgres-persistence.ts` | 512 | PostgreSQL schedule persistence | Medium |
+| `src/scheduler/cron.ts` | 414 | CronScheduler (polling + event triggers) | Low |
+| `src/planning/registry.ts` | 365 | Recipe and step handler registries | Low |
+| `src/storage/types.ts` | 342 | Storage interface definitions (legacy + new) | **High** |
+| `src/index.ts` | 270 | Public API re-exports | Low |
+| `src/events/socketio.ts` | 262 | Socket.IO event transport | Low |
+| `src/scheduler/sqlite-persistence.ts` | 261 | SQLite schedule persistence | Low |
+| `src/storage/memory.ts` | 227 | In-memory storage adapter | Low |
+
+---
+
+## Most Complex Functions
+
+| File:Function | Estimated Complexity | Issue Description | Refactor Suggestion |
+|---------------|---------------------|-------------------|---------------------|
+| `orchestrator.ts:executeStep` | High | ~185 lines; infinite `while(true)` retry loop; 4 distinct exit paths (success, skip, retry, fail); 5+ storage/event calls per iteration; 4-level nesting in catch block | Extract `handleStepError()` and `executeStepWithTimeout()` helper; separate retry orchestration from event emission |
+| `orchestrator.ts:executeWorkflow` | High | ~220 lines; manages hooks, checkpointing, timeouts, cancellation, success/failure divergence; complex error classification logic (lines 237–244) | Split into `runSteps()` + `finalizeRun()` helpers; extract error classification into a pure function |
+| `postgres.ts:createTables` | High | ~155 lines; 20+ sequential `sql\`...\`.execute(this.db)` calls; mixes initial DDL with alter-column migration; silent `.catch(() => {})` suppresses errors | Split into `createSchemaTables()` and `runMigrations()`; use a proper migration runner; avoid silent catch |
+| `postgres.ts:mapRunRow` | Medium | Repeated `typeof row.X === 'string' ? JSON.parse(row.X) : row.X` guard on every JSON column — 8 repetitions in one function | Extract a `parseJsonColumn(col: unknown): unknown` helper shared across all map methods |
+| `postgres.ts:createRun` | Medium | Accepts a union type `CreateRunInput \| Omit<WorkflowRunRecord, …>` — forces `'id' in run`, `'parentRunId' in run`, etc. inline discriminators throughout the method body | Consolidate to a single input type; bridge at the call site rather than inside the method |
+| `sqlite.ts:prepareStatements` | Medium | Bulk-prepares 15 SQL statements in one method; `listRuns` uses double-binding pattern (`kind, kind`, `statusJson, statusJson`) which is fragile and easily mis-ordered | Each statement can be lazily prepared on first use; document or encapsulate the double-bind idiom |
+| `planner.ts:generatePlan` | Medium | Applies three independent mutation passes (hints, constraints, config) over the steps array using nested loops; emits `PlanModification` records as a side effect | Extract `applyHints()`, `applyAdditionalConfig()` as pure functions returning `{ steps, modifications }` |
+| `engine.ts:startRun` | Medium | Handles both the immediate-start and queue paths, emits multiple events, performs queue insertion — 60 lines with branching and inline event building | Extract `enqueueOrExecute()` helper to isolate the concurrency decision; move event building to a factory |
+| `webhook.ts:sendWebhook` | Medium | Retry loop, timeout via AbortController, SSRF re-validation on every send, payload signing, concurrency queue interaction — all in one method | SSRF validation at `addEndpoint` time only (URL is static); extract `buildHeaders()` |
+| `planner.ts:evaluateCondition` | Low–Medium | 10-case switch statement; regex instantiated on every call via `new RE2(conditionValue)` inside the `matches` branch | Cache compiled RE2 instances per pattern; no structural issue but the hot-path instantiation is a performance concern |
+
+---
+
+## Coupling & Cohesion Issues
+
+1. **Dual storage interface (`StorageAdapter` vs. `WorkflowStorage`) in `storage/types.ts`**
+   - **Problem**: The file defines two nearly-identical storage interfaces: the legacy `StorageAdapter` (used by the engine) and a new `WorkflowStorage` (used by `PostgresStorageAdapter` internally). `PostgresStorageAdapter` implements both simultaneously. This doubles the number of types for runs/steps (`WorkflowRunRecord` vs. `ExtendedWorkflowRunRecord`, `RunStatus` vs. `ExtendedRunStatus`, `StepStatus` vs. `ExtendedStepStatus`, `ListRunsOptions` vs. `ExtendedListRunsOptions`).
+   - **Suggested Fix**: Pick one interface as canonical and migrate all adapters to it; keep the other as a shim alias during transition. The duplicated status union types should be unified.
+
+2. **`postgres.ts` is a god class**
+   - **Problem**: `PostgresStorageAdapter` (1,354 lines) is responsible for: connection pool management, lazy dependency loading, DDL/migration, all CRUD operations for three tables, the extended `WorkflowStorage` API (7 additional methods), row-mapping helpers, atomic dequeue, and transaction wrapping. Unrelated responsibilities are co-located.
+   - **Suggested Fix**: Extract `PostgresMigrationRunner` (DDL), `PostgresRunRepository`, and `PostgresStepRepository` as internal collaborators.
+
+3. **Lazy-loaded module globals in `postgres.ts` and `postgres-persistence.ts`**
+   - **Problem**: `let Kysely: any; let PostgresDialect: any; let sql: any; let pgModule: any;` are module-level mutable variables populated by `loadPostgresDeps()` during `initialize()`. These are effectively global singletons shared across all adapter instances. Concurrent `initialize()` calls could create a race condition. All type safety is lost (`any`).
+   - **Suggested Fix**: Store loaded dependencies as instance properties populated in `initialize()`, or use a module-level `Promise` cache so the load happens exactly once and the result is strongly typed.
+
+4. **`executeStep` is tightly coupled to storage, events, logger, and abort controller**
+   - **Problem**: The function signature passes a 5-field `StepExecutionOptions` object, and inside it makes direct calls to `storage.createStep`, `storage.updateStep`, `events.emit` (×5–6 per iteration), `definition.hooks.*` (×3), and `abortController.signal`. It is essentially untestable in isolation without mocking all infrastructure.
+   - **Suggested Fix**: Extract an `StepExecutionContext` interface that provides `onStarted`, `onSucceeded`, `onFailed`, `onCanceled` callbacks; the orchestrator wires these to storage/events; the step function only calls the context.
+
+5. **`executeRun` is a no-op pass-through in `engine.ts`**
+   - **Problem**: `executeRun` (lines 324–332) calls `launchRun` with identical arguments. It exists only as an indirection, adding a layer of abstraction with no logic.
+   - **Suggested Fix**: Remove `executeRun`; call `launchRun` directly from `startRun` and `processQueue`.
+
+6. **`SQLiteStorageAdapter.transaction()` misrepresents its async contract**
+   - **Problem**: The `transaction()` method (marked `@deprecated`) has an `async` signature but actually runs synchronously via `better-sqlite3`. The JSDoc warns "only works for synchronous operations," but callers expecting async-safe semantics will be misled.
+   - **Suggested Fix**: Remove the method (it is already deprecated); expose only `transactionSync()`.
+
+---
+
+## Refactoring Candidates
+
+1. **Unify the dual storage interface hierarchy**
+   - **Location**: `src/storage/types.ts`, `src/storage/postgres.ts`, `src/storage/sqlite.ts`, `src/storage/memory.ts`
+   - **Problem**: Two parallel type families (`StorageAdapter`/`WorkflowStorage`, `WorkflowRunRecord`/`ExtendedWorkflowRunRecord`, `RunStatus`/`ExtendedRunStatus`) exist as an in-progress migration that was never completed. All consumers must understand both, and `PostgresStorageAdapter` implements both simultaneously.
+   - **Suggested Approach**: Merge the two interfaces; remove the `Extended*` duplicates by upgrading `RunStatus` to include `'pending'` and `'timeout'` and adding `output` to the base record. Adapters can implement a single interface.
+   - **Effort**: Large
+
+2. **Extract `PostgresMigrationRunner` from `PostgresStorageAdapter`**
+   - **Location**: `src/storage/postgres.ts:314–465` (`createTables`)
+   - **Problem**: 155 lines of sequential DDL mixed with the adapter. It also silently swallows `ALTER TABLE` errors, making it hard to reason about migration state.
+   - **Suggested Approach**: Move all DDL into a standalone `PostgresMigrationRunner` class with versioned migrations and explicit error handling. `PostgresStorageAdapter` calls `runner.migrate()` during `initialize()`.
+   - **Effort**: Medium
+
+3. **Decompose `executeStep` in the orchestrator**
+   - **Location**: `src/core/orchestrator.ts:296–479`
+   - **Problem**: ~185-line function with 4 exit paths, 4-level nesting, and direct coupling to all infrastructure. The retry delay sleep path duplicates cancellation handling from the outer path.
+   - **Suggested Approach**: Extract `handleStepSuccess()`, `handleStepCancellation()`, and `handleStepRetry()` — each taking the step record and emitting the right events/storage calls. The main function becomes a loop calling these.
+   - **Effort**: Medium
+
+4. **Fix lazy-loaded dependency globals in postgres adapters**
+   - **Location**: `src/storage/postgres.ts:13–16`, `src/scheduler/postgres-persistence.ts:11–15`
+   - **Problem**: `let Kysely: any` etc. as module-level mutable globals. Both files duplicate this pattern. Type safety lost, race condition risk on concurrent initialization.
+   - **Suggested Approach**: Create a shared `src/utils/postgres-deps.ts` module (it may partially exist as `loadPostgresDeps`) that returns a typed, promise-cached result; store the resolved deps as instance properties.
+   - **Effort**: Small
+
+5. **Cache RE2 instances in `evaluateCondition`**
+   - **Location**: `src/planning/planner.ts:88–93`
+   - **Problem**: `new RE2(conditionValue)` is called on every condition evaluation. In a hot planning path with many recipes and conditions, this allocates a new compiled regex object on each call.
+   - **Suggested Approach**: Add a `Map<string, RE2>` cache at module scope or on the `RuleBasedPlanner` instance; look up or create before matching.
+   - **Effort**: Small
+
+6. **Remove `executeRun` pass-through in `WorkflowEngine`**
+   - **Location**: `src/core/engine.ts:323–332`
+   - **Problem**: `executeRun` adds a layer of indirection with zero logic, making the call chain harder to follow (`startRun → executeRun → launchRun`).
+   - **Suggested Approach**: Delete `executeRun`; call `launchRun` directly from `startRun` (line 270) and `processQueue` (line 392).
+   - **Effort**: Small
+
+7. **Extract a `parseJsonColumn` helper in `postgres.ts` row mappers**
+   - **Location**: `src/storage/postgres.ts:861–940` (four `map*Row` methods)
+   - **Problem**: The guard `typeof row.X === 'string' ? JSON.parse(row.X) : row.X` is repeated ~10 times across four mapper methods, indicating that Kysely returns JSONB as either a string or a parsed object depending on configuration.
+   - **Suggested Approach**: Extract `parseJsonColumn(col: unknown): unknown` and call it from all mappers. Alternatively, configure Kysely with a `pg.types.setTypeParser` for the JSONB OID to always return parsed objects, eliminating the guard entirely.
+   - **Effort**: Small
+
+8. **Encapsulate the SQLite double-binding pattern**
+   - **Location**: `src/storage/sqlite.ts:329–341` (`listRuns`)
+   - **Problem**: Prepared statements use `? IS NULL OR field = ?` which requires each parameter to be passed twice: `kind, kind` / `statusJson, statusJson` / `parentRunId, parentRunId`. This is fragile — if parameter order changes, bugs are silent.
+   - **Suggested Approach**: Add a small helper `nullableParam(val)` returning `[val, val]` to make the doubling explicit and documented, or switch to Kysely for SQLite queries to get type-safe query building.
+   - **Effort**: Small
+
+9. **Remove or complete the deprecated `SQLiteStorageAdapter.transaction()` method**
+   - **Location**: `src/storage/sqlite.ts:440–446`
+   - **Problem**: The `async transaction()` method has a misleading contract — it wraps a synchronous transaction with an async signature, only works if the callback does no real async I/O, and is deprecated. It remains in the public API creating a footgun.
+   - **Suggested Approach**: Remove the method in the next minor version (or immediately if semver allows). Consumers should use `transactionSync()`. Add a clear deprecation notice in the changelog.
+   - **Effort**: Small
+
+10. **Consolidate magic timeout/retry defaults into named constants**
+    - **Location**: `src/core/orchestrator.ts:304–307`, `src/core/engine.ts:484`, `src/events/webhook.ts:145–151`
+    - **Problem**: Default values like `maxRetries: 3`, `retryDelay: 1000`, `retryBackoff: 2`, `timeout: 60000`, `defaultTimeout: 5000` are magic numbers scattered across files. They are inconsistent (`orchestrator.ts` defaults `maxRetries` to 3 inline; `webhook.ts` defaults `defaultRetries` to 3 separately).
+    - **Suggested Approach**: Collect all engine defaults into a `src/core/defaults.ts` constants file (`DEFAULT_MAX_RETRIES`, `DEFAULT_RETRY_DELAY_MS`, `DEFAULT_WAIT_TIMEOUT_MS`, etc.) and reference them everywhere.
+    - **Effort**: Small

package/.codekin/reports/complexity/2026-04-11_complexity-report.md

@@ -0,0 +1,152 @@
+# Complexity Report: stepflow
+
+**Date**: 2026-04-11T02:46:40.781Z
+**Repository**: /srv/repos/stepflow
+**Branch**: main
+**Workflow Run**: 7c4174ae-8cba-4ad8-9a30-b2f56cf4c98b
+**Session**: 474ba458-5157-4ff3-8ef4-802b1bc389e5
+
+---
+
+Now I have enough information to produce the report.
+
+## Summary
+
+**Overall Complexity Rating: Medium**
+
+The codebase is a TypeScript workflow orchestration library (~14,300 lines across source + tests). The implementation is generally clean and well-structured, but several files are oversized, the storage layer has two parallel interface lineages with significant duplication, and the orchestrator's `executeStep` function carries the highest cyclomatic complexity. No deeply pathological nesting exists, but coupling between the `postgres.ts` adapter and two different storage interfaces is the most acute maintenance risk.
+
+Key metrics:
+- **Largest file:** `src/storage/postgres.ts` — 1,354 lines
+- **Deepest nesting:** `executeStep` in `orchestrator.ts` — 4–5 levels (`while → try → if → if → try`)
+- **Most complex function:** `executeStep` — retry loop, cancellation guards, hooks, event emission, 4 error-handling branches
+- **Duplicate interface footprint:** `StorageAdapter` vs. `WorkflowStorage` — two complete CRUD contracts implemented in the same `postgres.ts` class
+
+---
+
+## Largest Files
+
+| File | Lines | Primary Responsibility | Refactor Priority |
+|------|-------|------------------------|-------------------|
+| `src/storage/postgres.ts` | 1,354 | PostgreSQL adapter (implements both `StorageAdapter` and `WorkflowStorage`) | **High** |
+| `src/core/engine.test.ts` | 1,364 | Engine integration tests | Low (test file) |
+| `src/planning/planning.test.ts` | 727 | Planner integration tests | Low (test file) |
+| `src/events/webhook.test.ts` | 657 | Webhook transport tests | Low (test file) |
+| `src/core/engine.ts` | 692 | `WorkflowEngine` class — run lifecycle, queue, resume | Medium |
+| `src/storage/sqlite.ts` | 621 | SQLite adapter | Medium |
+| `src/planning/planner.ts` | 576 | `RuleBasedPlanner` — recipe selection, plan generation | Low |
+| `src/planning/types.ts` | 566 | Planning domain types (Recipe, Plan, Planner interfaces) | Low |
+| `src/core/orchestrator.ts` | 564 | Step execution loop, retry logic, hooks | **High** |
+| `src/events/webhook.ts` | 557 | WebhookEventTransport — SSRF guards, signing, concurrency | Medium |
+| `src/scheduler/postgres-persistence.ts` | 512 | PostgreSQL schedule persistence | Low |
+| `src/scheduler/cron.ts` | 414 | CronScheduler — polling + event-driven triggers | Low |
+| `src/storage/types.ts` | 342 | Storage type definitions (two parallel interface families) | **High** |
+| `src/events/socketio.ts` | 262 | Socket.IO event transport | Low |
+| `src/index.ts` | 270 | Public API barrel file | Low |
+
+---
+
+## Most Complex Functions
+
+| File:Function | Estimated Complexity | Issue Description | Refactor Suggestion |
+|---------------|---------------------|-------------------|---------------------|
+| `orchestrator.ts:executeStep` | Very High (CC ~12) | Single `while(true)` loop wraps: `AbortSignal` check, step record creation, `beforeStep` hook, conditional timeout vs. `raceWithAbort`, `afterStep` hook, cancellation detection, `onStepError` hook, three error branches (`skip`/`retry`/`fail`), sleep-with-abort, and re-throw. 4–5 nesting levels. | Extract `handleStepError(error, attempt, strategy)` and `executeStepOnce(step, context, options)` as separate functions |
+| `orchestrator.ts:executeWorkflow` | High (CC ~8) | Combines run status update, event emission, context construction, timeout setup, `beforeRun` hook, step loop with skip checks, `afterRun` hook, success/failure/timeout/cancel branching in one try/catch | Split success path and failure classification into `finalizeSuccess()` / `finalizeFailure()` helpers |
+| `storage/postgres.ts:createTables` | High (CC ~7) | 150-line method issues 15+ raw SQL statements sequentially with ad-hoc `catch(() => {})` for ALTER TABLE idempotency. No migration versioning. | Replace with a proper migration runner (numbered migration files or Kysely-migrate) |
+| `storage/postgres.ts:mapRunRow` | Medium (CC ~6) | Repeated `typeof x === 'string' ? JSON.parse(x) : x` ternary for every JSONB column (6 occurrences in `mapRunRow` alone, duplicated in `mapExtendedRunRow`) | Extract `parseJsonColumn<T>(col: string | T): T` helper; used in all `mapXRow` methods |
+| `events/webhook.ts:sendWebhook` | Medium (CC ~6) | Retry loop with DNS validation re-run on every attempt, payload size check, dynamic header assembly, HMAC signing, and `AbortController` per attempt | Extract `deliverOnce(url, headers, body, timeout)` and call from `sendWebhookWithRetry` |
+| `events/webhook.ts:isBlockedHost` | Medium (CC ~9) | Flat function with 9 early-return branches testing IPv4 ranges, IPv6 literals, loopback, link-local — logic duplicated almost identically in `isBlockedIp` | Merge `isBlockedHost` and `isBlockedIp` into a single `isBlockedAddress(address: string)` that handles both hostname and resolved-IP cases |
+| `planner.ts:selectRecipe` | Medium (CC ~6) | Three sequential priority checks (forced, preferred, scored) each with early returns, plus a fallback chain of two more returns | Already reasonably structured; document the scoring ladder with inline comments |
+| `storage/postgres.ts:updateRun` | Medium (CC ~5) | Builds `updateData` object via 6 independent `if` guards covering two different input shapes (`UpdateRunInput` and `Partial<WorkflowRunRecord>`) simultaneously | Accept only `UpdateRunInput`; deprecate the `Partial<WorkflowRunRecord>` overload |
+| `engine.ts:waitForRun` | Medium (CC ~5) | Interleaves early-return for already-completed runs with Promise-based event subscription, dual cleanup via `cleanup()` closure, nested `try/catch` inside the event callback | Extract the Promise setup into a `awaitRunEvent(runId, timeout)` utility |
+| `planner.ts:evaluateCondition` | Low-Medium (CC ~11) | Large `switch` on 9 operators; each case is self-contained but the function is called in a hot loop for every condition on every recipe | Acceptable as-is; consider a `conditionEvaluators: Record<ConditionOperator, Evaluator>` map if operators are user-extensible |
+
+---
+
+## Coupling & Cohesion Issues
+
+**1. `storage/postgres.ts` implements two unrelated storage interfaces**
+
+`PostgresStorageAdapter` simultaneously implements `StorageAdapter` (the legacy interface with `WorkflowRunRecord`, `WorkflowRunStepRecord`) and `WorkflowStorage` (the newer interface with `ExtendedWorkflowRunRecord`, `StepResult`). This means `postgres.ts` contains two nearly identical sets of CRUD methods (`createRun`/`getRun`/`updateRun` in both shapes), two `mapRunRow` functions (`mapRunRow` and `mapExtendedRunRow`) that differ only in the target type, and two separate status type hierarchies (`RunStatus` vs. `ExtendedRunStatus`). Any schema change must be applied in multiple places.
+
+*Suggested fix:* Decide on one canonical interface. If `WorkflowStorage` is the future, mark `StorageAdapter` as deprecated and migrate callers. Provide an adapter shim for backward compatibility during the transition rather than carrying both implementations indefinitely.
+
+**2. `storage/types.ts` defines two parallel type families**
+
+`StorageAdapter` + `WorkflowRunRecord`/`WorkflowRunStepRecord` and `WorkflowStorage` + `ExtendedWorkflowRunRecord`/`StepResult` overlap heavily. `ExtendedRunStatus` adds `'pending'` and `'timeout'` to `RunStatus`; `ExtendedStepStatus` renames `'succeeded'` to `'completed'`. These differences are not documented as deliberate — they appear to be the result of incremental additions without consolidation.
+
+*Suggested fix:* Unify the status enums (`RunStatus` should include `'timeout'`; step status should use consistent terminology). Remove the `Extended*` types once the single interface is adopted.
+
+**3. `engine.ts` holds both scheduling concerns and run lifecycle concerns**
+
+`WorkflowEngine` manages the in-memory run queue with priority insertion (`queueRun`, `processQueue`), active-run tracking (`activeRuns` map), child spawning delegation, event subscription forwarding, and shutdown. This is reasonable but the queue and concurrency control logic (`hasCapacity`, `queueRun`, `processQueue`) could become an independent `RunQueue` class, making `WorkflowEngine` a thinner coordinator.
+
+**4. `events/webhook.ts` duplicates IP-range logic across two functions**
+
+`isBlockedHost` and `isBlockedIp` both check the same IPv4 private ranges (10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x, 0.0.0.0) with near-identical code. A future range addition or bug fix must be applied twice.
+
+**5. `scheduler/postgres-persistence.ts` repeats the Kysely lazy-load pattern from `storage/postgres.ts`**
+
+Both files declare module-level `let Kysely`, `let PostgresDialect`, `let sql`, `let pgModule` and both call `loadPostgresDeps()` in `initialize()`. This cross-file duplication of boilerplate means any change to the lazy-loading pattern (e.g., adding a new exported symbol) must be applied in two places.
+
+*Suggested fix:* Centralize the Kysely instantiation in `utils/postgres-deps.ts` and return a ready-to-use `Kysely` instance, rather than returning the constructor for callers to instantiate manually.
+
+---
+
+## Refactoring Candidates
+
+**1. Consolidate dual storage interfaces (`StorageAdapter` / `WorkflowStorage`)**
+
+- **Location:** `src/storage/types.ts`, `src/storage/postgres.ts`
+- **Problem:** Two overlapping interface families with near-duplicate type definitions, status enums that differ by one or two values, and two sets of CRUD methods in `PostgresStorageAdapter`. Every schema or status change requires dual edits.
+- **Suggested approach:** Choose `WorkflowStorage` as the single target. Introduce a `LegacyStorageAdapterBridge` shim that wraps a `WorkflowStorage` into the `StorageAdapter` shape for backward compatibility. Unify `RunStatus` to include `'timeout'`; unify step status terminology to `'succeeded'`. Remove `Extended*` type aliases.
+- **Effort:** Large
+
+**2. Extract step execution helpers from `orchestrator.ts:executeStep`**
+
+- **Location:** `src/core/orchestrator.ts:296–479`
+- **Problem:** The `executeStep` function is a 183-line `while(true)` loop combining timeout handling, cancellation, hook invocation, event emission, and three error recovery strategies. High cyclomatic complexity makes it difficult to unit-test individual error paths.
+- **Suggested approach:** Extract `executeStepHandler(step, context, abortController)` (pure execution + timeout), `handleStepSuccess(stepRecord, ...)`, and `handleStepError(step, error, attempt, strategy, ...)` (retry/skip/fail branching). `executeStep` becomes a thin coordinator.
+- **Effort:** Medium
+
+**3. Merge `isBlockedHost` and `isBlockedIp` into one utility**
+
+- **Location:** `src/events/webhook.ts:487–555`
+- **Problem:** Two functions with near-identical IPv4-range checks. A missed range in one is a security regression.
+- **Suggested approach:** Consolidate into `isBlockedAddress(address: string): boolean` operating on dotted-decimal IPv4 or hostname strings. Call it from both `validateWebhookUrl` and `validateResolvedHost`.
+- **Effort:** Small
+
+**4. Extract a `parseJsonColumn` helper for storage mappers**
+
+- **Location:** `src/storage/postgres.ts:861–940`, `src/storage/sqlite.ts`
+- **Problem:** The pattern `typeof col === 'string' ? JSON.parse(col) : col` appears 10+ times across `mapRunRow`, `mapExtendedRunRow`, `mapStepRow`, `mapStepResultRow`, and `mapEventRow` in postgres.ts, and again in sqlite.ts's mapper.
+- **Suggested approach:** `function parseJsonColumn<T>(col: string | T | null | undefined, fallback?: T): T | undefined` — extracted to a shared `src/storage/utils.ts`. Eliminates all inline ternaries.
+- **Effort:** Small
+
+**5. Replace `createTables` ad-hoc migration with a versioned migration runner**
+
+- **Location:** `src/storage/postgres.ts:314–465`
+- **Problem:** The 150-line `createTables` method issues 15+ raw SQL statements and silently swallows `ALTER TABLE` errors as idempotency. There is no migration version tracking, so it is impossible to determine the current schema version or safely evolve the schema.
+- **Suggested approach:** Introduce a `schema_migrations` table tracking applied versions. Replace the `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` hack with numbered migration files applied sequentially. This also enables rollback logic.
+- **Effort:** Large
+
+**6. Refactor `WorkflowEngine` queue management into a `RunQueue` class**
+
+- **Location:** `src/core/engine.ts:112–399`
+- **Problem:** `WorkflowEngine` mixes run-lifecycle concerns (start, cancel, resume, wait) with an in-memory priority queue implementation (`queueRun`, `processQueue`, `hasCapacity`, `runQueue` array, `activeRuns` map). As concurrency features grow, this class will accumulate more queue-specific logic.
+- **Suggested approach:** Extract a `RunQueue` class that owns `runQueue`, `activeRuns`, `hasCapacity`, `queueRun`, `processQueue`, and the `QueuedRun` interface. `WorkflowEngine` delegates to it.
+- **Effort:** Medium
+
+**7. Centralize Kysely lazy-loading in `utils/postgres-deps.ts`**
+
+- **Location:** `src/utils/postgres-deps.ts`, `src/storage/postgres.ts:13–16`, `src/scheduler/postgres-persistence.ts:12–15`
+- **Problem:** Module-level `let Kysely`, `let PostgresDialect`, `let sql`, `let pgModule` declarations and `loadPostgresDeps()` calls are copy-pasted into two different files, and the callers then call `new Kysely(...)` themselves.
+- **Suggested approach:** Have `loadPostgresDeps` return an already-constructed `Kysely<any>` factory or a `buildKysely(pool)` helper. Callers receive a usable query builder, not raw constructors.
+- **Effort:** Small
+
+**8. Add a `retryUntilAbort` helper to eliminate duplicated sleep-abort patterns**
+
+- **Location:** `src/core/orchestrator.ts:462–473`, `src/utils/retry.ts`
+- **Problem:** The `sleep(delay, abortController.signal)` call inside the retry loop is followed by a catch that checks `WorkflowCanceledError` and updates the step record — a pattern that will be repeated if a second retry site is ever added.
+- **Suggested approach:** Provide a `sleepWithAbort(ms, signal, onAbort?)` utility in `src/utils/retry.ts` that handles the cancellation check and throws consistently, removing the need for a catch at the call site.
+- **Effort:** Small

package/.codekin/reports/complexity/2026-04-14_complexity-report.md

@@ -0,0 +1,34 @@
+# Complexity Report: stepflow
+
+**Date**: 2026-04-14T01:04:23.188Z
+**Repository**: /srv/repos/stepflow
+**Branch**: main
+**Workflow Run**: 21addb61-3850-4a9f-9504-0c0627b6a8d5
+**Session**: 01abcef0-2ca7-4ee5-b46f-a7959609ab9a
+
+---
+
+## Code Complexity Report — Stepflow
+
+The report has been saved to `.codekin/reports/complexity/2026-04-14_complexity-report.md`.
+
+**Overall rating: Medium-High**
+
+Key findings:
+
+**Largest files** (top 3):
+- `src/storage/postgres.ts` — 1,354 lines (4.5× the 300-line guideline), a God object with 20+ methods across 8 distinct responsibilities
+- `src/core/engine.ts` — 692 lines, mixes queue management with lifecycle orchestration
+- `src/core/orchestrator.ts` — 564 lines, hosts the two most complex functions in the codebase
+
+**Hottest complexity spots:**
+- `orchestrator.ts: executeStep()` — CC ≈ 20, 7 levels of nesting in the retry loop
+- `orchestrator.ts: executeWorkflow()` — 217-line function with inline timeout scheduling, checkpointing, and lifecycle hooks all interleaved
+- `postgres.ts: createTables()` — 152 lines of undifferentiated SQL blocks
+
+**Highest-impact refactoring opportunities (quick wins):**
+1. Extract a `parseJsonColumn<T>()` utility to eliminate the 8+ identical JSON parsing idioms duplicated across postgres and sqlite adapters (Small effort)
+2. Replace `evaluateCondition()` switch with a strategy map (Small effort)
+3. Extract event/status string literals into a `src/core/constants.ts` file (Small effort)
+4. Replace the O(n) array-splice run queue with a priority heap (Small effort)
+5. Introduce a shared `Semaphore` utility — both `engine.ts` and `webhook.ts` have hand-rolled concurrency controllers (Small effort)

package/.codekin/reports/dependencies/2026-04-04_dependency-health.md

@@ -0,0 +1,94 @@
+# Dependency Health Report: stepflow
+
+**Date**: 2026-04-04T06:58:47.515Z
+**Repository**: /srv/repos/stepflow
+**Branch**: main
+**Workflow Run**: caf445eb-aa6a-4887-a75d-0068f9ea47ac
+**Session**: 40a62583-ab64-444b-be60-b6caef82eab5
+
+---
+
+Now I have all the data needed. Here is the full dependency health assessment:
+
+---
+
+## Summary
+
+| Package Manager | Total Deps | Outdated | Vulnerabilities | Risk Level |
+|---|---|---|---|---|
+| npm | 296 | 7 | 3 (2 high, 1 moderate) | **High** |
+
+**Notes:** 296 total installed packages (64 prod, 231 dev, 87 optional). Direct production dependencies: `cron-parser`, `re2`. Direct devDependencies: 10 packages. Peer dependencies: `better-sqlite3`, `kysely`, `pg`.
+
+---
+
+## Security Vulnerabilities
+
+| Package | Severity | Advisory | Description | Fixed In |
+|---|---|---|---|---|
+| `kysely` | **HIGH** (CVSS 8.1) | [GHSA-8cpq-38p9-67gx](https://github.com/advisories/GHSA-8cpq-38p9-67gx) | MySQL SQL Injection via insufficient backslash escaping in `sql.lit(string)` and similar string-literal methods | `>=0.28.14` |
+| `kysely` | **HIGH** (CVSS 8.1) | [GHSA-fr9j-6mvq-frcv](https://github.com/advisories/GHSA-fr9j-6mvq-frcv) | MySQL SQL Injection via backslash escape bypass in non-type-safe JSON path key usage | `>=0.28.14` |
+| `picomatch` | **HIGH** (CVSS 7.5) | [GHSA-c2c7-rcm5-vvqj](https://github.com/advisories/GHSA-c2c7-rcm5-vvqj) | ReDoS vulnerability via extglob quantifiers — denial-of-service via malicious glob patterns (indirect dep of `chokidar`/`tsup`) | `>=4.0.4` |
+| `brace-expansion` | **MODERATE** (CVSS 6.5) | [GHSA-f886-m6hf-6m8v](https://github.com/advisories/GHSA-f886-m6hf-6m8v) | Zero-step sequence (e.g. `{1..0}`) causes process hang and memory exhaustion (indirect dep) | `>=5.0.5` |
+| `picomatch` | MODERATE (CVSS 5.3) | [GHSA-3v7f-55p6-f55p](https://github.com/advisories/GHSA-3v7f-55p6-f55p) | Method injection via POSIX character classes causing incorrect glob matching (indirect dep of `chokidar`/`tsup`) | `>=4.0.4` |
+
+**Scope assessment:** The `kysely` vulnerabilities are in a peer dependency used for the PostgreSQL/MySQL adapter path. They affect MySQL dialect users who pass unsanitised input via `sql.lit()` or JSON path keys. SQLite users are not affected. The `picomatch` and `brace-expansion` issues are in dev toolchain transitive deps (`tsup` → `chokidar`) and do not affect the published package.
+
+---
+
+## Outdated Dependencies
+
+| Package | Current | Latest | Age of Current | Type |
+|---|---|---|---|---|
+| `@types/node` | 22.19.5 | 25.5.2 | ~84 days (3 major versions behind) | devDependency |
+| `typescript` | 5.9.3 | 6.0.2 | — (1 major version behind; v6 released 2026-03-23) | devDependency |
+| `re2` | 1.23.3 | 1.24.0 | ~54 days (released 2026-02-09) | dependency (prod) |
+| `kysely` | 0.28.12 | 0.28.15 | ~22 days (released 2026-03-13) | peerDependency / devDependency |
+| `vitest` | 4.1.0 | 4.1.2 | ~23 days (released 2026-03-12) | devDependency |
+| `@vitest/coverage-v8` | 4.1.0 | 4.1.2 | ~23 days | devDependency |
+| `@types/pg` | 8.18.0 | 8.20.0 | — (2 minor versions behind) | devDependency |
+
+---
+
+## Abandoned / Unmaintained Packages
+
+All items below are **transitive/indirect** dependencies — none are direct. Most trace back to the `prebuild-install` → `node-pre-gyp` chain used by `better-sqlite3` and `re2` for native addon installation.
+
+| Package | Installed Version | Last npm Publish | Age |
+|---|---|---|---|
+| `any-promise` | 1.3.0 | 2022-06-13 | ~3.8 years |
+| `tunnel-agent` | 0.6.0 | 2022-06-27 | ~3.8 years |
+| `util-deprecate` | 1.0.2 | 2022-06-28 | ~3.8 years |
+| `thenify` | 3.3.1 | 2022-06-27 | ~3.8 years |
+| `github-from-package` | 0.1.1 | 2022-11-11 | ~3.4 years |
+| `deep-extend` | 0.6.0 | 2023-07-10 | ~2.7 years |
+| `safe-buffer` | 5.2.1 | 2023-07-10 | ~2.7 years |
+| `bindings` | 1.5.0 | 2023-07-10 | ~2.7 years |
+| `file-uri-to-path` | 2.0.0 | 2023-07-10 | ~2.7 years |
+| `mz` | 2.7.0 | 2023-11-07 | ~2.4 years |
+
+These packages are effectively stable and in maintenance-only mode (no API surface changes expected). Their abandonment is low operational risk, but they represent supply-chain exposure if they are ever compromised on npm.
+
+---
+
+## Recommendations
+
+1. **[CRITICAL] Update `kysely` to `>=0.28.14` immediately.** Two high-severity SQL injection CVEs (GHSA-8cpq-38p9-67gx, GHSA-fr9j-6mvq-frcv) affect all versions `<=0.28.13`. The fix is available in `0.28.15` (released 2026-03-31). Since `kysely` is a peer dependency, consumers must update their own `kysely` version; update the peer/dev dep range floor in `package.json` to `>=0.28.14` and run `npm install` to update the lockfile.
+
+2. **[HIGH] Update `picomatch` to `>=4.0.4`.** Two CVEs (ReDoS GHSA-c2c7-rcm5-vvqj at CVSS 7.5, method injection GHSA-3v7f-55p6-f55p) are present in the installed `4.0.x` range. This is pulled in transitively by `tsup`/`chokidar`. Run `npm update picomatch` or update `chokidar` when a version that pins `picomatch>=4.0.4` is released.
+
+3. **[MODERATE] Update `brace-expansion` to `>=5.0.5`.** The installed range `4.0.0–5.0.4` is vulnerable to a process-hanging ReDoS (GHSA-f886-m6hf-6m8v, CVSS 6.5). Run `npm update brace-expansion` to pull in the patched version.
+
+4. **[HIGH] Plan migration to TypeScript 6.** TypeScript 6.0.2 is now available and includes breaking changes (stricter inference, removed deprecated emit options). Schedule an upgrade cycle: run `tsc` against the new compiler on a branch, address any new type errors, then merge. TypeScript 5.9 will not receive bug fixes once support ends.
+
+5. **[MEDIUM] Update `@types/node` from `22.x` to `22.x` latest (semver-wanted), and plan a roadmap to `25.x`.** The installed version (`22.19.5`) is 3 major type-definition versions behind `25.5.2`. While types don't affect runtime, using stale `@types/node` means missing Node.js API types and incorrect/missing signatures for newer APIs. Update to the wanted `22.19.17` now, then evaluate a bump to `24.x` or `25.x` after the TypeScript 6 migration.
+
+6. **[MEDIUM] Update `re2` to `1.24.0`.** The production `re2` package (a direct dependency) has a new minor release. As a native addon that is loaded at runtime, staying current ensures compatibility with newer Node.js ABI versions and any security fixes in the C++ RE2 library.
+
+7. **[LOW] Update `vitest` and `@vitest/coverage-v8` to `4.1.2`.** These are patch releases that likely include bug fixes. They are low-risk to update (`npm update vitest @vitest/coverage-v8`) and should be kept in sync since mismatched versions can cause coverage reporting failures.
+
+8. **[LOW] Audit the `prebuild-install` dependency chain.** Ten transitive packages in the native addon prebuilt-install chain (`tunnel-agent`, `any-promise`, `github-from-package`, etc.) have not been published in 2–4 years. Consider whether `better-sqlite3` or `re2` have moved to alternative install mechanisms that shed these deps, and upgrade those packages to their latest versions to reduce supply-chain surface area.
+
+9. **[INFO] Verify `kysely` peer dependency minimum version in `package.json`.** The current `peerDependencies` floor is `>=0.27.0`, which includes the now-vulnerable range `<=0.28.13`. Update the peer dep constraint to `>=0.28.14` to prevent downstream consumers from inadvertently installing a vulnerable version of `kysely` when using this library.
+
+10. **[INFO] Consider replacing `tunnel-agent` and `safe-buffer` transitive deps long-term.** Both are effectively superseded by Node.js built-ins (`https.Agent` and `Buffer` respectively). They persist only as transitive deps of `prebuild-install`. File upstream issues or switch to alternative prebuilt strategies (e.g., `node-gyp-build` with bundled binaries) if those deps cannot be shed through normal upgrades.

package/.codekin/reports/dependencies/2026-04-11_dependency-health.md

@@ -0,0 +1,93 @@
+# Dependency Health Report: stepflow
+
+**Date**: 2026-04-11T02:46:13.072Z
+**Repository**: /srv/repos/stepflow
+**Branch**: main
+**Workflow Run**: 672a3272-e7d7-4127-b865-4e02a47eac94
+**Session**: 0b582a44-067e-4ef0-b863-b0cd566a81fd
+
+---
+
+Now I have all the data needed to compile the report.
+
+## Dependency Health Assessment — `@multiplier-labs/stepflow` v0.2.6
+
+_Assessment date: 2026-04-11 | Package manager: **npm** | Lock file: `package-lock.json`_
+
+---
+
+## Summary
+
+| Package Manager | Total Deps | Outdated (direct) | Vulnerabilities | Risk Level |
+|---|---|---|---|---|
+| npm | 296 (12 direct) | 7 | 4 (3 high, 1 moderate) | **HIGH** |
+
+---
+
+## Security Vulnerabilities
+
+| Package | Severity | Advisory | Description | Fixed In |
+|---|---|---|---|---|
+| `kysely` | **HIGH** (CVSS 8.1) | GHSA-8cpq-38p9-67gx | SQL Injection via insufficient backslash escaping in `sql.lit()` and similar string-literal methods | `0.28.14` |
+| `kysely` | **HIGH** (CVSS 8.1) | GHSA-fr9j-6mvq-frcv | SQL Injection via backslash escape bypass in non-type-safe JSON path key usage | `0.28.14` |
+| `picomatch` | **HIGH** (CVSS 7.5) | GHSA-c2c7-rcm5-vvqj | ReDoS (Denial of Service) via extglob quantifiers — affects transitive dep from `vitest`/`chokidar` chain | `4.0.4` |
+| `vite` | **HIGH** | GHSA-p9ff-h696-f583 | Arbitrary file read via Vite Dev Server WebSocket — transitive dep via `vitest` | `8.0.5` |
+| `vite` | **HIGH** | GHSA-v2wj-q39q-566r | `server.fs.deny` access control bypass with query strings — transitive dep via `vitest` | `8.0.5` |
+| `vite` | Moderate | GHSA-4w7w-66w2-5vf9 | Path traversal in optimized deps `.map` handling — transitive dep via `vitest` | `8.0.5` |
+| `brace-expansion` | Moderate (CVSS 6.5) | GHSA-f886-m6hf-6m8v | Zero-step sequence causes process hang and memory exhaustion — transitive dep | `5.0.5` |
+| `picomatch` | Moderate (CVSS 5.3) | GHSA-3v7f-55p6-f55p | Method injection in POSIX character classes causes incorrect glob matching | `4.0.4` |
+
+> **Note:** `kysely` appears as both a `devDependency` and `peerDependency` in this project. The SQL injection issues affect MySQL dialect users specifically; SQLite and PostgreSQL dialects have lower exposure, but upgrading is still critical.
+
+---
+
+## Outdated Dependencies
+
+| Package | Current | Latest | Gap | Type |
+|---|---|---|---|---|
+| `@types/node` | `22.19.5` | `25.6.0` | 3 major versions | devDependency |
+| `typescript` | `5.9.3` | `6.0.2` | 1 major version | devDependency |
+| `kysely` | `0.28.12` | `0.28.16` | 4 patches (**security**) | devDependency / peerDependency |
+| `re2` | `1.23.3` | `1.24.0` | 1 minor | production dependency |
+| `vitest` | `4.1.0` | `4.1.4` | 4 patches (transitive vuln fix) | devDependency |
+| `@vitest/coverage-v8` | `4.1.0` | `4.1.4` | 4 patches | devDependency |
+| `@types/pg` | `8.18.0` | `8.20.0` | 2 patches | devDependency |
+
+---
+
+## Abandoned / Unmaintained Packages
+
+These are all **transitive dependencies** pulled in via the build/test toolchain (`tsup`, `prebuild-install`, `vitest`). Direct replacement is not possible without upstream action, but they represent long-term risk.
+
+| Package | Installed Version | Est. Last Release | Dependency Path | Notes |
+|---|---|---|---|---|
+| `any-promise` | `1.3.0` | ~2016 (~10 yrs) | `tsup` → `mz` → `any-promise` | Effectively abandoned; superseded by native Promises |
+| `object-assign` | `4.1.1` | ~2017 (~9 yrs) | `tsup` → build chain | Superseded by `Object.assign()` natively in Node.js |
+| `file-uri-to-path` | `1.0.0` | ~2017 (~9 yrs) | `bindings` → `file-uri-to-path` | No longer needed for modern Node.js |
+| `tunnel-agent` | `0.6.0` | ~2018 (~8 yrs) | `prebuild-install` → `request` chain | `request` itself is deprecated |
+| `safe-buffer` | `5.2.1` | ~2020 (~6 yrs) | `readable-stream` → `safe-buffer` | Superseded by native `Buffer` APIs |
+| `source-map` | `0.7.6` | ~2021 (~5 yrs) | `sucrase` → `source-map` | Minimal maintenance; `sucrase` is a dev-only tool |
+
+---
+
+## Recommendations
+
+1. **[Critical] Upgrade `kysely` to `≥0.28.14` immediately.** Two HIGH-severity SQL injection vulnerabilities (GHSA-8cpq-38p9-67gx, GHSA-fr9j-6mvq-frcv) affect all versions ≤0.28.13. Update both `devDependencies` and adjust `peerDependencies` range (`"kysely": ">=0.27.0"`) to document the minimum safe version. The fix is available at `0.28.16` (current latest).
+
+2. **[High] Upgrade `vitest` to `≥4.1.4` to pull in patched `vite` (≥8.0.5) and `picomatch` (≥4.0.4).** Three HIGH/moderate vulnerabilities in `vite` (GHSA-p9ff-h696-f583, GHSA-v2wj-q39q-566r, GHSA-4w7w-66w2-5vf9) and two in `picomatch` are fixed by bumping vitest. Although these only run in the dev server context, they pose a real risk in CI or development environments.
+
+3. **[High] Run `npm audit fix` to resolve `brace-expansion` (GHSA-f886-m6hf-6m8v).** This moderate ReDoS/memory-exhaustion vulnerability is in a transitive dep with a straightforward fix available. Running `npm audit fix` should resolve all 4 outstanding advisories once `kysely` and `vitest` are updated first.
+
+4. **[Medium] Upgrade `@types/node` from `22.x` to `24.x` (or `25.x`) in a planned sprint.** The installed version is 3 major versions behind. While `@types/node` bumps rarely break code, staying far behind obscures real type errors and misses new Node.js API typings. Align with the Node.js LTS version in use.
+
+5. **[Medium] Evaluate `TypeScript 6.x` migration.** The project uses `typescript ^5.7.2` while `6.0.2` is now the latest stable release. TypeScript 6 ships breaking changes (notably around module resolution and `erasableSyntaxOnly`). Plan a migration branch to assess impact on the codebase and tsup build config.
+
+6. **[Medium] Update `re2` to `1.24.0`.** `re2` is a **production dependency** — it directly affects the package published to consumers. Patch updates should be applied promptly; `1.24.0` is a minor bump with bug fixes.
+
+7. **[Low] Update peer dependency minimum for `kysely` to `>=0.28.14` in `package.json`.** Even if downstream users manage their own `kysely` install, advertising a range that includes vulnerable versions is irresponsible. Tightening the peer constraint signals the minimum safe version to consumers.
+
+8. **[Low] Audit and potentially remove `prebuild-install` → `tunnel-agent` chain.** `tunnel-agent` is pulled in via `re2`'s native build tooling (`prebuild-install`). Check whether `re2` 1.24.0 still ships prebuilt binaries for all target platforms; if so, `prebuild-install` (and its abandoned transitive deps) may not run at all in production.
+
+9. **[Low] Pin `vitest` and `@vitest/coverage-v8` to matching patch versions** (`4.1.4`). The `^4.1.0` range means CI will auto-install the latest patch, but local developer environments may lag. Lock to a specific version to ensure consistent test environments across machines.
+
+10. **[Informational] No production bundle contamination detected.** All dev dependencies (`vitest`, `tsup`, `typescript`, `@types/*`) are correctly scoped to `devDependencies` and excluded from the published package. The only two production dependencies are `cron-parser` and `re2`, which is appropriately lean for a library.

package/.codekin/reports/docs-audit/2026-04-04_docs-audit.md

@@ -0,0 +1,10 @@
+# Documentation Audit: stepflow
+
+**Date**: 2026-04-04T05:50:31.890Z
+**Repository**: /srv/repos/stepflow
+**Branch**: main
+**Workflow Run**: 2acc3a04-1b4b-44a9-99d6-b90a2a3d5860
+**Session**: 56f3e016-4ada-4633-bc2b-bd2a3932d6ab
+
+---
+