akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

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 (587) hide show
  1. package/CHANGELOG.md +1190 -52
  2. package/README.md +62 -37
  3. package/SECURITY.md +46 -31
  4. package/dist/akm +162 -38
  5. package/dist/akm-migrate +44 -0
  6. package/dist/assets/backends/schtasks-template.xml +2 -1
  7. package/dist/assets/hints/cli-hints-full.md +268 -118
  8. package/dist/assets/hints/cli-hints-short.md +87 -24
  9. package/dist/assets/{profiles → improve-strategies}/catchup.json +3 -1
  10. package/dist/assets/{profiles → improve-strategies}/consolidate.json +3 -1
  11. package/dist/assets/{profiles → improve-strategies}/default.json +6 -7
  12. package/dist/assets/improve-strategies/frequent.json +15 -0
  13. package/dist/assets/{profiles → improve-strategies}/graph-refresh.json +4 -2
  14. package/dist/assets/{profiles → improve-strategies}/memory-focus.json +4 -1
  15. package/dist/assets/{profiles → improve-strategies}/proactive-maintenance.json +5 -5
  16. package/dist/assets/{profiles → improve-strategies}/quick.json +4 -2
  17. package/dist/assets/improve-strategies/reflect-distill.json +30 -0
  18. package/dist/assets/{profiles → improve-strategies}/thorough.json +1 -1
  19. package/dist/assets/prompts/consolidate-system.md +5 -5
  20. package/dist/assets/prompts/extract-session.md +2 -6
  21. package/dist/assets/prompts/memory-infer-user.md +2 -3
  22. package/dist/assets/prompts/reflect-llm-framed-contract.md +11 -0
  23. package/dist/assets/prompts/reflect-llm-schema-contract.md +3 -0
  24. package/dist/assets/prompts/reflect-output-repair.md +3 -0
  25. package/dist/assets/stash-skeleton/README.md +38 -10
  26. package/dist/assets/stash-skeleton/facts/conventions/assets/agent.md +8 -0
  27. package/dist/assets/stash-skeleton/facts/conventions/assets/command.md +8 -0
  28. package/dist/assets/stash-skeleton/facts/conventions/assets/fact.md +14 -1
  29. package/dist/assets/stash-skeleton/facts/conventions/assets/knowledge.md +13 -1
  30. package/dist/assets/stash-skeleton/facts/conventions/assets/lesson.md +9 -1
  31. package/dist/assets/stash-skeleton/facts/conventions/assets/memory.md +11 -0
  32. package/dist/assets/stash-skeleton/facts/conventions/assets/script.md +9 -0
  33. package/dist/assets/stash-skeleton/facts/conventions/assets/skill.md +9 -0
  34. package/dist/assets/stash-skeleton/facts/conventions/assets/workflow.md +8 -0
  35. package/dist/assets/stash-skeleton/facts/conventions/backlinks.md +100 -0
  36. package/dist/assets/stash-skeleton/facts/conventions/domains.md +64 -0
  37. package/dist/assets/stash-skeleton/facts/conventions/organization.md +136 -0
  38. package/dist/assets/tasks/core/extract.yml +3 -2
  39. package/dist/assets/tasks/core/improve.yml +2 -1
  40. package/dist/assets/tasks/core/index-refresh.yml +1 -0
  41. package/dist/assets/tasks/core/sync.yml +1 -0
  42. package/dist/assets/tasks/core/version-check.yml +2 -1
  43. package/dist/assets/tasks/improve/akm-graph-refresh-weekly.yml +5 -0
  44. package/dist/assets/tasks/improve/akm-improve-catchup.yml +8 -0
  45. package/dist/assets/tasks/improve/akm-improve-consolidate.yml +5 -0
  46. package/dist/assets/tasks/improve/akm-improve-frequent.yml +5 -0
  47. package/dist/assets/tasks/improve/akm-improve-nightly.yml +5 -0
  48. package/dist/assets/templates/html/health.html +5 -4
  49. package/dist/assets/workflows/workflow-template.md +31 -15
  50. package/dist/cli/invocation.js +279 -0
  51. package/dist/cli/parse-args.js +5 -90
  52. package/dist/cli/retired-commands.js +78 -0
  53. package/dist/cli/shared.js +158 -48
  54. package/dist/cli-node.mjs +2 -1
  55. package/dist/cli.js +747 -293
  56. package/dist/commands/agent/agent-dispatch.js +19 -18
  57. package/dist/commands/agent/agent-support.js +0 -24
  58. package/dist/commands/agent/contribute-cli.js +43 -97
  59. package/dist/commands/completions.js +80 -23
  60. package/dist/commands/config-cli.js +44 -281
  61. package/dist/commands/env/env-binding.js +13 -9
  62. package/dist/commands/env/env-cli.js +76 -159
  63. package/dist/commands/env/env.js +12 -163
  64. package/dist/commands/env/marker-path.js +6 -0
  65. package/dist/commands/env/secret-cli.js +45 -61
  66. package/dist/commands/env/secret.js +32 -62
  67. package/dist/commands/feedback-cli.js +179 -85
  68. package/dist/commands/health/accept-rate.js +58 -0
  69. package/dist/commands/health/advisories.js +7 -8
  70. package/dist/commands/health/checks.js +279 -94
  71. package/dist/commands/health/html-report.js +197 -578
  72. package/dist/commands/health/improve-metrics.js +277 -246
  73. package/dist/commands/health/llm-usage.js +19 -19
  74. package/dist/commands/health/md-report.js +16 -7
  75. package/dist/commands/health/metrics.js +67 -32
  76. package/dist/commands/health/renderers.js +47 -0
  77. package/dist/commands/health/report-view-model.js +508 -0
  78. package/dist/commands/health/stash-exposure.js +1 -1
  79. package/dist/commands/health/surfaces.js +16 -56
  80. package/dist/commands/health/task-runs.js +3 -67
  81. package/dist/{migrate-storage-node.mjs → commands/health/types-checks.js} +1 -5
  82. package/dist/commands/health/types-improve.js +29 -0
  83. package/dist/{output/text/save.js → commands/health/types-metrics.js} +1 -2
  84. package/dist/commands/health/types-result.js +7 -0
  85. package/dist/commands/health/types-runs.js +4 -0
  86. package/dist/commands/health/types-session-log.js +4 -0
  87. package/dist/commands/health/types-windows.js +4 -0
  88. package/dist/commands/health/types.js +26 -21
  89. package/dist/commands/health/windows.js +2 -3
  90. package/dist/commands/health.js +296 -167
  91. package/dist/commands/improve/anti-collapse.js +5 -5
  92. package/dist/commands/improve/autonomy-gate.js +68 -0
  93. package/dist/commands/improve/collapse-detector.js +65 -52
  94. package/dist/commands/improve/consolidate/chunking.js +9 -7
  95. package/dist/commands/improve/consolidate/eligibility.js +1 -23
  96. package/dist/commands/improve/consolidate/merge.js +4 -0
  97. package/dist/commands/improve/consolidate.js +454 -1354
  98. package/dist/commands/improve/content-hash.js +39 -0
  99. package/dist/commands/improve/distill/content-repair.js +4 -10
  100. package/dist/commands/improve/distill/promote-memory.js +89 -64
  101. package/dist/commands/improve/distill/quality-gate.js +118 -42
  102. package/dist/commands/improve/distill-guards.js +1 -1
  103. package/dist/commands/improve/distill-promotion-policy.js +33 -888
  104. package/dist/commands/improve/distill.js +607 -363
  105. package/dist/commands/improve/eligibility.js +165 -79
  106. package/dist/commands/improve/extract-cli.js +35 -126
  107. package/dist/commands/improve/extract-prompt.js +6 -35
  108. package/dist/commands/improve/extract.js +640 -391
  109. package/dist/commands/improve/feedback-valence.js +2 -12
  110. package/dist/commands/improve/improve-cli.js +134 -135
  111. package/dist/commands/improve/improve-result-file.js +30 -50
  112. package/dist/commands/improve/improve-run-types.js +4 -0
  113. package/dist/commands/improve/improve-strategies.js +135 -0
  114. package/dist/commands/improve/improve.js +904 -701
  115. package/dist/commands/improve/locks.js +64 -111
  116. package/dist/commands/improve/loop-stages.js +1110 -923
  117. package/dist/commands/improve/memory/derived-ref.js +124 -0
  118. package/dist/commands/improve/memory/memory-belief.js +79 -7
  119. package/dist/commands/improve/memory/memory-contradiction-detect.js +49 -52
  120. package/dist/commands/improve/memory/memory-improve.js +25 -37
  121. package/dist/commands/improve/outcome-loop.js +25 -88
  122. package/dist/commands/improve/preparation.js +1034 -813
  123. package/dist/commands/improve/proactive-maintenance.js +34 -9
  124. package/dist/commands/improve/proposal-envelope.js +31 -0
  125. package/dist/commands/improve/reflect.js +983 -794
  126. package/dist/commands/improve/run-context.js +119 -0
  127. package/dist/commands/improve/salience.js +24 -127
  128. package/dist/commands/improve/session-asset.js +7 -3
  129. package/dist/commands/improve/shared.js +14 -34
  130. package/dist/commands/improve/source-identity.js +28 -0
  131. package/dist/commands/improve/triage.js +20 -17
  132. package/dist/commands/lint/base-linter.js +340 -313
  133. package/dist/commands/lint/env-key-rules.js +31 -47
  134. package/dist/commands/lint/index.js +185 -30
  135. package/dist/commands/{events.js → log.js} +28 -38
  136. package/dist/commands/migrate-cli.js +54 -0
  137. package/dist/commands/migration-tool.js +55 -0
  138. package/dist/commands/observability-cli.js +70 -208
  139. package/dist/commands/proposal/diff-format.js +50 -0
  140. package/dist/commands/proposal/drain-policies.js +0 -6
  141. package/dist/commands/proposal/drain.js +91 -40
  142. package/dist/commands/proposal/proposal-cli.js +134 -132
  143. package/dist/commands/proposal/proposal-types.js +56 -0
  144. package/dist/commands/proposal/proposal.js +83 -65
  145. package/dist/commands/proposal/propose-cli.js +88 -0
  146. package/dist/commands/proposal/propose.js +105 -88
  147. package/dist/commands/proposal/repository.js +1303 -278
  148. package/dist/commands/proposal/validators/proposal-quality-validators.js +16 -6
  149. package/dist/commands/proposal/validators/proposal-validators.js +61 -12
  150. package/dist/commands/proposal/validators/proposals.js +6 -8
  151. package/dist/commands/read/curate.js +78 -73
  152. package/dist/commands/read/knowledge.js +510 -13
  153. package/dist/commands/read/registry-search.js +2 -2
  154. package/dist/commands/read/remember-cli.js +84 -15
  155. package/dist/commands/read/search-cli.js +203 -96
  156. package/dist/commands/read/search.js +126 -94
  157. package/dist/commands/read/show.js +226 -250
  158. package/dist/commands/registry-cli.js +34 -60
  159. package/dist/commands/remember.js +18 -57
  160. package/dist/commands/sources/add-cli.js +104 -49
  161. package/dist/commands/sources/bundle-cli.js +166 -0
  162. package/dist/commands/sources/bundle-config-ops.js +63 -0
  163. package/dist/commands/sources/info.js +27 -15
  164. package/dist/commands/sources/init.js +30 -40
  165. package/dist/commands/sources/installed-stashes.js +469 -172
  166. package/dist/commands/sources/schema-repair.js +10 -9
  167. package/dist/commands/sources/self-update.js +182 -121
  168. package/dist/commands/sources/source-add.js +169 -178
  169. package/dist/commands/sources/source-clone.js +144 -41
  170. package/dist/commands/sources/source-manage.js +94 -59
  171. package/dist/commands/sources/sources-cli.js +64 -205
  172. package/dist/commands/sources/stash-cli.js +91 -54
  173. package/dist/commands/sources/stash-skeleton.js +1 -1
  174. package/dist/commands/tasks/tasks-cli.js +106 -104
  175. package/dist/commands/tasks/tasks.js +445 -262
  176. package/dist/commands/workflow-cli.js +75 -228
  177. package/dist/core/action-contributors.js +1 -1
  178. package/dist/core/activation-policy.js +49 -0
  179. package/dist/core/adapter/adapters/agent-skills-adapter.js +181 -0
  180. package/dist/core/adapter/adapters/akm-adapter.js +528 -0
  181. package/dist/core/adapter/adapters/akm-lint.js +392 -0
  182. package/dist/core/adapter/adapters/akm-metadata.js +387 -0
  183. package/dist/core/adapter/adapters/akm-task-adapter.js +149 -0
  184. package/dist/core/adapter/adapters/akm-workflow-adapter.js +180 -0
  185. package/dist/core/adapter/adapters/claude-adapter.js +61 -0
  186. package/dist/core/adapter/adapters/dotenv-adapter.js +187 -0
  187. package/dist/core/adapter/adapters/generic-files-adapter.js +119 -0
  188. package/dist/core/adapter/adapters/index.js +80 -0
  189. package/dist/core/adapter/adapters/llm-wiki-adapter.js +419 -0
  190. package/dist/core/adapter/adapters/okf-adapter.js +391 -0
  191. package/dist/core/adapter/adapters/opencode-adapter.js +68 -0
  192. package/dist/core/adapter/adapters/shared.js +286 -0
  193. package/dist/core/adapter/adapters/tool-dir-shared.js +217 -0
  194. package/dist/core/adapter/adapters/website-snapshot-adapter.js +155 -0
  195. package/dist/core/adapter/bundle-adapter.js +4 -0
  196. package/dist/core/adapter/detect-adapter.js +17 -0
  197. package/dist/core/adapter/recognize-match.js +44 -0
  198. package/dist/core/adapter/registry.js +56 -0
  199. package/dist/core/adapter/types.js +4 -0
  200. package/dist/core/asset/akm-markdown.js +30 -0
  201. package/dist/core/asset/asset-placement.js +243 -0
  202. package/dist/core/asset/asset-ref.js +110 -79
  203. package/dist/core/asset/asset-serialize.js +20 -0
  204. package/dist/core/asset/frontmatter.js +28 -12
  205. package/dist/core/asset/markdown.js +40 -51
  206. package/dist/core/asset/resolve-ref.js +274 -0
  207. package/dist/core/asset/stash-meta.js +2 -2
  208. package/dist/core/bundle-id.js +51 -0
  209. package/dist/core/common.js +281 -86
  210. package/dist/core/config/config-io.js +42 -128
  211. package/dist/core/config/config-schema.js +233 -855
  212. package/dist/core/config/config-sources.js +162 -39
  213. package/dist/core/config/config-types.js +16 -11
  214. package/dist/core/config/config-version.js +29 -0
  215. package/dist/core/config/config-walker.js +126 -37
  216. package/dist/core/config/config.js +154 -331
  217. package/dist/core/config/deep-merge.js +41 -0
  218. package/dist/core/config/engine-semantics.js +28 -0
  219. package/dist/core/config/experimental.js +21 -0
  220. package/dist/core/config/schema/embedding.js +38 -0
  221. package/dist/core/config/schema/engines.js +116 -0
  222. package/dist/core/config/schema/experimental.js +47 -0
  223. package/dist/core/config/schema/feedback.js +31 -0
  224. package/dist/core/config/schema/improve-processes.js +389 -0
  225. package/dist/core/config/schema/improve.js +94 -0
  226. package/dist/core/config/schema/index-config.js +176 -0
  227. package/dist/core/config/schema/output.js +18 -0
  228. package/dist/core/config/schema/primitives.js +94 -0
  229. package/dist/core/config/schema/search.js +30 -0
  230. package/dist/core/config/schema/setup.js +18 -0
  231. package/dist/core/config/schema/sources-bundles.js +169 -0
  232. package/dist/core/config/schema/workflow.js +29 -0
  233. package/dist/core/env-secret-ref.js +155 -20
  234. package/dist/core/errors.js +17 -15
  235. package/dist/core/events-types.js +4 -0
  236. package/dist/core/events.js +46 -128
  237. package/dist/core/extra-params.js +62 -0
  238. package/dist/core/file-change.js +17 -0
  239. package/dist/core/file-lock.js +202 -57
  240. package/dist/core/fs-txn.js +392 -0
  241. package/dist/core/git-message.js +59 -0
  242. package/dist/core/improve-result.js +167 -0
  243. package/dist/core/lesson-lint.js +1 -17
  244. package/dist/core/logs-db.js +1 -1
  245. package/dist/core/maintenance-barrier.js +135 -0
  246. package/dist/core/migration-operation.js +44 -0
  247. package/dist/core/mutation-target.js +78 -0
  248. package/dist/core/paths.js +22 -25
  249. package/dist/core/platform.js +10 -0
  250. package/dist/core/recognition-util.js +128 -0
  251. package/dist/core/redaction.js +392 -0
  252. package/dist/core/standards/resolve-standards-context.js +36 -65
  253. package/dist/core/standards/resolve-stash-standards.js +2 -2
  254. package/dist/core/standards/resolve-type-conventions.js +5 -5
  255. package/dist/core/state/migrations.js +242 -11
  256. package/dist/core/state-db.js +98 -10
  257. package/dist/core/structured.js +1 -1
  258. package/dist/core/subprocess.js +303 -0
  259. package/dist/core/text-truncation.js +9 -5
  260. package/dist/core/time.js +20 -0
  261. package/dist/core/type-presentation.js +130 -0
  262. package/dist/core/warn.js +0 -3
  263. package/dist/core/write-source.js +834 -118
  264. package/dist/indexer/bundle-identity-guard.js +92 -0
  265. package/dist/indexer/db/graph-db.js +1 -25
  266. package/dist/indexer/db/llm-cache.js +1 -1
  267. package/dist/indexer/ensure-index.js +30 -9
  268. package/dist/indexer/graph/graph-boost.js +9 -30
  269. package/dist/indexer/graph/graph-extraction.js +41 -27
  270. package/dist/indexer/graph/graph-types.js +4 -0
  271. package/dist/indexer/index-writer-lock.js +93 -49
  272. package/dist/indexer/index-written-assets.js +100 -53
  273. package/dist/indexer/indexer.js +746 -329
  274. package/dist/indexer/init.js +18 -25
  275. package/dist/indexer/installations.js +142 -0
  276. package/dist/indexer/passes/dir-staleness.js +18 -10
  277. package/dist/indexer/passes/memory-inference.js +25 -15
  278. package/dist/indexer/passes/metadata.js +412 -243
  279. package/dist/indexer/scan/doc-to-entry.js +160 -0
  280. package/dist/indexer/scan/drain-dir.js +134 -0
  281. package/dist/indexer/search/db-search.js +292 -108
  282. package/dist/indexer/search/fts-query.js +64 -0
  283. package/dist/indexer/search/ranking-contributors.js +145 -25
  284. package/dist/indexer/search/ranking-types.js +4 -0
  285. package/dist/indexer/search/ranking.js +28 -71
  286. package/dist/indexer/search/search-attribution.js +67 -0
  287. package/dist/indexer/search/search-fields.js +18 -3
  288. package/dist/indexer/search/search-hit-enrichers.js +30 -40
  289. package/dist/indexer/search/search-source.js +157 -111
  290. package/dist/indexer/search/semantic-status.js +4 -1
  291. package/dist/indexer/usage/usage-events.js +10 -30
  292. package/dist/indexer/walk/file-context.js +3 -45
  293. package/dist/indexer/walk/matchers.js +42 -73
  294. package/dist/indexer/walk/path-resolver.js +11 -5
  295. package/dist/indexer/walk/walker.js +42 -14
  296. package/dist/integrations/agent/builder-shared.js +7 -0
  297. package/dist/integrations/agent/builders.js +5 -58
  298. package/dist/integrations/agent/config.js +3 -143
  299. package/dist/integrations/agent/detect.js +17 -2
  300. package/dist/integrations/agent/engine-resolution.js +231 -0
  301. package/dist/integrations/agent/index.js +1 -2
  302. package/dist/integrations/agent/model-aliases.js +8 -3
  303. package/dist/integrations/agent/profiles.js +6 -99
  304. package/dist/integrations/agent/prompts.js +46 -18
  305. package/dist/integrations/agent/runner-dispatch.js +78 -13
  306. package/dist/integrations/agent/runner.js +76 -208
  307. package/dist/integrations/agent/spawn.js +48 -279
  308. package/dist/integrations/harnesses/aider/agent-builder.js +9 -8
  309. package/dist/integrations/harnesses/aider/index.js +2 -12
  310. package/dist/integrations/harnesses/amazonq/agent-builder.js +10 -16
  311. package/dist/integrations/harnesses/amazonq/index.js +3 -17
  312. package/dist/integrations/harnesses/claude/agent-builder.js +2 -3
  313. package/dist/integrations/harnesses/claude/config-import.js +1 -3
  314. package/dist/integrations/harnesses/claude/index.js +1 -14
  315. package/dist/integrations/harnesses/claude/session-log.js +27 -75
  316. package/dist/integrations/harnesses/codex/agent-builder.js +8 -7
  317. package/dist/integrations/harnesses/codex/index.js +2 -13
  318. package/dist/integrations/harnesses/copilot/agent-builder.js +9 -9
  319. package/dist/integrations/harnesses/copilot/index.js +1 -13
  320. package/dist/integrations/harnesses/gemini/agent-builder.js +8 -9
  321. package/dist/integrations/harnesses/gemini/index.js +1 -13
  322. package/dist/integrations/harnesses/ids.js +24 -0
  323. package/dist/integrations/harnesses/index.js +31 -33
  324. package/dist/integrations/harnesses/opencode/agent-builder.js +23 -5
  325. package/dist/integrations/harnesses/opencode/config-import.js +1 -3
  326. package/dist/integrations/harnesses/opencode/index.js +1 -18
  327. package/dist/integrations/harnesses/opencode/session-log.js +67 -125
  328. package/dist/integrations/harnesses/opencode-sdk/harness.js +3 -17
  329. package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js +274 -191
  330. package/dist/integrations/harnesses/openhands/agent-builder.js +12 -10
  331. package/dist/integrations/harnesses/openhands/index.js +2 -12
  332. package/dist/integrations/harnesses/pi/agent-builder.js +11 -18
  333. package/dist/integrations/harnesses/pi/index.js +3 -16
  334. package/dist/integrations/harnesses/shared.js +17 -0
  335. package/dist/integrations/harnesses/types.js +38 -34
  336. package/dist/integrations/lockfile.js +211 -24
  337. package/dist/integrations/session-logs/index.js +24 -40
  338. package/dist/integrations/session-logs/provider-base.js +113 -0
  339. package/dist/llm/client.js +182 -110
  340. package/dist/llm/embedders/deterministic.js +2 -2
  341. package/dist/llm/embedders/remote.js +21 -9
  342. package/dist/llm/feature-gate.js +17 -57
  343. package/dist/llm/graph-extract.js +12 -13
  344. package/dist/llm/index-passes.js +8 -42
  345. package/dist/llm/memory-infer.js +144 -1
  346. package/dist/llm/metadata-enhance.js +45 -30
  347. package/dist/llm/structured-call.js +16 -8
  348. package/dist/llm/usage-persist.js +30 -5
  349. package/dist/llm/usage-telemetry.js +59 -6
  350. package/dist/output/cli-hints.js +1 -2
  351. package/dist/output/command-registry.js +27 -0
  352. package/dist/output/context.js +22 -7
  353. package/dist/output/format-exempt.js +80 -0
  354. package/dist/output/generic-render.js +251 -0
  355. package/dist/output/html-render.js +11 -16
  356. package/dist/output/render-registry.js +57 -0
  357. package/dist/output/renderers.js +15 -281
  358. package/dist/output/shapes/curate.js +10 -1
  359. package/dist/output/shapes/events.js +12 -7
  360. package/dist/output/shapes/helpers.js +58 -84
  361. package/dist/output/shapes/passthrough.js +8 -40
  362. package/dist/output/shapes/proposal/producer.js +15 -7
  363. package/dist/output/shapes/registry.js +12 -6
  364. package/dist/output/shapes.js +0 -9
  365. package/dist/output/text/{init.js → bundle-create.js} +3 -1
  366. package/dist/output/text/bundle-show.js +7 -0
  367. package/dist/output/text/command-format.js +562 -0
  368. package/dist/output/text/env.js +1 -3
  369. package/dist/output/text/events.js +8 -7
  370. package/dist/output/text/helpers.js +15 -1375
  371. package/dist/output/text/proposal/producer.js +4 -2
  372. package/dist/output/text/proposal-format.js +202 -0
  373. package/dist/output/text/registry-commands.js +1 -2
  374. package/dist/output/text/registry.js +12 -6
  375. package/dist/output/text/show-directives.js +117 -0
  376. package/dist/output/text/show-format.js +103 -0
  377. package/dist/output/text/sync.js +5 -0
  378. package/dist/output/text/workflow-format.js +332 -0
  379. package/dist/output/text/workflow.js +1 -2
  380. package/dist/output/text.js +10 -19
  381. package/dist/registry/factory.js +4 -6
  382. package/dist/registry/origin-resolve.js +16 -27
  383. package/dist/registry/providers/skills-sh.js +3 -3
  384. package/dist/registry/providers/static-index.js +15 -25
  385. package/dist/registry/resolve.js +43 -94
  386. package/dist/registry/semver.js +43 -0
  387. package/dist/runtime.js +81 -12
  388. package/dist/scripts/akm-migrate.js +35529 -0
  389. package/dist/setup/detect.js +5 -7
  390. package/dist/setup/detected-engines.js +136 -0
  391. package/dist/setup/engine-config.js +100 -0
  392. package/dist/setup/registry-stash-loader.js +3 -3
  393. package/dist/setup/semantic-assets.js +12 -9
  394. package/dist/setup/setup.js +444 -208
  395. package/dist/setup/steps/connection-shared.js +120 -0
  396. package/dist/setup/steps/connection.js +108 -305
  397. package/dist/setup/steps/platforms.js +13 -12
  398. package/dist/setup/steps/semantic.js +15 -3
  399. package/dist/setup/steps/sources.js +21 -15
  400. package/dist/setup/steps/stashdir.js +6 -4
  401. package/dist/setup/steps/tasks.js +236 -119
  402. package/dist/setup/steps.js +3 -2
  403. package/dist/sources/freshness.js +39 -0
  404. package/dist/sources/provider-factory.js +11 -17
  405. package/dist/sources/providers/filesystem.js +2 -3
  406. package/dist/sources/providers/git-install.js +278 -34
  407. package/dist/sources/providers/git-provider.js +54 -56
  408. package/dist/sources/providers/git-stash.js +420 -91
  409. package/dist/sources/providers/git.js +2 -2
  410. package/dist/sources/providers/npm.js +16 -19
  411. package/dist/sources/providers/provider-utils.js +47 -22
  412. package/dist/sources/providers/sync-from-ref.js +3 -9
  413. package/dist/sources/providers/website.js +2 -2
  414. package/dist/sources/resolve.js +11 -10
  415. package/dist/sources/snapshot-fetchers/types.js +4 -0
  416. package/dist/sources/{website-ingest.js → snapshot-fetchers/website-ingest.js} +110 -41
  417. package/dist/storage/database.js +60 -4
  418. package/dist/storage/engines/sqlite-migrations.js +156 -5
  419. package/dist/storage/locations.js +1 -2
  420. package/dist/storage/repositories/canaries-repository.js +1 -1
  421. package/dist/storage/repositories/events-repository.js +51 -11
  422. package/dist/storage/repositories/improve-runs-repository.js +6 -32
  423. package/dist/storage/repositories/index-connection.js +79 -0
  424. package/dist/storage/repositories/index-db.js +4 -3
  425. package/dist/storage/repositories/index-entries-repository.js +863 -0
  426. package/dist/{indexer/db/entry-mapper.js → storage/repositories/index-entry-mapper.js} +19 -2
  427. package/dist/storage/repositories/index-entry-types.js +4 -0
  428. package/dist/storage/repositories/index-fts-repository.js +167 -0
  429. package/dist/storage/repositories/index-llm-cache-repository.js +108 -0
  430. package/dist/storage/repositories/index-meta-repository.js +49 -0
  431. package/dist/{indexer/db/schema.js → storage/repositories/index-schema.js} +226 -100
  432. package/dist/storage/repositories/index-sql.js +12 -0
  433. package/dist/storage/repositories/index-utility-repository.js +356 -0
  434. package/dist/storage/repositories/index-vec-repository.js +250 -0
  435. package/dist/storage/repositories/outcome-repository.js +119 -0
  436. package/dist/storage/repositories/proposals-repository.js +317 -75
  437. package/dist/storage/repositories/registry-cache.js +1 -1
  438. package/dist/storage/repositories/salience-repository.js +172 -0
  439. package/dist/storage/repositories/task-history-repository.js +110 -3
  440. package/dist/storage/repositories/workflow-runs-repository.js +68 -35
  441. package/dist/tasks/backends/cron.js +169 -46
  442. package/dist/tasks/backends/exec-utils.js +76 -3
  443. package/dist/tasks/backends/index.js +6 -9
  444. package/dist/tasks/backends/launchd.js +292 -55
  445. package/dist/tasks/backends/schtasks.js +557 -70
  446. package/dist/tasks/backends/types.js +4 -0
  447. package/dist/tasks/command-executable.js +93 -0
  448. package/dist/tasks/embedded.js +56 -38
  449. package/dist/tasks/parser.js +156 -64
  450. package/dist/tasks/resolve-akm-bin.js +144 -51
  451. package/dist/tasks/runner.js +377 -209
  452. package/dist/tasks/schedule.js +108 -19
  453. package/dist/tasks/scheduler-invocation.js +296 -0
  454. package/dist/tasks/schema.js +1 -1
  455. package/dist/tasks/task-id.js +35 -0
  456. package/dist/tasks/validator.js +30 -16
  457. package/dist/workflows/authoring/authoring.js +96 -148
  458. package/dist/workflows/authoring/scope-key.js +1 -1
  459. package/dist/workflows/cli.js +0 -20
  460. package/dist/workflows/concurrency-policy.js +15 -0
  461. package/dist/workflows/exec/brief.js +25 -59
  462. package/dist/workflows/exec/frozen-judge.js +47 -0
  463. package/dist/workflows/exec/native-executor.js +157 -94
  464. package/dist/workflows/exec/report.js +365 -200
  465. package/dist/workflows/exec/run-workflow.js +46 -40
  466. package/dist/workflows/exec/scheduler.js +12 -41
  467. package/dist/workflows/exec/step-work.js +239 -205
  468. package/dist/workflows/exec/workflow-engine-gate.js +67 -0
  469. package/dist/workflows/ir/compile.js +141 -283
  470. package/dist/workflows/ir/freeze.js +233 -0
  471. package/dist/workflows/ir/plan-hash.js +40 -5
  472. package/dist/workflows/ir/schema.js +537 -1
  473. package/dist/workflows/parser.js +878 -306
  474. package/dist/workflows/program/expressions.js +20 -208
  475. package/dist/workflows/program/schema.js +7 -10
  476. package/dist/workflows/renderer.js +99 -121
  477. package/dist/workflows/resource-limits.js +22 -0
  478. package/dist/workflows/runtime/checkin.js +1 -1
  479. package/dist/workflows/runtime/plan-classifier.js +131 -0
  480. package/dist/workflows/runtime/runs.js +200 -113
  481. package/dist/workflows/runtime/unit-checkin.js +1 -1
  482. package/dist/workflows/runtime/unit-phases.js +20 -0
  483. package/dist/workflows/runtime/workflow-asset-loader.js +235 -97
  484. package/dist/workflows/schema.js +1 -11
  485. package/dist/workflows/validate-summary.js +4 -26
  486. package/dist/workflows/validator.js +52 -30
  487. package/docs/README.md +42 -78
  488. package/docs/migration/README.md +8 -0
  489. package/docs/migration/release-notes/0.6.0.md +1 -1
  490. package/docs/migration/release-notes/0.7.0.md +9 -8
  491. package/docs/migration/release-notes/0.9.0.md +158 -14
  492. package/docs/migration/v0.7-to-v0.8.md +46 -47
  493. package/docs/migration/v0.8-to-v0.9.md +844 -0
  494. package/docs/reference/README.md +12 -0
  495. package/docs/reference/data-and-telemetry.md +333 -0
  496. package/package.json +21 -17
  497. package/schemas/akm-asset-envelope.json +93 -0
  498. package/schemas/akm-config.json +4636 -0
  499. package/schemas/akm-task.json +87 -0
  500. package/{dist/schemas → schemas}/akm-workflow.json +127 -82
  501. package/dist/akm-migrate-storage +0 -38
  502. package/dist/assets/help/help-accept.md +0 -12
  503. package/dist/assets/help/help-improve.md +0 -84
  504. package/dist/assets/help/help-proposals.md +0 -17
  505. package/dist/assets/help/help-propose.md +0 -17
  506. package/dist/assets/help/help-reject.md +0 -11
  507. package/dist/assets/profiles/frequent.json +0 -13
  508. package/dist/assets/profiles/recombine-only.json +0 -21
  509. package/dist/assets/profiles/reflect-distill.json +0 -30
  510. package/dist/assets/profiles/synthesize.json +0 -15
  511. package/dist/assets/prompts/procedural-system.md +0 -44
  512. package/dist/assets/prompts/recombine-system.md +0 -40
  513. package/dist/assets/prompts/staleness-detect-system.md +0 -6
  514. package/dist/assets/tasks/core/backup.yml +0 -4
  515. package/dist/assets/tasks/graph-refresh-weekly.yml +0 -10
  516. package/dist/assets/templates/html/default.html +0 -78
  517. package/dist/assets/templates/html/vendor/echarts.min.js +0 -45
  518. package/dist/assets/wiki/index-template.md +0 -12
  519. package/dist/assets/wiki/ingest-workflow-template.md +0 -83
  520. package/dist/assets/wiki/log-template.md +0 -8
  521. package/dist/assets/wiki/schema-template.md +0 -61
  522. package/dist/cli/config-migrate.js +0 -150
  523. package/dist/cli/config-validate.js +0 -39
  524. package/dist/commands/graph/graph-cli.js +0 -124
  525. package/dist/commands/graph/graph.js +0 -487
  526. package/dist/commands/improve/calibration.js +0 -161
  527. package/dist/commands/improve/dedup.js +0 -482
  528. package/dist/commands/improve/extract-watch.js +0 -140
  529. package/dist/commands/improve/hot-probation.js +0 -45
  530. package/dist/commands/improve/improve-auto-accept.js +0 -276
  531. package/dist/commands/improve/improve-profiles.js +0 -168
  532. package/dist/commands/improve/procedural.js +0 -398
  533. package/dist/commands/improve/recombine.js +0 -818
  534. package/dist/commands/improve/schema-similarity-gate.js +0 -168
  535. package/dist/commands/lint/agent-linter.js +0 -44
  536. package/dist/commands/lint/command-linter.js +0 -44
  537. package/dist/commands/lint/default-linter.js +0 -16
  538. package/dist/commands/lint/fact-linter.js +0 -39
  539. package/dist/commands/lint/knowledge-linter.js +0 -16
  540. package/dist/commands/lint/memory-linter.js +0 -61
  541. package/dist/commands/lint/registry.js +0 -41
  542. package/dist/commands/lint/skill-linter.js +0 -45
  543. package/dist/commands/lint/task-linter.js +0 -50
  544. package/dist/commands/lint/workflow-linter.js +0 -81
  545. package/dist/commands/proposal/legacy-import.js +0 -115
  546. package/dist/commands/sources/history.js +0 -196
  547. package/dist/commands/tasks/default-tasks.js +0 -186
  548. package/dist/commands/wiki-cli.js +0 -292
  549. package/dist/core/asset/asset-registry.js +0 -76
  550. package/dist/core/asset/asset-spec.js +0 -316
  551. package/dist/core/config/config-migration.js +0 -602
  552. package/dist/core/deep-merge.js +0 -38
  553. package/dist/core/eval/rank-metrics.js +0 -113
  554. package/dist/core/ripgrep/install.js +0 -163
  555. package/dist/core/ripgrep/resolve.js +0 -81
  556. package/dist/indexer/db/db.js +0 -1414
  557. package/dist/indexer/manifest.js +0 -170
  558. package/dist/indexer/passes/metadata-contributors.js +0 -31
  559. package/dist/indexer/usage/unmigrated-vaults-guard.js +0 -94
  560. package/dist/integrations/harnesses/opencode-sdk/index.js +0 -25
  561. package/dist/llm/call-ai.js +0 -62
  562. package/dist/llm/memory-infer-impl.js +0 -138
  563. package/dist/output/shapes/distill.js +0 -14
  564. package/dist/output/shapes/history.js +0 -11
  565. package/dist/output/text/distill.js +0 -6
  566. package/dist/output/text/enable-disable.js +0 -8
  567. package/dist/output/text/history.js +0 -6
  568. package/dist/output/text/wiki.js +0 -16
  569. package/dist/registry/build-index.js +0 -386
  570. package/dist/schemas/akm-config.json +0 -14225
  571. package/dist/scripts/migrate-storage.js +0 -13169
  572. package/dist/scripts/migrations/import-fs-improve-runs-to-db.js +0 -10169
  573. package/dist/scripts/migrations/v16-to-v17.js +0 -141
  574. package/dist/setup/legacy-config.js +0 -106
  575. package/dist/storage/repositories/consolidation-repository.js +0 -38
  576. package/dist/storage/repositories/recombine-repository.js +0 -213
  577. package/dist/wiki/wiki-templates.js +0 -15
  578. package/dist/wiki/wiki.js +0 -1012
  579. package/dist/workflows/authoring/workflow-program-template.yaml +0 -31
  580. package/dist/workflows/db.js +0 -350
  581. package/dist/workflows/exec/watch.js +0 -116
  582. package/dist/workflows/program/parser.js +0 -760
  583. package/dist/workflows/program/project.js +0 -105
  584. package/docs/data-and-telemetry.md +0 -227
  585. package/docs/migration/release-notes/0.9.0-beta.60.md +0 -19
  586. /package/dist/sources/{wiki-fetchers → snapshot-fetchers}/registry.js +0 -0
  587. /package/dist/sources/{wiki-fetchers → snapshot-fetchers}/youtube.js +0 -0
