@multiplier-labs/stepflow 0.3.4 → 0.3.8

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/dependencies/2026-04-11_dependency-health.md

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

@@ -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
-
----
-

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

@@ -1,138 +0,0 @@
-# Documentation Audit: stepflow
-
-**Date**: 2026-04-11T02:47:05.901Z
-**Repository**: /srv/repos/stepflow
-**Branch**: main
-**Workflow Run**: 24ff56b6-9441-43f2-8563-c985920b774f
-**Session**: ba7bd622-3564-476e-976b-21918677f818
-
----
-
-Now I have enough information to write the complete report.
-
-## Summary
-
-**Audit date:** 2026-04-11 | **Repository:** `/srv/repos/stepflow` | **Branch:** `main`
-
-The repository contains **3 documentation files** totalling **2,167 lines**. All three share the same commit timestamp (`2026-04-11 05:43:05`) from the initial import, so git-log staleness analysis is not applicable — all docs and code landed together. Cross-referencing documentation claims against the actual TypeScript source reveals the documentation is largely accurate and comprehensive, with **2 confirmed accuracy issues** and **1 minor fragmentation observation**.
-
-**Health rating: Well-maintained** — minimal sprawl, no redundancy, nearly all claims verified against source.
-
----
-
-## Documentation Inventory
-
-| Path | Lines | Last Modified | Purpose | Status |
-|------|-------|---------------|---------|--------|
-| `README.md` | 408 | 2026-04-11 | Project overview, quick start, core concepts, feature tour, storage/event/scheduler options, planning system intro | Current |
-| `docs/github-packages-setup.md` | 97 | 2026-04-11 | Publish and consume `@multiplier-labs/stepflow` via GitHub Packages; CI/CD token setup | Current |
-| `docs/stepflow-api-reference.md` | 1,662 | 2026-04-11 | Full API reference: every class, interface, method signature, configuration option, PostgreSQL schema, integration patterns | Current (2 minor issues) |
-
----
-
-## Staleness Findings
-
-Because all documentation and source files share the same initial-commit timestamp, there is no temporal drift to report — no doc file predates its covered code or vice versa. No broken internal cross-links were found between the three files; the README's link to `docs/stepflow-api-reference.md` resolves correctly, and the GitHub Packages guide is self-contained.
-
-No references to non-existent file paths, removed CLI commands, or deprecated config keys were found in any of the three documents.
-
----
-
-## Accuracy Issues
-
-### Issue 1 — Non-existent `getSchedule()` method (confirmed)
-
-**File:** `docs/stepflow-api-reference.md`  
-**Location:** Scheduler section (approximate line 499)  
-**Claim:** Documents a `scheduler.getSchedule(scheduleId: string): Promise<WorkflowSchedule>` method.  
-**Reality:** The `Scheduler` interface in `src/scheduler/types.ts` defines only `getSchedules(): Promise<WorkflowSchedule[]>` (plural, no `scheduleId` parameter). The singular `getSchedule(id)` does not exist on the interface.  
-**Impact:** Any developer who copies the shown usage will get a TypeScript compile error and runtime failure.
-
-### Issue 2 — `getInterruptedRuns()` method needs verification
-
-**File:** `docs/stepflow-api-reference.md`  
-**Location:** Storage adapter section (approximate line 785)  
-**Claim:** References `storage.getInterruptedRuns()` on `SQLiteStorageAdapter`.  
-**Reality:** This method does not appear in the `StorageAdapter` interface (`src/storage/types.ts`) nor in the `WorkflowStorage` interface. It may be an undocumented implementation-only method, a leftover reference to a removed method, or a documentation invention. Requires reading `src/storage/sqlite.ts` to confirm.  
-**Impact:** Medium — if the method does not exist, documented usage will fail at compile time.
-
-### Everything Else — Verified Accurate
-
-All of the following were cross-checked against source and match exactly:
-
-- All exported names in `src/index.ts` match the TypeScript Types Reference section in the API reference.
-- All `RunStatus`, `StepStatus`, `StepErrorStrategy` union literal values are correct.
-- All `WorkflowContext`, `WorkflowStep`, `WorkflowHooks`, `WorkflowDefinition` interface properties and types are correct.
-- All `StorageAdapter` and `WorkflowStorage` method signatures are correct.
-- All 14 `BuiltInEventType` literals are correct.
-- All `EventTransport` method signatures are correct.
-- All `WorkflowSchedule` properties and `Scheduler` interface methods (except the `getSchedule` issue above) are correct.
-- All 10 `ConditionOperator` values, all `Recipe`, `Plan`, `PlannedStep` interfaces are correct.
-- All 9 error class names, error codes, and constructor signatures are correct.
-- `WorkflowEngineConfig` and `StartRunOptions` interfaces are correct.
-- `package.json` scripts (`build`, `dev`, `typecheck`, `test`, `test:watch`, `test:coverage`) match README claims.
-- Peer dependency versions (`better-sqlite3 >=11.0.0`, `kysely >=0.27.0`, `pg >=8.13.0`) match `package.json`.
-- Package name `@multiplier-labs/stepflow` and subpath exports (`/storage`, `/events`, `/scheduler`) are correct throughout all docs.
-
----
-
-## Overlap & Redundancy
-
-There is no meaningful overlap between the three files. Each occupies a distinct lane:
-
-- `README.md` — conceptual overview and feature tour (prose-heavy, code snippets for motivation)
-- `docs/github-packages-setup.md` — ops/distribution concern (PAT setup, CI/CD tokens, `npm version`)
-- `docs/stepflow-api-reference.md` — exhaustive technical reference
-
-Both `README.md` and `docs/stepflow-api-reference.md` contain a Quick Start section, but they use different examples (order-processing workflow vs. email-campaign workflow) and serve different readers (README = first-time evaluator, API ref = returning developer). This is a reasonable design choice, not a redundancy problem.
-
-**No merge recommendations are warranted.**
-
----
-
-## Fragmentation
-
-With only 3 files, fragmentation is not a concern. The split between README and API reference follows widely accepted open-source convention. The GitHub Packages setup guide is appropriately separated as a distribution/ops concern that would clutter the main README.
-
-No spec, proposal, or planning documents exist in the repo. No "completed feature" spec files need to be folded in or removed.
-
----
-
-## Action Items
-
-### Delete
-
-| File | Reason it's safe to delete |
-|------|----------------------------|
-| — | No deletion candidates. All three files serve distinct, active purposes. |
-
-### Consolidate
-
-| Source Files | Target File | What to Keep / Drop |
-|---|---|---|
-| — | — | No consolidation needed. Files do not overlap in scope. |
-
-### Update
-
-| File | Section Needing Update | What Changed |
-|------|------------------------|--------------|
-| `docs/stepflow-api-reference.md` | Scheduler section — `getSchedule(scheduleId)` method | Remove or replace with correct `getSchedules(): Promise<WorkflowSchedule[]>`. The documented method does not exist on the `Scheduler` interface. |
-| `docs/stepflow-api-reference.md` | Storage section — `getInterruptedRuns()` on `SQLiteStorageAdapter` | Verify against `src/storage/sqlite.ts`. If the method no longer exists or was never part of the public interface, remove the reference. If it's an implementation detail not on the interface, add a note clarifying it is not part of the `StorageAdapter` contract. |
-
----
-
-## Recommendations
-
-1. **Fix `getSchedule()` → `getSchedules()`** in `docs/stepflow-api-reference.md`. This is a confirmed broken API reference that will cause compile errors if followed. One-line fix.
-
-2. **Verify `getInterruptedRuns()`** by reading `src/storage/sqlite.ts`. If the method is absent, delete the reference. If present, ensure it is either promoted to the `StorageAdapter` interface (if intentionally public) or marked as an internal implementation detail.
-
-3. **Add a version changelog or `CHANGELOG.md`** if the package begins publishing new minor/major versions. Currently at `0.2.6`, with no changelog. As the API stabilises this becomes important for downstream consumers to understand what changed between releases.
-
-4. **Pin documented peer-dependency versions in the API reference.** The reference correctly lists minimum versions but does not mention tested/recommended ranges. As `better-sqlite3`, `kysely`, and `pg` release new majors, this becomes a source of drift. Consider a compatibility table or tested-with note.
-
-5. **Add a `CONTRIBUTING.md` or development-setup section** for contributors. The `package.json` has `dev`, `test`, `build`, and `typecheck` scripts, but there is no document explaining how to run the test suite locally, set up a Postgres instance for integration tests, or submit changes. This gap matters as the project gains external contributors.
-
-6. **Keep `docs/github-packages-setup.md` updated on PAT scope requirements.** GitHub periodically revises fine-grained PAT scopes. The current instructions reference `read:packages` — this is correct today, but is the most likely part of that document to go stale.
-
-7. **Consider lightweight doc-testing** (e.g., extracting TypeScript code blocks and running `tsc --noEmit` on them as part of CI). The one confirmed accuracy issue (`getSchedule`) would have been caught automatically if the Quick Start and integration examples were compiled as part of the build.

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

