akm workflow engine — third-party library survey

Date: 2026-08-01. Scope: find a TS/JS library measurably better than the two already under review (bunqueue, openworkflow — deliberately excluded here) for replacing akm's hand-rolled engine in src/workflows/.

0. What akm actually needs (measured from the code)

Sizes (wc -l, MPL-2.0 headers included):

Hard requirements read out of the code, not assumed:

1. Short-lived process, no daemon. akm workflow run is a one-shot CLI. The header of /home/user/akm/src/workflows/exec/run-workflow.ts documents an explicit drain of child-process handles so the event loop closes and the process exits — there is no resident engine and adding one is a regression.
2. SQLite already is the journal. workflow_runs, workflow_run_steps, workflow_run_units in state.db, all raw SQL in /home/user/akm/src/storage/repositories/workflow-runs-repository.ts, migrated by /home/user/akm/src/storage/engines/sqlite-migrations.ts.
3. Multi-process safety by lease, not by singleton. 90-second engine_lease_holder/engine_lease_until on the run row; expired leases are claimable (crash recovery); a second workflow run on a live-leased run refuses. Concurrent read-only akm workflow brief runs against the same DB by design.
4. Content-derived unit identity for resume. <node_id>:<sha256(canonicalJson(item))[:12]> — resume reuses journaled results even if the producer re-emits items in a different order. This is stronger than the position/replay identity every generic engine uses.
5. A frozen data plan, not code-defined workflows. IR v3 (/home/user/akm/src/workflows/ir/schema.ts): unit | agent | map | gate nodes, route specs, per-engine frozen concurrency caps, plan_hash integrity, budget caps. Authored as YAML/markdown, compiled and frozen into plan_json. Every generic library expects workflows expressed as TypeScript functions.
6. A harness-neutral external driver protocol. brief.ts (713) + report.ts (1,977) let an outside agent session execute units and report back, producing byte-identical unit graphs to the native engine. 2,690 LOC that no library has any analogue for.
7. Zero-native-addon distribution. Runtime deps are 7 tiny pure-JS packages; better-sqlite3 is optional. .github/workflows/release.yml compiles bun-linux-x64/arm64, bun-darwin-x64/arm64, bun-windows-x64 via bun build --compile. A hard native dependency breaks the standalone binary.
8. Long-running steps. Units are LLM/agent invocations with per-invocation timeoutMs up to 2**31-1 ms.
9. MPL-2.0 distribution — needs MIT/Apache-2.0/BSD/ISC.

The generic, library-shaped slice of exec+ir is small: scheduler.ts (118) + the lease/resume plumbing inside run-workflow.ts (~325 of 814) + retry/concurrency wiring inside native-executor.ts (~130 of 1,334) ≈ 570 LOC ≈ 6.5 % of exec+ir. Everything else is akm's authoring format, its gate semantics, its prompt/artifact model, and its driver protocol.

1. Eliminated on the no-server constraint (one line each, verified)

2. Eliminated on the storage constraint

3. Eliminated as "not orchestrators"

4. Candidates evaluated in full

Rubric: server-free embed / SQLite durability + resume / orchestration primitives / long-step tolerance / maturity / % of exec+ir replaced.

4.1 Weft — @lostgradient/weft@0.16.0 (MIT)

The only library found that was designed for akm's runtime shape.

• Bun-native (engines: {bun: ">=1.3.13"}), 4.6 MB, deps zod + @msgpack/msgpack.
• Storage adapters are subpath exports, including ./storage/sqlite/bun — i.e. bun:sqlite, no native addon, which is the one thing LangGraph gets wrong. Also ./storage/sqlite/node, lmdb, turso, neon, postgres, http, memory.
• Checkpoint-per-yield* (state snapshot, no replay-determinism constraint), so a 30-minute LLM step is fine.
• Primitives: ctx.all(), ctx.race()/raceKeyed(), activity retry policies, ctx.sleep() durable timers, ctx.waitUntil(pred, timeout), waitForSignal(), mutex + semaphore.
• Windows: bun build --compile targets include windows-x64 — matches akm's release matrix exactly.

Killer flaw — the concurrency model is the opposite of akm's. From the README: "Run a single engine per durable store; pointing two at the same store is not yet coordinated and can double-resume a workflow", plus "Engine.create() recovers by default after registering workflow definitions, so fresh processes resume persisted running workflows". For akm that means every akm workflow run <x> boot would auto-resume every persisted running workflow, and two overlapping CLI invocations can double-execute. akm's 90-second run lease exists precisely to make N short-lived processes safe against one SQLite file; Weft has no equivalent and tells you to enforce singleton-ness "in infrastructure". Docs also state the server runtime is Bun-only for this launch line.