@@ -2,18 +2,18 @@
2
2
  // License, v. 2.0. If a copy of the MPL was not distributed with this
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  /**
5
- * index.db schema, version stamps, and targeted migrations — extracted from
6
- * indexer/db/db.ts. This isolates the one genuinely risky area (schema
7
- * evolution) from the CRUD/FTS/vector queries that stay in db.ts.
5
+ * index.db schema, version stamps, and targeted migrations, kept in the
6
+ * storage layer. This isolates the one genuinely risky area (schema
7
+ * evolution) from the CRUD/FTS/vector queries.
8
8
  *
9
9
  * The meta accessors, embedding purge, and vec-availability probe that
10
- * `ensureSchema` leans on remain in db.ts (they are part of the database
11
- * lifecycle) and are imported back here.
10
+ * `ensureSchema` leans on live in the sibling `index-meta-repository` /
11
+ * `index-vec-repository` modules.
12
12
  */
13
13
  import { bestEffort } from "../../core/best-effort.js";
14
14
  import { warn } from "../../core/warn.js";
15
- import { ensureUsageEventsSchema } from "../usage/usage-events.js";
16
- import { getMeta, isVecAvailable, purgeEmbeddings, setMeta } from "./db.js";
15
+ import { getMeta, setMeta } from "./index-meta-repository.js";
16
+ import { isVecAvailable, purgeEmbeddings } from "./index-vec-repository.js";
17
17
  // ── Constants ───────────────────────────────────────────────────────────────
