akm-cli 0.9.0-rc.2 → 0.9.0-rc.3

package/docs/migration/release-notes/0.9.0.md

@@ -1,8 +1,9 @@
 Migration notes for akm v0.9.0
 
-This is the final 0.9.0 cut. If you were already running a 0.9.0 beta, the
-main upgrade work is to align scripts, prompts, and stash layout with the
-released command surface.
+These notes apply to the 0.9.0 release candidates and final release. If you
+were already running a 0.9.0 beta, align scripts, prompts, and stash layout
+with the current command surface and verify every durable artifact before
+normal use.
 
 Key operator-facing changes:
 
@@ -17,6 +18,9 @@ Key operator-facing changes:
 - Proposal workflow is fully consolidated around `akm improve`, `akm propose`,
   and `akm proposal ...`. Update any old `akm reflect`, `akm distill`,
   `akm accept`, `akm reject`, or `akm proposals` usage.
+- Config, `state.db`, and `workflow.db` are now classified independently by the
+  explicit `akm migrate` coordinator. Normal commands refuse old, future, or
+  divergent durable schemas instead of attempting migration as a side effect.
 
 Primary public command family for 0.9.0:
 
@@ -28,11 +32,24 @@ Primary public command family for 0.9.0:
 - `akm proposal accept <id>`
 - `akm proposal reject <id> --reason "..."`
 
-Recommended post-upgrade checks:
-
-- Run `akm help migrate 0.9.0` on every machine where the CLI is installed.
+Required upgrade checks:
+
+- Before crossing from 0.8 to 0.9, create an independent filesystem backup and
+  prepare a valid 0.9 config. The installed 0.8 binary does not know the 0.9
+  migration protocol: install or stage the 0.9 binary, then run
+  `akm migrate apply --config <prepared-0.9-config>` before any normal command.
+- On an existing 0.9 installation, run `akm migrate status`. If it reports
+  `ready`, run `akm migrate apply`; an already-current active config is used as
+  the target.
+- Do not continue when status reports `blocked`. Preserve the reported backup
+  run and resolve the named artifact or active-operation error first.
+- Restore is explicit and destructive: `akm backup restore --for 0.9.0 --run
+  <backup-run-id> --confirm`. It creates and verifies a rescue backup before
+  replacing current artifacts.
+- Run `akm help migrate 0.9.0` for the storage and command-surface checklist.
 - Run `akm-migrate-storage --yes` once if the stash ever used `vaults/`.
-- Rebuild the index with `akm index`.
+- Rebuild derived search data with `akm index` only after migration status is
+  `current`; indexing does not migrate config or durable schemas.
 - Review agent instructions and docs for old `vault`, `reflect`, and `distill`
   examples.
 

package/docs/migration/v0.8-to-v0.9.md

@@ -8,18 +8,100 @@ installation, then migrate the affected assets deliberately.
 
 ## Engine And Task Assets
 
-Before editing a 0.8 configuration, create a recovery bundle:
+The 0.8 binary does not contain `akm migrate` or the
+`upgrade --migration-config` contract. Do not attempt to invoke either command
+with 0.8, and do not use 0.8 self-update to cross this boundary.
+
+Use this package-manager/manual boundary procedure instead:
+
+1. Stop AKM writers, schedulers, and workflow drivers.
+2. Prepare the complete 0.9 config in a separate file. Do not replace the live
+   0.8 config; AKM cannot infer names when old LLM and agent profiles collide.
+3. Take an independent filesystem backup of the live 0.8 `config.json`,
+   `state.db`, and `workflow.db` (including any SQLite `-wal`/`-shm` files).
+   Store it outside AKM's data directory and verify it before continuing.
+4. Install 0.9 with the package manager, or download, checksum, and stage the
+   0.9 standalone binary. A package-manager install replaces the managed 0.8
+   package; a standalone operator should retain the old executable. Keep the
+   independent data backup in either case.
+5. Invoke the newly installed or staged 0.9 binary, whose migration startup
+   bypass can read the old installation without loading its config normally:
+
+Package-manager installation examples for step 4:
 
 ```sh
-akm backup create --for 0.9.0
+npm install -g akm-cli@0.9.0
+# or: bun install -g akm-cli@0.9.0
+# or: pnpm add -g akm-cli@0.9.0
 ```
 
