akm docs

0.9.2 architecture deletion audit

This file is the reconstruction ledger for the 0.9.2 release branch. It is a deletion audit, not a compatibility roadmap. A release change is complete only when the superseded runtime is absent, the remaining boundary is explicit, and one contract suite proves that boundary.

Target architecture

  1. Task v2 exists only as input to the explicit akm migrate command. Normal task load, run, scheduler, and projection accept task v3 only.
  2. Markdown and GitHub-shaped YAML workflow sources compile to source IR v1. Source IR freezes to durable plan IR v4 and one workflow engine executes it.
  3. Durable plan IR v4 is the only executable stored workflow plan. Pre-v4 plans are rejected; there is no compatibility decoder or replay engine.
  4. Command, task, and workflow execution share one resolver and lowering pipeline. Old dispatchers are deleted rather than wrapped.
  5. Configuration and database schemas are current-only runtime contracts. Exact-prefix additive state DDL and the verified data-preserving migration 002 rebuild run automatically. Historical destructive migration 018 requires successful akm upgrade intent and one verified sibling safety snapshot; an already-existing unversioned file (with an absent or empty migration ledger) likewise requires a verified snapshot before migration 001, with one writer lock retained through ledger initialization and migrations 001–002. There is no general storage migration framework.
  6. Semantic inference uses the ordinary external @huggingface/transformers dependency. AKM does not copy that package into src/vendor or dist/vendor, pin its transitive runtime layout, or carry a second installed-consumer dependency policy.
  7. Tests pin each public boundary once. Fault tests remain where they prove a distinct safety invariant; characterization and surface-by-surface copies do not.

Kept boundaries

Boundary Kept behavior
Package upgrade akm upgrade continues to update npm/Bun/pnpm or a standalone binary. After a successful replacement it owns the narrow state-ledger safety gate for migration 018 and pre-existing unversioned files; it does not run a general data migration.
Task migration akm migrate status, akm migrate apply --dry-run, and akm migrate apply inspect or atomically convert task-v2 files to task v3. Ambiguous inputs remain blocked.
Database upgrade Exact-prefix additive migrations and the data-preserving 002 rebuild run automatically. Migration 018 requires akm upgrade, which holds one writer-exclusion window across the exact-ledger recheck, one inode-bound and verified sibling state.db snapshot, and its immutable released SQL. An existing unversioned file is snapshotted before ledger creation or migration 001, and the same writer lock remains held through migrations 001–002; ordinary open writes nothing. Unknown/divergent ledgers fail closed.
Workflow resume Only a valid, immutable durable-v4 plan resumes. Source/config/index are not reread.
Source formats Peer .md and .yml workflow sources enter the same source-IR compiler and the same v4 freezer.

Deleted architecture

Deleted surface Status
Vendored Hugging Face/ONNX runtime and copied semantic package tree Removed
Installed-consumer semantic dependency manifest/provenance enforcement Removed
Config-generation and config-shape migration coordinator Removed
workflow.db/index.db/state.db cutover coordinator, backup/restore engine, and crash journal Removed
General akm-migrate storage and akm-migrate-storage surfaces Removed
Legacy ref-grammar/content/source/task-target migration modules Removed
Pre-v4 workflow plan decoder/replayer Removed
Runtime task-v2 reader/executor Removed; explicit task migrator only
akm agent --command stored-command alias Removed; use akm command run
Optional harness fields retained for external compatibility Removed; harness contract is required/current
Proposal filesystem importer and legacy proposal-row decoder Removed
Legacy session log readers and persisted-id projection bridge Removed
Duplicate migration characterization/property/differential suites Removed
Duplicate execution characterization layer Removed
Synchronous lockfile writer exported only for the deleted general migrator Removed; test fixtures seed lock state from tests/_helpers
Three-database cutover and quarantine runtime Removed; released migration 020 and its historical table DDL remain immutable, with no current reader or writer
General database backup/restore machinery Removed; the state-ledger gate has one non-reusable VACUUM INTO safety-copy step before migration 018 or before migration 001 for an existing unversioned file
External driver protocol (workflow brief / workflow report / --settle) Removed; decision record RESOLVED (Option B) — see docs/architecture/specs/driver-protocol-keep-or-cut.md §10

Active audit