18
18
  // NOTE: schema changes are additive. DB_VERSION is a forensic stamp only — it
19
19
  // no longer gates any destructive path (the old nuclear drop-and-rebuild was
@@ -21,7 +21,54 @@ import { getMeta, isVecAvailable, purgeEmbeddings, setMeta } from "./db.js";
21
21
  // older/partial DB forward without dropping data). Graph re-keying uses a
22
22
  // TARGETED, graph-only migration (migrateGraphFilesSchema) — the model for any
23
23
  // incompatible change: migrate in place, never wipe the whole index.
24
- export const DB_VERSION = 17;
24
+ //
25
+ // v17→v18 (Chunk-5 Step 2, spec §14.4): the `entries` table gains the durable
26
+ // bundle-adapter identity/provenance columns — `item_ref` (`<bundle>//<concept
27
+ // -id>` canonical stored spelling), `bundle_id`/`component_id`/`concept_id`/
28
+ // `adapter_id` provenance, `type` (open token), and `content_hash`/`document
29
+ // _json`. They land ADDITIVELY ALONGSIDE the legacy `entry_key`/`dir_path`/
30
+ // `stash_dir`/`entry_json`/`entry_type` columns (dev-time transitional shape):
31
+ // the writer populates the identity/provenance columns while every reader still
32
+ // keys on the legacy columns, so the battery stays green while the reader
33
+ // repoint + ref-grammar flip land incrementally. The legacy columns + this
34
+ // coexistence are removed once every reader is repointed onto `item_ref`
35
+ // (spec §3.3 — single clean shape, no dual read-path). The index is a
36
+ // regenerable derived cache, so an `akm index` rebuild repopulates the new
37
+ // columns on any DB opened at an older version.
38
+ //
39
+ // v18→v19 (Chunk-5 flip F4c, spec §11.4): `entries.item_ref` becomes THE durable
40
+ // identity — its lookup index is upgraded to UNIQUE (every indexed row now
41
+ // carries item_ref; NULLs are distinct in a SQLite UNIQUE index, so write-back
42
+ // stragglers coexist). The durable state keyed off refs (`usage_events.entry_ref`)
43
+ // is re-keyed onto item_ref by the one-time §11.4 migration cutover
44
+ // (020-three-db-cutover) with orphan quarantine in `legacy_state`. The index is
45
+ // regenerable, so a rebuild is an acceptable fallback if the UNIQUE upgrade finds
46
+ // a duplicate on a partially-migrated DB.
47
+ //
48
+ // v19→v20 (Chunk-8 WI-8.3, three-DB merge): index.db STOPS owning `usage_events`
49
+ // + `legacy_state`. Both are durable, non-regenerable state and now live in
50
+ // state.db (folded by state migration 020; the cutover rescues the old index.db
51
+ // rows across). index.db is a regenerable cache, so dropping their DDL from the
52
+ // schema path needs no migration — a rebuild simply no longer re-creates them.
53
+ // STANDARD REBUILD NOTE: after this bump, any index.db opened at v19 is rebuilt
54
+ // from the stash on the next `akm index`; usage_events/legacy_state are read
55
+ // exclusively from state.db thereafter.
56
+ //
57
+ // Reader/writer repoint progress (spec §3.3 "single clean shape"): the `entries`
58
+ // upsert (index-entries-repository `getUpsertStmts`) uses the UNIQUE `item_ref`
59
+ // as its PRIMARY conflict target, and the graph-boost related-ref reader
60
+ // (`listRelatedPathsForFile`) resolves the user-facing ref from
61
+ // `concept_id`/`item_ref` instead of stripping `entry_key`. The legacy
62
+ // `entry_key`/`dir_path`/`stash_dir`/`entry_type`/`entry_json` columns are NOT
63
+ // yet removable: they retain live consumers outside this module — `entry_key`
64
+ // (mv-cli re-key, usage-event legacy resolution, index-entry-mapper, the LLM
65
+ // cache), `entry_json` (the row payload every reader decodes), `entry_type`
66
+ // (FTS + workflow loader), `stash_dir`/`dir_path` (scan/delete/utility scoping).
67
+ // The upsert therefore keeps `entry_key` as a NULL-item_ref-safe SECOND conflict
68
+ // target (the LLM metadata-enhance re-upsert still writes existing rows with a
69
+ // NULL item_ref) and degrades to it entirely when the item_ref index is the
70
+ // non-unique fallback. Both are deletable once every remaining reader repoints.
71
+ export const DB_VERSION = 20;
25
72
  export const EMBEDDING_DIM = 384;
