@multiplier-labs/stepflow 0.3.4 → 0.3.8

package/dist/scheduler/index.d.ts

@@ -1,6 +1,6 @@
-export { C as CronScheduler, a as CronSchedulerConfig, P as PostgresSchedulePersistence, b as PostgresSchedulePersistenceConfig, S as SQLiteSchedulePersistence, c as SQLiteSchedulePersistenceConfig, d as SchedulePersistence, e as Scheduler, T as TriggerType, h as WorkflowSchedule } from '../index-Cd0IZ40L.js';
+export { C as CronScheduler, a as CronSchedulerConfig, P as PostgresSchedulePersistence, b as PostgresSchedulePersistenceConfig, S as SQLiteSchedulePersistence, c as SQLiteSchedulePersistenceConfig, d as SchedulePersistence, e as Scheduler, T as TriggerType, h as WorkflowSchedule } from '../index-CdXDv30T.js';
 import '../types-K5Gjk3H_.js';
-import '../types-DSEjiLMj.js';
+import '../types-BfWe5yP6.js';
 import '../types-DZUdWmCc.js';
 import 'better-sqlite3';
 import 'pg';

package/dist/scheduler/index.js

@@ -2,7 +2,7 @@ import {
   CronScheduler,
   PostgresSchedulePersistence,
   SQLiteSchedulePersistence
-} from "../chunk-FMPJBK2N.js";
+} from "../chunk-TVSADUYU.js";
 import "../chunk-JPXPB7U5.js";
 export {
   CronScheduler,

package/dist/storage/index.d.ts

@@ -1,7 +1,7 @@
-import { i as StorageAdapter, j as WorkflowRunRecord, d as ListRunsOptions, P as PaginatedResult, k as WorkflowRunStepRecord, W as WorkflowEventRecord, L as ListEventsOptions, C as CreateRunInput, U as UpdateRunInput, e as StepResult } from '../types-DSEjiLMj.js';
-export { E as ExtendedListRunsOptions, a as ExtendedRunStatus, b as ExtendedStepStatus, c as ExtendedWorkflowRunRecord, S as StepRecord, f as StepflowDatabase, g as StepflowRunsTable, h as StepflowStepResultsTable, l as WorkflowStorage } from '../types-DSEjiLMj.js';
+import { i as StorageAdapter, j as WorkflowRunRecord, d as ListRunsOptions, P as PaginatedResult, k as WorkflowRunStepRecord, W as WorkflowEventRecord, L as ListEventsOptions, C as CreateRunInput, U as UpdateRunInput, e as StepResult } from '../types-BfWe5yP6.js';
+export { E as ExtendedListRunsOptions, a as ExtendedRunStatus, b as ExtendedStepStatus, c as ExtendedWorkflowRunRecord, S as StepRecord, f as StepflowDatabase, g as StepflowRunsTable, h as StepflowStepResultsTable, l as WorkflowStorage } from '../types-BfWe5yP6.js';
 import Database from 'better-sqlite3';
-import { L as Logger } from '../types-K5Gjk3H_.js';
+import { Logger } from '../index.js';
 import { Kysely } from 'kysely';
 import { Pool, PoolConfig } from 'pg';
 
@@ -312,6 +312,7 @@ interface WorkflowRunsTable {
     input_json: string;
     metadata_json: string;
     context_json: string;
+    completed_steps_json: string | null;
     output_json: string | null;
     error_json: string | null;
     priority: number;
@@ -665,4 +666,5 @@ declare class PostgresTransactionAdapter extends PostgresStorageCore {
     protected get warnLabel(): string;
 }
 
-export { CreateRunInput, ListEventsOptions, ListRunsOptions, MemoryStorageAdapter, PaginatedResult, PostgresStorageAdapter as PostgresStorage, PostgresStorageAdapter, type PostgresStorageConfig, type PostgresStorageConfig as PostgresStorageOptions, PostgresTransactionAdapter, SQLiteStorageAdapter, type SQLiteStorageConfig, StepResult, StorageAdapter, UpdateRunInput, WorkflowEventRecord, WorkflowRunRecord, WorkflowRunStepRecord };
+export { CreateRunInput, ListEventsOptions, ListRunsOptions, MemoryStorageAdapter, PaginatedResult, PostgresStorageAdapter as PostgresStorage, PostgresStorageAdapter, PostgresTransactionAdapter, SQLiteStorageAdapter, StepResult, StorageAdapter, UpdateRunInput, WorkflowEventRecord, WorkflowRunRecord, WorkflowRunStepRecord };
+export type { PostgresStorageConfig, PostgresStorageConfig as PostgresStorageOptions, SQLiteStorageConfig };

package/dist/storage/index.js

@@ -3,7 +3,7 @@ import {
   PostgresStorageAdapter,
   PostgresTransactionAdapter,
   SQLiteStorageAdapter
-} from "../chunk-5XJBAPXF.js";
+} from "../chunk-4IDPWWGS.js";
 import "../chunk-JPXPB7U5.js";
 export {
   MemoryStorageAdapter,

package/dist/{types-DSEjiLMj.d.ts → types-BfWe5yP6.d.ts}

@@ -124,6 +124,7 @@ interface CreateRunInput {
     parentRunId?: string;
     input: Record<string, unknown>;
     context?: Record<string, unknown>;
+    completedSteps?: string[];
     metadata?: Record<string, unknown>;
     priority?: number;
     timeoutMs?: number;
@@ -134,6 +135,7 @@ interface CreateRunInput {
 interface UpdateRunInput {
     status?: ExtendedRunStatus;
     context?: Record<string, unknown>;
+    completedSteps?: string[];
     output?: Record<string, unknown>;
     error?: {
         code: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplier-labs/stepflow",
-  "version": "0.3.4",
+  "version": "0.3.8",
   "description": "A durable, type-safe workflow orchestration engine for Node.js with SQLite persistence, scheduling, and real-time events",
   "type": "module",
   "license": "MIT",
@@ -43,21 +43,25 @@
       "import": "./dist/scheduler/index.js"
     }
   },
+  "engines": {
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:package": "node scripts/check-package.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "cron-parser": "^5.5.0",
-    "re2": "^1.24.0"
+    "cron-parser": "^5.10.1",
+    "re2": "^1.27.0"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11.0.0",
-    "kysely": ">=0.28.16",
+    "kysely": ">=0.28.17",
     "pg": ">=8.13.0"
   },
   "peerDependenciesMeta": {
@@ -73,17 +77,25 @@
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.6.0",
     "@types/pg": "^8.18.0",
-    "@vitest/coverage-v8": "^4.1.4",
-    "better-sqlite3": "^12.8.0",
-    "kysely": "^0.28.16",
-    "pg": "^8.20.0",
-    "tsup": "^8.5.1",
-    "typescript": "^5.7.2",
-    "vitest": "^4.1.4"
+    "@vitest/coverage-v8": "^4.1.12",
+    "better-sqlite3": "^13.0.3",
+    "kysely": "^0.29.4",
+    "pg": "^8.23.0",
+    "tsup": "^9.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.12"
   },
   "overrides": {
-    "postcss": ">=8.5.10"
-  }
+    "postcss": ">=8.5.18",
+    "brace-expansion": ">=5.0.8",
+    "esbuild": ">=0.28.1",
+    "tar": ">=7.5.21",
+    "vite": ">=8.3.3",
+    "nanoid": "^3.3.17"
+  },
+  "files": [
+    "dist"
+  ]
 }

package/.codekin/reports/code-review/2026-04-11_code-review-daily.md

@@ -1,146 +0,0 @@
-# Daily Code Review: stepflow
-
-**Date**: 2026-04-11T02:46:56.903Z
-**Repository**: /srv/repos/stepflow
-**Branch**: main
-**Workflow Run**: 592ed81f-2d62-4608-bf34-98470c42c55b
-**Session**: 99646d28-b2e3-4d3a-bcdf-1478c0bc9eff
-
----
-
-Let me verify the most critical findings before writing the final report.Now I have enough detail to write the full report.
-
----
-
-## Daily Automated Code Review — `@multiplier-labs/stepflow` v0.2.6
-
-**Date**: 2026-04-11 | **Commit**: `bd16961` (Initial commit — only commit in repo)
-
----
-
-### Critical
-
-**None found.**
-
----
-
-### Warnings
-
-**[W1] Checkpoint resume derives completedStepKeys from context keys — fragile assumption**
-`src/core/engine.ts:569`
-```typescript
-const completedStepKeys = new Set(Object.keys(run.context));
-```
-`run.context` stores step results keyed by step key. If a step writes to context before throwing, its key will appear in context but the step didn't complete. On resume, that step would be silently skipped. There is no separate `completedSteps` log to distinguish "wrote result" from "finished cleanly."
-**Recommendation**: Track a dedicated `completedSteps: string[]` field in the persisted run record, written atomically with the step result, and use that set during resume.
-
----
-
-**[W2] `isBlockedIp` does not cover IPv6 reserved ranges beyond loopback and link-local**
-`src/events/webhook.ts:533–557`
-The resolved-IP check (`isBlockedIp`) handles IPv4 private ranges well, and blocks `::1` and `fe80:` for IPv6. However it does not block:
-- `fc00::/7` — Unique Local Addresses (ULA, the IPv6 equivalent of RFC 1918)
-- `ff00::/8` — Multicast
-- `2001:db8::/32` — Documentation range
-- `::ffff:0:0/96` — IPv4-mapped IPv6 addresses (could bypass IPv4 private range checks)
-
-`isBlockedHost` is more aggressive (blocks all bracket-wrapped IPv6 literals), so the static check is safe. But if `validateResolvedHost` receives a resolved IPv6 address in any format other than `[addr]`, the gap applies.
-**Recommendation**: In `isBlockedIp`, add IPv4-mapped check (`::ffff:` prefix) and ULA check (`/^f[cd]/i`).
-
----
-
-**[W3] `enqueueRequest` doesn't guard against `maxConcurrentRequests <= 0`**
-`src/events/webhook.ts:475–479`
-```typescript
-if (this.activeRequests < this.maxConcurrentRequests) {
-  execute();
-} else {
-  this.requestQueue.push(execute);
-}
-```
-If `maxConcurrentRequests` is set to `0` (or negative), the condition is never true and all requests queue forever — effectively a deadlock. There is no constructor validation.
-**Recommendation**: Add `if (maxConcurrentRequests <= 0) throw new Error('maxConcurrentRequests must be > 0')` in the constructor.
-
----
-
-**[W4] `withRetry` abort throws a generic `Error('Aborted')` instead of `WorkflowCanceledError`**
-`src/utils/retry.ts:83–85`
-```typescript
-if (opts.signal?.aborted) {
-  throw new Error('Aborted');
-}
-```
-The `sleep()` helper (line 58) correctly throws `WorkflowCanceledError` on abort, but the pre-attempt abort check throws a plain `Error`. Downstream error classification (e.g. `instanceof WorkflowCanceledError`) will fail for aborts caught before the first sleep.
-**Recommendation**: Change to `throw new WorkflowCanceledError('run')` to match the `sleep()` path.
-
----
-
-**[W5] Hook errors log without run context**
-`src/core/orchestrator.ts:258`
-```typescript
-logger.error('afterRun hook failed:', hookError);
-```
-The error is intentionally swallowed (correct behavior), but the log line has no `runId` or `kind`, making production debugging unnecessarily hard.
-**Recommendation**: `logger.error(\`afterRun hook failed for run ${runId}:\`, hookError)`
-
----
-
-**[W6] Integration and edge-case test coverage gaps**
-
-No integration tests exercise the full lifecycle across multiple adapters. Specific gaps:
-- Resume of a partially-completed run (directly relevant to W1 above)
-- `maxConcurrency` queuing with priority ordering
-- Webhook retries under network failure simulations
-- Scheduler DST-boundary cron behavior
-- Hook error recovery scenarios (`beforeRun`, `afterRun`, `onStepError` throwing)
-- SQLite transaction rollback verification
-
-The current test suite is unit-level and covers the happy path well, but these edge cases are where durable-execution bugs hide.
-
----
-
-### Info
-
-**[I1] CI workflow publishes without running tests**
-`.github/workflows/publish.yml:23–29`
-The publish job runs `npm ci` → `npm run build` → `npm publish`. There is no `npm test` or `npm run typecheck` step. A broken release could be published if tests are skipped.
-**Recommendation**: Add `- run: npm test` and `- run: npm run typecheck` between Install and Publish steps.
-
----
-
-**[I2] `calculateRetryDelay` is defined but never called internally**
-`src/utils/retry.ts:115–121`
-`withRetry` computes delay inline (`currentDelay * opts.backoff`) rather than calling `calculateRetryDelay`. The exported helper is a public API, but the internal inconsistency means the two can drift.
-**Recommendation**: Refactor `withRetry` to call `calculateRetryDelay` for the delay computation, or document that they are intentionally separate.
-
----
-
-**[I3] Peer dependency lower bounds are not tested**
-`package.json:57–71`
-`better-sqlite3>=11`, `kysely>=0.27`, `pg>=8.13` are wide ranges. Only the devDependency pinned versions are tested. If a consumer uses the minimum allowed version and it has a breaking API difference, the error surface is silent.
-**Recommendation**: Add a CI matrix job that installs minimum peer dependency versions and runs the test suite.
-
----
-
-**[I4] Short webhook secrets not warned against**
-`src/events/webhook.ts:24`
-The `secret` field accepts any string. A very short secret (< 16 bytes) produces a weak HMAC. The JSDoc example (`process.env.WEBHOOK_SECRET`) is good, but there is no runtime warning or minimum-length enforcement.
-**Recommendation**: Add a `secret.length < 16` warning log in `signPayload` at minimum, or throw in the constructor.
-
----
-
-**[I5] `retryDelay` in webhook config is not applied with backoff**
-`src/events/webhook.ts` — webhook retries use a fixed `retryDelay` with no backoff, while the core `withRetry` utility supports exponential backoff. This inconsistency means repeated webhook failures hammer the endpoint at a fixed rate.
-**Recommendation**: Either apply backoff to webhook retries (using the existing `withRetry` utility) or document the fixed-delay intent.
-
----
-
-### Summary
-
-| Severity | Count |
-|---|---|
-| Critical | 0 |
-| Warning | 6 |
-| Info | 5 |
-
-The codebase is well-structured with good TypeScript discipline, solid SSRF protection, and thoughtful SQLite query design. The top priorities are **W1** (checkpoint resume correctness) and **W4** (abort error type mismatch), both of which are correctness bugs rather than just style issues. **W2** is a security hardening gap. The CI publish-without-tests gap (**I1**) is a process risk worth closing quickly.

package/.codekin/reports/code-review/2026-04-13_code-review-daily.md

@@ -1,74 +0,0 @@
-# Daily Code Review: stepflow
-
-**Date**: 2026-04-13T01:32:56.537Z
-**Repository**: /srv/repos/stepflow
-**Branch**: main
-**Workflow Run**: 12fb929b-3da3-4e1b-a8fc-e9b497a0eb42
-**Session**: c3af596a-a1f0-43c3-922e-8ed0cd0562f0
-
----
-
----
-
-## Daily Code Review — 2026-04-13
-
-**Project:** `@multiplier-labs/stepflow` — TypeScript workflow orchestration library
-**Coverage:** 93.88% | **Recent changes:** Initial commit only (no incremental changes in 7 days)
-
----
-
-### CRITICAL (4)
-
-**C1 — Unhandled `JSON.parse()` in all storage adapters**
-`src/storage/sqlite.ts`, `src/storage/postgres.ts`, `src/scheduler/*-persistence.ts`
-Every row deserialization call is bare `JSON.parse()`. Corrupted DB rows will throw unhandled `SyntaxError` and crash the process. Wrap all calls in try-catch with safe fallbacks.
-
-**C2 — DNS lookup blocks event loop on every webhook send**
-`src/events/webhook.ts` ~line 417
-`validateResolvedHost()` calls `dns.lookup()` with no timeout, no caching. A stalling DNS resolver can hang the entire event loop for 30+ seconds. Add a per-call timeout (via `AbortController`) and a short-TTL cache.
-
-**C3 — No `shutdown()` method; timers are untracked**
-`src/core/engine.ts` ~lines 369–374
-`setTimeout` / `setImmediate` handles in `launchRun()` are never stored or cleared. The process cannot exit cleanly while delayed runs are pending. Implement `WorkflowEngine.shutdown()` that cancels all tracked handles.
-
-**C4 — Race condition in `waitForRun`**
-`src/core/engine.ts` ~lines 480–527
-Storage is polled _before_ subscribing to events. A run completing in that window emits an event that is never received, causing an infinite wait. Fix: subscribe first, then check storage; unsubscribe immediately if terminal.
-
----
-
-### WARNING (10)
-
-| # | File | Issue |
-|---|------|-------|
-| W1 | `package.json` deps | `npm audit`: `picomatch` (HIGH ReDoS) + `brace-expansion` (MODERATE hang). Run `npm audit fix`. |
-| W2 | `src/storage/postgres.ts:13-16` | 48 `any` casts — concentrated in lazy Kysely imports. Use conditional types or `unknown` + guards. |
-| W3 | `src/events/webhook.ts` | Webhook secret length not enforced despite docs recommending ≥ 32 bytes. Validate in `addEndpoint()`. |
-| W4 | `src/events/webhook.ts` | DNS validation is outside the retry loop — DNS failures skip all retry logic. Move inside loop. |
-| W5 | `src/scheduler/cron.ts:96-97` | `start()` after `stop()` can create duplicate subscriptions. Unconditionally unsubscribe at top of `start()`. |
-| W6 | `src/storage/postgres.ts` | PG connection pool not closed if adapter goes out of scope without explicit `close()`. Document + warn. |
-| W7 | `src/core/engine.ts:405-412` | No depth/count limit on `spawnChild()` — recursive workflows can spawn unboundedly. Add `maxChildDepth`. |
-| W8 | `src/core/orchestrator.ts:87-93` | `emitEvent()` called without error handling — transport failures can abort workflow execution. Wrap in try-catch. |
-| W9 | `src/scheduler/cron.ts` | Invalid persisted cron strings crash the scheduler on startup. Catch `CronExpressionParser.parse()` errors. |
-| W10 | `src/storage/sqlite.ts` | SQLite single-writer limitation not documented. Add prominent warning; recommend Postgres for multi-worker. |
-
----
-
-### INFO (5)
-
-- **I1** — Test files are very large (engine.test.ts: 1364 lines). Split by feature for maintainability.
-- **I2** — Resume/checkpoint semantics undocumented for distributed use (single-process only).
-- **I3** — `registerWorkflow()` doesn't validate `kind` format or duplicate step keys.
-- **I4** — Error stacks sanitized on write but not on read — defense-in-depth gap.
-- **I5** — No circuit breaker for consistently failing webhook endpoints.
-
----
-
-**Top 5 priorities:**
-1. `JSON.parse()` error handling in all storage adapters (C1)
-2. `WorkflowEngine.shutdown()` with timer cleanup (C3)
-3. Fix subscribe-then-check ordering in `waitForRun` (C4)
-4. `npm audit fix` for dep vulnerabilities (W1)
-5. DNS caching + timeout in webhook transport (C2/W4)
-
-Report saved to `.codekin/reports/code-review/2026-04-13_code-review-daily.md`.

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.