The following work remains before this branch is release-ready:

Scheduler-backend consolidation is complete and independently approved. One shared conformance matrix covers cross-platform CAS/ownership/rollback behavior, including zero native mutations on rejected operations; backend-local parsing, encoding, stabilization, compensation, and fault cases remain.

Size checkpoint

Branch-level, git diff --shortstat origin/release/0.9.2...HEAD (measured at commit 120e1c0b; re-measure before any later commit changes the diff):

Path Files changed Insertions Deletions Net
src/ 120 +10,776 -4,100 +6,676
tests/ 160 +23,822 -1,501 +22,321
docs/ 33 +14,604 -191 +14,413
Overall (unfiltered) 328 +51,222 -5,931 +45,291

The three path rows do not sum to the overall row — a file changed outside all three globs (CHANGELOG.md, STABILITY.md, README.md, schemas/**, and similar repo-root/schema files are common in a docs-and-vocabulary close-out phase) is counted in the overall row and in none of the three, and git diff --shortstat's own file count is not a per-glob sum in any case.

The prior checkpoint's figure — against origin/main, commit 092400a19, net +33,075 (+79,209/-46,134) — no longer reproduces and was never comparable to begin with: it measured a different base branch (origin/main, not origin/release/0.9.2, the actual release this work diffs against) at a much earlier commit, before P3a, P3b, and P4 landed. Re-measured against the correct base at this checkpoint, the true figure is net +45,291 (+51,222/-5,931).

Deletions this phase lands — one row per §3 family (docs/plans/specs/p4-deletions-closeout.md), each git diff --shortstat <family-parent>..<family-commit> -- src/:

Family Commit src/ shortstat Files deleted outright
A1 — GitHub Action locator grammar (§3.1) 290fdab3 7 files changed, +40/-243 none — the grammar was excised from files that keep other responsibilities (source-v3.ts, prepare.ts, semantics.ts, uses.ts, errors.ts, task-source-v4.ts); schemas/akm-task.json's githubActionRef removal is outside src/
A2 — task source v3 acceptance out of src/ (§3.2) 09691628 33 files changed, +638/-1,230 src/tasks/model/definition.ts, src/tasks/model/schedule.ts, src/tasks/runner.ts, src/tasks/runtime-v3.ts, src/tasks/source/parse-v3-adapter.ts, src/workflows/ir/source-freeze-v4.ts
A3 — multi-job confinement (§3.3) fde346da 10 files changed, +108/-106 src/workflows/source-ir/ordering.ts

src/tasks/source-v3.ts is not on either deleted-file list — per §0 (R-R1) it shrinks in place and keeps its name (further shrunk again, outside these three families, by this same review-fix pass's finding 4: a dead export { UsageError } and its supporting import). A2's insertions (+638) exceed a pure deletion because the same commit adds the vendored frozen migrator parser (scripts/akm-migrate/migrate/task-source-v3-frozen.ts, outside src/) and the new src/workflows/source-ir/triggers.ts that classifyTaskV3Triggers re-homes into (§3.2.3/P4-N3) — both required additions, not incidental growth.

The audit's own rule, restated: deletions must show. src/ is still net-positive against origin/release/0.9.2 — +6,676 lines (+10,776/-4,100) — and that is expected, not a shortfall. P2 and P3 added real, load-bearing capability release/0.9.2 did not have: task source v4 (typed inputs: with defaults/validation, a single bounded output: schema, per-schedule enabled), the input-binding contract shared between task and workflow params, child workflows (direct and task-wrapped composition, recursive freeze, independent resume, cancellation propagation, composition bounds), workflow outputs:, source IR v1 (the Markdown and GitHub-shaped YAML adapters plan irVersion 5 compiles from), the phase-specific UsageErrorCode family (D7, 38 codes' worth of task/workflow domain diagnostics), and two new introspection verbs (akm task explain, akm workflow plan). P4's three deletion families above removed real dead weight — the GitHub Action locator grammar, task source v3's parser and its P1b/P2b compat shims, and the multi-job parse/ordering machinery — but no version of this refactor was ever going to make src/ net-negative against the pre-refactor release while also shipping child workflows and a new task source generation. Claiming otherwise would be the hand-waved "significantly reduced" this section is bound not to write.