akm-cli 0.9.30 → 0.10.261001-beta

package/docs/architecture/specs/reviews/task-workflow-unification/findings-consolidated.md

@@ -0,0 +1,152 @@
+# Consolidated findings — three independent Opus reviews of spec v7 + codebase
+
+Sources: review-1.md (758 lines), review-2.md (645), review-3.md (602).
+"R1/R2/R3" = which reviewers found it independently. 3/3 = unanimous.
+
+## Critical (all confirmed by ≥2 reviewers)
+
+C1. 3/3 — **`output:` is NOT a duplicate; the flatten collides two different schemas.**
+    `unit.output` = per-dispatch structured-result schema (LLM responseSchema, structured
+    retry, driver --result-file); `step.output` = promoted artifact / reducer result feeding
+    the gate loop. Deleting the bag merges them and makes per-item schemas on map steps
+    unexpressible. (compile.ts:204,229; step-work.ts:555-561; native-executor.ts:663,928,1092)
+
+C2. 3/3 — **`run:` shell units are unrepresentable in IR v3 / the dispatch seam.**
+    UnitDispatchRequest.engine and IrInvocation.engine are required; FrozenEngineSnapshot is
+    a closed 2-kind union; freeze hard-errors with no engine; IR rejects empty instructions;
+    no shell runner exists; brief/report behavior undefined. §10's "no IR/freeze changes" is
+    false. (unit-dispatch.ts:15-19; ir/schema.ts:29-85,434-441,481-497; freeze.ts:49-75)
+
+C3. 3/3 — **The unit input-hash preimage is unaddressed → silent replay-reuse bugs.**
+    hashVersion 4 hashes template instructions/item/inputs/params/dispatch/env NAMES only.
+    run: text, uses: refs, cwd, shell, appended prose, and env literal values are all
+    outside the preimage; editing any of them would reuse completed journal rows. The
+    prose-append also can't happen "at one seam" — prompts are assembled per-unit at
+    dispatch (item/inputs/gate blocks), so the append must be a freeze-time concat plus a
+    hash-version bump. (step-work.ts:333-393,473-500)
+
+C4. 3/3 — **The cascade's far layers don't exist; the worked example is a no-op today.**
+    DefaultsSchema has no `model` (passthrough swallows it silently); `defaults.llm` is
+    explicitly hard-rejected as retired; freeze's layer list is only [documentDefaults,
+    unit]; there is no persona layer. The spec presents "exposing an existing mechanism";
+    reality is a 2-layer mechanism that must be extended to 5.
+    (config-schema.ts:102-108,234-241; freeze.ts:50,163-209)
+
+C5. 2/3 — **`uses: scripts/*` reverses a documented security boundary.**
+    Script run/setup/cwd frontmatter is advisory/display-only today; "registering a bundle
+    never activates code" is an explicit invariant; executing a third-party bundle's script
+    at cron time is net-new RCE surface with no activation-policy rule.
+    (indexer/passes/metadata.ts:140-144; renderers.ts:118-142; core/activation-policy.ts)
+
+## Major
+
+M1. 3/3 — **`params` acquires 3-4 conflicting meanings** (frontmatter schema declarations,
+    workflow run-args, command placeholder fills, cascade value field) — the same
+    indictment the spec levels at `prompt:`. Cascaded params also violate the params-are-
+    non-secret/un-redactable contract and inject undeclared names the flag validators
+    reject. (ir/params.ts:34-72; param-secrets.ts:9-19; akm-workflow.json:22-32)
+
+M2. 3/3 — **Command-template filling contradicts the real placeholder contract.**
+    Placeholders are $ARGUMENTS/$1-$9 positional (+ {{name}} advertised, but
+    fillPlaceholders only substitutes positional {{0}} leniently — a live bug); named
+    `params:` has no projection onto positionals; the proposed fill-time hard error makes
+    every $ARGUMENTS command unusable as a target. (renderers.ts:164-186;
+    matchers.ts:126; agent-dispatch.ts:63-72)
+
+M3. 3/3 — **`env:` list shape is NOT additive.** IR types env as string[]; the input hash
+    deliberately carries env NAMES ONLY (values never durable); literal values would be
+    frozen into plan_json, hashed, and surfaced by brief; every resolved value joins
+    sensitiveValues with no floor, so `LOG_LEVEL: debug` over-redacts "debug" everywhere;
+    AKM_ITEM fan-out needs per-unit env (env resolves once per step today).
+    (ir/compile.ts:46; step-work.ts:353-357,387; native-executor.ts:449-457,1163-1193)
+
+M4. 3/3 — **Alias portability claim unimplemented.** BUILTIN_ALIASES has only
+    claude/opencode columns; `model: sonnet` passes through verbatim to LLM endpoints and
+    opencode-sdk. (model-aliases.ts:45-76,103-109)
+
+M5. 2/3 — **`agent:` selector needs plumbing + a provenance decision.** systemPrompt and
+    toolPolicy cannot reach a workflow unit; the self-declared `tools:` policy is gated by
+    a writable-vs-third-party provenance ceiling applied at the show layer that freeze
+    knows nothing about. ALSO: the spec's corroboration "command assets already read an
+    agent: field" is FALSE — it's a type-classification signal; nothing consumes the value.
+    (native-executor.ts:1026-1035; renderers.ts:250-262; matchers.ts:234-236)
+
+M6. 2/3 — **The kind-gated llm hard error §3.4 argues against is dead code in freeze** —
+    computed only when kind==="llm", then guarded kind!=="llm" && llm!==undefined
+    (unreachable); workflows silently DROP llm overrides on agent engines; the live error
+    exists only on the task path. (freeze.ts:67-73; runner.ts:497-502)
+
+M7. 3/3 — **Migration section overclaims.** Not a byte-rewrite (existing migrator rewrites
+    scalars in place, journals byte diffs, refuses read-only bundles; .yml→.md renames
+    break that model); `name:` silently dropped; llm.supportsJsonSchema/contextLength/
+    enableThinking have no home in the nine value fields; command ARRAYS have no shell
+    spelling; "strays named by path" is not structural — refusals key on config/DB shape,
+    not leftover files, and placement/sync filter by extension, so a stray .yml is invisible
+    or wrongly installed; `<id>.yml` + `<id>.md` collide on one conceptId.
+    (task-target-ref-migration.ts:27,44-66; asset-placement.ts:159-170; tasks.ts:155-164,414)
+
+M8. 2/3 — **Markdown-task recognition collides with the .md-claiming workflow adapter**
+    (ordered first; claims any .md without a different type:), so `type: task` is mandatory
+    and "tasks/ residence" recognition is unimplementable as written; contradicts
+    okf-support.md's current text; akm-task format-family goldens are marked immutable.
+    (adapters/index.ts:73-90; akm-workflow-adapter.ts:60-76)
+
+M9. 2/3 — **`run:` shell text defeats akm-bin resolution.** resolveNestedAkmCommand
+    rewrites bare `akm` in pre-split argv to the current installation; all ten shipped
+    templates depend on it; shell text makes it impossible without sniffing.
+    (runner.ts:277-289,343-348; command-executable.ts:10-22)
+
+M10. 2/3 — **Optional prose contradicts two live invariants** — the parser errors on a
+    missing/empty step section and the IR rejects empty instructions.
+    (workflows/parser.ts:281-296; ir/schema.ts:434-441)
+
+M11. 1/3 — **uses: tasks/<id> makes freeze IO-dependent, and lint never freezes** — all
+    composition errors escape lint (freeze has exactly one caller: run start); cross-bundle
+    ref scoping undefined. (freeze.ts:39-43; runs.ts:241)
+
+M12. 2/3 — **`defaults.on_error` already exists at document level** — "graph keys are
+    steps-only" silently deletes it; no §8 migration row. (program/schema.ts:210; compile.ts:231)
+
+M13. 1/3 — **Markdown tasks inherit the lint/OKF/improve surface** — the akm adapter
+    special-cases type:"task" as pure YAML so markdown checks never fire; an
+    improve-eligible body is now the literal executable prompt of a scheduled agent.
+    (akm-adapter.ts:388-434)
+
+## Notable minors (deduped)
+
+- `status: draft` overloads OKF lifecycle with scheduler activation — second gate beside
+  `enabled:`, no precedence, `deprecated` undefined. (2/3)
+- `prompt: agents/x` today ships RAW file bytes incl. frontmatter to the model — live bug,
+  worse than §3.5 states. (2/3)
+- §3.5 embodiment sentence reads backwards (--model wins over hint). (1/3)
+- Engine nodes are .passthrough() with blacklists — "strict schema" claim overstated;
+  cwd/shell/env/params would be silently accepted. (2/3)
+- Trigger-keys claim inaccurate: the runner also gates `enabled` at fire time. (1/3)
+- Value fields on `uses: workflows/*` tasks are structurally inert (run-workflow takes
+  ref+params only). (1/3)
+- Subdir task ids: placement indexes `sub/x` but validateTaskId rejects `/` — inherited
+  bug; `.yml` hardcoded in id length budget. (1/3)
+- Embedded templates: enumeration filters .yml, drops non-command targets; setup's YAML
+  round-trip would destroy markdown bodies. (2/3)
+- Model aliases: gate judgeEngine sits outside the cascade. (1/3)
+- Composition can breach the 256 KiB instruction cap; single-file provenance lost. (1/3)
+- task_history.target_kind is a persisted 3-value enum the vocabulary outgrows. (1/3)
+- cwd × isolation:worktree × llm-runner interaction unspecified. (1/3)
+- uses: table covers 5 of ~15 placement types; no rule for the rest. (1/3)
+
+## Verified accurate (all three ran verification passes)
+
+The §2 freeze-cascade description, the UnitDispatchRequest field inventory, the
+resolveModel 4-tier chain, engines.ts kind-split (as blacklists), the 368-line parser and
+87-line orphan schema counts, the scheduler-ABI stability claim, and the journaled
+0.9.0 migration extension point all check out.
+
+## Convergent verdict
+
+Direction (markdown tasks, uses:/run:, steps-are-tasks, cascade *shape*) survives.
+The spec's §10 non-goals are false: this IS an IR + freeze + hash-version change and must
+be costed as one. Required redesigns before implementation: keep two output concepts;
+specify the shell unit kind in IR + dispatch; freeze-time prose concat + hash bump; build
+(not "expose") the 5-layer cascade; split params' meanings (GHA's inputs/with split exists
+precisely for this); a security/activation-policy design for script execution; rewrite §8
+migration against the real migrator mechanics.

