akm-cli 0.9.30 → 0.10.261001-beta

package/docs/architecture/testing/testing-workflow.md

@@ -0,0 +1,446 @@
+# Testing Workflow
+
+This project is a CLI with three risk-heavy areas:
+
+- command behavior across real files, config, and cache directories
+- managed-source install/update flows
+- binary deployment and self-upgrade behavior
+
+The safest way to test it is in layers: fast local checks first, then end-to-end
+CLI coverage, then Docker-based deployment and upgrade validation. This document
+owns automated test workflow and test-authoring guidance only. The authoritative
+manual setup, command matrix, expected behavior, release gates, evidence, and
+cleanup live in [AKM Manual Testing Runbook](./manual-testing-checklist.md).
+
+## What To Validate
+
+- core CLI flows: `setup`, `index`, `search`, `show`, `info`, `bundle list`, `config`
+- asset lifecycle: add assets, re-index, search, show, and incremental refresh
+- managed-source lifecycle: `akm bundle add`, `akm bundle list`, `akm bundle update`, `akm bundle remove`
+- binary lifecycle: install, run, `akm upgrade --check`, `akm upgrade`
+- cross-environment behavior on Ubuntu, Debian, Alpine, and Fedora containers
+
+## Test Layers In This Repo
+
+### 1. Fast local correctness
+
+Run these before any release candidate or merge:
+
+```sh
+bun run test:unit
+bunx biome check --write src/ tests/
+bunx tsc --noEmit
+```
+
+Use this when you want the shortest full-project signal:
+
+```sh
+bun run check
+```
+
+Relevant coverage:
+
+- `tests/integration/self-update.test.ts` - self-upgrade detection and checksum enforcement
+- `tests/integration/registry-*.test.ts`, `tests/provider-registry.test.ts` - `list`, `remove`, `update`, cache cleanup, install resolution, tar safety, local/git/npm paths
+- `tests/integration/setup-run.test.ts` - full setup wizard orchestration and failure handling
+- `tests/integration/install-script.test.ts` - repeatable `install.sh` edge cases and permission paths
+
+### Writing deterministic, isolated tests
+
+Both `scripts/test-unit.sh` (`bun run test:unit`) and `scripts/test-integration.sh`
+(`bun run test:integration`) shard their target across up to `min(nproc, 8)`
+concurrent `bun test` processes, splitting the file list round-robin — neither
+runner is a single shared process, and neither is "the unit suite" alone.
+Within one shard, every file assigned to that process still runs in **one
+shared process**: one `process.env`, one module-singleton namespace, and
+(under fake timers) one global clock for every file in that shard. A test that
+mutates shared state without restoring it, or that asserts on a wall-clock
+measurement, can pass on one scheduling and
+fail on another — the two release/0.8.0 flakes (scoring-pipeline Issue #14
+reading the wrong index DB after a sibling mutated `XDG_DATA_HOME`; the
+llm-client timeout test racing real timers) were both this class.
+
+Rules (conventions, not statically enforced — the lint script that policed
+them was deleted in 0.9.8; the runtime guard in `src/core/paths.ts` throws
+`TEST_ISOLATION_MISSING` and the preload tripwire catches leaks):
+
+1. **Never mutate `AKM_*` / `XDG_*` / `HOME` on `process.env` directly.** Use the
+   sanctioned helpers in `tests/_helpers/sandbox.ts`:
+   - `sandboxStashDir`, `sandboxXdgConfigHome`, `sandboxXdgDataHome`,
+     `sandboxXdgCacheHome`, `sandboxXdgStateHome`, `sandboxHome` — set the env var
+     to an isolated temp dir and return a `cleanup` that restores the prior value.
+     Chain them and call `cleanup()` in `afterEach`.
+   - `withEnv({ AKM_BUNDLE_DIR }, async () => …)` — scoped override that always
+     restores in a `finally`, even on throw. Use this for per-call overrides
+     around an in-process CLI invocation.
+   - `makeStashDir` / `makeSandboxDir` — temp dirs that are NOT wired into env
+     (pass them to `withEnv` or a subprocess env object yourself).
+
+   The DB path resolves from `XDG_DATA_HOME`; if you `akmIndex` then `akmSearch`,
+   both must see the **same** sandboxed `XDG_DATA_HOME` or the search reads a
+   different (empty/stale) DB. Sandbox it in `beforeEach`.
+
+2. **Do not assert on a measured wall-clock delta.** `expect(Date.now() - start)
+   .toBeLessThan(N)` races the scheduler. Assert the *observable result* instead
+   (e.g. `result.reason === "timeout"`), or drive time deterministically with
+   `jest.useFakeTimers()` + `jest.advanceTimersByTime(...)` and a fetch/spawn stub.
+   Asserting on a `durationMs` field computed from injected fixture timestamps is
+   fine (it is deterministic).
+
+3. **Sort/compare on the value the user sees.** When a test asserts ordering,
+   make the production sort key the same quantized value that is displayed
+   (`db-search.ts` sorts on the clamped+rounded score, then breaks ties by name),
+   so an invisible sub-display-precision epsilon can never reorder visible ties.
+
+4. **Avoid stateful feedback within one test.** Re-running `akmSearch` without
+   `skipLogging: true` writes utility/recency rows that perturb the next search's
+   ranking. Pass `skipLogging: true` when you need repeatable ranking across
+   calls in a single test.
+
+If a file legitimately needs a literal env value (e.g. pure path-resolution unit
+tests) and restores via its own save/restore wrapper, add it to the linter's
+`ENV_ASSIGN_ALLOWED` set with a one-line justification — the list may only shrink.
+
+### 2. End-to-end CLI validation
+
+Run the full integration suite when changing CLI behavior, indexing, search,
+config, source management, or output shaping:
+
+```sh
+bun run test:integration
+```
+
+Collectively, these suites (`tests/integration/`) exercise real flows,
+including:
+
+- fallback search without an index
+- `index -> search -> show`
+- CLI subprocess execution through `src/cli.ts`
+- config read/write behavior
+- registry-source compatibility
+- progressive indexing and re-indexing
+- update and upgrade command error paths
+- knowledge `#fragment` selection and mixed asset discovery
+
+## Semantic Search States
+
+Semantic search does not behave as a simple on/off feature at runtime. Testing
+should distinguish between saved-config state and actual readiness.
+
+### Config intent
+
+Semantic search intent is saved independently as `semanticSearchMode`:
+
+- `off` when the user opts out explicitly
+- `auto` when the user wants semantic search enabled
+
+Setup should not flip intent from `auto` back to `off` because preparation or
+verification fails transiently.
+
+### Runtime readiness
+
+Actual semantic readiness is tracked separately from config intent. Runtime state
+can be:
+
+- `pending` when semantic search is enabled but not yet verified
+- `ready-js` when every entry has a vector (the name is historical; there is no other vector path)
+- `blocked` when semantic search cannot run with the current provider/setup
+
+These cases are covered by `tests/integration/setup-run.test.ts` and the focused
+semantic/config suites.
+
+The real-model gate (`AKM_SEMANTIC_TESTS=1`) honors an explicit `HF_HOME` and
+otherwise uses the ignored, repo-local `.ci-cache/huggingface` directory. That
+path is outside the preload's disposable test `HOME`, so a second local run
+reuses the model without exposing the developer's normal AKM cache. Gated CI
+sets the same path and restores it from a model/source-identified Actions
+cache. Candidate tags and manual runs are restore-only; only the scheduled
+default-branch run may save a cache entry.
+
+The same gate runs real semantic index/search round-trips against the declared
+external dependency. Package acceptance separately verifies the ordinary npm
+package surface; there is no installed-consumer compatibility architecture or
+copied semantic runtime to audit.
+
+### What to test explicitly
+
+- config stays `off` only when the user disables semantic search intentionally
+- config stays `auto` when preparation is skipped intentionally
+- config stays `auto` when preparation fails but runtime status becomes `blocked`
+- runtime status becomes `pending`, `ready-js`, or `blocked` as appropriate
+- index and info output report readiness state instead of only config intent
+
+### 3. Docker deployment validation
+
+Run the Docker matrix when changing install, packaging, startup, runtime
+dependencies, or platform behavior:
+
+```sh
+AKM_DOCKER_TESTS=1 bun test tests/integration/docker-install.test.ts
+```
+
+Or run the shell orchestrator directly:
+
+```sh
+./tests/docker/run-docker-tests.sh
+```
+
+This validates two deployment methods across four Linux families:
+
+- bun-based install: Ubuntu, Debian, Alpine, Fedora
+- compiled binary install: Ubuntu, Debian, Fedora
+
+Binary validation currently excludes Alpine. The compiled Linux binary used in
+this repo's Docker tests is not packaged for Alpine/musl compatibility, so the
+binary deployment gate focuses on the glibc-based targets we currently support.
+
+The Docker smoke test in `tests/docker/smoke-test.sh` verifies:
+
+- `akm --help`
+- `akm bundle create`
+- bundle directory creation
+- `akm index`
+- `akm search`
+- `akm show`
+- `akm info`
+- `akm bundle list`
+- incremental re-index after adding a new asset
+
+### 4. Benchmark (agent utility)
+
+The LLM-provider-driven, multi-seed agent-utility benchmark (`akm-bench`) now
+lives in the standalone repo **[itlackey/akm-bench](https://github.com/itlackey/akm-bench)**.
+Run it from there after any change to `src/output/`, `src/commands/read/show.ts`,
+APPLY directives, or other content that affects what agents see.
+
+For curate/search ranking quality, run the retrieval eval of
+**[itlackey/akm-eval](https://github.com/itlackey/akm-eval)**
+(`evals/retrieval/run --corpus public`, with `AKM_BIN` naming the build under
+test). It scores `akm search` and `akm curate` against graded judgments and
+calls no model service. The in-repo curate benchmark that used to do this,
+`akm-eval-curate-bench`, left with the rest of `scripts/akm-eval/`; see
+`docs/maintainers/eval.md`.
+
+## Recommended Workflow
+
+### Normal change
+
+Use this for most code changes:
+
+```sh
+bun run test:unit
+bun run test:integration
+bunx biome check --write src/ tests/
+bunx tsc --noEmit
+```
+
+### Install, packaging, or release-related change
+
+Use this when touching `src/cli.ts`, `src/commands/sources/self-update.ts`, install flows,
+source management, or Docker assets:
+
+```sh
+bun run test:unit
+bun test tests/integration/self-update.test.ts tests/integration/setup-run.test.ts tests/integration/install-script.test.ts
+./tests/docker/run-docker-tests.sh
+bunx biome check --write src/ tests/
+bunx tsc --noEmit
+```
+
+### Release gate
+
+Use this before publishing a release:
+
+```sh
+bun run release:check
+```
+
+If Docker is available, prefer `./tests/docker/run-docker-tests.sh` over a
+single-variant container run so both bun and binary installs are covered.
+
+For a local release gate without Docker, use:
+
+```sh
+./tests/release-check.sh --skip-docker
+```
+
+That script now runs a dedicated install/setup regression suite before the full
+test run so first-run, installer, and wizard failures surface early.
+
+The local script is only one half of release validation. Follow the
+[maintainer release checklist](../../maintainers/release-checklist.md) to
+run **Gated CI** from a `gated-ci/candidate-*` tag targeting the exact candidate
+commit, or manually dispatch it with the full candidate
+SHA after the workflow reaches the default branch. Its real-embedding, Docker,
+and Linux/macOS/Windows scheduler jobs must all succeed, and the release PR
+must link the resulting Actions run. The weekly scheduled run detects
+default-branch drift; it cannot attest a different release-candidate commit.
+
+## Manual QA Authority
+
+Use [AKM Manual Testing Runbook](./manual-testing-checklist.md) for every manual
+flow. Its full sandbox is mandatory; the smaller historical XDG-only setup is
+unsafe because `AKM_CONFIG_DIR` can bypass it. The runbook also owns expected
+exits/channels, fixtures, release evidence, platform gates, and cleanup.
+
+## Docker Deployment Validation
+
+### Automated matrix
+
+The repo already contains Dockerfiles for:
+
+- `tests/docker/Dockerfile.ubuntu-bun`
+- `tests/docker/Dockerfile.debian-bun`
+- `tests/docker/Dockerfile.alpine-bun`
+- `tests/docker/Dockerfile.fedora-bun`
+- `tests/docker/Dockerfile.ubuntu-binary`
+- `tests/docker/Dockerfile.debian-binary`
+- `tests/docker/Dockerfile.fedora-binary`
+
+`Dockerfile.alpine-binary` does not exist and is deliberately not part of this
+matrix: binary validation excludes Alpine (see above) because the compiled
+binary targets glibc and Alpine is musl-based.
+
+Run one variant if you need a focused repro:
+
+```sh
+./tests/docker/run-docker-tests.sh ubuntu-binary
+./tests/docker/run-docker-tests.sh --bun-only
+./tests/docker/run-docker-tests.sh --binary-only
+```
+
+### What the Docker matrix proves
+
+- the CLI starts in minimal Linux images
+- runtime dependencies are sufficient for `bundle create`, `index`, `search`, and `show`
+- bun-linked installs work after building from source
+- compiled Linux binaries run correctly when copied into the image
+- the CLI can create a fresh bundle, build an index, and discover new assets
+
+Treat this matrix as a release gate for shell-level regressions too. The Docker
+smoke path exercises real entrypoint scripts and container command execution,
+which can catch failures that unit and subprocess tests miss.
+
+### What it does not prove by itself
+
+- that the published release artifact matches the local compiled binary
+- that `install.sh` works against a real GitHub release
+- that self-upgrade can replace the running binary in-place
+
+Those should be validated in disposable containers as described next.
+
+## Published Artifact Acceptance
+
+Published binary, installer, checksum, native-platform, and self-upgrade
+procedures are release-facing manual gates. Run sections 21-22 of the
+[manual runbook](./manual-testing-checklist.md); do not validate release bytes
+with an installer fetched from raw `main`.
+
+## Upgrade Regression Coverage
+
+Managed-source updates and CLI self-upgrade are separate implementations.
+Provider/registry suites cover source add/update/remove/cache behavior;
+`tests/integration/self-update.test.ts` covers install-method detection,
+orchestration, checksum, and failure paths. Real managed-source and self-upgrade
+acceptance is manual and lives in section 21 of the
+[manual runbook](./manual-testing-checklist.md).
+
+### Upgrade rehearsal gate
+
+`tests/integration/upgrade-rehearsal/` installs the PREVIOUS published stable
+`akm-cli` release as a real global npm package (real `npm pack` / `npm
+install --global` into a throwaway prefix — see `scripts/package-install.ts`)
+under the label `live`, drives it to build a realistic home — a filesystem
+bundle, a git bundle (with an in-bundle symlink at its root), a website
+bundle, an npm bundle, three scheduled tasks (two granted, one left
+ungranted) plus a manual task, and a synced native (fake) crontab — then
+installs the CANDIDATE build OVER `live`, in the SAME prefix: an in-place
+swap, the same thing a real `npm i -g akm-cli@…`/`bun add -g` upgrade does,
+not a side-by-side install. It then runs the CANDIDATE against that home
+(`migrate status`/`apply`, `bundle list` with every bundle confirmed enabled,
+`search`/`show`, `task sync` dry-run and real — plain, no `--rebind`, as an
+upgrading user actually runs it — executing the generated cron command and
+confirming it ran the candidate, `task run`, `health`, `improve --dry-run`), and
+finally installs a separate untouched copy of the PREVIOUS release and runs
+it back against the candidate-written home to prove read-back still works.
+It exists because no other suite drives a real prior release against a real
+candidate build: the symlink-abort regression fixed in 0.9.17-alpha.3
+(`d76af0a7b`) went undetected by the full unit/integration suite,
+`tests/release-check.sh`, and the Docker matrix, because no fixture combined
+a git bundle with an in-bundle symlink, a website bundle, an npm bundle, an
+ungranted task, and a real crontab row in one home. Plain `task sync` proves
+clean specifically because the candidate lands inside the SAME prefix the
+previous release's scheduler rows already point at — no launcher path moves,
+so nothing needs rebinding; a side-by-side install (a separate prefix) would
+need `--rebind` instead, which is not what an in-place package-manager
+upgrade does. `tests/integration/previous-release-corpus.test.ts` covers
+persisted-data shapes read in isolation; this gate covers the whole CLI
+surface driven end to end across two real installed releases.
+
+Run it locally with:
+
+```sh
+bun run build
+AKM_UPGRADE_REHEARSAL=1 TMPDIR=/tmp bun test --timeout=900000 tests/integration/upgrade-rehearsal/
+```
+
+Unset (the default), the suite logs one line and skips — it never fails
+"inconclusively" (#795): every missing capability (no `npm` on `PATH`, no
+network reachable to resolve/fetch the previous release, no candidate build)
+throws naming the fix instead. Env overrides:
+
+- `AKM_UPGRADE_FROM=<version>` — pin the previous release instead of
+  resolving the highest published stable version below the candidate's
+  `package.json` version.
+- `AKM_CANDIDATE_TARBALL=<path>` — use an already-packed candidate tarball
+  (`tests/release-check.sh` passes `$PACKAGE_CANDIDATE`) instead of running
+  `npm pack` on the working tree (which requires `dist/cli.js` — run
+  `bun run build` first).
+
+Fetched previous-release tarballs are cached under
+`${TMPDIR:-/tmp}/akm-upgrade-rehearsal/previous-release/<version>/` so repeat
+runs do not re-hit the network. It is wired into CI as the `upgrade-rehearsal`
+job (`.github/workflows/ci.yml`) and into `tests/release-check.sh` right
+after packing the release candidate.
+
+## Coverage Gap Guide
+
+This repo now has broad coverage across the major CLI, indexing, registry, and
+semantic-search paths. Use this file as a current gap guide, not a greenfield
+test plan.
+
+### Areas With Strong Existing Coverage
+
+- database and scoring (`tests/integration/db.test.ts`, `tests/integration/db-scoring.test.ts`, `tests/integration/fts-field-weighting.test.ts`)
+- search/show CLI surfaces (`tests/integration/commands/search-cli-envelope.test.ts`, `tests/integration/commands/show.test.ts`, and the other `search-*`/`show-*` suites under `tests/integration/`)
+- registry install/search/update/list flows
+- workflow, vault, and wiki behavior
+- semantic status, vector search, and embedding config behavior
+- CLI error handling and output shaping
+- Docker install validation
+
+### Highest-Value Remaining Gaps
+
+1. corrupt or version-mismatched DB fallback behavior during search
+2. local model download and ONNX startup failures
+3. partial embedding-generation failures during indexing
+4. concurrent search/embedder behavior under load
+5. semantic readiness reporting parity between `setup`, `search`, and `info`
+6. broader platform CI for Alpine/musl, ARM, and Windows edge cases
+
+### When Adding Tests
+
+- prefer focused `bun:test` files under `tests/`
+- use isolated temp config/cache/stash dirs
+- cover the user-visible CLI behavior when the risk is output shaping or command routing
+- cover internal units directly when the risk is scoring, metadata extraction, or persistence
+
+### Useful Existing Suites To Extend
+
+- `tests/integration/commands/search-cli-envelope.test.ts`
+- `tests/integration/commands/show.test.ts`
+- `tests/integration/vector-search.test.ts`
+- `tests/integration/semantic-status.test.ts`
+- `tests/setup-wizard.test.ts`, `tests/setup-scheduled-tasks.test.ts`
+- `tests/integration/info-command.test.ts`
+- `tests/integration/docker-install.test.ts`

package/docs/architecture/workflow-engine.md

@@ -0,0 +1,223 @@
+# Architecture: The Workflow Engine
+
+A workflow compiles to a frozen plan, persists run and unit state, dispatches
+its work, verifies declared gates, and resumes without replaying completed
+units. This page is the architecture-level reference for that engine — how a
+run's plan is frozen and stored, how dispatch and resume actually work, how
+one engine owns a run, and how isolated file-mutating units execute. For the
+exact frontmatter/body syntax that produces the plan, see
+[Workflow Schema](../reference/workflow-schema.md). For the day-to-day
+commands that drive a run, see [Running Workflows](../guides/run-workflows.md).
+
+> **`akm workflow run` is Experimental (see `STABILITY.md`), ungated, and the only
+> execution surface.** It is the canonical start/resume/execute command; there is
+> no separate external-driver protocol.
+
+## Frozen plans
+
+The first `akm workflow run <ref>` compiles either peer source format
+(Markdown or GitHub-Actions-style YAML) straight to the one plan type and
+stores it as durable plan **`irVersion` 6** on the run row (`plan_json` +
+`plan_hash`); a new start never emits an older version. `plan_ir_version` and
+`plan_hash` are recorded provenance, not gates: a stored plan is decoded as it
+is — irVersion 4 and 5 plans included — and one frozen by an older or newer
+akm that still decodes simply runs (with one warning). A newer akm's plan that
+does not decode is refused with a message naming "Upgrade akm".
+
+The durable plan records `sourceHash`, the sha256 of the workflow source file
+at freeze. It is used only for the resume warning below, never to refuse a
+run.
+
+Dispatch-significant material is immutable. The resolved request is frozen,
+the resolved target is frozen, and runner selection is frozen.
+Working directory (`cwd`) identity is frozen.
+Git identity and its commit OID are frozen. The executable a unit runs is
+resolved at dispatch, so upgrading a CLI (say, `claude`) never strands a run.
+Exact models, inference, tools and authorization,
+execution limits, parameter snapshots, command/script bytes, and verifier
+selection therefore cannot drift under an in-flight run.
+
+Workflow environment asset values are the narrow live-value exception within
+authored workflow inputs.
+The environment owner key set and secret-token topology are frozen.
+Literal values remain frozen. Pass-through bindings
+materialize at dispatch from the current process, and env/secret references
+materialize their current values only after owner/topology checks. Durable
+plans never store secret values or enable whole-process `inheritEnv`.
+
+**A run executes the plan compiled at creation; edits to source need a new
+run.** Resuming a run re-reads its workflow source only to warn, once, when
+the source changed since the freeze — the run continues on the frozen plan.
+Orchestration decisions are pure functions of the frozen plan, run params,
+and journaled results.
+
+## Child workflows
+
+A step that composes another workflow — directly (`uses: workflows/<ref>`)
+or through a task whose own target is a workflow (`uses: tasks/<ref>`) —
+freezes to a `child-workflow` frozen target. Unlike the `command`/`shell`/
+`script` targets, a `child-workflow` target carries the child's **complete
+frozen plan, embedded**: compiling the parent recursively compiles,
+validates, and freezes each child in full — depth-first, all of it — before
+the parent run is ever published. Nothing about a child is re-read at
+dispatch time; the embedded plan is authoritative. See
+[Workflow Schema: Child workflows](../reference/workflow-schema.md#child-workflows)
+for the authoring-side view, including the three composition bounds (depth,
+cycle, aggregate embedded bytes) enforced at freeze.
+
+**Decoding.** An embedded child plan is decoded by the same structural
+decoder as its parent, recursively. Its `planHash` and the target's
+`contentHash` are recorded provenance, carried as data and never re-verified
+against the bytes.
+
+**The dispatch seam.** Dispatching a step whose target is
+`kind: "child-workflow"` is the one branch point in
+`dispatchJournaledAttempt` (`src/workflows/exec/native-executor.ts`) that
+does not call the ordinary unit dispatcher: it calls
+`driveChildWorkflowUnit` instead, with everything the composing unit already
+resolved — the frozen target, the parent's dispatch context, the child's
+resolved params, and the unit input hash. The branch sits **inside** the
+existing retry loop, after the parent unit's attempt row is already claimed
+`running` (so a crash between claiming that row and publishing the child
+leaves a recoverable `running` parent unit and no orphaned child) and
+**before** the ordinary post-dispatch journaling (redaction, attempt
+finishing), which runs unchanged either way — a
+child-workflow unit is journaled exactly like any other.
+
+**The drive contract.** `driveChildWorkflowUnit` validates and resolves the
+child's params through the same input-binding
+resolution every frozen target uses, computes the child's identity key from
+`{parentRunId, parentUnitId, unitInputHash}`, and publishes the child run —
+idempotently: the same three inputs always resolve to the same child row,
+so a retried or resumed composing step re-drives the run it already started
+rather than starting a new one, and only a change to the composing step's
+own inputs (params, an upstream step output it reads, or gate feedback from
+a rejected verification loop) produces a different child. A child found
+already `blocked` or `failed` is not re-driven — driving happens once per
+call, and a terminal-but-unhealthy child surfaces through the status mapping
+below instead. The child's final status maps onto the composing unit, and
+from there onto the parent step and run, exactly as described in [Workflow
+Schema: Child execution](../reference/workflow-schema.md#child-execution).
+
+**Why `runWorkflowSteps` is reused, not a second executor.** The child drive
+calls the exact same exported entry point `akm workflow run` calls —
+`runWorkflowSteps(options)`, pointed at the child's run id as `target` —
+with no special-casing for "this target is a child": resolving a run id,
+decoding the stored plan, taking that run's own lock, and walking its spine
+through `completeWorkflowStep` are identical to the top-level path. That
+reuse is what makes child run locks arbitrate two-parent contention with no
+new mechanism, and what makes a resumed parent skip a completed child step
+with zero dispatcher calls. The child drive passes a no-op
+`disposeDispatchResources` (the parent's `finally` remains the sole owner of
+the process-lifecycle drain for the whole process) and no `maxSteps` or
+`maxRetries` (the parent's own budgets count only its own spine steps). The
+lower-level `driveRun` that `runWorkflowSteps` wraps stays module-private —
+reaching for it directly, instead of the public entry point, would be
+exactly the second executor this design avoids.
+
+**Why `hashVersion` is 7, and why child composition did not move it.** The
+version prefix mixed into a unit's input hash is 7
+(`src/workflows/exec/step-work.ts`); 0.9.2 bumped it — a single, durable
+5 → 7 step, since every released tag on the line carries 5 — when
+`taskInputs`, the resolved values of a composed task's reference-kind
+`inputBindings`, joined the preimage (see [ADR
+0002](decisions/0002-unit-reuse-and-input-hash-scope.md)). Child composition
+itself contributed nothing to that bump: the parent unit's input-hash
+preimage already covers everything the child drive depends on — the frozen
+target carries the child's ref, plan hash, content hash, binding mode, and
+its entire embedded plan, so any change anywhere in the child changes the
+parent unit's own input hash transitively. The child run id (minted at
+dispatch) and its result (the child's last step output) are unit *outputs*, not inputs, so neither
+belongs in the preimage — adding either would be a hashing-boundary
+violation, not a fix.
+
+## Resume skips completed units
+
+Resume never re-reads config or the asset index, and reads the workflow
+source only for the drift warning above. It consumes the frozen plan plus
+the journaled attempts and results. A stored plan that this akm cannot
+decode is not an error to fix in place: `akm workflow run` marks such a run
+abandoned (status `failed`) and says to start a new run with
+`akm workflow run <ref>`; `akm workflow status`, `list`, and `abandon` never
+read the plan at all. A plan frozen by a newer akm that this one cannot
+decode is left untouched, and the message names upgrading akm.
+
+Every dispatched unit is journaled under a content-derived identity — the
+node id plus a hash of its item for a map unit (`<node>:solo` otherwise) —
+together with an input hash over everything the unit was asked to do (its
+frozen instructions and target, declared `inputs:` artifacts, the params
+snapshot, gate feedback). On
+re-run, a unit whose journal row is `completed` is **reused**, never
+re-dispatched; a failed or missing unit is dispatched live. The recorded
+input hash is informational: a completed unit stays completed even when the
+params row or an upstream artifact changed since — a fresh run is what
+recomputes it.
+
+## Durable attempts and at-least-once dispatch
+
+Workflow dispatch is at-least-once. Every unit has a stable content-derived
+unit id and an append-only sequence of attempts.
+A crash reclaim reuses the same stable dispatchId for the interrupted attempt.
+An explicit retry gets a new dispatchId under one stable unit id and increments the attempt number.
+
+One driver per run (below) keeps a second engine off a run, and a finished
+attempt accepts no second terminal write, but neither can prove whether an
+external process completed immediately before a crash. An ambiguous crash
+outcome may re-run and can produce a duplicate side effect. Workflow actions
+should be idempotent or use the stable dispatch identity as their own
+deduplication key.
+
+## One engine drives a run (the run lock)
+
+`akm workflow run` takes the run's **lock file** before reading the plan or
+dispatching anything: one `O_EXCL` file per run id under the data directory
+(`workflow-run-locks/<run id>.lock`, next to `state.db`), recording the
+holder's pid, released when the invocation exits. A second `workflow run`
+against a run another live process holds refuses up front with
+`RUN_LEASE_HELD` (exit 75), naming the holder pid. A lock whose holder pid is
+dead is reclaimed at once, so a crashed engine never wedges a run; nothing
+expires by age and nothing renews. `workflow status` and `list` never take
+the lock.
+
+## Concurrency limits
+
+Native fan-out (`akm workflow run`) uses the minimum of four limits: the
+map's declared `concurrency`, the run's frozen `workflow.maxConcurrency`, the
+selected frozen LLM engine's `concurrency` (including an SDK engine's
+fallback LLM), and the current host's CPU-derived safety limit. Reapplying
+host safety keeps a run safe when it resumes on a smaller machine.
+
+- **Unset (default):** the CPU-derived value `min(16, max(1, cores − 2))` — a
+  conservative default that leaves headroom on the host and matches the
+  original Claude-Code cap.
+- **Set:** an explicit positive integer, clamped when frozen to `[1, 64]`
+  (values above 64 are clamped down, never rejected, so one config shared
+  across machines with different core counts never hard-fails).
+
+```console
+$ akm config set workflow.maxConcurrency 8   # raise the frozen workflow limit
+$ akm config get workflow.maxConcurrency
+8
+```
+
+A workflow that fans out is authorizing **N parallel agents**, not one — see
+[Running Workflows: workflow sources are executed code](../guides/run-workflows.md#security-workflow-sources-are-executed-code)
+for what that means for trust.
+
+## Run scope and persistence
+
+Run state (`plan_json`, `plan_hash`, step statuses, and the unit journal)
+persists in the project's `state.db`; the per-run lock file sits beside it. Run state is scoped to
+the current project directory — the nearest `.akm/config.json`, git root,
+bundle root, or current directory — so the same workflow can run
+independently in separate projects, and `akm workflow list`/`status` without
+an explicit run id only ever see runs in that scope.
+
+## See also
+
+- [Workflow Schema](../reference/workflow-schema.md) — exact frontmatter,
+  refs, gates, and outputs syntax
+- [Running Workflows](../guides/run-workflows.md) — start, inspect, resume,
+  and abandon a run
+- [Author's Guide: Writing Workflows](../guides/author-workflows.md) — writing
+  and testing a workflow definition