26
73
  // #624-P1: graph_files re-keyed to (stash_root, file_path, body_hash). Bumped 3→4
27
74
  // as a marker; the actual migration is the targeted drop in migrateGraphFilesSchema.
@@ -62,6 +109,102 @@ const REGISTRY_INDEX_CACHE_DDL = `
62
109
  CREATE INDEX IF NOT EXISTS idx_registry_cache_fetched
63
110
  ON registry_index_cache(fetched_at);
64
111
  `;
112
+ /**
113
+ * Create the graph-extraction tables (`graph_meta`/`graph_files`/`graph_file_entities`/
114
+ * `graph_file_relations`/`graph_extraction_queue`). Extracted verbatim from
115
+ * {@link ensureSchema} (called at the same point, between `migrateGraphFilesSchema`
116
+ * and `migrateGraphDataFromLegacy`) — a pure, behavior-identical decomposition.
117
+ */
118
+ function ensureGraphTables(db) {
119
+ db.exec(`
120
+ CREATE TABLE IF NOT EXISTS graph_meta (
121
+ stash_root TEXT PRIMARY KEY,
122
+ schema_version INTEGER NOT NULL,
123
+ generated_at TEXT NOT NULL,
124
+ considered_files INTEGER NOT NULL DEFAULT 0,
125
+ extracted_files INTEGER NOT NULL DEFAULT 0,
126
+ entity_count INTEGER NOT NULL DEFAULT 0,
127
+ relation_count INTEGER NOT NULL DEFAULT 0,
128
+ extraction_coverage REAL NOT NULL DEFAULT 0,
129
+ density REAL NOT NULL DEFAULT 0,
130
+ extractor_id TEXT,
131
+ extraction_run_id TEXT,
132
+ model TEXT,
133
+ prompt_version TEXT,
134
+ batch_size INTEGER,
135
+ cache_hits INTEGER NOT NULL DEFAULT 0,
136
+ cache_misses INTEGER NOT NULL DEFAULT 0,
137
+ truncation_count INTEGER NOT NULL DEFAULT 0,
138
+ failure_count INTEGER NOT NULL DEFAULT 0
139
+ );
140
+
141
+ CREATE TABLE IF NOT EXISTS graph_files (
142
+ stash_root TEXT NOT NULL,
143
+ file_path TEXT NOT NULL,
144
+ file_order INTEGER NOT NULL,
145
+ file_type TEXT NOT NULL,
146
+ body_hash TEXT NOT NULL,
147
+ confidence REAL,
148
+ status TEXT NOT NULL DEFAULT 'extracted',
149
+ reason TEXT,
150
+ extraction_run_id TEXT,
151
+ PRIMARY KEY (stash_root, file_path, body_hash)
152
+ );
153
+
154
+ CREATE UNIQUE INDEX IF NOT EXISTS idx_graph_files_path
155
+ ON graph_files(stash_root, file_path);
156
+
157
+ CREATE INDEX IF NOT EXISTS idx_graph_files_stash_order
158
+ ON graph_files(stash_root, file_order);
159
+
160
+ CREATE TABLE IF NOT EXISTS graph_file_entities (
161
+ stash_root TEXT NOT NULL,
162
+ file_path TEXT NOT NULL,
163
+ body_hash TEXT NOT NULL,
164
+ entity_order INTEGER NOT NULL,
165
+ entity_norm TEXT NOT NULL,
166
+ entity TEXT NOT NULL,
167
+ PRIMARY KEY (stash_root, file_path, body_hash, entity_order),
168
+ FOREIGN KEY (stash_root, file_path, body_hash)
169
+ REFERENCES graph_files(stash_root, file_path, body_hash) ON DELETE CASCADE
170
+ );
171
+
172
+ CREATE INDEX IF NOT EXISTS idx_graph_file_entities_entity_norm
173
+ ON graph_file_entities(stash_root, entity_norm);
174
+
175
+ CREATE TABLE IF NOT EXISTS graph_file_relations (
176
+ stash_root TEXT NOT NULL,
177
+ file_path TEXT NOT NULL,
178
+ body_hash TEXT NOT NULL,
179
+ relation_order INTEGER NOT NULL,
180
+ from_entity_norm TEXT NOT NULL,
181
+ from_entity TEXT NOT NULL,
182
+ to_entity_norm TEXT NOT NULL,
183
+ to_entity TEXT NOT NULL,
184
+ relation_type TEXT,
185
+ confidence REAL,
186
+ PRIMARY KEY (stash_root, file_path, body_hash, relation_order),
187
+ FOREIGN KEY (stash_root, file_path, body_hash)
188
+ REFERENCES graph_files(stash_root, file_path, body_hash) ON DELETE CASCADE
189
+ );
190
+
191
+ -- #624-P3: lazy graph-extraction queue. Standalone table (NO FK to
192
+ -- graph_files — a queued file by definition has no graph row yet).
193
+ -- Idempotent on (stash_root, file_path); drained highest-priority-first.
194
+ -- CREATE TABLE IF NOT EXISTS is the forward migration (no DB_VERSION bump).
195
+ CREATE TABLE IF NOT EXISTS graph_extraction_queue (
196
+ stash_root TEXT NOT NULL,
197
+ file_path TEXT NOT NULL,
198
+ body_hash TEXT NOT NULL,
199
+ queued_at TEXT NOT NULL DEFAULT (datetime('now')),
200
+ priority INTEGER NOT NULL DEFAULT 0,
201
+ PRIMARY KEY (stash_root, file_path)
202
+ );
203
+
204
+ CREATE INDEX IF NOT EXISTS idx_graph_extraction_queue_drain
205
+ ON graph_extraction_queue(stash_root, priority DESC, queued_at);
206
+ `);
207
+ }
65
208
  export function ensureSchema(db, embeddingDim) {
66
209
  // Create meta table first so we can check version
67
210
  db.exec(`
@@ -90,13 +233,35 @@ export function ensureSchema(db, embeddingDim) {
90
233
  entry_json TEXT NOT NULL,
91
234
  search_text TEXT NOT NULL,
92
235
  entry_type TEXT NOT NULL,
93
- derived_from TEXT
236
+ derived_from TEXT,
237
+ -- Chunk-5 Step 2 / DB v18 (spec 14.4): bundle-adapter identity + provenance,
238
+ -- ADDITIVE alongside the legacy columns above. item_ref is the durable
239
+ -- <bundle>//<concept-id> spelling; nullable during the transition so a
240
+ -- pre-repoint reader path never trips a NOT NULL on a partially-migrated row.
241
+ item_ref TEXT,
242
+ bundle_id TEXT,
243
+ component_id TEXT,
244
+ concept_id TEXT,
245
+ adapter_id TEXT,
246
+ type TEXT,
247
+ content_hash TEXT,
248
+ document_json TEXT
94
249
  );
95
250
 
96
251
  CREATE INDEX IF NOT EXISTS idx_entries_dir ON entries(dir_path);
97
252
  CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(entry_type);
98
253
  CREATE INDEX IF NOT EXISTS idx_entries_file_path ON entries(file_path);
99
254
  `);
255
+ // v18: backfill the bundle-adapter identity/provenance columns on databases
256
+ // created against a pre-v18 binary (partial schema) — same PRAGMA-then-ALTER
257
+ // guard pattern as `ensureDerivedFromColumn`. Runs BEFORE the item_ref index
258
+ // so the CREATE INDEX below never references a not-yet-added column.
259
+ ensureBundleRefColumns(db);
260
+ // v19 (F4c, spec §11.4): item_ref is THE durable identity — its index is
261
+ // UNIQUE. Every indexed row now carries item_ref; SQLite treats NULLs as
262
+ // distinct in a UNIQUE index, so NULL-item_ref write-back stragglers coexist.
263
+ // A pre-v19 DB carries a NON-unique `idx_entries_item_ref`, so drop-then-create.
264
+ ensureUniqueItemRefIndex(db);
100
265
  // Phase 5A / DB v17: backfill `derived_from` column + index on databases
101
266
  // that were created at v17 fresh OR carry a partial v17 schema (a DB whose
102
267
  // `index_meta.version` was bumped to 17 but whose `entries` table still
@@ -152,7 +317,9 @@ export function ensureSchema(db, embeddingDim) {
152
317
  );
153
318
  `);
154
319
  }
155
- // Usage events table — created by ensureUsageEventsSchema() at runtime.
320
+ // usage_events + legacy_state moved to state.db (Chunk-8 WI-8.3, DB_VERSION
321
+ // v20). index.db no longer creates them; usage_events writers/readers open
322
+ // state.db. utility_scores (a regenerable index.db cache) stays here.
156
323
  // Utility scores table (aggregated per-entry utility metrics)
157
324
  db.exec(`
158
325
  CREATE TABLE IF NOT EXISTS utility_scores (
@@ -229,94 +396,7 @@ export function ensureSchema(db, embeddingDim) {
229
396
  // migrateGraphDataFromLegacy() copies the data across so the graph is PRESERVED
230
397
  // (not re-extracted).
231
398
  migrateGraphFilesSchema(db);
232
- db.exec(`
233
- CREATE TABLE IF NOT EXISTS graph_meta (
234
- stash_root TEXT PRIMARY KEY,
235
- schema_version INTEGER NOT NULL,
236
- generated_at TEXT NOT NULL,
237
- considered_files INTEGER NOT NULL DEFAULT 0,
238
- extracted_files INTEGER NOT NULL DEFAULT 0,
239
- entity_count INTEGER NOT NULL DEFAULT 0,
240
- relation_count INTEGER NOT NULL DEFAULT 0,
241
- extraction_coverage REAL NOT NULL DEFAULT 0,
242
- density REAL NOT NULL DEFAULT 0,
243
- extractor_id TEXT,
244
- extraction_run_id TEXT,
245
- model TEXT,
246
- prompt_version TEXT,
247
- batch_size INTEGER,
248
- cache_hits INTEGER NOT NULL DEFAULT 0,
249
- cache_misses INTEGER NOT NULL DEFAULT 0,
250
- truncation_count INTEGER NOT NULL DEFAULT 0,
251
- failure_count INTEGER NOT NULL DEFAULT 0
252
- );
253
-
254
- CREATE TABLE IF NOT EXISTS graph_files (
255
- stash_root TEXT NOT NULL,
256
- file_path TEXT NOT NULL,
257
- file_order INTEGER NOT NULL,
258
- file_type TEXT NOT NULL,
259
- body_hash TEXT NOT NULL,
260
- confidence REAL,
261
- status TEXT NOT NULL DEFAULT 'extracted',
262
- reason TEXT,
263
- extraction_run_id TEXT,
264
- PRIMARY KEY (stash_root, file_path, body_hash)
265
- );
266
-
267
- CREATE UNIQUE INDEX IF NOT EXISTS idx_graph_files_path
268
- ON graph_files(stash_root, file_path);
269
-
270
- CREATE INDEX IF NOT EXISTS idx_graph_files_stash_order
271
- ON graph_files(stash_root, file_order);
272
-
273
- CREATE TABLE IF NOT EXISTS graph_file_entities (
274
- stash_root TEXT NOT NULL,
275
- file_path TEXT NOT NULL,
276
- body_hash TEXT NOT NULL,
277
- entity_order INTEGER NOT NULL,
278
- entity_norm TEXT NOT NULL,
279
- entity TEXT NOT NULL,
280
- PRIMARY KEY (stash_root, file_path, body_hash, entity_order),
281
- FOREIGN KEY (stash_root, file_path, body_hash)
282
- REFERENCES graph_files(stash_root, file_path, body_hash) ON DELETE CASCADE
283
- );
284
-
285
- CREATE INDEX IF NOT EXISTS idx_graph_file_entities_entity_norm
286
- ON graph_file_entities(stash_root, entity_norm);
287
-
288
- CREATE TABLE IF NOT EXISTS graph_file_relations (
289
- stash_root TEXT NOT NULL,
290
- file_path TEXT NOT NULL,
291
- body_hash TEXT NOT NULL,
292
- relation_order INTEGER NOT NULL,
293
- from_entity_norm TEXT NOT NULL,
294
- from_entity TEXT NOT NULL,
295
- to_entity_norm TEXT NOT NULL,
296
- to_entity TEXT NOT NULL,
297
- relation_type TEXT,
298
- confidence REAL,
299
- PRIMARY KEY (stash_root, file_path, body_hash, relation_order),
300
- FOREIGN KEY (stash_root, file_path, body_hash)
301
- REFERENCES graph_files(stash_root, file_path, body_hash) ON DELETE CASCADE
302
- );
303
-
304
- -- #624-P3: lazy graph-extraction queue. Standalone table (NO FK to
305
- -- graph_files — a queued file by definition has no graph row yet).
306
- -- Idempotent on (stash_root, file_path); drained highest-priority-first.
307
- -- CREATE TABLE IF NOT EXISTS is the forward migration (no DB_VERSION bump).
308
- CREATE TABLE IF NOT EXISTS graph_extraction_queue (
309
- stash_root TEXT NOT NULL,
310
- file_path TEXT NOT NULL,
311
- body_hash TEXT NOT NULL,
312
- queued_at TEXT NOT NULL DEFAULT (datetime('now')),
313
- priority INTEGER NOT NULL DEFAULT 0,
314
- PRIMARY KEY (stash_root, file_path)
315
- );
316
-
317
- CREATE INDEX IF NOT EXISTS idx_graph_extraction_queue_drain
318
- ON graph_extraction_queue(stash_root, priority DESC, queued_at);
319
- `);
399
+ ensureGraphTables(db);
320
400
  // #624-P1 migration step 2: copy any renamed-aside legacy graph data into the
321
401
  // new-shape tables (just created above), then drop the legacy tables. No-op
322
402
  // unless migrateGraphFilesSchema renamed a legacy graph_files this open.
@@ -385,8 +465,8 @@ export function ensureSchema(db, embeddingDim) {
385
465
  setMeta(db, "embeddingDim", String(embeddingDim));
386
466
  }
387
467
  }
388
- // Usage telemetry table
389
- ensureUsageEventsSchema(db);
468
+ // Usage telemetry (usage_events) lives in state.db since Chunk-8 WI-8.3 —
469
+ // no longer created here.
390
470
  // Registry index cache table — caches remote registry index documents so
391
471
  // `akm search` does not hit the network on every invocation.
392
472
  db.exec(REGISTRY_INDEX_CACHE_DDL);
@@ -410,6 +490,52 @@ function ensureDerivedFromColumn(db) {
410
490
  db.exec("CREATE INDEX IF NOT EXISTS idx_entries_derived_from ON entries(derived_from)");
411
491
  }, "entries table may not exist on a brand-new DB before CREATE — caller is responsible");
412
492
  }