-The immutable bundle is stored under `$CACHE/migration-backups/0.9.0`
-(`$XDG_CACHE_HOME/akm` by default on Linux). It records both present and absent files for
-`config.json`, `state.db`, and `workflow.db`, verifies every captured file by
-SHA-256, and is created automatically before AKM first opens either canonical
-durable database for the 0.9 engine migrations. Do not move individual files
-into or out of the bundle; verification fails closed on any mismatch.
+```sh
+# Package-manager install: this `akm` is now the 0.9 binary.
+akm migrate status --config ./prepared-0.9.json
+akm migrate apply --config ./prepared-0.9.json --dry-run
+akm migrate apply --config ./prepared-0.9.json
+
+# Or invoke a checksummed staged standalone binary explicitly.
+./akm-0.9 migrate status --config ./prepared-0.9.json
+./akm-0.9 migrate apply --config ./prepared-0.9.json
+```
+
+Status and dry-run perform the same read-only eligibility checks and report the
+source config plus target config explicitly. Apply validates the target in
+memory, creates a verified recovery run, applies pending `state.db` and
+`workflow.db` migrations one transaction at a time, and atomically installs the
+prepared config last. If any later artifact fails, apply restores config and
+both databases from the verified run before returning. Each artifact is
+classified independently, so a current config with pre-cutover databases can be
+recovered safely.
+
+Apply records durable `prepared`, `state-applied`, `workflow-applied`,
+`config-applied`, `rollback-prepared`, and `committed` phases. Every phase stores
+streaming size/SHA fingerprints for config, both databases, and SQLite sidecars;
+a resume or rollback first requires the exact live generation. After a process
+crash, ordinary config and canonical database access fail closed; `akm migrate
+status` reports the pending phase and `akm migrate apply` resumes idempotently
+from the retained target and verified backup. Apply also refuses before backup
+while managed database handles, maintenance activities, AKM mutation locks, or
+workflow claims are live.
+
+Canonical state/workflow opens check for pending recovery both before and after
+registering their maintenance activity. Config writers perform the second check
+while holding the same config lock used by migration, closing the check/start
+race without recreating files or accepting a write.
+
+Each database mutation also writes an operation-specific generation marker in
+the migration transaction. If the process dies after the durable mutation but
+before advancing the apply journal, recovery accepts only that authenticated
+one-artifact adjacent generation while every unaffected fingerprint remains
+exact. Config adjacency is authenticated against the exact serialized target.
+If rollback restore commits before the apply journal is removed, the next apply
+authenticates the live files against the backup generation and removes only the
+stale apply journal.
+
+Once already running a contract-capable 0.9 release, future self-upgrades may
+pass a prepared target through the coordinated upgrade path:
+
+```sh
+akm upgrade --migration-config ./prepared-0.9.json
+```
+
+This command is not the 0.8-to-0.9 procedure. The already-installed 0.8 binary
+cannot contain or enforce safeguards added in 0.9, so operators must follow the
+manual boundary above rather than relying on 0.8 self-update. For 0.9+ upgrades,
+the current binary preflights only its current artifact state; it does not parse
+a prepared config for the future release. After installation, only the new
+binary receives `--config` during apply. If the active config is already current,
+no migration-config flag is needed.
+
+Recovery runs are stored under
+`$DATA/backups/migrations/<installation-id>/<run-id>/`. They record present and
+absent `config.json`, `state.db`, and `workflow.db` artifacts, ordered migration
+ledgers, sizes, and streaming SHA-256 hashes. SQLite snapshots must also pass
+`PRAGMA quick_check` and ledger-prefix validation before the manifest is
+published. `akm backup create --for 0.9.0` creates an additional unique run when
+an operator wants a manual snapshot. Routine config writes, telemetry, and
+already-current database opens do not depend on any historical run.
 
 Replace `profiles.llm.<name>` and `profiles.agent.<name>` with one
 `engines.<name>` map. Replace `defaults.llm`, `defaults.agent`, and
@@ -374,19 +456,42 @@ workflow lease exists. Then, while still running the 0.9 binary, restore the
 complete pre-cutover snapshot:
 
 ```sh
-akm backup restore --for 0.9.0 --confirm
+akm backup restore --for 0.9.0 --run <run-id> --confirm
 ```
 
-Restore verifies the manifest, permissions, sizes, and checksums before
-replacing anything. It restores each original file and removes a canonical DB
-that the manifest recorded as originally absent, including its WAL/SHM
-sidecars. Restore also holds the global maintenance barrier from its last
-lock/lease check through replacement, so a new index writer, improve/extract
-lock, lockfile writer, or workflow engine lease cannot start in that window.
-The recovery bundle itself remains in `$CACHE` for repeatable recovery. If
-verification reports corruption, preserve the bundle and recover
-from an independent backup; do not delete the manifest or regenerate it from a
-post-cutover config.
+Restore verifies the selected run before changing live files and then creates a
+second verified rescue run of the current installation. It stages every
+replacement beside its destination, writes a durable restore journal,
+quarantines each database together with its WAL/SHM sidecars, and only then
+publishes clean staged files. The journal records a durable committed phase
+before cleanup: an earlier interruption rolls back, while an interruption after
+commit finishes cleanup without mixing generations. While either recovery phase
+is pending, ordinary config and canonical database access fail closed before
+accepting writes or recreating absent files. The selected and rescue runs remain
+under `$DATA`; if verification reports corruption, preserve them and recover
+from an independent backup.
+
+Recovery validates the complete restore journal before removing or renaming any
+path: journal format and migration version, phase, exact artifact and SQLite
+sidecar set, operation-bound stage/quarantine names, path uniqueness, source
+backup, and the expected prepared/committed filesystem state. A malformed or
+stale journal remains in place and recovery fails closed for operator diagnosis.
+Committed recovery additionally authenticates each published artifact against
+the selected backup's byte size and streaming SHA-256, then reruns config-state
+validation or SQLite `quick_check` and ledger validation before deleting any
+quarantine or journal.
+
+Prepared rollback is itself crash-idempotent. The journal fingerprints the
+original config/database/sidecar generation before quarantine. If recovery dies
+after restoring a quarantine or deleting a stage but before journal deletion,
+the next recovery authenticates the already-restored destination and continues
+cleanup. A same-ledger but byte-different substitution fails closed.
+
+Migration config files, manifests, and apply/restore journals are read through
+bounded readers (1 MiB each). Oversized local control files fail closed rather
+than being loaded wholesale. Apply also measures the complete serialized journal
+before its first write; a near-limit config whose expanded target would exceed
+the same cap is rejected before any apply journal or artifact mutation.
 
 Only after restore succeeds should you install the older AKM binary. A 0.8
 binary must not run against a 0.9 config or against `state.db` migration 017 /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-rc.2",
+  "version": "0.9.0-rc.3",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [