akm docs

0.9.2 single-runtime reconstruction brief

This is the recovery ledger for rebuilding pull request #817 around one runtime architecture. It is both the implementation brief and the status record. Every phase ends in a recoverable Git commit, and this table is updated with the exact commit and verification result before the next phase begins.

Identity and recovery sources

The prior damaged replay and partial temporary replays are evidence only. No file or commit is promoted from them without replaying the original successful operation against the approved input and verifying the result.

Required architecture

  1. Legacy task files are accepted only by the explicit v2-to-v3 migrator. Normal loading, scheduling, projection, and execution accept task v3 only.
  2. Markdown and GitHub-shaped YAML workflow sources compile into one source IR. That IR freezes into durable plan v4 and one workflow engine executes it.
  3. Durable plan v4 is the only executable or resumable stored workflow plan. Pre-v4 plans are rejected; they do not enter a parallel decoder/replayer.
  4. Command, task, and workflow execution use one resolver and lowering path. Shared lowering replaces superseded dispatchers instead of wrapping them.
  5. Compatibility is confined to deliberate input and storage boundaries. It is not threaded through the current runtime.
  6. Semantic inference uses the normal external @huggingface/transformers package/build input. There is no copied runtime under src/vendor, no installed-consumer dependency policy, and no second semantic package tree.
  7. A contract boundary is tested once. Distinct fault, security, durability, and platform behavior remains covered; duplicated characterization and consumer-by-consumer ownership tests are removed.

Upgrade behavior that remains

These are product upgrade paths. They do not authorize general compatibility runtimes, three-database cutover machinery, old config-shape coordinators, or pre-v4 workflow replay.

Explicit deletion and replacement ledger

Superseded surface Required result
src/vendor Hugging Face/ONNX copy Delete; resolve the ordinary external dependency
Installed-consumer semantic manifest/provenance policy Delete
Runtime task-v2 readers/executors Delete; explicit migrator owns v2 input
Pre-v4 workflow plan execution Delete; reject at the storage boundary
Parallel Markdown/YAML execution paths Replace with peer parsers feeding one source IR
Old command/task/workflow dispatch paths Replace with shared resolve/prepare/lower/dispatch ownership
Config-generation/general migration coordinator Delete
Three-database cutover, backup/restore engine, and crash journal Delete
Legacy ref/content/source/task-target migration modules Delete
Legacy proposal/session/persisted-id projection bridges Delete unless a current storage invariant proves ownership
Characterization/meta-analyzer/consumer-copy test suites Delete or consolidate at the owning boundary

Every deletion is checked for callers, documentation, package closure, and a remaining owner. A green test alone is not evidence that two architectures are acceptable.

Pull-request review fixes that must survive reconstruction

Replay rules

Checkpoint plan and live status

Phase Scope Status Recovery commit Verification / blocker
0 Brief, exact base, recovery inputs Complete 559c7ed5f Fresh no-hardlinks clone at exact approved input; brief committed
1 External semantic dependency and task-v3 runtime boundary Complete 191b0df6d Vendored runtime deleted; task v2 migration-only; focused 63/63 and tsc --noEmit green
2 Peer workflow sources, one source IR, durable-v4-only engine Complete 371bd09dd Source-IR checkpoint 78/78; final v4-only boundary 127/127 and tsc --noEmit green; pre-v4 decoder/replayer deleted
3 Shared execution lowering; delete config/storage/general migration compatibility Complete 2a64bbace Proposal source ingress and reflect lowering received independent approval; the post-phase residue audit is recorded below
4 Apply and independently verify all four PR review fixes Complete 8460f684e Independent combined review approved all four fixes after 159 focused tests, TypeScript, Biome, and compiled standalone acceptance
5 Post-review cleanup, docs, ownership/deletion audit, duplicate-test consolidation Complete 6cbe88052 All scoped cleanup is independently approved and integrated. The canonical index now has one exact generation, item-ref identity, bundle-owned cleanup/writability, and fail-closed read preflight. Its 58-file integration delta passes 869/869; the prior full unit and integration baselines remain green.
6 Install/schema generation, formatting, architecture and diff audit Complete 1aee64eb98 Frozen install, schema, formatting, and exact diff/zero-hit architecture audit complete. No duplicate runtime remains; the audit's active documentation corrections are independently approved and integrated.
7 Full unit/integration/package/release gates and remediation Complete 89cd5e3977 Official release-check.sh including Docker is green: unit 3836/3836, integration 5606 pass / 52 gated skips / 0 fail, Docker 7/7 targets and 182/182 smoke assertions. Package, Node 24, semantic/slow, and standalone evidence is also green.
8 Immutable candidate review and PR update In progress d5540702e7 Two independent reviews approved the exact candidate and release/0.9.2 was fast-forwarded without force. Fresh exact-SHA CI exposed one host-masked test fixture; a tests-only remediation is in progress before any PR metadata changes.

Phase 8 remote ledger

Phase 3 recovery checkpoints

Phase 4 recovery checkpoints

The post-phase audit confirmed the core task-v3-only, workflow-v4-only, source-IR, external semantic dependency, and shared lowering cutovers. It also identified the following remaining cleanup owned by phase 5: remove the dual legacy/current derived-index schema, gate destructive historical state-ledger upgrades safely, decide and pin the prompt-free interactive agent boundary, remove exact-version Hugging Face fallback branches, remove the health session-log compatibility result, and consolidate duplicated boundary, execution, scheduler-backend, and credential-safety tests without deleting unique fault/security/durability/platform invariants.

Phase 5 recovery checkpoints

Phase 7 recovery checkpoints

Rejected phase 5 candidates

Required final evidence