akm-cli 0.9.16-alpha.1 → 0.9.16

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

@@ -1,110 +1,72 @@
 Migration notes for akm v0.9.16
 
-The index is redesigned end to end (`docs/plans/index-redesign.md`): `akm
-index` is now reconcile-then-drain instead of a walk/clean/embed/finalize
-phase pipeline, everything derived from a file is keyed by the hash of what
-it was derived from, and there is exactly one text table
-(`unit_texts`/`units_fts`) and one vector table (`units`/`units_vec`) instead
-of the old entry-level and fragment-level duplicates. The derived `index.db`
-generation changes from v23 to v24.
+Scheduled execution is now authorized by host-local config and bound to the
+specific source installed under a bundle id. Existing
+`scheduler.enabled` entries need a `sourceId` before the 0.9.16 runtime will
+load them. Run this once after upgrading:
 
-**First run after upgrade.** On the first normal read (or an explicit `akm
-index`), akm detects the v23 cache cannot serve queries under v24 and
-rebuilds the derived generation: `entries` and every unit are re-derived from
-your files (a stat walk plus a parse of everything, since the old generation
-has no `files` stat cache to diff against — this is CPU-bound and fast, not
-network-bound). The new unit vector store starts empty: the old
-`embeddings`/`entries_vec` tables it replaces are not carried forward, so
-every unit is embedded once at your configured provider, the same as a fresh
-install. On a large corpus this is a real, paid cost, once per embedding
-model, and it is never repeated for unchanged text again:
-not on a rename, not on the next `akm index --full`, not on a future
-generation bump, only on a genuine content or model change. Search works
-lexically from the first minute of the rebuild and gains semantic results as
-the embedding queue drains in the background. `akm index status` reports the
-queue's progress (units with a vector for the active identity, versus
-still-pending) without triggering any writes. Do not run an older akm against
-an index this release has already rebuilt: upgrade that binary instead.
+```sh
+akm migrate apply
+akm task sync
+```
 