Maturity — disqualifying for a shipping CLI. GitHub stevekinney/weft: 7 stars, 1 fork, sole maintainer, bus factor 1. npm: first publish 2026-06-03, 16 versions, latest 2026-07-25 — eight weeks old. Explicitly pre-1.0 with an experimental/candidate-stable tier split and an incomplete "Tier-0". 1,065 commits in 8 weeks by one person is a velocity profile that is as likely to be abandoned as to reach 1.0.

4.2 Mastra workflows — @mastra/core@1.55.0 + @mastra/libsql@1.18.0 (Apache-2.0)

• Genuinely server-free for embedding: mastra dev is an optional playground; the workflow engine runs in-process via workflow.createRunAsync().
• Storage is pluggable; @mastra/libsql wraps @libsql/client and takes a file: URL, so local SQLite durability is real and supported. Snapshots survive restarts; workflow.getWorkflowRunById() + createWorkflowStateReader() recover a run in a brand-new process.
• Control flow: .then/.parallel/.branch/.dowhile/.dountil/.foreach({concurrency}), step retries, suspend/resume. Good coverage of akm's unit/map/route.
• License fine. Maintained (1,437 releases since Oct 2024).

Why it does not win:

• Durability model mismatch. Mastra's snapshots are written on suspend (suspend(), sleep(), human-in-the-loop). It has no run lease, no crash-recovery daemon, and no per-unit idempotency key equivalent to akm's content-derived sha256(item) unit ids. akm would keep hand-rolling exactly the parts it already hand-rolls.
• Weight is disqualifying for this CLI. @mastra/core alone is 59 MB unpacked / 2,862 files / 31 runtime deps, including three parallel copies of the AI SDK provider layer (@ai-sdk/provider-v5/v6/v7), execa, ws, @modelcontextprotocol/sdk, and posthog-node (vendor telemetry). akm's entire runtime dependency set today is 7 small pure-JS packages and it ships a compiled single binary. This is a >10× install-surface increase plus a telemetry dependency in a tool whose repo carries docs/reference/data-and-telemetry.md.
• Release churn. ~1,437 versions in 22 months (~2/day) against a CLI that pins deps hard (see the pinNotes entry in package.json).
• akm would still own the IR compiler, gates, artifact promotion, brief/report.

4.3 XState v5 — xstate@5.32.5 (MIT)

• Best maturity on this list: MIT, zero dependencies, 2.3 MB, Stately-backed, huge install base, stable v5 line.
• Persistence exists — actor.getPersistedSnapshot() / createActor(m, { snapshot }) — and machines can be built at runtime from akm's frozen IR JSON.

But it is a state-machine library, not a durable execution engine. What akm would still hand-roll after adopting it: the unit journal and its SQLite schema, content-derived unit ids and idempotent resume, retry/backoff, the frozen concurrency caps, the 90-second run lease, gate loops and feedback threading, artifact promotion/validation, and the entire brief/report protocol. Worse, a restored XState actor re-invokes its promise actors — the invoked LLM call is not journaled, so naive restore re-runs paid work. akm would have to wrap every invoke in its existing journal anyway, at which point XState is contributing only step sequencing and route evaluation (~300–500 LOC of run-workflow.ts + step-work.ts), while adding a second source of truth for run state next to workflow_runs.

4.4 Effect — @effect/workflow@0.19.1 + @effect/cluster@0.60.2 (MIT)

Durable workflows for Effect: DurableDeferred, DurableClock, activity journaling, compensation. The only real engine is ClusterWorkflowEngine, which maps each workflow to a cluster Entity and routes through Sharding — so you take on @effect/cluster + @effect/sql + @effect/rpc + @effect/platform + @effect/experimental as peers, and a runner topology.

Directly disqualifying evidence for akm's exact pattern: two open upstream issues — Effect-TS/effect#6176 (filed 2026-04-15, still open) and #6179 — report that SQLite-backed @effect/workflow/@effect/cluster storage degrades under "one persistent runner + multiple short-lived client processes on the same SQLite store", producing PersistenceError and SqliteError: database is locked. That is precisely akm's topology (one engine invocation + concurrent brief/report CLI processes on state.db). Plus: adopting Effect means rewriting akm's imperative engine into the Effect runtime — an enormous, non-incremental change to an MPL-2.0 codebase that today has 7 dependencies.

