akm-cli 0.10.261126 → 0.10.261127

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/dist/commands/health/improve-metrics.js +23 -3
  3. package/dist/commands/health/md-report.js +4 -3
  4. package/dist/commands/improve/consolidate/pair-pass.js +52 -27
  5. package/dist/commands/improve/loop-stages.js +3 -2
  6. package/dist/commands/lint/base-linter.js +23 -20
  7. package/dist/commands/lint/index.js +26 -4
  8. package/dist/commands/sources/plugin-upgrade.js +23 -3
  9. package/dist/core/adapter/adapters/akm-lint.js +35 -12
  10. package/dist/core/adapter/adapters/shared.js +11 -22
  11. package/dist/core/asset/asset-ref.js +3 -2
  12. package/dist/core/asset/frontmatter-lint.js +17 -22
  13. package/dist/core/asset/lint-text.js +50 -0
  14. package/dist/indexer/indexer.js +5 -0
  15. package/dist/output/text/command-format.js +2 -1
  16. package/dist/scripts/akm-migrate-node.js +86 -37
  17. package/dist/scripts/akm-migrate.js +86 -37
  18. package/dist/storage/repositories/index-layout-repository.js +81 -0
  19. package/dist/storage/repositories/index-schema.js +18 -0
  20. package/dist/storage/repositories/task-history-repository.js +28 -0
  21. package/dist/storage/repositories/workflow-runs-repository.js +25 -0
  22. package/dist/tasks/run/attempt-lifecycle.js +8 -1
  23. package/dist/tasks/run/reconcile-abandoned.js +75 -0
  24. package/dist/tasks/run/run-task.js +9 -1
  25. package/dist/tasks/run/task-result.js +2 -0
  26. package/dist/workspace/graph-duplicates.js +124 -28
  27. package/dist/workspace/graph.js +39 -7
  28. package/docs/architecture/internals/health-advisories.md +1 -1
  29. package/docs/architecture/internals/improve-workflow.md +1 -1
  30. package/docs/architecture/internals/indexing.md +2 -2
  31. package/docs/architecture/internals/storage-locations.md +23 -4
  32. package/docs/reference/cli.md +7 -2
  33. package/docs/reference/workspace.md +11 -8
  34. package/package.json +1 -1