-**Config keys removed.** `embedding.maxInputTokens`, `embedding.maxTokens`,
-`embedding.batchSize`, and `embedding.contextLength` are gone from the
-schema entirely (0.9.15 had already stopped reading them for packing;
-0.9.16 removes them outright). `akm index` packs every embedding request
-against the provider's own probed context window and slot count — this is
-unchanged from 0.9.15, only what it packs (units instead of whole entries)
-moved. `search.minScore` is also gone: reciprocal-rank fusion was tried and
-measured worse (0.918 mean vs. a 0.933 pre-redesign baseline, full table in
-`docs/plans/index-redesign.md`) and rejected. What ships instead scores
-lexical evidence by magnitude through the calibrated BM25 transform
-(`stableFtsScore`) and fuses it with cosine similarity at a 0.7/0.3 split,
-with the exact/prefix/relaxed lexical tier a hit came from ranking ahead of
-that fused score — the transform's realized output band turned out to be
-only 0.021 wide after weighting, too narrow on its own to separate a strong
-match from a weak one. No separate floor is applied over any of it, which
-is why `minScore` has nothing left to tune. A config file that still sets any of these five keys
-loads without error — they are simply ignored, like `embedding.chunkSize`
-before them — see [Retired
-Configuration](../../reference/configuration.md#retired-configuration).
+The migrator binds each existing grant to the bundle source currently in
+config, drops grants whose bundle no longer exists, and writes a config backup
+before changing the file. `akm migrate status` and `akm migrate apply
+--dry-run` report this as a blocking migration because silently trusting a new
+source would defeat the boundary. Task frontmatter cannot enable scheduling.
+Use `akm task enable <bundle//tasks/name>` or `akm task disable ...`; a plain
+`akm task sync` reconciles all enabled bundles and removes installed entries
+for bundles that have since been disabled.
 
-**`--skip-if-locked` is deprecated and does nothing.** Index runs no longer
-take a rebuild lock at all — every write is a short, idempotent,
-content-addressed transaction, and two concurrent `akm index` runs converge
-on the same end state instead of contending — so there is nothing left to
-skip around. Passing the flag prints one deprecation warning and the run
-proceeds exactly as an ordinary `akm index` would; it is kept only so an
-existing script or scheduled task does not fail on an unknown flag.
+Replacing a bundle's source locator or component root invalidates its old
+scheduler grants. Re-enable the reviewed task after the replacement. Normal
+content updates, adapter detection, and website crawl-policy changes keep the
+same source identity.
+Removing a bundle revokes all grants owned by that bundle. A bundle with
+`enabled: false` is inert for content reads, writes, indexing, execution, and
+scheduling, and it cannot remain `defaultBundle` or `defaultWriteTarget`.
+Explicit lifecycle operations such as `akm bundle update <name>` may still
+refresh a disabled bundle without activating its content.
 
-**`--enrich` and `--re-enrich` are removed.** Plain `akm index` now always
-performs metadata enrichment when an LLM engine is configured (the same
-behavior `--enrich` used to opt into); re-enrichment of index-time LLM
-passes is not exposed in this slice. Both flags now fail with a `UsageError`
-(exit 2) naming the replacement, rather than silently doing nothing.
+Two bundle ids may no longer point at the same physical content root, including
+through symbolic links. This alias is not safe to rewrite automatically because
+durable refs name the bundle id. Keep the id whose refs should survive and
+remove the duplicate config entry; config errors name both ids and the shared
+root.
 
-**`--clean` and `--dry-run` are removed.** Every `akm index` run already
-removes stale entries as part of reconcile — the same work `--clean` used to
-opt into — so there is no longer a distinct pass for `--dry-run` to preview.
-Both flags now fail with a `UsageError` (exit 2) instead of being silently
-accepted.
+Config inheritance now has a portable-data boundary. An inherited config may
+supply ordinary portable settings, including engine endpoint and model fields,
+but host authority is always local. Inherited bundle/default declarations,
+scheduler grants, execution policy, credentials, executable paths/arguments,
+setup state, registry declarations, and write-capable strategy hooks are
+ignored with a warning. Bundle-relative `extends` paths are checked against
+the bundle's physical root, including every link in an extends chain.
 
-**`akm index`'s result envelope renames two fields and drops one.**
-`generatedMetadata` is now `entriesUpserted`: it always counted the files
-reconcile added or changed, never LLM-generated metadata, so a script reading
-it as enrichment coverage was being misled. `directoriesScanned` is now
-`sourcesScanned`, because reconcile is a flat per-file stat walk with no
-directory granularity left to count, and it reports configured source roots.
-`directoriesSkipped` is gone: it could only ever be `0` under the new walk.
-The text output's summary line follows the same change. A script reading the
-old names gets `undefined` and should switch to the new ones.
+Commands and personas can no longer set `workspace`, `environment`, or
+`runtime` in frontmatter. Those values select host execution context and now
+produce a configuration error. Asset-requested tools are constrained by the
+local allowlist:
 
-**`akm index status` is new.** A cheap, read-only snapshot — files tracked,
-entries, distinct units, how many have a vector for the active embedding
-identity, the identity itself, and the last reconcile/build times — with no
-writes. It mirrors `akm info`'s handling of a missing or unreadable index: an
-absent index reads as the ordinary first-run state, and one that exists but
-cannot be read is reported, never silently presented as empty.
+```json
+{
+  "execution": {
+    "allowedTools": ["read_file", "search"]
+  }
+}
+```
 
-**Exit codes are unchanged.** `INDEX_DB_CONTENDED` (exit 75) already existed
-and still means the same thing — a second connection held a write
-transaction long enough to exhaust SQLite's own busy timeout — but it now
-covers genuinely rare contention instead of also standing in for the old
-rebuild lock's own failure modes, which no longer exist because the rebuild
-lock itself is gone.
+Use `"*"` only when every asset the host may execute is trusted. If an asset
+requests tools that the selected transport cannot enforce, akm fails before
+dispatch instead of sending an over-privileged request.
 
-**The optional cross-encoder rerank pass moves from `akm curate` to `akm
-search`.** It was always meant for search; `search.curateRerank` (0.9.15,
-#951) is renamed `search.rerank` with no compatibility alias — the old key
-shipped hours earlier and default-off, so nobody has it meaningfully set.
-`akm curate` no longer reranks at all.
+The old combined `--allow-insecure` switch has been removed. The two unrelated
+decisions are now explicit:
 
-**`"ready-js"` is retired from `akm info`'s `semanticSearch.status` and from
-`akm index`'s verification status.** It named a pure-JS cosine-similarity
-fallback for when the `sqlite-vec` extension was unavailable; the new unit
-vector store has no BLOB-table fallback to fall back to, so nothing produces
-that value any more. The two surfaces now diverge in what replaces it:
-`akm info`'s `semanticSearch.status` reports `"pending"` until the
-embedding queue finishes draining and `"ready-vec"` once it has — a host
-without the extension can never reach `"ready-vec"` (`vecAvailable` false
-rules it out) and stays `"pending"` indefinitely; that status has no
-`"blocked"` value at all. `akm index`'s own verification status reports the
-same `"pending"`/`"ready-vec"`, plus `"blocked"` when a run makes no
-embedding progress at all.
+- `--allow-insecure-transport` permits a reviewed plain-HTTP bundle or
+  registry endpoint.
+- `--allow-dangerous-env-keys` permits reviewed dangerous environment-key
+  findings during bundle add/update or env activation.
+
+Update scripts to use the narrow flag that matches the risk being accepted.
+Neither flag implies the other.

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

@@ -7,11 +7,6 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
-- [0.9.16](0.9.16.md) — the index redesign: `akm index` is now
-  reconcile-then-drain over one content-addressed text table and one vector
-  table, index generation v23-to-v24, five retired config keys, `--enrich`/
-  `--re-enrich`/`--clean`/`--dry-run` removed, `--skip-if-locked` now a
-  no-op, and the new `akm index status`
 - [0.9.15](0.9.15.md) — exit-code 75 for lease/state.db contention,
   `--require-engines` scheduled task templates, `--no-probe` cli-version
   skip, thinking-control wire forms, embedding re-embed safety and

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -104,7 +104,6 @@ with:
   content: Review the execution contract.
 schedule:
   - cron: "15 4 * * 1"
-    enabled: false
 engine: reviewer
 model: exact-model-id
 timeout: 45000
@@ -134,12 +133,11 @@ earlier 0.9.x releases and are summarized further down):
   parses, runs with `akm task run`, and is silently skipped by
   `akm task sync` (zero bindings, zero failures) — it never has to declare
   a trigger just to be a valid document.
-- **`akm.enabled` becomes per-schedule-binding.** v3's single
-  document-level `enabled: false` becomes that schedule entry's own
-  `enabled: false` in v4 — there is no longer a document-level flag at all.
-  A disabled task with no cron trigger (only `on.workflow_dispatch`) has no
-  v4 representation and is `blocked` for manual review (see
-  [The migration procedure](#the-migration-procedure)).
+- **Source-owned enablement is removed.** Current task source v4 carries no
+  `enabled` field. `akm-migrate` removes v2/v3/v4 source flags and seeds the
+  host-local `scheduler.enabled` allow-list only from native scheduler
+  bindings it can prove are currently enabled. A source cannot activate
+  itself merely by being installed from a bundle.
 - **Typed `inputs:` with defaults and `required:`.** v4 tasks can declare
   named, bounded-JSON-Schema parameters, each optionally carrying a
   `default` or `required: true` (mutually exclusive). `akm task run`
@@ -224,7 +222,7 @@ by hand using this field mapping:
 |---|---|
 | `command:` (array, argv style) | `run:` (string) plus `shell:` |
 | `timeoutMs:` | `timeout:` |
-| `enabled:` (document level) | removed — use `schedule:` as a list of `{cron, enabled}` entries |
+| `enabled:` (document level) | removed — use host-local `scheduler.enabled` (`akm task enable` / `disable`) |
 | `schedule:` (cron string) | still accepted as a bare string, or as the list form above |
 
 validate it, and rerun the preview. You can either write the replacement
@@ -248,7 +246,6 @@ Common blocked reasons and what to do about each:
 | `github-action-target-removed` | The task's `uses:` is a GitHub Action locator (`owner/repo[/path]@ref`); that spelling has no task source v4 equivalent. | Rewrite the target as `commands/`, `scripts/`, `workflows/`, or `akm/command` by hand. |
 | `with-on-non-command-target` | A `with:` block is authored on a target other than `uses: akm/command`. | Declare `inputs:` on the task instead; a workflow step composing it binds them with its own `with:`. |
 | `ambiguous-scheduling-source` | The document declares both `akm.schedule` and `on:`. | Pick one; the migrator will not guess which one wins. |
-| `enabled-false-has-no-schedule-entry` | `akm.enabled: false` with no cron trigger to attach it to (the only trigger is `on.workflow_dispatch`). | Task source v4 has no document-level `enabled` flag — decide whether the task should be scheduled (add a cron) or left manual-only (drop `akm.enabled`), then re-run. |
 | `read-only-source` | The owning source or file is not writable. | Move or re-source the file somewhere writable, or edit it by hand. |
 | `invalid-v3-task` | The v3 document itself is structurally invalid (unknown fields, missing selector, malformed trigger, etc). | Fix the underlying v3 document first — the migrator translates structure, it does not repair it. |