package/docs/architecture/specs/reviews/task-workflow-unification/library-eval-alternatives.md

@@ -0,0 +1,352 @@
+# 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):
+
+| area | LOC |
+|---|---|
+| `src/workflows/exec` | 7,070 |
+| `src/workflows/ir` | 1,635 |
+| **exec + ir (the replacement target)** | **8,705** |
+| `src/workflows/runtime` | 1,889 |
+| `src/workflows` total | 13,046 |
+
+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)
+
+| Candidate | Evidence |
+|---|---|
+| Temporal | `@temporalio/worker@1.21.1` deps include `@grpc/grpc-js` — the SDK is a gRPC client of a separate Temporal Server cluster. |
+| Inngest | `inngest@4.14.0` is an SDK; execution is driven by `inngest-cli@1.40.0` ("workflow orchestration platform… run on servers") or Inngest Cloud calling back into your HTTP endpoint. |
+| Trigger.dev | Tasks execute inside Trigger.dev's own runners (cloud or self-hosted Docker stack); the package is a client. |
+| Hatchet | `@hatchet-dev/typescript-sdk@1.28.1` is a worker client for the Hatchet engine (Postgres + gRPC engine service). |
+| Windmill | Rust worker + Postgres server product; TS is the *script* language, not an embeddable library. |
+| n8n | Full Node application/server with its own DB and editor UI; not a library. |
+| Restate | Requires the Restate runtime/sidecar to invoke and journal handlers. |
+| Netflix Conductor / Orkes | Java server + Elasticsearch/Redis/Postgres; TS SDK is a client. |
+| Camunda / Zeebe | Zeebe broker cluster; `zeebe-node`/`@camunda8/sdk` are gRPC job-worker clients. |
+| Azure Durable Functions | `durable-functions@3.5.0` requires the Azure Functions host + Durable Task storage provider. |
+| Dapr Workflow | `@dapr/durabletask-js@1.0.0` talks to the Dapr sidecar / durabletask gRPC endpoint. |
+| AWS durable execution | `@aws/durable-execution-sdk-js@2.2.0` — Lambda-hosted durable functions. |
+| Convex | `@convex-dev/workflow@0.4.4` is a component of the hosted Convex backend. |
+| Cloudflare Workflows | Workers/Durable Objects runtime only. |
+| Vercel Workflow DevKit | `workflow@4.8.0` ships Next/Nuxt/Astro/Nitro/SvelteKit/Nest adapters — a web-framework durable-function SDK bound to a deployed "world", not a CLI library. |
+| Upstash Workflow | `@upstash/workflow` — QStash HTTP service re-invokes your endpoint per step. |
+| Obelisk | Rust/WASM engine shipped as a standalone binary, not a TS library. |
+| HotMesh | `@hotmeshio/hotmesh@0.27.0` peerDeps `pg` **and** `nats`; also `SEE LICENSE IN LICENSE` (non-standard). |
+| Resonate | `@resonatehq/sdk@0.11.4` peerDeps `pg` + `@nats-io/transport-node`; local mode is in-memory (not crash-durable), durability needs the Resonate server/Postgres. |
+| Smithers | `smithers-orchestrator@0.32.0` is an *application* (React UI, `@smithers-orchestrator/{ui,aws,gcp,cli,driver,engine}`), not an embeddable engine. |
+| Eve (Vercel) | `eve@0.29.4` is a Nitro-based agent *framework* (`nitro` dep, `node>=24`), an app scaffold not a library. |
+| RaySpec | `@rayspec/workflow-durable@1.6.2` delegates durability to `@rayspec/durable-dbos` → DBOS → Postgres; 1 week old, no adoption. |
+
+## 2. Eliminated on the storage constraint
+
+| Candidate | Evidence |
+|---|---|
+| **DBOS Transact (TS)** | **Verified against the current artifact, not memory.** `@dbos-inc/dbos-sdk@4.25.14`, published **2026-07-30**: only DB dependency is `pg@^8.11.3`; the unpacked tarball contains **zero** files matching `*sqlite*`; the only DSN scheme in `dist/src/*.js` is `postgresql://`; `README.md` still says "a lightweight **Postgres-backed** library". Every `@dbos-inc/*-datasource` package is explicitly "with PostgreSQL support". DBOS's June-2026 announcement of a SQLite durability backend applies to the **Go** SDK (and Python, whose docs default the system DB to SQLite) — **it has not landed in TypeScript.** Verdict: **fail today**, re-check when a TS SQLite system DB ships. |
+| pg-boss | `pg-boss@12.26.4` deps `pg` — Postgres-only by construction. |
+| BullMQ | `bullmq@6.0.5` — "Queue for messages and jobs based on Redis"; requires a Redis server. |
+| Absurd | `absurd-sdk@0.4.0` — "PostgreSQL-based durable task execution". |
+| Agenda / node-resque / bee-queue | MongoDB / Redis / Redis respectively. |
+| SideQuest | `@sidequest/engine@1.16.2` is **LGPL-3.0-or-later** — copyleft on a linked library; avoid for a distributed CLI. |
+
+## 3. Eliminated as "not orchestrators"
+
+| Candidate | Evidence |
+|---|---|
+| bree | `bree@9.2.9` — cron/date scheduler that spawns worker threads. No DAG, no journal, no resume. |
+| croner | `croner@10.0.1` — zero-dep cron expression evaluator. Schedule only. akm already gets scheduling from `schtasks`/cron in `src/tasks/`. |
+| better-queue | `better-queue@3.8.12` — in-process job queue with pluggable stores; no step journal, no fan-out graph, no resume-mid-workflow. |
+| p-queue / p-limit / fastq | Concurrency limiters. akm already has `core/concurrent.ts` + `scheduler.ts` doing exactly this with the extra frozen-cap policy. |
+| workflow-es | `workflow-es@2.3.5`, **last published 2022-06-29**, 19 versions, deps on `inversify@^4` + `reflect-metadata@^0.1` (both several majors stale). Unmaintained; TS-decorator/DI-heavy; would not build cleanly under Bun + modern TS. Dead. |
+| @deepkit/workflow | FSM only (`1.0.19`, Sep 2025); no persistence, no durability. |
+
+---
+
+## 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.
+
+| criterion | |
+|---|---|
+| server-free embed | **partial** — in-process, but assumes one long-lived engine per store |
+| SQLite durability + resume | **pass** — `bun:sqlite` adapter, checkpoint per yield |
+| orchestration primitives | **pass** — all/race/retry/timers/signals/semaphore |
+| long-running steps | **pass** |
+| maturity | **fail** — 7★, 8 weeks old, bus factor 1, pre-1.0 |
+| % exec+ir replaced | **~6 %** (scheduler + lease/resume plumbing), and it *removes* the lease guarantee |
+
+### 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.
+
+| criterion | |
+|---|---|
+| server-free embed | **pass** |
+| SQLite durability + resume | **partial** — libSQL storage yes; snapshot-on-suspend, no lease, no crash-resume daemon |
+| orchestration primitives | **pass** — parallel/branch/loops/foreach-concurrency/retries |
+| long-running steps | **pass** |
+| maturity | **partial** — active and adopted, but 59 MB, 31 deps, posthog telemetry, extreme churn |
+| % exec+ir replaced | **~10–15 %** of exec, **0 %** of ir |
+
+### 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`.
+
+| criterion | |
+|---|---|
+| server-free embed | **pass** |
+| SQLite durability + resume | **fail** — snapshot serialization only; no journal, no effect durability, no resume semantics |
+| orchestration primitives | **partial** — parallel states/routing yes; no concurrency caps, no retry policy, no fan-out-over-data |
+| long-running steps | **pass** |
+| maturity | **pass** — the strongest here |
+| % exec+ir replaced | **~4–6 %**, and it duplicates run state |
+
+### 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](https://github.com/Effect-TS/effect/issues/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.
+
+| criterion | |
+|---|---|
+| server-free embed | **fail/partial** — needs cluster runner topology |
+| SQLite durability + resume | **fail** — documented, currently-open lock failures under akm's multi-process pattern |
+| orchestration primitives | **pass** |
+| long-running steps | **pass** |
+| maturity | **partial** — Effect core is mature; `@effect/workflow` is 0.19.x and moving fast |
+| % exec+ir replaced | ~15 % nominally, at the cost of rewriting the other 85 % in Effect |
+
+### 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.
+
+| criterion | |
+|---|---|
+| server-free embed | **pass** |
+| SQLite durability + resume | **partial** — works, but native addon + "local testing" positioning + superstep granularity |
+| orchestration primitives | **pass** — Send fan-out, interrupts, retry policies |
+| long-running steps | **partial** — node-level replay on crash |
+| maturity | **pass** — large ecosystem, MIT |
+| % exec+ir replaced | **~10 %**, and it breaks single-binary distribution |
+
+### 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**.