@multiplier-labs/stepflow 0.3.3 → 0.3.6

package/.codekin/reports/comments/2026-04-04_comment-assessment.md

@@ -1,179 +0,0 @@
-# Comment Assessment: stepflow
-
-**Date**: 2026-04-04T06:59:29.464Z
-**Repository**: /srv/repos/stepflow
-**Branch**: main
-**Workflow Run**: c4721f8a-9287-4e91-b3a7-17151c71b861
-**Session**: 0bf68b75-f778-4c55-9c9d-a011d10130be
-
----
-
-Now I have a thorough picture of the codebase. Let me produce the final report.
-
-## Summary
-
-**Language**: TypeScript (strict mode) | **Files**: 43 source files (~14,000 LoC) | **Modules**: core, storage, events, scheduler, planning, utils
-
-Overall comment coverage is **high** — approximately **90%** of public API surface is documented, and ~70% of complex logic has inline explanation. The codebase demonstrates professional-grade JSDoc discipline: every exported type, interface, config object, and error class carries a doc comment. File-level module comments are present on nearly every file. The main gaps are a duplicated/misplaced JSDoc block in `postgres.ts`, thin coverage on a handful of `StorageAdapter` implementation methods, and the absence of `@param`/`@returns` tags on several private helpers. Test files are undocumented, which is standard practice but leaves intent implicit for complex scenarios.
-
-**Overall rating: 8.5 / 10**
-
----
-
-## Well-Documented Areas
-
-### `src/core/orchestrator.ts`
-Exemplary documentation. The two private helpers `executeWithTimeout` and `raceWithAbort` carry unusually thorough comments explaining *why* the `finally` cleanup blocks exist (memory-leak prevention, listener accumulation). The module-level JSDoc accurately describes the file's role. Inline comments mark every logical phase of `executeWorkflow` and `executeStep` (checkpoint resume, cancellation checks, error strategy branching).
-
-```typescript
-/**
- * Execute a function with a timeout.
- *
- * Uses Promise.race to resolve as soon as either the function completes, the
- * timeout fires, or the abort signal triggers. The `finally` block is critical:
- * without it, the losing promise's timer/listener would remain active, leaking
- * memory — especially problematic in long-running engines processing many steps.
- */
-```
-
-### `src/utils/retry.ts`
-Every exported symbol has full JSDoc with `@param`, `@returns`, and `@throws` tags. The `sleep` function documents its cancellation contract. `DEFAULT_RETRY_OPTIONS` is explicitly exported and described. A closing comment on the unreachable branch (`// This should never be reached, but TypeScript needs it`) is an honest and useful annotation.
-
-### `src/core/types.ts`
-All foundational types are documented. `StepErrorStrategy` includes inline prose describing the effect of each union member:
-```typescript
-/**
- * - 'fail': Stop the workflow immediately
- * - 'retry': Retry the step up to maxRetries times
- * - 'skip': Mark as skipped and continue to next step
- */
-```
-
-### `src/utils/errors.ts`
-Each of the eight custom error classes has a one-line JSDoc that clearly states the triggering condition. `WorkflowEngineError.fromError` documents its fallback behavior.
-
-### `src/storage/postgres.ts` — configuration and schema sections
-`PostgresStorageConfig` has `@example` blocks for both the basic and shared-pool cases. Kysely row types (`WorkflowRunsTable`, `WorkflowRunStepsTable`, etc.) document every column inline, including semantic meaning, units, and null semantics. The `qb` getter explains the schema-scoping invariant.
-
-### `src/utils/postgres-deps.ts`
-The lazy-loader pattern is precisely explained in the file-level comment, and the `@throws` tags on `loadPostgresDeps` enumerate both failure modes. The `// any is intentional here` comment pre-empts reviewer questions about the `PostgresDeps` interface.
-
-### `src/events/socketio.ts`
-`setupClientHandlers` includes a full `@example` block showing correct usage including the authorization callback pattern. The `close()` method clarifies that the underlying Socket.IO socket lifecycle is the caller's responsibility.
-
-### `src/planning/planner.ts` — `scoreConditions`
-The scoring formula comment is unusually transparent:
-```typescript
-// Base score 50 ensures condition-matched recipes beat unconditional defaults (score 10).
-// Each additional condition adds 10 points, capped at 100 so forced recipes (100) still win.
-```
-
-### `src/utils/id.ts`
-Despite being a single exported function, it documents the ID format, design rationale (time-ordering, collision resistance, URL safety), and the approximate output length.
-
----
-
-## Underdocumented Areas
-
-| File | Issue | Severity |
-|---|---|---|
-| `src/storage/postgres.ts:563–565` | Two JSDoc blocks stacked immediately on top of each other (`listRuns` doc + `applyRunsFilters` doc) with no actual method between them; the `listRuns` method itself gets the private helper's comment, and `listRuns` is effectively undocumented | High |
-| `src/storage/postgres.ts:516–524` | `getRun`, `createStep`, `getStep`, `updateStep`, `getSteps`, `createEvent`, `listEvents` — none have JSDoc; only `createRun`, `updateRun`, and `listRuns` are documented | High |
-| `src/core/engine.ts:109–119` | `QueuedRun` interface is documented but the `WorkflowEngine` class declaration at line 121 has no JSDoc block (the preceding `@example` block belongs to a dangling doc comment from the closing `*/` of the example at line 107, making it visually orphaned) | High |
-| `src/storage/types.ts:80–200` | `WorkflowEventRecord`, `StepResult`, `StepRecord`, `CreateRunInput`, `UpdateRunInput`, `StorageAdapter` interface and all its method signatures lack individual JSDoc; only the top-level record types are documented | Medium |
-| `src/scheduler/cron.ts` (internal methods) | Private methods `checkAndTriggerSchedules`, `handleWorkflowCompletionTriggers`, `calculateNextRun` have no JSDoc; the polling and event-subscription architecture is not explained | Medium |
-| `src/core/engine.ts:324–332` | `executeRun` is documented as "Execute a run (internal method)" with no detail; it is a thin wrapper that calls `launchRun` — the indirection is unexplained | Medium |
-| `src/storage/sqlite.ts` | `createStep`, `updateStep`, `getSteps`, `createEvent`, `listEvents` methods lack JSDoc; only configuration types are documented | Medium |
-| `src/planning/registry.ts` | `MemoryStepHandlerRegistry` and `MemoryRecipeRegistry` class-level JSDoc is absent; method comments are single-line but several complex query methods (e.g., `getByKind`, `getVariant`) have no parameter documentation | Medium |
-| `src/events/webhook.ts` | `WebhookEventTransport` class body is not visible in sampling; retry/backoff logic for failed webhook deliveries is expected to lack inline explanation based on surrounding pattern | Medium |
-| `src/storage/memory.ts:67–200` | `listRuns` filter/sort/pagination logic has inline `// Filter by X` headers but no explanation of sort stability guarantees or edge-case behaviour (e.g., null `startedAt`) | Low |
-| `src/scheduler/sqlite-persistence.ts` | Prepared-statement initialization pattern (using `stmts` nullable object) is not commented; the reason for lazy initialization vs. constructor setup is implicit | Low |
-| `src/utils/logger.ts` | `sanitizeErrorForStorage` is exported but has no JSDoc — its role (stripping sensitive fields before DB writes) is non-obvious from the name alone | Low |
-| `src/core/engine.ts` (test files) | `src/core/engine.test.ts` has no describe-level comments explaining what scenario each test group targets; complex concurrency and resume tests lack rationale comments | Low |
-| `src/storage/types.ts` | `ExtendedRunStatus` and `ExtendedStepStatus` comment says "New" but those are likely legacy designations now; no explanation of when to use extended vs. core status types | Low |
-| `src/planning/types.ts` | `PlanModificationType` union values (`'add_step'`, `'remove_step'`, `'modify_step'`, `'set_default'`) are not individually annotated with their intended semantics | Low |
-
----
-
-## Comment Quality Issues
-
-**1. Stacked / orphaned JSDoc block — `src/storage/postgres.ts:563–568`**
-
-```typescript
-  /**
-   * List workflow runs with filtering and pagination.
-   */
-  /**
-   * Apply common run filters to a Kysely query builder.
-   * Used by both the data query and count query in listRuns to avoid duplication.
-   */
-  private applyRunsFilters<T ...>(
-```
-
-Two `/** */` blocks appear consecutively. TypeScript/JSDoc tooling attaches the *last* block to the declaration, meaning `listRuns` (a public method) loses its documentation entirely and only the private helper `applyRunsFilters` gets a comment. The public method's JSDoc is silently discarded. This is a bug in the comment structure.
-
-**2. `WorkflowEngine` class body starts without a JSDoc — `src/core/engine.ts:109–121`**
-
-The `@example` closing marker at line 107 (`*/`) is followed by the undocumented `QueuedRun` interface, then the `export class WorkflowEngine` at line 121 with no doc comment of its own. The intended class-level JSDoc (lines 83–108) is rendered as a freestanding comment, not as attached JSDoc for `WorkflowEngine`. IDEs will not show hover documentation for the class constructor.
-
-**3. `StorageAdapter.listRuns` — `src/storage/types.ts` (approximately line 130–160)**
-
-The `StorageAdapter` interface lists all method signatures but provides no per-method JSDoc. A consumer implementing the interface receives no guidance on whether `listRuns` should be transactional, whether filters are AND- or OR-combined, or what an empty result looks like.
-
-**4. `cancelRun` comment inaccuracy — `src/core/engine.ts:444`**
-
-```typescript
-// Update status in storage (the orchestrator will also update on completion)
-await this.storage.updateRun(runId, { status: 'canceled', finishedAt: new Date() });
-```
-
-The comment says "the orchestrator will also update on completion" but when `cancelRun` is called, the orchestrator may not be running (if the run was still queued). The comment implies a double-write that is only sometimes true, which could mislead a reader investigating status inconsistencies.
-
-**5. `ensureInitialized` — `src/storage/postgres.ts:246`**
-
-This private guard method has no JSDoc. Since it throws on un-initialized state, documenting the throw condition would aid callers implementing `StorageAdapter`.
-
-**6. `ExtendedRunStatus` comment — `src/storage/types.ts:12–23`**
-
-```typescript
-/**
- * Extended status of a workflow run.
- * Adds 'pending' and 'timeout' to the core statuses.
- */
-```
-
-`RunStatus` (core) already includes `'queued'` and `'running'`; `ExtendedRunStatus` adds `'pending'` and `'timeout'`. The comment correctly notes the additions, but gives no guidance on *when* a consumer should use `ExtendedRunStatus` vs. `RunStatus` — the distinction between the two parallel type hierarchies is undocumented.
-
----
-
-## Recommendations
-
-**1. Fix the stacked JSDoc block in `src/storage/postgres.ts:563–568`**
-Remove or merge the orphaned `listRuns` JSDoc into a single block placed directly above the `async listRuns(...)` method declaration. The `applyRunsFilters` private helper should retain its own comment, but it should immediately precede that private method, not `listRuns`. This is a correctness issue: as written, `listRuns` is invisible to IDE hover and documentation generators.
-
-**2. Attach the `WorkflowEngine` class-level JSDoc in `src/core/engine.ts`**
-The `@example` block (lines 83–107) and the `QueuedRun` interface (lines 109–119) currently sit between the intended class doc and the class declaration. Move `QueuedRun` above the class-level JSDoc, or place the class JSDoc immediately before `export class WorkflowEngine` at line 121. Without this fix, TypeScript language servers do not display hover documentation for the class or its constructor.
-
-**3. Add JSDoc to `StorageAdapter` method signatures in `src/storage/types.ts`**
-The `StorageAdapter` interface is the primary extension point for library consumers implementing custom backends. Document at minimum: `createRun`, `updateRun`, `listRuns` (note AND semantics for filters), `createStep`, `updateStep`, and `createEvent`. Include `@param` descriptions and `@returns` contracts. This directly impacts third-party adapter authors.
-
-**4. Document `sanitizeErrorForStorage` in `src/utils/logger.ts`**
-This exported utility performs security-sensitive work (scrubbing error objects before persistence), but it has no JSDoc. A doc comment should state what fields are removed (e.g., `stack`), why (storage size / privacy), and what the return type contract is. Its current name gives no indication it performs sanitization beyond what the type system shows.
-
-**5. Document the `ExtendedRunStatus` / `RunStatus` dual hierarchy in `src/storage/types.ts`**
-Add a comment block before `ExtendedRunStatus` explaining when each type should be used (e.g., "Use `RunStatus` for the core engine; use `ExtendedRunStatus` when working with the extended storage schema which includes `pending` and `timeout`"). This prevents consumers from accidentally mixing the two.
-
-**6. Add inline comments to `CronScheduler`'s internal scheduling loop in `src/scheduler/cron.ts`**
-The private methods responsible for polling (`checkAndTriggerSchedules`), event-based triggering (`handleWorkflowCompletionTriggers`), and next-run calculation (`calculateNextRun`) contain the most nuanced logic in the scheduler module (timezone handling, cron expression parsing, status matching). Each should have at minimum a one-paragraph JSDoc explaining its role and any non-obvious invariants (e.g., why the poll interval is 1 second by default, how `lastRunAt` prevents double-firing).
-
-**7. Fix the `cancelRun` comment inaccuracy in `src/core/engine.ts:444`**
-Replace `// Update status in storage (the orchestrator will also update on completion)` with a comment that accurately reflects the dual-write scenario: the orchestrator updates status when it catches `WorkflowCanceledError`, but this pre-emptive write ensures the status is visible immediately and handles the case where the run was queued (never started). This removes a misleading implication about guaranteed orchestrator involvement.
-
-**8. Add JSDoc to `getRun`, `createStep`, `updateStep`, and `listEvents` in `src/storage/postgres.ts`**
-These `StorageAdapter` implementation methods (~lines 516–750) have no doc comments, unlike `createRun`, `updateRun`, and `listRuns`. At minimum, note any PostgreSQL-specific behaviour that differs from the `MemoryStorageAdapter` (e.g., JSON serialization round-trips, `null` vs. `undefined` handling for optional fields).
-
-**9. Annotate `PlanModificationType` union values in `src/planning/types.ts`**
-The four modification types (`'add_step'`, `'remove_step'`, `'modify_step'`, `'set_default'`) are used in the planner output to describe what was changed, but their intended semantics are not documented. Add inline comments (or expand the type into a documented discriminated union) so that consumers of `Plan.modifications` know how to interpret and render each modification type.
-
-**10. Add a brief rationale comment in `src/core/engine.ts:568–574` (`resumeRun` checkpoint logic)**
-The line `const completedStepKeys = new Set(Object.keys(run.context))` silently encodes a convention: that the `context` object's keys are exactly the completed step keys. This is a non-obvious coupling between the orchestrator's checkpoint-save strategy (`storage.updateRun(runId, { context: { ...context.results } })`) and the resume logic. A one-line comment (`// context keys == completed step keys by orchestrator checkpoint convention`) would make this invariant explicit and prevent it from being accidentally broken.

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

@@ -1,152 +0,0 @@
-# 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/dependencies/2026-04-04_dependency-health.md

@@ -1,94 +0,0 @@
-# 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/docs-audit/2026-04-04_docs-audit.md

@@ -1,10 +0,0 @@
-# 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
-
----
-