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
- Task v2 exists only as input to the explicit
akm migratecommand. Normal task load, run, scheduler, and projection accept task v3 only. - 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.
- Durable plan IR v4 is the only executable stored workflow plan. Pre-v4 plans are rejected; there is no compatibility decoder or replay engine.
- Command, task, and workflow execution share one resolver and lowering pipeline. Old dispatchers are deleted rather than wrapped.
- 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 upgradeintent 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. - Semantic inference uses the ordinary external
@huggingface/transformersdependency. AKM does not copy that package intosrc/vendorordist/vendor, pin its transitive runtime layout, or carry a second installed-consumer dependency policy. - 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:
audit remaining source modules for old dispatchers or compatibility aliasesclosed out by P4 §3 (docs/plans/specs/p4-deletions-closeout.md). P4's three deletion families were exactly this: the GitHub Action locator grammar (a recognized-but-dead dispatcher variant), task source v3 acceptance and its P1b/P2b compat shims (src/tasks/runtime-v3.ts,src/tasks/runner.ts,src/workflows/ir/source-freeze-v4.ts,src/tasks/source/parse-v3-adapter.ts,src/tasks/model/{definition,schedule}.ts), and the multi-job parse/ordering machinery (src/workflows/source-ir/ordering.ts). Each family ran a zero-consumer grep before deleting (pasted into its own commit body) and a post-deletion sweep after; the Size checkpoint section below has each family's ownsrc/shortstat and file list. Confirmed still-zero at this checkpoint:rg -n 'github-action|remote-action-acquisition|isGithubLocatorShape|GITHUB_OWNER' src/ schemas/,rg -n 'parseTaskV3Yaml|parseTaskV3Document|classifyTaskV3Uses|TASK_V3_SCHEMA_VERSION' src/,rg -n 'canonicalTopologicalJobs|job-count-limit|missing-job-dependency|job-dependency-cycle|duplicate-job-dependency|exactly one source-IR job|Multi-job workflow cannot execute' src/. One item remains and is deliberately not folded into this close-out: §8 row R-R1 (P3a §0, P3b §0) defers renamingschema-v4.ts/freeze-v4.ts/environment-v4.tsand theTaskV3*/PreparableTaskDocumenttype family to a follow-up commit, on the binding rationale that a rename storm across ~40 import sites would bury the deletion diff this checkpoint exists to prove. That is a naming cleanup, not a live dispatcher or compatibility alias — nothing on that list still branches on a retired grammar or version — so it is real remaining work, named here rather than dropped, without reopening this bullet.- run architecture-focused tests, full unit/integration checks, build, package closure, and release checks on one immutable candidate.
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.