4.5 LangGraph JS — @langchain/langgraph@1.4.8 + @langchain/langgraph-checkpoint-sqlite@1.0.3 (MIT)

Closest "real product" fit conceptually: graph of nodes, Send API for data-driven fan-out, interrupt()/Command(resume=…), retry policies, per-thread checkpoints in SQLite, no server required (LangGraph Platform is optional).

Blockers:

• @langchain/langgraph-checkpoint-sqlite depends on better-sqlite3@^12 — a native addon. akm keeps better-sqlite3 optional precisely so bun build --compile produces a runtime-free binary for 5 targets including Windows. Making it mandatory is a distribution regression; the package does not offer a bun:sqlite driver.
• Upstream positions SqliteSaver as "local testing"; Postgres is the documented production saver.
• Checkpointing is at superstep boundaries, so a crash mid-node re-runs the whole node — weaker than akm's per-unit content-hash journal, i.e. it would re-pay for LLM calls akm currently reuses.
• Pulls @langchain/core (peer) + @langchain/langgraph-sdk + @langchain/protocol into a 7-dependency CLI.
• Graph-of-code model vs. akm's frozen IR data plan; brief/report have no home.

4.6 Also looked at, not worth a full row

• @clawdbot/lobster@2026.6.11 (MIT, deps ajv+yaml) — "typed JSON-first pipelines, jobs, and approval gates", local-first, fan-out/retries/timeouts. Conceptually the closest thing to akm's gate model found on npm. But it is an OpenClaw-native plugin shell, still described as in planning, with no documented durable journal or resume contract and no adoption. Not a credible swap; possibly worth watching.
• liteflow@1.1.0 — "a lightweight SQLite-based workflow tracker". Tracking, not execution. No fan-out, no retries, no resume.
• @gobing-ai/ts-dual-workflow-engine, @pi-stef/agent-workflows, nervous-system, @workglow/job-queue — sub-1.0, single-author, no adoption, no durability contract. Same or worse risk profile than Weft with fewer features.

5. Ranked shortlist

1. Weft (@lostgradient/weft) — the only library whose design matches akm (Bun-native, bun:sqlite, in-process, checkpoint-per-step, MIT, Windows compile target), but it explicitly does not coordinate multiple processes against one store and auto-resumes everything on Engine.create(), which contradicts akm's lease model; and at 7 stars / 8 weeks / bus factor 1 it is not adoptable by a shipping CLI. Watch, do not adopt.
2. Mastra (@mastra/core + @mastra/libsql) — real server-free SQLite durability and the best control-flow coverage of akm's unit/map/route, but 59 MB / 31 deps / bundled posthog-node / ~2 releases-per-day churn is indefensible against a 7-dependency single-binary CLI, and its snapshot-on-suspend model leaves akm hand-rolling leases and unit idempotency anyway.
3. XState v5 — by far the safest dependency (MIT, zero deps, 2.3 MB, stable), but it is not durable execution: restored actors re-invoke their effects, so akm keeps its journal, lease, retries and gates and gains only step sequencing — while creating a second run-state source of truth.

6. Bottom line

Nothing found beats hand-rolling, and nothing found is measurably better than the two candidates already under review.

The reason is structural, not a gap in the search. akm's engine is 8,705 LOC of exec+ir, but only ~570 of them (~6 %) are the generic durable-execution concerns a library sells: bounded concurrency, retry, journal-and-resume, lease. The other ~94 % is akm's own product — the IR v3 compiler and freeze/plan-hash pipeline, the LLM/agent/SDK dispatch with frozen per-engine caps, artifact promotion and output-schema validation, artifact-judged gates with bounded feedback loops, and the 2,690-LOC brief/report harness-neutral driver protocol. No library on npm has an analogue for the last item, and every library would replace akm's workflow_run_units journal with its own schema, which is the exact table brief/report read from — so adoption costs an extra translation layer on top of the rewrite.

Three specific things akm already does that none of these libraries do: content-derived unit identity (sha256(canonicalJson(item))) that survives item reordering; a claimable 90-second run lease that makes N short-lived CLI processes safe against one SQLite file; and byte-identical unit graphs across the native and external-driver execution paths.

Recommendation: keep the engine. If a dependency is wanted, the defensible scope is below the engine, not instead of it — e.g. keep using core/concurrent.ts or swap it for p-limit/p-queue. Re-open this evaluation if DBOS Transact TS ships a SQLite system database (Go has it, Python defaults to it, TS at 4.25.14/2026-07-30 does not), or if Weft reaches 1.0 with documented multi-process lease coordination.