@@ -55,9 +55,9 @@ filesystem (NFS, SMB/CIFS, 9p, CephFS, FUSE including virtiofs; Linux detection
55
55
  ### `$DATA/index.db` (search index)
56
56
 
57
57
  A derived cache. `src/storage/repositories/index-schema.ts` (`ensureSchema`)
58
- creates ten tables: `index_meta`, `entries`, `entries_fts`, `entry_fragments`,
59
- `asset_links`, `embeddings`, `utility_scores`, `index_dir_state`,
60
- `llm_enrichment_cache`, and `registry_index_cache`.
58
+ creates twelve tables: `index_meta`, `entries`, `entries_fts`, `entry_fragments`,
59
+ `asset_links`, `embeddings`, `entry_layout`, `duplicate_pairs`, `utility_scores`,
60
+ `index_dir_state`, `llm_enrichment_cache`, and `registry_index_cache`.
61
61
 
62
62
  The layout number is `index_meta.version`, currently 26
63
63
  (`CANONICAL_INDEX_DB_VERSION`, `src/storage/repositories/index-entry-schema.ts`).
@@ -165,6 +165,17 @@ value is a derived memory or `{ "noChange": true }`, and an unrecognised or
165
165
  corrupt value falls through to a recompute (`src/indexer/passes/memory-inference.ts`,
166
166
  `src/indexer/db/llm-cache.ts`). `clearStaleCacheEntries` removes orphans.
167
167
 
168
+ #### `entry_layout` and `duplicate_pairs`
169
+
170
+ `entry_layout`: `entry_id` INTEGER PRIMARY KEY, `grp`, `x`, `y`, `z` (each
171
+ embedded entry's group by meaning and place in 3D). `duplicate_pairs`: `rank`
172
+ INTEGER PRIMARY KEY, `a`, `b` (entry ids), `cosine`. Derived from the stored
173
+ vectors at the end of `akm index` and rewritten whole when they change
174
+ (`src/storage/repositories/index-layout-repository.ts`); `index_meta.layoutKey`
175
+ is the hash of the vectors they were computed from, and `layoutGroups`,
176
+ `duplicateThreshold` and `duplicatesTruncated` describe them. `assets.graph`
177
+ reads them.
178
+
168
179
  #### `utility_scores`
169
180
 
170
181
  `entry_id` INTEGER PRIMARY KEY (FK to `entries(id)`, ON DELETE CASCADE),
@@ -245,13 +256,21 @@ One row per task run.
245
256
  |---|---|---|
246
257
  | `id` | INTEGER PRIMARY KEY AUTOINCREMENT | |
247
258
  | `task_id` | TEXT NOT NULL | |
248
- | `status` | TEXT NOT NULL | |
259
+ | `status` | TEXT NOT NULL | `active` while running, then `completed`, `blocked` or `failed`; `interrupted` when its owner process is provably gone (see below) |
249
260
  | `started_at` | TEXT NOT NULL | ISO-8601 |
250
261
  | `completed_at`, `failed_at` | TEXT | ISO-8601 |
251
262
  | `log_path` | TEXT | The per-run flat log file |
252
263
  | `target_kind`, `target_ref` | TEXT | Task target |
253
264
  | `metadata_json` | TEXT NOT NULL DEFAULT '{}' | |
254
265
 
266
+ An `active` row records its owner in `metadata_json.owner` (pid, host, and on Linux the boot id and process start
267
+ time). Each task run first marks `interrupted` the active rows whose owner is provably gone: a different boot, a dead
268
+ pid, or a pid reused by another process. A row owned by another host, or with no liveness evidence, stays `active`; a
269
+ row reserved before owners were recorded is interrupted only when it started before the current boot. Elapsed time
270
+ never decides, and no row is deleted. The same pass settles workflow units and unit attempts still `running` under a
271
+ `completed` or `failed` run that no live process drives (its run lock is absent or stale) as `failed` with
272
+ `failure_reason` `interrupted`.
273
+
255
274
  Unique index `idx_task_history_run` on `(task_id, started_at)`; indexes on
256
275
  `task_id`, `started_at`, `(target_kind, target_ref)`, `status`.
257
276
 
@@ -1870,6 +1870,9 @@ updates with its own release.
1870
1870
 
1871
1871
  `akm upgrade --next` means "newest available, prereleases included". The result
1872
1872
  carries `channel: "next"` (`"latest"` otherwise), plus the CLI's inferred `currentChannel` and each installed plugin's configured `channel` and `channelMismatch`.
1873
+ A plugin is updated, current within its configured channel, or skipped with the reason in its `message`; a channel is
1874
+ never switched without `--channel`. When a plugin's bundled akm differs from the CLI, its `message` also names the
1875
+ engine skew `akm health` reports. The text output, AKM Desktop and the scheduled version check show the same result.
1873
1876
 
1874
1877
  - **CLI.** The target is the `next` dist-tag of `akm-cli` (read from the npm
1875
1878
  registry, so it works for binary installs too) when that is newer than the
@@ -2608,12 +2611,14 @@ in order:
2608
2611
  rewritten every such key it can reach forgets the old engine names and adds one
2609
2612
  note to `assetEngineKeys.notes` listing each renamed engine and the flag that
2610
2613
  replaces it (see [The `engines` form](configuration.md#the-engines-form));
2611
- 5. refs in the text files akm indexes in writable bundles that still use the spelling from
2614
+ 5. refs in the markdown and YAML files akm indexes in writable bundles that still use the spelling from
2612
2615
  before refs became bundle paths (`knowledge/WORK/x`, now `WORK/x`; #1432),
2613
2616
  in frontmatter and body: `[bundle//]<folder>/<path>[.md]`, `<type>:<path>`
2614
2617
  and `wiki:<path>`, rewritten (`assetContentRefs`) under one backup directory
2615
2618
  per run. An old spelling that is now another file's ref is not rewritten
2616
- and is listed in `assetContentRefs.shadowed`;
2619
+ and is listed in `assetContentRefs.shadowed`. JSON, plain text, scripts and
2620
+ other files are never read or rewritten, so frozen corpora and captured
2621
+ results stay byte-for-byte, and a second run changes nothing;
2617
2622
  6. superseded residue removed (`deadResidue`): pre-0.9.0 `.akm` leftovers in
2618
2623
  the stash, and the transaction-journal, maintenance-barrier, lock-mutex and
2619
2624
  version-stamp files older releases kept under `$DATA`, `$STATE` and
@@ -202,7 +202,8 @@ them, in column form, so 30,000 assets stay a few megabytes:
202
202
  "lastShownAt": ["2026-11-02T09:14:03Z"], "modifiedAt": ["2026-03-30T17:02:11.000Z"],
203
203
  "positive": [2], "negative": [0], "tags": [[0]] },
204
204
  "links": { "from": [0], "to": [3], "kind": [1] },
205
- "duplicates": { "threshold": 0.96, "a": [0], "b": [9], "cosine": [0.9871], "truncated": false }
205
+ "duplicates": { "threshold": 0.96, "a": [0], "b": [9], "cosine": [0.9871], "truncated": false },
206
+ "groups": { "count": 36, "group": [4], "x": [12.5], "y": [-3.1], "z": [40.2] }
206
207
  }
207
208
  ```
208
209
 
@@ -218,13 +219,15 @@ usage history is available. `lastShownAt` is the latest of those shows (UTC), `n
218
219
  answered by an accepted fix does not count). `modifiedAt` is the file's modification time, `null` when it cannot be
219
220
  read; in a Git checkout it is when the file was last written there, not its last commit.
220
221
 
221
- `duplicates` lists pairs of assets (indexes into `nodes`) whose stored embeddings have a cosine of at least `threshold`
222
- (0.96), most alike first, at most 2,000 (`truncated` says there were more). To avoid comparing every pair, the assets
223
- are first grouped by meaning (spherical k-means on their vectors, from a fixed start, so the same index gives the same
224
- pairs) and only pairs inside a group are compared. It is `null` without at least eight embedded assets. It is kept
225
- while the embeddings are the same, so an index build that changes none costs nothing; after one that does, the first
226
- read of a 16,000-asset library takes about five seconds. `available` is `false`,
227
- with a `note`, when there is no index.
222
+ `groups` and `duplicates` are computed by `akm index` at the end of each build whose vectors changed, over every
223
+ embedded asset, and stored in `index.db`; the read only looks them up. The embedded assets are grouped by meaning
224
+ (spherical k-means on their vectors, from a fixed start, so the same vectors give the same groups), at most 36 groups.
225
+ `groups.group[i]` is asset `i`'s group (`-1` when it has no vector), and `x`, `y`, `z` its place in 3D: groups alike in
226
+ meaning lie near each other, and an asset sits inside its group's sphere. `duplicates` lists pairs of assets (indexes
227
+ into `nodes`) whose stored embeddings have a cosine of at least `threshold` (0.96), most alike first, at most 2,000
228
+ (`truncated` says there were more); only pairs inside a group are compared. Pairs and places of assets that are not
229
+ returned (a bundle that is not enabled) are left out. Both are `null` without at least eight embedded assets, and until
230
+ an `akm index` of this release has run. `available` is `false`, with a `note`, when there is no index.
228
231
 
229
232
  ## `bundles.list`
230
233
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "akm-cli",
3
- "version": "0.10.261126",
3
+ "version": "0.10.261127",
4
4
  "type": "module",
5
5
  "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
6
6
  "keywords": [