493
+ /**
494
+ * Chunk-5 Step 2 / DB v18 schema guard.
495
+ *
496
+ * Ensures the bundle-adapter identity/provenance columns exist on the open
497
+ * `entries` table. Called from `ensureSchema()` after the entries CREATE so a
498
+ * legacy database (created against a pre-v18 binary) gains the new columns
499
+ * without a rebuild. All columns are nullable and added ADDITIVELY — the
500
+ * writer populates `item_ref`/`bundle_id`/`component_id`/`concept_id`/
501
+ * `adapter_id`/`type` while readers still key on the legacy columns. Idempotent:
502
+ * a `PRAGMA table_info` lookup gates each ALTER.
503
+ */
504
+ function ensureBundleRefColumns(db) {
505
+ bestEffort(() => {
506
+ const cols = db.prepare("PRAGMA table_info(entries)").all();
507
+ const have = new Set(cols.map((c) => c.name));
508
+ const additive = [
509
+ ["item_ref", "TEXT"],
510
+ ["bundle_id", "TEXT"],
511
+ ["component_id", "TEXT"],
512
+ ["concept_id", "TEXT"],
513
+ ["adapter_id", "TEXT"],
514
+ ["type", "TEXT"],
515
+ ["content_hash", "TEXT"],
516
+ ["document_json", "TEXT"],
517
+ ];
518
+ for (const [name, sqlType] of additive) {
519
+ if (!have.has(name))
520
+ db.exec(`ALTER TABLE entries ADD COLUMN ${name} ${sqlType}`);
521
+ }
522
+ }, "entries table may not exist on a brand-new DB before CREATE — caller is responsible");
523
+ }
524
+ /**
525
+ * Chunk-5 flip F4c / DB v19 schema guard.
526
+ *
527
+ * Upgrade `entries.item_ref`'s lookup index to UNIQUE (item_ref is now THE
528
+ * durable identity — spec §11.4). A pre-v19 DB has a NON-unique
529
+ * `idx_entries_item_ref`, so we DROP-then-CREATE (a `CREATE UNIQUE INDEX IF NOT
530
+ * EXISTS` under the same name would no-op against the existing non-unique index).
531
+ * SQLite treats NULLs as distinct in a UNIQUE index. Duplicate durable identities
532
+ * are an invalid index and fail the schema open rather than enabling a dual-key
533
+ * fallback.
534
+ */
535
+ function ensureUniqueItemRefIndex(db) {
536
+ db.exec("DROP INDEX IF EXISTS idx_entries_item_ref");
537
+ db.exec("CREATE UNIQUE INDEX idx_entries_item_ref ON entries(item_ref)");
538
+ }
413
539
  /**
414
540
  * Returns true when a table exists in the current database.
415
541
  */
@@ -0,0 +1,12 @@
1
+ // This Source Code Form is subject to the terms of the Mozilla Public
2
+ // License, v. 2.0. If a copy of the MPL was not distributed with this
3
+ // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
+ /**
5
+ * Shared SQL constants for the `index.db` storage repositories.
6
+ */
7
+ /**
8
+ * SQLite parameter chunk size — chosen well below SQLITE_MAX_VARIABLE_NUMBER
9
+ * (default 999 on most builds) so multi-row `IN (?, ?, ...)` queries stay
10
+ * within bounds. Shared by the entries / fts / utility / llm-cache repos.
11
+ */
12
+ export const SQLITE_CHUNK_SIZE = 500;