@@ -1,121 +0,0 @@
-# Documentation Audit: stepflow
-
-**Date**: 2026-04-13T01:17:34.517Z
-**Repository**: /srv/repos/stepflow
-**Branch**: main
-**Workflow Run**: 54339665-09b6-4e19-8981-c8fc3144a296
-**Session**: 386a6c34-ce83-4c68-a8e7-e668435ced26
-
----
-
-Now I'll produce the final structured report based on the audit findings.
-
-## Summary
-
-**Total documentation files:** 3 (2,167 lines total)
-**Files needing attention:** 1 (minor — one missing error class entry)
-**Health rating:** Well-maintained
-
-The repository has a lean, focused documentation set: one root README, one GitHub Packages setup guide, and one comprehensive API reference. All three files share the same last-modified date (2026-04-11, the initial commit), so there is no divergence between doc age and code age. Code examples, configuration keys, export paths, and API signatures were cross-checked against the source and are accurate. The only finding is a single missing entry in the error-class table.
-
----
-
-## Documentation Inventory
-
-| Path | Lines | Last Modified | Purpose | Status |
-|------|-------|--------------|---------|--------|
-| `README.md` | 408 | 2026-04-11 | Project overview, quick-start, install, basic usage examples | Current |
-| `docs/github-packages-setup.md` | 97 | 2026-04-11 | Instructions for authenticating with and publishing to GitHub Packages NPM registry | Current |
-| `docs/stepflow-api-reference.md` | 1,662 | 2026-04-11 | Complete API reference: WorkflowEngine, storage adapters, event transports, scheduler, planner, error types, TypeScript types | Current (1 omission) |
-
----
-
-## Staleness Findings
-
-No staleness issues detected. All three documentation files were committed in the initial commit (2026-04-11) alongside the source code they describe. There is only one commit in the repository (`bd16961 Initial commit`), so no code has changed after the docs were written.
-
-No broken internal links were found:
-- `README.md` references `docs/github-packages-setup.md` — file exists.
-- `README.md` references `docs/stepflow-api-reference.md` — file exists.
-- All markdown anchor links (`#error-classes`, `#workflow-engine`, etc.) resolve to sections present in their respective files.
-
----
-
-## Accuracy Issues
-
-**Issue 1 — Missing error class in API Reference**
-
-`WaitForRunTimeoutError` is exported from `src/index.ts` and implemented in `src/utils/errors.ts`, but it does not appear in the error-class table in `docs/stepflow-api-reference.md` (the table covers eight error types; this is the ninth).
-
-- **Exported symbol:** `WaitForRunTimeoutError` with code `WAIT_FOR_RUN_TIMEOUT`, constructor signature `(runId, timeoutMs)`.
-- **Where it is thrown:** `WorkflowEngine.waitForRun()` when the timeout elapses before the run completes.
-- **Impact:** Users who encounter this error and search the API reference will not find it documented.
-
-**Issue 2 — Storage adapter naming ambiguity (very minor)**
-
-The TypeScript types section mentions both `StorageAdapter` and `WorkflowStorage` interfaces without explaining that `WorkflowStorage` is the extended/current interface while `StorageAdapter` is the narrower legacy surface. This distinction is inferable from the source but is not stated in the docs.
-
-No issues were found with:
-- Install / setup instructions (match `package.json` scripts and peer deps).
-- Subpath export paths (`/storage`, `/events`, `/scheduler`) — all match `package.json` `exports` field.
-- Code examples for `WorkflowEngine`, storage adapters, event transports, scheduler, and planner.
-- All nine documented config keys for `WorkflowEngineConfig`, `PostgresStorageConfig`, and `SQLiteStorageConfig`.
-
----
-
-## Overlap & Redundancy
-
-No meaningful overlap exists across the three files. Each file occupies a distinct niche:
-
-- `README.md` — orientation and quick-start; deliberately high-level.
-- `docs/github-packages-setup.md` — operational runbook for package publishing; not replicated elsewhere.
-- `docs/stepflow-api-reference.md` — exhaustive API detail; README does not duplicate it.
-
-The README links to the API reference rather than reproducing its content, which is the correct pattern.
-
-**No merge or deletion actions are warranted on overlap grounds.**
-
----
-
-## Fragmentation
-
-No fragmentation detected. The documentation set is already consolidated: three files covering three distinct concerns. There are no orphaned spec documents, proposal files, or feature-design docs in the repository. The `docs/` directory contains exactly two files, both purposeful and non-overlapping.
-
-No "plan" or "proposal" documents describing completed work were found.
-
----
-
-## Action Items
-
-### Delete
-
-| File | Reason |
-|------|--------|
-| *(none)* | No files are outdated, superseded, or describe completed proposals with no reference value. |
-
-### Consolidate
-
-| Source Files | Target File | Notes |
-|-------------|-------------|-------|
-| *(none)* | — | No consolidation needed; the current three-file structure is appropriate. |
-
-### Update
-
-| File | Section Needing Update | What Changed |
-|------|----------------------|--------------|
-| `docs/stepflow-api-reference.md` | Error Classes table | Add missing `WaitForRunTimeoutError` entry: code `WAIT_FOR_RUN_TIMEOUT`, constructor `(runId, timeoutMs)`, thrown by `waitForRun()` on timeout. |
-| `docs/stepflow-api-reference.md` | TypeScript Types Reference | Add a one-sentence note clarifying that `WorkflowStorage` is the current extended interface and `StorageAdapter` is the narrower legacy one, so users know which to implement. |
-
----
-
-## Recommendations
-
-1. **Add `WaitForRunTimeoutError` to the error-class table** in `docs/stepflow-api-reference.md`. It is exported, thrown at a documented public API boundary (`waitForRun`), and its absence is the only real gap in API coverage.
-
-2. **Clarify `StorageAdapter` vs `WorkflowStorage`** in the TypeScript types section — a single sentence noting which is the current recommended interface and which is the narrower legacy surface will prevent confusion for implementors.
-
-3. **Add a `CHANGELOG.md` or version-history section** to `README.md` as the project evolves past v0.2.6. The current single-commit history makes this unnecessary now, but without it, future contributors will have no changelog to update when they introduce breaking changes.
-
-4. **Protect documentation accuracy through CI.** Because the repository has no docs-linting step, future code changes could silently invalidate examples. Consider adding a `docs:check` script (e.g., `markdownlint`, `markdown-link-check`) to the GitHub Actions workflow so broken links and formatting regressions are caught automatically.
-
-5. **Keep the three-file structure.** The current organisation (`README.md` + `docs/github-packages-setup.md` + `docs/stepflow-api-reference.md`) is clean and proportional to the codebase size. Resist splitting the API reference into per-module files until the reference exceeds ~3,000 lines or the docs audience clearly segments by module.