@dikolab/kbdb 0.2.2 → 0.3.1

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 (520) hide show
  1. package/README.md +47 -31
  2. package/dist/bench/constants/corpus-defaults.constant.d.ts +3 -0
  3. package/dist/bench/functions/format-report.function.d.ts +11 -0
  4. package/dist/bench/functions/generate-corpus.function.d.ts +12 -0
  5. package/dist/bench/functions/measure-operation.function.d.ts +14 -0
  6. package/dist/bench/functions/seeded-rng.function.d.ts +11 -0
  7. package/dist/bench/functions/zipf-word.function.d.ts +13 -0
  8. package/dist/bench/index.d.ts +10 -0
  9. package/dist/bench/typings/bench-result.interface.d.ts +11 -0
  10. package/dist/bench/typings/bench-suite-result.interface.d.ts +10 -0
  11. package/dist/bench/typings/corpus-config.interface.d.ts +11 -0
  12. package/dist/bench/typings/corpus-section.interface.d.ts +9 -0
  13. package/dist/cli.cjs +523 -80
  14. package/dist/cli.cjs.map +4 -4
  15. package/dist/cli.mjs +515 -72
  16. package/dist/cli.mjs.map +4 -4
  17. package/dist/kbdb-worker.cjs +395 -60
  18. package/dist/kbdb-worker.cjs.map +4 -4
  19. package/dist/mod.cjs +17 -0
  20. package/dist/mod.cjs.map +2 -2
  21. package/dist/mod.mjs +17 -0
  22. package/dist/mod.mjs.map +2 -2
  23. package/dist/src/shared/auto-capture/classes/auto-capture-controller.class.d.ts +33 -0
  24. package/dist/src/shared/auto-capture/constants/auto-capture-defaults.constant.d.ts +8 -0
  25. package/dist/src/shared/auto-capture/functions/build-capture-prompt.function.d.ts +11 -0
  26. package/dist/src/shared/auto-capture/functions/evaluate-trigger.function.d.ts +12 -0
  27. package/dist/src/shared/auto-capture/index.d.ts +7 -0
  28. package/dist/src/shared/auto-capture/typings/auto-capture-config.interface.d.ts +13 -0
  29. package/dist/src/shared/auto-capture/typings/auto-capture-state.interface.d.ts +13 -0
  30. package/dist/src/shared/auto-capture/typings/auto-capture-trigger.interface.d.ts +7 -0
  31. package/dist/src/shared/cli/constants/global-help.constant.d.ts +8 -0
  32. package/dist/src/shared/cli/constants/leaf-help.constant.d.ts +7 -0
  33. package/dist/src/shared/cli/constants/memory-protocol-body.constant.d.ts +7 -0
  34. package/dist/src/shared/cli/constants/query-guidance-body.constant.d.ts +7 -0
  35. package/dist/src/shared/cli/constants/subcommand-help.constant.d.ts +8 -0
  36. package/dist/src/shared/cli/functions/collect-files.function.d.ts +13 -0
  37. package/dist/src/shared/cli/functions/compute-section-kbid.function.d.ts +15 -0
  38. package/dist/src/shared/cli/functions/dispatch-command.function.d.ts +3 -1
  39. package/dist/src/shared/cli/functions/format-mcp-output.function.d.ts +9 -0
  40. package/dist/src/shared/cli/functions/format-text-output.function.d.ts +9 -0
  41. package/dist/src/shared/cli/functions/generate-group-help.function.d.ts +11 -0
  42. package/dist/src/shared/cli/functions/handle-data-command.function.d.ts +16 -0
  43. package/dist/src/shared/cli/functions/handle-mcp.function.d.ts +15 -0
  44. package/dist/src/shared/cli/functions/handle-migrate.function.d.ts +15 -0
  45. package/dist/src/shared/cli/functions/hydrate-search-previews.function.d.ts +14 -0
  46. package/dist/src/shared/cli/functions/install-default-skills.function.d.ts +12 -0
  47. package/dist/src/shared/cli/functions/resolve-skill-names.function.d.ts +16 -0
  48. package/dist/src/shared/cli/functions/run-check.function.d.ts +47 -5
  49. package/dist/src/shared/cli/functions/run-export.function.d.ts +34 -0
  50. package/dist/src/shared/cli/functions/run-gc.function.d.ts +6 -0
  51. package/dist/src/shared/cli/functions/run-learn.function.d.ts +35 -6
  52. package/dist/src/shared/cli/functions/run-recall.function.d.ts +45 -0
  53. package/dist/src/shared/cli/functions/run-search.function.d.ts +53 -15
  54. package/dist/src/shared/cli/functions/version-gate.function.d.ts +15 -0
  55. package/dist/src/shared/cli/functions/wrap-command.function.d.ts +15 -0
  56. package/dist/src/shared/cli/index.d.ts +4 -0
  57. package/dist/src/shared/cli/typings/agent-create-client.interface.d.ts +42 -0
  58. package/dist/src/shared/cli/typings/agent-get-client.interface.d.ts +36 -0
  59. package/dist/src/shared/cli/typings/check-client.interface.d.ts +58 -0
  60. package/dist/src/shared/cli/typings/cli-deps.interface.d.ts +48 -0
  61. package/dist/src/shared/cli/typings/cli-options.interface.d.ts +15 -0
  62. package/dist/src/shared/cli/typings/disconnectable-client.interface.d.ts +26 -0
  63. package/dist/src/shared/cli/typings/dispatch-client.type.d.ts +27 -0
  64. package/dist/src/shared/cli/typings/learn-client.interface.d.ts +52 -0
  65. package/dist/src/shared/cli/typings/learn-io.interface.d.ts +5 -0
  66. package/dist/src/shared/cli/typings/learn-result.model.d.ts +19 -0
  67. package/dist/src/shared/cli/typings/search-client.interface.d.ts +71 -0
  68. package/dist/src/shared/cli/typings/search-display.model.d.ts +18 -0
  69. package/dist/src/shared/embedding/classes/null-embedding-provider.class.d.ts +20 -0
  70. package/dist/src/shared/embedding/constants/near-duplicate-thresholds.constant.d.ts +15 -0
  71. package/dist/src/shared/embedding/functions/build-vector-index.function.d.ts +14 -0
  72. package/dist/src/shared/embedding/functions/cosine-similarity.function.d.ts +10 -0
  73. package/dist/src/shared/embedding/functions/detect-near-duplicates.function.d.ts +18 -0
  74. package/dist/src/shared/embedding/functions/jaccard-coefficient.function.d.ts +9 -0
  75. package/dist/src/shared/embedding/functions/read-vector-index-meta.function.d.ts +10 -0
  76. package/dist/src/shared/embedding/functions/rrf-fuse.function.d.ts +14 -0
  77. package/dist/src/shared/embedding/functions/search-vectors.function.d.ts +14 -0
  78. package/dist/src/shared/embedding/index.d.ts +16 -0
  79. package/dist/src/shared/embedding/typings/embedding-config.interface.d.ts +20 -0
  80. package/dist/src/shared/embedding/typings/embedding-provider.interface.d.ts +23 -0
  81. package/dist/src/shared/embedding/typings/near-duplicate-candidate.model.d.ts +23 -0
  82. package/dist/src/shared/embedding/typings/near-duplicate-result.model.d.ts +24 -0
  83. package/dist/src/shared/embedding/typings/vector-index-entry.model.d.ts +12 -0
  84. package/dist/src/shared/embedding/typings/vector-index-meta.model.d.ts +11 -0
  85. package/dist/src/shared/embedding/typings/vector-search-result.model.d.ts +7 -0
  86. package/dist/src/shared/mcp/classes/mcp-server.class.d.ts +8 -0
  87. package/dist/src/shared/mcp/constants/tool-agent-create.constant.d.ts +3 -0
  88. package/dist/src/shared/mcp/constants/tool-agent-delete.constant.d.ts +3 -0
  89. package/dist/src/shared/mcp/constants/tool-agent-get.constant.d.ts +3 -0
  90. package/dist/src/shared/mcp/constants/tool-agent-list.constant.d.ts +3 -0
  91. package/dist/src/shared/mcp/constants/tool-auto-capture-review.constant.d.ts +8 -0
  92. package/dist/src/shared/mcp/constants/tool-check.constant.d.ts +3 -0
  93. package/dist/src/shared/mcp/constants/tool-content.constant.d.ts +3 -0
  94. package/dist/src/shared/mcp/constants/tool-export.constant.d.ts +3 -0
  95. package/dist/src/shared/mcp/constants/tool-gc.constant.d.ts +3 -0
  96. package/dist/src/shared/mcp/constants/tool-learn.constant.d.ts +3 -0
  97. package/dist/src/shared/mcp/constants/tool-rebuild.constant.d.ts +3 -0
  98. package/dist/src/shared/mcp/constants/tool-recall.constant.d.ts +3 -0
  99. package/dist/src/shared/mcp/constants/tool-retrieve.constant.d.ts +3 -0
  100. package/dist/src/shared/mcp/constants/tool-search.constant.d.ts +3 -0
  101. package/dist/src/shared/mcp/constants/tool-skill-delete.constant.d.ts +3 -0
  102. package/dist/src/shared/mcp/constants/tool-skill-get.constant.d.ts +3 -0
  103. package/dist/src/shared/mcp/constants/tool-skill-learn.constant.d.ts +3 -0
  104. package/dist/src/shared/mcp/constants/tool-skill-list.constant.d.ts +3 -0
  105. package/dist/src/shared/mcp/constants/tool-status.constant.d.ts +3 -0
  106. package/dist/src/shared/mcp/constants/tool-unlearn.constant.d.ts +3 -0
  107. package/dist/src/shared/mcp/functions/as-boolean-or-undefined.function.d.ts +7 -0
  108. package/dist/src/shared/mcp/functions/as-string-array-or-undefined.function.d.ts +7 -0
  109. package/dist/src/shared/mcp/functions/as-string-array.function.d.ts +7 -0
  110. package/dist/src/shared/mcp/functions/as-string.function.d.ts +8 -0
  111. package/dist/src/shared/mcp/functions/build-skills-text.function.d.ts +18 -0
  112. package/dist/src/shared/mcp/functions/handle-agent-prompt.function.d.ts +14 -0
  113. package/dist/src/shared/mcp/functions/handle-mcp-request.function.d.ts +14 -0
  114. package/dist/src/shared/mcp/functions/handle-prompt-get.function.d.ts +4 -3
  115. package/dist/src/shared/mcp/functions/handle-skill-prompt.function.d.ts +16 -0
  116. package/dist/src/shared/mcp/functions/handle-tool-auto-capture-review.function.d.ts +12 -0
  117. package/dist/src/shared/mcp/functions/handle-tool-check.function.d.ts +11 -0
  118. package/dist/src/shared/mcp/functions/handle-tool-content.function.d.ts +12 -0
  119. package/dist/src/shared/mcp/functions/handle-tool-export.function.d.ts +12 -0
  120. package/dist/src/shared/mcp/functions/handle-tool-gc.function.d.ts +11 -0
  121. package/dist/src/shared/mcp/functions/handle-tool-learn.function.d.ts +12 -0
  122. package/dist/src/shared/mcp/functions/handle-tool-rebuild.function.d.ts +11 -0
  123. package/dist/src/shared/mcp/functions/handle-tool-retrieve.function.d.ts +12 -0
  124. package/dist/src/shared/mcp/functions/handle-tool-search.function.d.ts +13 -0
  125. package/dist/src/shared/mcp/functions/handle-tool-skill-delete.function.d.ts +12 -0
  126. package/dist/src/shared/mcp/functions/handle-tool-skill-get.function.d.ts +13 -0
  127. package/dist/src/shared/mcp/functions/handle-tool-skill-learn.function.d.ts +13 -0
  128. package/dist/src/shared/mcp/functions/handle-tool-skill-list.function.d.ts +11 -0
  129. package/dist/src/shared/mcp/functions/handle-tool-status.function.d.ts +11 -0
  130. package/dist/src/shared/mcp/functions/handle-tool-unlearn.function.d.ts +12 -0
  131. package/dist/src/shared/mcp/functions/parse-agent-meta.function.d.ts +14 -0
  132. package/dist/src/shared/mcp/functions/parse-skill-arguments.function.d.ts +11 -0
  133. package/dist/src/shared/mcp/functions/read-agent-meta.function.d.ts +17 -0
  134. package/dist/src/shared/mcp/functions/resolve-skill-refs.function.d.ts +23 -0
  135. package/dist/src/shared/mcp/functions/run-startup-health-check.function.d.ts +14 -0
  136. package/dist/src/shared/mcp/typings/mcp-capabilities.interface.d.ts +16 -0
  137. package/dist/src/shared/mcp/typings/mcp-client.interface.d.ts +45 -0
  138. package/dist/src/shared/mcp/typings/mcp-completion.interface.d.ts +43 -0
  139. package/dist/src/shared/mcp/typings/mcp-content-result.model.d.ts +9 -0
  140. package/dist/src/shared/mcp/typings/mcp-export-result.model.d.ts +11 -0
  141. package/dist/src/shared/mcp/typings/mcp-gc-result.model.d.ts +15 -0
  142. package/dist/src/shared/mcp/typings/mcp-integrity-check-result.model.d.ts +16 -0
  143. package/dist/src/shared/mcp/typings/mcp-integrity-error.model.d.ts +9 -0
  144. package/dist/src/shared/mcp/typings/mcp-notification.interface.d.ts +9 -0
  145. package/dist/src/shared/mcp/typings/mcp-rebuild-result.model.d.ts +9 -0
  146. package/dist/src/shared/mcp/typings/mcp-request.interface.d.ts +11 -0
  147. package/dist/src/shared/mcp/typings/mcp-resource-result.interface.d.ts +12 -0
  148. package/dist/src/shared/mcp/typings/mcp-resource-template.interface.d.ts +11 -0
  149. package/dist/src/shared/mcp/typings/mcp-response.interface.d.ts +18 -0
  150. package/dist/src/shared/mcp/typings/mcp-server-info.interface.d.ts +7 -0
  151. package/dist/src/shared/mcp/typings/mcp-server-state.interface.d.ts +16 -0
  152. package/dist/src/shared/mcp/typings/mcp-tool-annotations.interface.d.ts +32 -0
  153. package/dist/src/shared/mcp/typings/mcp-tool-definition.interface.d.ts +15 -0
  154. package/dist/src/shared/mcp/typings/mcp-tool-result.interface.d.ts +19 -0
  155. package/dist/src/shared/mcp/typings/mcp-worker-client.interface.d.ts +220 -0
  156. package/dist/src/shared/mcp/typings/tool-call-result.model.d.ts +17 -0
  157. package/dist/src/shared/sync/functions/build-import-report.function.d.ts +18 -0
  158. package/dist/src/shared/sync/functions/parse-export-entry.function.d.ts +11 -0
  159. package/dist/src/shared/sync/functions/resolve-conflict.function.d.ts +13 -0
  160. package/dist/src/shared/sync/functions/serialize-export-entry.function.d.ts +8 -0
  161. package/dist/src/shared/sync/index.d.ts +9 -0
  162. package/dist/src/shared/sync/typings/conflict-resolution.type.d.ts +8 -0
  163. package/dist/src/shared/sync/typings/export-entry.interface.d.ts +13 -0
  164. package/dist/src/shared/sync/typings/export-options.interface.d.ts +9 -0
  165. package/dist/src/shared/sync/typings/import-options.interface.d.ts +7 -0
  166. package/dist/src/shared/sync/typings/import-report.interface.d.ts +15 -0
  167. package/dist/src/shared/wasm-codec/functions/decode-add-section-result.function.d.ts +48 -0
  168. package/dist/src/shared/wasm-codec/functions/decode-one-recall-result.function.d.ts +14 -0
  169. package/dist/src/shared/wasm-codec/functions/decode-option-string.function.d.ts +12 -0
  170. package/dist/src/shared/wasm-codec/functions/decode-recall-document.function.d.ts +14 -0
  171. package/dist/src/shared/wasm-codec/functions/decode-recall-reference.function.d.ts +14 -0
  172. package/dist/src/shared/wasm-codec/functions/decode-recall-sibling.function.d.ts +13 -0
  173. package/dist/src/shared/wasm-codec/functions/decode-scored-results.function.d.ts +58 -0
  174. package/dist/src/shared/wasm-codec/functions/decode-section-match.function.d.ts +15 -0
  175. package/dist/src/shared/wasm-codec/functions/decode-section-record-trailing.function.d.ts +14 -0
  176. package/dist/src/shared/wasm-codec/functions/decode-section-record.function.d.ts +14 -0
  177. package/dist/src/shared/wasm-codec/functions/decode-section-records.function.d.ts +33 -0
  178. package/dist/src/shared/wasm-codec/functions/decode-section-type.function.d.ts +13 -0
  179. package/dist/src/shared/wasm-codec/functions/decode-wasm-list.function.d.ts +17 -0
  180. package/dist/src/shared/wasm-codec/functions/encode-add-section-params.function.d.ts +52 -0
  181. package/dist/src/shared/wasm-codec/index.d.ts +2 -0
  182. package/dist/src/shared/wasm-codec/typings/add-section-input.model.d.ts +45 -0
  183. package/dist/src/shared/wasm-codec/typings/add-section-result.model.d.ts +27 -0
  184. package/dist/src/shared/wasm-codec/typings/document-manifest.model.d.ts +19 -0
  185. package/dist/src/shared/wasm-codec/typings/document-section.model.d.ts +12 -0
  186. package/dist/src/shared/wasm-codec/typings/item-decoder.type.d.ts +6 -0
  187. package/dist/src/shared/wasm-codec/typings/near-duplicate.model.d.ts +16 -0
  188. package/dist/src/shared/wasm-codec/typings/paged-search-result.model.d.ts +21 -0
  189. package/dist/src/shared/wasm-codec/typings/section-match.model.d.ts +31 -0
  190. package/dist/src/shared/wasm-codec/typings/section-record-trailing.model.d.ts +38 -0
  191. package/dist/src/shared/wasm-codec/typings/section-record.model.d.ts +66 -0
  192. package/dist/src/shared/wasm-codec/typings/section-type-result.model.d.ts +12 -0
  193. package/dist/src/shared/worker-client/classes/worker-client.class.d.ts +16 -0
  194. package/dist/src/shared/worker-client/functions/handle-ipc-data.function.d.ts +16 -0
  195. package/dist/src/shared/worker-client/functions/send-ipc-request.function.d.ts +19 -0
  196. package/dist/src/shared/worker-client/index.d.ts +1 -1
  197. package/dist/src/shared/worker-client/typings/add-section-result.model.d.ts +31 -15
  198. package/dist/src/shared/worker-client/typings/export-result.model.d.ts +14 -0
  199. package/dist/src/shared/worker-client/typings/gc-result.model.d.ts +6 -0
  200. package/dist/src/shared/worker-client/typings/json-rpc-response.interface.d.ts +16 -0
  201. package/dist/src/shared/worker-client/typings/pending-call.interface.d.ts +7 -0
  202. package/dist/src/shared/worker-client/typings/recall-document.model.d.ts +16 -0
  203. package/dist/src/shared/worker-client/typings/recall-params.model.d.ts +15 -0
  204. package/dist/src/shared/worker-client/typings/recall-reference.model.d.ts +32 -0
  205. package/dist/src/shared/worker-client/typings/recall-sibling.model.d.ts +11 -0
  206. package/dist/src/shared/worker-client/typings/recall-single-result.model.d.ts +40 -0
  207. package/dist/src/shared/worker-client/typings/search-result.model.d.ts +12 -0
  208. package/dist/src/shared/worker-client/typings/section.model.d.ts +16 -0
  209. package/dist/src/shared/worker-daemon/classes/ipc-error.class.d.ts +17 -0
  210. package/dist/src/shared/worker-daemon/classes/worker-daemon.class.d.ts +35 -0
  211. package/dist/src/shared/worker-daemon/constants/wasm-method-map.constant.d.ts +16 -0
  212. package/dist/src/shared/worker-daemon/functions/build-ipc-error-response.function.d.ts +9 -0
  213. package/dist/src/shared/worker-daemon/functions/check-catalog-version.function.d.ts +9 -0
  214. package/dist/src/shared/worker-daemon/functions/check-preconditions.function.d.ts +10 -0
  215. package/dist/src/shared/worker-daemon/functions/detect-stale-pid.function.d.ts +15 -0
  216. package/dist/src/shared/worker-daemon/functions/dispatch-request.function.d.ts +35 -0
  217. package/dist/src/shared/worker-daemon/functions/handle-check-version.function.d.ts +23 -0
  218. package/dist/src/shared/worker-daemon/functions/handle-config-method.function.d.ts +11 -0
  219. package/dist/src/shared/worker-daemon/functions/handle-read-ops.function.d.ts +52 -0
  220. package/dist/src/shared/worker-daemon/functions/handle-write-ops.function.d.ts +44 -0
  221. package/dist/src/shared/worker-daemon/functions/parse-auto-capture-section.function.d.ts +14 -0
  222. package/dist/src/shared/worker-daemon/functions/parse-catalog-version.function.d.ts +10 -0
  223. package/dist/src/shared/worker-daemon/functions/parse-embedding-section.function.d.ts +13 -0
  224. package/dist/src/shared/worker-daemon/functions/parse-worker-toml.function.d.ts +11 -0
  225. package/dist/src/shared/worker-daemon/functions/run-startup-integrity-check.function.d.ts +18 -0
  226. package/dist/src/shared/worker-daemon/functions/scan-near-duplicates.function.d.ts +21 -0
  227. package/dist/src/shared/worker-daemon/functions/wasm-bridge.function.d.ts +51 -0
  228. package/dist/src/shared/worker-daemon/functions/wasm-memory-helpers.function.d.ts +22 -0
  229. package/dist/src/shared/worker-daemon/functions/write-lock.function.d.ts +32 -0
  230. package/dist/src/shared/worker-daemon/typings/allocator-ref.interface.d.ts +16 -0
  231. package/dist/src/shared/worker-daemon/typings/daemon-config.interface.d.ts +6 -0
  232. package/dist/src/shared/worker-daemon/typings/fs-adapter.interface.d.ts +22 -0
  233. package/dist/src/shared/worker-daemon/typings/handler-context.interface.d.ts +18 -0
  234. package/dist/src/shared/worker-daemon/typings/memory-ref.interface.d.ts +13 -0
  235. package/dist/src/shared/worker-daemon/typings/wasm-fn.type.d.ts +2 -0
  236. package/dist/src/shared/worker-daemon/typings/write-lock.interface.d.ts +15 -0
  237. package/dist/wasm/fs-database/kbdb_fs_database.d.ts +22 -1
  238. package/dist/wasm/fs-database/kbdb_fs_database.js +28 -1
  239. package/dist/wasm/fs-database/kbdb_fs_database_bg.wasm +0 -0
  240. package/dist/wasm/fs-database/kbdb_fs_database_bg.wasm.d.ts +1 -0
  241. package/dist/wasm/kb-worker/kbdb_worker.d.ts +48 -1
  242. package/dist/wasm/kb-worker/kbdb_worker.js +60 -1
  243. package/dist/wasm/kb-worker/kbdb_worker_bg.wasm +0 -0
  244. package/dist/wasm/kb-worker/kbdb_worker_bg.wasm.d.ts +2 -0
  245. package/dist/wasm/query-parser/kbdb_query_parser_bg.wasm +0 -0
  246. package/dist/worker.mjs +396 -60
  247. package/dist/worker.mjs.map +4 -4
  248. package/docs/details/cli.md +102 -15
  249. package/docs/details/library-api.md +55 -6
  250. package/docs/details/mcp-server.md +10 -4
  251. package/docs/details/search-and-ranking.md +63 -5
  252. package/docs/details/storage.md +2 -0
  253. package/docs/goals/auto-capture.md +378 -0
  254. package/docs/goals/benchmarking.md +296 -0
  255. package/docs/goals/cli.md +255 -14
  256. package/docs/goals/concurrency.md +259 -0
  257. package/docs/goals/database.md +244 -17
  258. package/docs/goals/document.md +1 -1
  259. package/docs/goals/hybrid-search.md +436 -0
  260. package/docs/goals/mcp.md +83 -14
  261. package/docs/goals/query-parser.md +98 -4
  262. package/docs/goals/query-result.md +177 -10
  263. package/docs/goals/semantic-dedup.md +229 -0
  264. package/docs/goals/skills.md +72 -0
  265. package/docs/goals/sync.md +217 -0
  266. package/docs/goals/worker-daemon.md +54 -7
  267. package/docs/modules/rust/fs-database/functions/integrity.md +11 -0
  268. package/docs/modules/rust/fs-database/functions/section.md +23 -6
  269. package/docs/modules/rust/fs-database/indexes/vectors.md +110 -0
  270. package/docs/modules/rust/fs-database/module.md +1 -0
  271. package/docs/modules/rust/fs-database/types/section.md +27 -1
  272. package/docs/modules/rust/overview.md +2 -1
  273. package/docs/modules/rust/query-parser/functions/module.md +2 -2
  274. package/docs/modules/rust/query-parser/functions/pipeline.md +44 -6
  275. package/docs/modules/rust/query-parser/module.md +5 -4
  276. package/docs/modules/rust/query-parser/types/keyphrase.md +11 -0
  277. package/docs/modules/rust/query-parser/types/module.md +3 -3
  278. package/docs/modules/typescript/shared/auto-capture/module.md +73 -0
  279. package/docs/modules/typescript/shared/cli/functions.md +68 -3
  280. package/docs/modules/typescript/shared/embedding/functions.md +94 -0
  281. package/docs/modules/typescript/shared/embedding/module.md +71 -0
  282. package/docs/modules/typescript/shared/embedding/typings.md +122 -0
  283. package/docs/overview.md +148 -166
  284. package/docs/release-notes/0.2.0.md +3 -3
  285. package/docs/release-notes/0.3.0.md +89 -0
  286. package/docs/release-notes/0.3.1.md +111 -0
  287. package/docs/release-notes/README.md +2 -0
  288. package/package.json +1 -1
  289. package/src/shared/auto-capture/classes/auto-capture-controller.class.ts +62 -0
  290. package/src/shared/auto-capture/constants/auto-capture-defaults.constant.ts +15 -0
  291. package/src/shared/auto-capture/functions/build-capture-prompt.function.ts +27 -0
  292. package/src/shared/auto-capture/functions/evaluate-trigger.function.ts +50 -0
  293. package/src/shared/auto-capture/index.ts +7 -0
  294. package/src/shared/auto-capture/typings/auto-capture-config.interface.ts +13 -0
  295. package/src/shared/auto-capture/typings/auto-capture-state.interface.ts +13 -0
  296. package/src/shared/auto-capture/typings/auto-capture-trigger.interface.ts +7 -0
  297. package/src/shared/cli/constants/global-help.constant.ts +73 -0
  298. package/src/shared/cli/constants/leaf-help.constant.ts +219 -0
  299. package/src/shared/cli/constants/memory-protocol-body.constant.ts +39 -0
  300. package/src/shared/cli/constants/query-guidance-body.constant.ts +37 -0
  301. package/src/shared/cli/constants/subcommand-help.constant.ts +195 -0
  302. package/src/shared/cli/functions/collect-files.function.ts +55 -0
  303. package/src/shared/cli/functions/compute-section-kbid.function.ts +49 -0
  304. package/src/shared/cli/functions/dispatch-command.function.ts +53 -1
  305. package/src/shared/cli/functions/format-mcp-output.function.ts +41 -0
  306. package/src/shared/cli/functions/format-output.function.ts +36 -12
  307. package/src/shared/cli/functions/format-text-output.function.ts +42 -0
  308. package/src/shared/cli/functions/generate-group-help.function.ts +41 -0
  309. package/src/shared/cli/functions/generate-help.function.ts +56 -1
  310. package/src/shared/cli/functions/handle-data-command.function.ts +67 -0
  311. package/src/shared/cli/functions/handle-mcp.function.ts +56 -0
  312. package/src/shared/cli/functions/handle-migrate.function.ts +64 -0
  313. package/src/shared/cli/functions/hydrate-search-previews.function.ts +29 -0
  314. package/src/shared/cli/functions/install-default-skills.function.ts +296 -0
  315. package/src/shared/cli/functions/parse-args.function.ts +16 -0
  316. package/src/shared/cli/functions/resolve-skill-names.function.ts +43 -0
  317. package/src/shared/cli/functions/run-check.function.ts +87 -6
  318. package/src/shared/cli/functions/run-export.function.ts +40 -0
  319. package/src/shared/cli/functions/run-gc.function.ts +6 -0
  320. package/src/shared/cli/functions/run-init.function.ts +2 -0
  321. package/src/shared/cli/functions/run-learn.function.ts +68 -16
  322. package/src/shared/cli/functions/run-recall.function.ts +66 -0
  323. package/src/shared/cli/functions/run-search.function.ts +60 -15
  324. package/src/shared/cli/functions/version-gate.function.ts +44 -0
  325. package/src/shared/cli/functions/wrap-command.function.ts +34 -0
  326. package/src/shared/cli/index.ts +4 -0
  327. package/src/shared/cli/typings/agent-create-client.interface.ts +47 -0
  328. package/src/shared/cli/typings/agent-get-client.interface.ts +39 -0
  329. package/src/shared/cli/typings/check-client.interface.ts +66 -0
  330. package/src/shared/cli/typings/cli-deps.interface.ts +54 -0
  331. package/src/shared/cli/typings/cli-options.interface.ts +15 -0
  332. package/src/shared/cli/typings/disconnectable-client.interface.ts +29 -0
  333. package/src/shared/cli/typings/dispatch-client.type.ts +46 -0
  334. package/src/shared/cli/typings/learn-client.interface.ts +53 -0
  335. package/src/shared/cli/typings/learn-io.interface.ts +5 -0
  336. package/src/shared/cli/typings/learn-result.model.ts +16 -0
  337. package/src/shared/cli/typings/search-client.interface.ts +73 -0
  338. package/src/shared/cli/typings/search-display.model.ts +18 -0
  339. package/src/shared/embedding/classes/null-embedding-provider.class.ts +29 -0
  340. package/src/shared/embedding/constants/near-duplicate-thresholds.constant.ts +17 -0
  341. package/src/shared/embedding/functions/build-vector-index.function.ts +79 -0
  342. package/src/shared/embedding/functions/cosine-similarity.function.ts +31 -0
  343. package/src/shared/embedding/functions/detect-near-duplicates.function.ts +69 -0
  344. package/src/shared/embedding/functions/jaccard-coefficient.function.ts +26 -0
  345. package/src/shared/embedding/functions/read-vector-index-meta.function.ts +44 -0
  346. package/src/shared/embedding/functions/rrf-fuse.function.ts +33 -0
  347. package/src/shared/embedding/functions/search-vectors.function.ts +59 -0
  348. package/src/shared/embedding/index.ts +20 -0
  349. package/src/shared/embedding/typings/embedding-config.interface.ts +23 -0
  350. package/src/shared/embedding/typings/embedding-provider.interface.ts +25 -0
  351. package/src/shared/embedding/typings/near-duplicate-candidate.model.ts +25 -0
  352. package/src/shared/embedding/typings/near-duplicate-result.model.ts +26 -0
  353. package/src/shared/embedding/typings/vector-index-entry.model.ts +13 -0
  354. package/src/shared/embedding/typings/vector-index-meta.model.ts +14 -0
  355. package/src/shared/embedding/typings/vector-search-result.model.ts +8 -0
  356. package/src/shared/mcp/classes/mcp-server.class.ts +36 -4
  357. package/src/shared/mcp/constants/tool-agent-create.constant.ts +39 -0
  358. package/src/shared/mcp/constants/tool-agent-delete.constant.ts +26 -0
  359. package/src/shared/mcp/constants/tool-agent-get.constant.ts +24 -0
  360. package/src/shared/mcp/constants/tool-agent-list.constant.ts +18 -0
  361. package/src/shared/mcp/constants/tool-auto-capture-review.constant.ts +32 -0
  362. package/src/shared/mcp/constants/tool-check.constant.ts +21 -0
  363. package/src/shared/mcp/constants/tool-content.constant.ts +29 -0
  364. package/src/shared/mcp/constants/tool-export.constant.ts +27 -0
  365. package/src/shared/mcp/constants/tool-gc.constant.ts +21 -0
  366. package/src/shared/mcp/constants/tool-learn.constant.ts +58 -0
  367. package/src/shared/mcp/constants/tool-rebuild.constant.ts +21 -0
  368. package/src/shared/mcp/constants/tool-recall.constant.ts +36 -0
  369. package/src/shared/mcp/constants/tool-retrieve.constant.ts +31 -0
  370. package/src/shared/mcp/constants/tool-search.constant.ts +51 -0
  371. package/src/shared/mcp/constants/tool-skill-delete.constant.ts +24 -0
  372. package/src/shared/mcp/constants/tool-skill-get.constant.ts +27 -0
  373. package/src/shared/mcp/constants/tool-skill-learn.constant.ts +37 -0
  374. package/src/shared/mcp/constants/tool-skill-list.constant.ts +18 -0
  375. package/src/shared/mcp/constants/tool-status.constant.ts +20 -0
  376. package/src/shared/mcp/constants/tool-unlearn.constant.ts +25 -0
  377. package/src/shared/mcp/functions/as-boolean-or-undefined.function.ts +11 -0
  378. package/src/shared/mcp/functions/as-string-array-or-undefined.function.ts +17 -0
  379. package/src/shared/mcp/functions/as-string-array.function.ts +15 -0
  380. package/src/shared/mcp/functions/as-string.function.ts +10 -0
  381. package/src/shared/mcp/functions/build-skills-text.function.ts +43 -0
  382. package/src/shared/mcp/functions/create-tool-definitions.function.ts +74 -5
  383. package/src/shared/mcp/functions/handle-agent-create.function.ts +1 -1
  384. package/src/shared/mcp/functions/handle-agent-prompt.function.ts +68 -0
  385. package/src/shared/mcp/functions/handle-mcp-request.function.ts +202 -0
  386. package/src/shared/mcp/functions/handle-prompt-get.function.ts +18 -12
  387. package/src/shared/mcp/functions/handle-skill-prompt.function.ts +44 -0
  388. package/src/shared/mcp/functions/handle-tool-auto-capture-review.function.ts +24 -0
  389. package/src/shared/mcp/functions/handle-tool-call.function.ts +88 -2
  390. package/src/shared/mcp/functions/handle-tool-check.function.ts +21 -0
  391. package/src/shared/mcp/functions/handle-tool-content.function.ts +23 -0
  392. package/src/shared/mcp/functions/handle-tool-export.function.ts +25 -0
  393. package/src/shared/mcp/functions/handle-tool-gc.function.ts +21 -0
  394. package/src/shared/mcp/functions/handle-tool-learn.function.ts +69 -0
  395. package/src/shared/mcp/functions/handle-tool-rebuild.function.ts +21 -0
  396. package/src/shared/mcp/functions/handle-tool-retrieve.function.ts +40 -0
  397. package/src/shared/mcp/functions/handle-tool-search.function.ts +47 -0
  398. package/src/shared/mcp/functions/handle-tool-skill-delete.function.ts +34 -0
  399. package/src/shared/mcp/functions/handle-tool-skill-get.function.ts +59 -0
  400. package/src/shared/mcp/functions/handle-tool-skill-learn.function.ts +61 -0
  401. package/src/shared/mcp/functions/handle-tool-skill-list.function.ts +39 -0
  402. package/src/shared/mcp/functions/handle-tool-status.function.ts +21 -0
  403. package/src/shared/mcp/functions/handle-tool-unlearn.function.ts +24 -0
  404. package/src/shared/mcp/functions/parse-agent-meta.function.ts +27 -0
  405. package/src/shared/mcp/functions/parse-skill-arguments.function.ts +36 -0
  406. package/src/shared/mcp/functions/read-agent-meta.function.ts +41 -0
  407. package/src/shared/mcp/functions/resolve-skill-refs.function.ts +50 -0
  408. package/src/shared/mcp/functions/run-startup-health-check.function.ts +34 -0
  409. package/src/shared/mcp/typings/mcp-capabilities.interface.ts +16 -0
  410. package/src/shared/mcp/typings/mcp-client.interface.ts +47 -0
  411. package/src/shared/mcp/typings/mcp-completion.interface.ts +45 -0
  412. package/src/shared/mcp/typings/mcp-content-result.model.ts +9 -0
  413. package/src/shared/mcp/typings/mcp-export-result.model.ts +11 -0
  414. package/src/shared/mcp/typings/mcp-gc-result.model.ts +15 -0
  415. package/src/shared/mcp/typings/mcp-integrity-check-result.model.ts +17 -0
  416. package/src/shared/mcp/typings/mcp-integrity-error.model.ts +15 -0
  417. package/src/shared/mcp/typings/mcp-notification.interface.ts +9 -0
  418. package/src/shared/mcp/typings/mcp-rebuild-result.model.ts +9 -0
  419. package/src/shared/mcp/typings/mcp-request.interface.ts +11 -0
  420. package/src/shared/mcp/typings/mcp-resource-result.interface.ts +12 -0
  421. package/src/shared/mcp/typings/mcp-resource-template.interface.ts +11 -0
  422. package/src/shared/mcp/typings/mcp-response.interface.ts +18 -0
  423. package/src/shared/mcp/typings/mcp-server-info.interface.ts +7 -0
  424. package/src/shared/mcp/typings/mcp-server-state.interface.ts +17 -0
  425. package/src/shared/mcp/typings/mcp-tool-annotations.interface.ts +32 -0
  426. package/src/shared/mcp/typings/mcp-tool-definition.interface.ts +16 -0
  427. package/src/shared/mcp/typings/mcp-tool-result.interface.ts +19 -0
  428. package/src/shared/mcp/typings/mcp-worker-client.interface.ts +243 -0
  429. package/src/shared/mcp/typings/tool-call-result.model.ts +18 -0
  430. package/src/shared/sync/functions/build-import-report.function.ts +40 -0
  431. package/src/shared/sync/functions/parse-export-entry.function.ts +45 -0
  432. package/src/shared/sync/functions/resolve-conflict.function.ts +31 -0
  433. package/src/shared/sync/functions/serialize-export-entry.function.ts +18 -0
  434. package/src/shared/sync/index.ts +9 -0
  435. package/src/shared/sync/typings/conflict-resolution.type.ts +8 -0
  436. package/src/shared/sync/typings/export-entry.interface.ts +13 -0
  437. package/src/shared/sync/typings/export-options.interface.ts +9 -0
  438. package/src/shared/sync/typings/import-options.interface.ts +7 -0
  439. package/src/shared/sync/typings/import-report.interface.ts +15 -0
  440. package/src/shared/wasm-codec/functions/decode-add-section-result.function.ts +112 -0
  441. package/src/shared/wasm-codec/functions/decode-one-recall-result.function.ts +86 -0
  442. package/src/shared/wasm-codec/functions/decode-option-string.function.ts +24 -0
  443. package/src/shared/wasm-codec/functions/decode-recall-document.function.ts +59 -0
  444. package/src/shared/wasm-codec/functions/decode-recall-reference.function.ts +52 -0
  445. package/src/shared/wasm-codec/functions/decode-recall-sibling.function.ts +43 -0
  446. package/src/shared/wasm-codec/functions/decode-scored-results.function.ts +86 -0
  447. package/src/shared/wasm-codec/functions/decode-section-match.function.ts +80 -0
  448. package/src/shared/wasm-codec/functions/decode-section-record-trailing.function.ts +75 -0
  449. package/src/shared/wasm-codec/functions/decode-section-record.function.ts +85 -0
  450. package/src/shared/wasm-codec/functions/decode-section-records.function.ts +87 -0
  451. package/src/shared/wasm-codec/functions/decode-section-type.function.ts +30 -0
  452. package/src/shared/wasm-codec/functions/decode-wasm-list.function.ts +31 -0
  453. package/src/shared/wasm-codec/functions/encode-add-section-params.function.ts +68 -0
  454. package/src/shared/wasm-codec/index.ts +5 -0
  455. package/src/shared/wasm-codec/typings/add-section-input.model.ts +45 -0
  456. package/src/shared/wasm-codec/typings/add-section-result.model.ts +28 -0
  457. package/src/shared/wasm-codec/typings/document-manifest.model.ts +20 -0
  458. package/src/shared/wasm-codec/typings/document-section.model.ts +12 -0
  459. package/src/shared/wasm-codec/typings/item-decoder.type.ts +10 -0
  460. package/src/shared/wasm-codec/typings/near-duplicate.model.ts +16 -0
  461. package/src/shared/wasm-codec/typings/paged-search-result.model.ts +22 -0
  462. package/src/shared/wasm-codec/typings/section-match.model.ts +31 -0
  463. package/src/shared/wasm-codec/typings/section-record-trailing.model.ts +38 -0
  464. package/src/shared/wasm-codec/typings/section-record.model.ts +66 -0
  465. package/src/shared/wasm-codec/typings/section-type-result.model.ts +12 -0
  466. package/src/shared/worker-client/classes/worker-client.class.ts +19 -0
  467. package/src/shared/worker-client/functions/handle-ipc-data.function.ts +49 -0
  468. package/src/shared/worker-client/functions/send-ipc-request.function.ts +39 -0
  469. package/src/shared/worker-client/index.ts +4 -1
  470. package/src/shared/worker-client/typings/add-section-result.model.ts +32 -15
  471. package/src/shared/worker-client/typings/export-result.model.ts +14 -0
  472. package/src/shared/worker-client/typings/gc-result.model.ts +6 -0
  473. package/src/shared/worker-client/typings/json-rpc-response.interface.ts +17 -0
  474. package/src/shared/worker-client/typings/pending-call.interface.ts +7 -0
  475. package/src/shared/worker-client/typings/recall-document.model.ts +16 -0
  476. package/src/shared/worker-client/typings/recall-params.model.ts +15 -0
  477. package/src/shared/worker-client/typings/recall-reference.model.ts +32 -0
  478. package/src/shared/worker-client/typings/recall-sibling.model.ts +11 -0
  479. package/src/shared/worker-client/typings/recall-single-result.model.ts +41 -0
  480. package/src/shared/worker-client/typings/search-result.model.ts +12 -0
  481. package/src/shared/worker-client/typings/section.model.ts +16 -0
  482. package/src/shared/worker-daemon/classes/ipc-error.class.ts +22 -0
  483. package/src/shared/worker-daemon/classes/worker-daemon.class.ts +315 -46
  484. package/src/shared/worker-daemon/constants/wasm-method-map.constant.ts +69 -0
  485. package/src/shared/worker-daemon/functions/build-ipc-error-response.function.ts +16 -0
  486. package/src/shared/worker-daemon/functions/check-catalog-version.function.ts +54 -0
  487. package/src/shared/worker-daemon/functions/check-preconditions.function.ts +28 -0
  488. package/src/shared/worker-daemon/functions/create-host-imports.function.ts +19 -4
  489. package/src/shared/worker-daemon/functions/create-ipc-server.function.ts +5 -1
  490. package/src/shared/worker-daemon/functions/detect-stale-pid.function.ts +33 -0
  491. package/src/shared/worker-daemon/functions/dispatch-request.function.ts +190 -0
  492. package/src/shared/worker-daemon/functions/handle-check-version.function.ts +74 -0
  493. package/src/shared/worker-daemon/functions/handle-config-method.function.ts +27 -0
  494. package/src/shared/worker-daemon/functions/handle-read-ops.function.ts +236 -0
  495. package/src/shared/worker-daemon/functions/handle-write-ops.function.ts +257 -0
  496. package/src/shared/worker-daemon/functions/parse-auto-capture-section.function.ts +51 -0
  497. package/src/shared/worker-daemon/functions/parse-catalog-version.function.ts +20 -0
  498. package/src/shared/worker-daemon/functions/parse-embedding-section.function.ts +38 -0
  499. package/src/shared/worker-daemon/functions/parse-worker-toml.function.ts +104 -0
  500. package/src/shared/worker-daemon/functions/run-startup-integrity-check.function.ts +55 -0
  501. package/src/shared/worker-daemon/functions/scan-near-duplicates.function.ts +92 -0
  502. package/src/shared/worker-daemon/functions/wasm-bridge.function.ts +144 -0
  503. package/src/shared/worker-daemon/functions/wasm-memory-helpers.function.ts +41 -0
  504. package/src/shared/worker-daemon/functions/write-lock.function.ts +49 -0
  505. package/src/shared/worker-daemon/typings/allocator-ref.interface.ts +16 -0
  506. package/src/shared/worker-daemon/typings/daemon-config.interface.ts +7 -0
  507. package/src/shared/worker-daemon/typings/fs-adapter.interface.ts +22 -0
  508. package/src/shared/worker-daemon/typings/handler-context.interface.ts +19 -0
  509. package/src/shared/worker-daemon/typings/memory-ref.interface.ts +13 -0
  510. package/src/shared/worker-daemon/typings/wasm-fn.type.ts +2 -0
  511. package/src/shared/worker-daemon/typings/write-lock.interface.ts +13 -0
  512. package/src/wasm/fs-database/kbdb_fs_database.d.ts +22 -1
  513. package/src/wasm/fs-database/kbdb_fs_database.js +28 -1
  514. package/src/wasm/fs-database/kbdb_fs_database_bg.wasm +0 -0
  515. package/src/wasm/fs-database/kbdb_fs_database_bg.wasm.d.ts +1 -0
  516. package/src/wasm/kb-worker/kbdb_worker.d.ts +48 -1
  517. package/src/wasm/kb-worker/kbdb_worker.js +60 -1
  518. package/src/wasm/kb-worker/kbdb_worker_bg.wasm +0 -0
  519. package/src/wasm/kb-worker/kbdb_worker_bg.wasm.d.ts +2 -0
  520. package/src/wasm/query-parser/kbdb_query_parser_bg.wasm +0 -0
@@ -0,0 +1,144 @@
1
+ import type { WasmModules } from '../typings/wasm-modules.interface.ts';
2
+ import type { WasmFn } from '../typings/wasm-fn.type.ts';
3
+ import { IpcError } from '../classes/ipc-error.class.ts';
4
+
5
+ /**
6
+ * Retrieves a named export from the kb-worker WASM instance.
7
+ *
8
+ * @throws {Error} if WASM modules are not yet loaded
9
+ * @throws {Error} if the named export does not exist or is not a
10
+ * function
11
+ */
12
+ export function getWasmExport(
13
+ modules: WasmModules,
14
+ name: string,
15
+ ): WasmFn {
16
+ const fn = modules.kbWorker.exports[name] as WasmFn | undefined;
17
+ if (typeof fn !== 'function') {
18
+ throw new Error(`WASM export not found: ${name}`);
19
+ }
20
+ return fn;
21
+ }
22
+
23
+ /**
24
+ * Allocates `size` bytes in WASM linear memory.
25
+ *
26
+ * Returns `0` when `size` is zero or the allocator export is
27
+ * absent.
28
+ */
29
+ export function wasmAlloc(modules: WasmModules, size: number): number {
30
+ if (size === 0) return 0;
31
+ const allocFn = modules.kbWorker.exports['kbdb_alloc'] as
32
+ | WasmFn
33
+ | undefined;
34
+ if (typeof allocFn !== 'function') return 0;
35
+ return allocFn(size) as number;
36
+ }
37
+
38
+ /**
39
+ * Frees a previously allocated WASM memory region.
40
+ *
41
+ * No-ops when `ptr` or `size` is zero, or when the free export
42
+ * is absent.
43
+ */
44
+ export function wasmFree(
45
+ modules: WasmModules,
46
+ ptr: number,
47
+ size: number,
48
+ ): void {
49
+ if (ptr === 0 || size === 0) return;
50
+ const freeFn = modules.kbWorker.exports['kbdb_free'] as
51
+ | WasmFn
52
+ | undefined;
53
+ if (typeof freeFn === 'function') {
54
+ freeFn(ptr, size);
55
+ }
56
+ }
57
+
58
+ /**
59
+ * Writes `data` into WASM linear memory at `ptr`.
60
+ *
61
+ * @throws {Error} if the write would exceed memory bounds
62
+ */
63
+ export function wasmWrite(
64
+ modules: WasmModules,
65
+ ptr: number,
66
+ data: Uint8Array,
67
+ ): void {
68
+ if (data.length === 0) return;
69
+ const memView = new Uint8Array(modules.memory.buffer);
70
+ if (ptr + data.length > memView.length) {
71
+ throw new Error('WASM memory overflow');
72
+ }
73
+ memView.set(data, ptr);
74
+ }
75
+
76
+ /**
77
+ * Reads the WASM return slot, frees the underlying buffer, and
78
+ * returns its contents as a `Uint8Array`.
79
+ *
80
+ * Returns an empty array when the slot is unset or memory is
81
+ * unavailable.
82
+ */
83
+ export function readReturnSlot(modules: WasmModules): Uint8Array {
84
+ const getPtrFn = modules.kbWorker.exports['get_return_ptr'] as
85
+ | WasmFn
86
+ | undefined;
87
+ const getLenFn = modules.kbWorker.exports['get_return_len'] as
88
+ | WasmFn
89
+ | undefined;
90
+ if (
91
+ typeof getPtrFn !== 'function' ||
92
+ typeof getLenFn !== 'function'
93
+ ) {
94
+ return new Uint8Array(0);
95
+ }
96
+ const ptr = getPtrFn() as number;
97
+ const len = getLenFn() as number;
98
+ if (ptr === 0 || len === 0) return new Uint8Array(0);
99
+ const data = new Uint8Array(modules.memory.buffer, ptr, len).slice();
100
+ wasmFree(modules, ptr, len);
101
+ return data;
102
+ }
103
+
104
+ /**
105
+ * Calls a WASM export with binary-encoded input via the
106
+ * alloc/write/call/read/free protocol.
107
+ *
108
+ * @throws {IpcError} when the export returns `-1` (error sentinel)
109
+ */
110
+ export function callWasmSync(
111
+ modules: WasmModules,
112
+ exportName: string,
113
+ input: Uint8Array,
114
+ ): Uint8Array {
115
+ const fn = getWasmExport(modules, exportName);
116
+ const ptr = wasmAlloc(modules, input.length);
117
+ wasmWrite(modules, ptr, input);
118
+ const rc = fn(ptr, input.length) as number;
119
+ wasmFree(modules, ptr, input.length);
120
+ if (rc === -1) {
121
+ const errBytes = readReturnSlot(modules);
122
+ const errMsg = new TextDecoder().decode(errBytes);
123
+ throw new IpcError(-32000, errMsg || exportName + ' failed');
124
+ }
125
+ return readReturnSlot(modules);
126
+ }
127
+
128
+ /**
129
+ * Calls a zero-argument WASM export and checks its return code.
130
+ *
131
+ * @throws {IpcError} when the export returns `-1` (error sentinel)
132
+ */
133
+ export function callWasmZeroArg(
134
+ modules: WasmModules,
135
+ exportName: string,
136
+ ): void {
137
+ const fn = getWasmExport(modules, exportName);
138
+ const rc = fn() as number;
139
+ if (rc === -1) {
140
+ const errBytes = readReturnSlot(modules);
141
+ const errMsg = new TextDecoder().decode(errBytes);
142
+ throw new IpcError(-32000, errMsg || exportName + ' failed');
143
+ }
144
+ }
@@ -0,0 +1,41 @@
1
+ import { join } from 'node:path';
2
+ import type { MemoryRef } from '../typings/memory-ref.interface.ts';
3
+
4
+ /**
5
+ * Returns the current `ArrayBuffer` backing WASM linear memory.
6
+ *
7
+ * Must be called after WASM module instantiation. The buffer
8
+ * reference may change after WASM memory growth, so callers
9
+ * should call this function each time they need a fresh view.
10
+ *
11
+ * @param memoryRef - deferred reference to WASM linear memory
12
+ * @throws {Error} when memory is not yet initialised
13
+ */
14
+ export function getWasmBuffer(memoryRef: MemoryRef): ArrayBuffer {
15
+ if (!memoryRef.memory) {
16
+ throw new Error('WASM memory not initialized');
17
+ }
18
+ // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
19
+ return memoryRef.memory.buffer as ArrayBuffer;
20
+ }
21
+
22
+ /**
23
+ * Decodes a UTF-8 path from WASM linear memory and resolves it
24
+ * relative to `contextPath` when the path is not absolute.
25
+ *
26
+ * @param memoryRef - deferred reference to WASM linear memory
27
+ * @param contextPath - base directory for relative paths
28
+ * @param ptr - byte offset of the path string in WASM memory
29
+ * @param len - byte length of the path string
30
+ */
31
+ export function readWasmPathArg(
32
+ memoryRef: MemoryRef,
33
+ contextPath: string,
34
+ ptr: number,
35
+ len: number,
36
+ ): string {
37
+ const bytes = new Uint8Array(getWasmBuffer(memoryRef), ptr, len);
38
+ const decoded = new TextDecoder().decode(bytes);
39
+ if (decoded.startsWith('/')) return decoded;
40
+ return join(contextPath, decoded);
41
+ }
@@ -0,0 +1,49 @@
1
+ import type { WriteLockState } from '../typings/write-lock.interface.ts';
2
+
3
+ /**
4
+ * Acquires the single-writer lock.
5
+ *
6
+ * Enforces the single-writer guarantee: at most one write
7
+ * operation runs at a time inside the daemon. Concurrent writes
8
+ * are serialized through an in-memory FIFO queue -- each caller
9
+ * awaits this function and proceeds only when it is at the head
10
+ * of the queue. Read operations bypass this lock entirely and
11
+ * may proceed concurrently with writes and with each other.
12
+ *
13
+ * Crash recovery: the lock is purely in-memory. If the daemon
14
+ * process crashes mid-write, the OS reclaims process memory,
15
+ * releasing the lock automatically. The WASM engine is
16
+ * responsible for leaving on-disk state consistent (it uses
17
+ * atomic rename: write to a `.tmp` file, then `host_rename` to
18
+ * the final path).
19
+ *
20
+ * @param state - shared write-lock state
21
+ */
22
+ export function acquireWriteLock(state: WriteLockState): Promise<void> {
23
+ if (!state.locked) {
24
+ state.locked = true;
25
+ return Promise.resolve();
26
+ }
27
+ return new Promise<void>((resolve) => {
28
+ state.queue.push({ resolve });
29
+ });
30
+ }
31
+
32
+ /**
33
+ * Releases the single-writer lock.
34
+ *
35
+ * Grants the lock to the next queued waiter if one exists;
36
+ * otherwise marks the lock as free. Must always be called in a
37
+ * `finally` block after `acquireWriteLock` to prevent permanent
38
+ * lock starvation.
39
+ *
40
+ * @param state - shared write-lock state
41
+ */
42
+ export function releaseWriteLock(state: WriteLockState): void {
43
+ const next = state.queue.shift();
44
+ if (next !== undefined) {
45
+ next.resolve();
46
+ } else {
47
+ state.locked = false;
48
+ }
49
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * A mutable reference to the WASM allocator function.
3
+ *
4
+ * The `alloc` field starts as `null` and is wired up after the
5
+ * `kb-worker` WASM module is instantiated. Host import functions
6
+ * that must allocate memory in WASM linear memory check this
7
+ * reference before proceeding and return `-1` when it is null.
8
+ */
9
+ export interface AllocatorRef {
10
+ /**
11
+ * Allocates `size` bytes in WASM linear memory and returns the
12
+ * byte offset of the allocated region, or `null` when the
13
+ * allocator is not yet available.
14
+ */
15
+ alloc: ((size: number) => number) | null;
16
+ }
@@ -1,3 +1,6 @@
1
+ import type { EmbeddingConfig } from '../../embedding/typings/embedding-config.interface.ts';
2
+ import type { AutoCaptureConfig } from '../../auto-capture/typings/auto-capture-config.interface.ts';
3
+
1
4
  /** Configuration for the worker daemon process. */
2
5
  export interface DaemonConfig {
3
6
  /** Absolute path to the knowledge-base context directory. */
@@ -10,4 +13,8 @@ export interface DaemonConfig {
10
13
  readonly timeoutMs: number;
11
14
  /** Time-to-live in milliseconds for each cached item. */
12
15
  readonly itemTtlMs: number;
16
+ /** Embedding provider configuration. */
17
+ readonly embedding?: EmbeddingConfig;
18
+ /** Auto-capture behaviour configuration. */
19
+ readonly autoCapture?: AutoCaptureConfig;
13
20
  }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Minimal filesystem operations required by the WASM host imports.
3
+ *
4
+ * The default implementation delegates to `node:fs` synchronous
5
+ * APIs. Tests inject a stub to avoid touching the real filesystem.
6
+ */
7
+ export interface FsAdapter {
8
+ /** Read entire file as a Buffer. */
9
+ readFileSync(path: string): Buffer;
10
+ /** Write data buffer to file. */
11
+ writeFileSync(path: string, data: Uint8Array): void;
12
+ /** Rename `oldPath` to `newPath`. */
13
+ renameSync(oldPath: string, newPath: string): void;
14
+ /** Delete a file. */
15
+ unlinkSync(path: string): void;
16
+ /** List directory entries as strings. */
17
+ readdirSync(path: string): string[];
18
+ /** Create a directory (and parents) recursively. */
19
+ mkdirSync(path: string): void;
20
+ /** Return true if the path exists. */
21
+ existsSync(path: string): boolean;
22
+ }
@@ -0,0 +1,19 @@
1
+ import type { DaemonConfig } from './daemon-config.interface.ts';
2
+ import type { WasmModules } from './wasm-modules.interface.ts';
3
+
4
+ /**
5
+ * Runtime context passed to all IPC request handler functions.
6
+ *
7
+ * Groups the minimal shared state needed by every request handler
8
+ * so that handler functions can be standalone (not methods on a
9
+ * class) while still accessing WASM modules, configuration, and
10
+ * the database directory path.
11
+ */
12
+ export interface HandlerContext {
13
+ /** Absolute path to the `.kbdb` directory. */
14
+ readonly targetDir: string;
15
+ /** Parsed daemon configuration from `worker.toml`. */
16
+ readonly config: DaemonConfig;
17
+ /** Loaded WASM module instances. */
18
+ readonly modules: WasmModules;
19
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * A mutable reference to the WASM linear memory.
3
+ *
4
+ * The `memory` field starts as `null` and is wired up after the
5
+ * `kb-worker` WASM module is instantiated (the module exports its
6
+ * own memory rather than importing one). Host import functions
7
+ * read `memory` at call time, not at creation time, so the ref
8
+ * can be populated after the import record is built.
9
+ */
10
+ export interface MemoryRef {
11
+ /** WASM linear memory; `null` until the module is instantiated. */
12
+ memory: WebAssembly.Memory | null;
13
+ }
@@ -0,0 +1,2 @@
1
+ /** Callable WASM export function signature. */
2
+ export type WasmFn = (...args: unknown[]) => unknown;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Mutable state for the single-writer lock used by WorkerDaemon.
3
+ *
4
+ * Holds the current lock flag and the queue of pending waiters.
5
+ * Both fields are mutated by `acquireWriteLock` and
6
+ * `releaseWriteLock`.
7
+ */
8
+ export interface WriteLockState {
9
+ /** Whether the write lock is currently held. */
10
+ locked: boolean;
11
+ /** Queue of resolve callbacks for pending lock waiters. */
12
+ queue: { resolve: () => void }[];
13
+ }
@@ -5,7 +5,10 @@ declare namespace wasm_bindgen {
5
5
  /**
6
6
  * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
7
7
  *
8
- * On success: writes encoded kbid string to return slot, returns 0.
8
+ * On success: writes an encoded `AddSectionResult` to the return slot and
9
+ * returns 0. When `params.replace` is true and a section with the same
10
+ * `source_key` exists, the superseded section's index entries are removed
11
+ * and the returned `AddSectionResult.superseded` is set to its kbid.
9
12
  * On error: writes error message to return slot, returns -1.
10
13
  */
11
14
  export function db_add_section(ptr: number, len: number): number;
@@ -42,6 +45,23 @@ declare namespace wasm_bindgen {
42
45
  */
43
46
  export function db_check_version(ptr: number, len: number): number;
44
47
 
48
+ /**
49
+ * Exports the database to a target directory.
50
+ *
51
+ * `ptr`/`len` point to a UTF-8 string containing the target path.
52
+ *
53
+ * Copies `sections/`, `documents/`, and `catalog.toml` to the target.
54
+ * Indexes are not copied because they can be rebuilt from the data.
55
+ *
56
+ * The target path may be absolute or relative. It is an external output
57
+ * destination, not a database-internal path, so no path validation is
58
+ * applied to it.
59
+ *
60
+ * On success a summary string is placed in the return slot:
61
+ * `path={target}\nsections_exported={N}\ndocuments_exported={M}`
62
+ */
63
+ export function db_export(ptr: number, len: number): number;
64
+
45
65
  /**
46
66
  * Runs garbage collection. Returns 0 on success.
47
67
  * On success a summary string is placed in the return slot.
@@ -200,6 +220,7 @@ declare interface InitOutput {
200
220
  readonly db_add_to_index: (a: number, b: number) => number;
201
221
  readonly db_check_integrity: (a: number, b: number) => number;
202
222
  readonly db_check_version: (a: number, b: number) => number;
223
+ readonly db_export: (a: number, b: number) => number;
203
224
  readonly db_gc: (a: number, b: number) => number;
204
225
  readonly db_get_back_refs: (a: number, b: number) => number;
205
226
  readonly db_get_forward_refs: (a: number, b: number) => number;
@@ -7,7 +7,10 @@ let wasm_bindgen = (function(exports) {
7
7
  /**
8
8
  * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
9
9
  *
10
- * On success: writes encoded kbid string to return slot, returns 0.
10
+ * On success: writes an encoded `AddSectionResult` to the return slot and
11
+ * returns 0. When `params.replace` is true and a section with the same
12
+ * `source_key` exists, the superseded section's index entries are removed
13
+ * and the returned `AddSectionResult.superseded` is set to its kbid.
11
14
  * On error: writes error message to return slot, returns -1.
12
15
  * @param {number} ptr
13
16
  * @param {number} len
@@ -72,6 +75,30 @@ let wasm_bindgen = (function(exports) {
72
75
  }
73
76
  exports.db_check_version = db_check_version;
74
77
 
78
+ /**
79
+ * Exports the database to a target directory.
80
+ *
81
+ * `ptr`/`len` point to a UTF-8 string containing the target path.
82
+ *
83
+ * Copies `sections/`, `documents/`, and `catalog.toml` to the target.
84
+ * Indexes are not copied because they can be rebuilt from the data.
85
+ *
86
+ * The target path may be absolute or relative. It is an external output
87
+ * destination, not a database-internal path, so no path validation is
88
+ * applied to it.
89
+ *
90
+ * On success a summary string is placed in the return slot:
91
+ * `path={target}\nsections_exported={N}\ndocuments_exported={M}`
92
+ * @param {number} ptr
93
+ * @param {number} len
94
+ * @returns {number}
95
+ */
96
+ function db_export(ptr, len) {
97
+ const ret = wasm.db_export(ptr, len);
98
+ return ret;
99
+ }
100
+ exports.db_export = db_export;
101
+
75
102
  /**
76
103
  * Runs garbage collection. Returns 0 on success.
77
104
  * On success a summary string is placed in the return slot.
@@ -7,6 +7,7 @@ export const db_add_section: (a: number, b: number) => number;
7
7
  export const db_add_to_index: (a: number, b: number) => number;
8
8
  export const db_check_integrity: (a: number, b: number) => number;
9
9
  export const db_check_version: (a: number, b: number) => number;
10
+ export const db_export: (a: number, b: number) => number;
10
11
  export const db_gc: (a: number, b: number) => number;
11
12
  export const db_get_back_refs: (a: number, b: number) => number;
12
13
  export const db_get_forward_refs: (a: number, b: number) => number;
@@ -5,7 +5,10 @@ declare namespace wasm_bindgen {
5
5
  /**
6
6
  * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
7
7
  *
8
- * On success: writes encoded kbid string to return slot, returns 0.
8
+ * On success: writes an encoded `AddSectionResult` to the return slot and
9
+ * returns 0. When `params.replace` is true and a section with the same
10
+ * `source_key` exists, the superseded section's index entries are removed
11
+ * and the returned `AddSectionResult.superseded` is set to its kbid.
9
12
  * On error: writes error message to return slot, returns -1.
10
13
  */
11
14
  export function db_add_section(ptr: number, len: number): number;
@@ -42,6 +45,23 @@ declare namespace wasm_bindgen {
42
45
  */
43
46
  export function db_check_version(ptr: number, len: number): number;
44
47
 
48
+ /**
49
+ * Exports the database to a target directory.
50
+ *
51
+ * `ptr`/`len` point to a UTF-8 string containing the target path.
52
+ *
53
+ * Copies `sections/`, `documents/`, and `catalog.toml` to the target.
54
+ * Indexes are not copied because they can be rebuilt from the data.
55
+ *
56
+ * The target path may be absolute or relative. It is an external output
57
+ * destination, not a database-internal path, so no path validation is
58
+ * applied to it.
59
+ *
60
+ * On success a summary string is placed in the return slot:
61
+ * `path={target}\nsections_exported={N}\ndocuments_exported={M}`
62
+ */
63
+ export function db_export(ptr: number, len: number): number;
64
+
45
65
  /**
46
66
  * Runs garbage collection. Returns 0 on success.
47
67
  * On success a summary string is placed in the return slot.
@@ -344,6 +364,10 @@ declare namespace wasm_bindgen {
344
364
 
345
365
  /**
346
366
  * Adds a section. Returns 0 on success, -1 on error.
367
+ *
368
+ * On success the return slot holds the binary-encoded `AddSectionResult`
369
+ * (kbid + indexed_terms_count + elapsed_ms + superseded + warnings +
370
+ * near_duplicates) using the `Encode` trait wire format.
347
371
  */
348
372
  export function worker_add_section(ptr: number, len: number): number;
349
373
 
@@ -365,6 +389,19 @@ declare namespace wasm_bindgen {
365
389
  */
366
390
  export function worker_compose(ptr: number, len: number): number;
367
391
 
392
+ /**
393
+ * Exports the database to a target directory.
394
+ *
395
+ * `ptr`/`len` point to a UTF-8 string containing the target path.
396
+ *
397
+ * Delegates directly to `db_export` in `kbdb-fs-database`. Does not require
398
+ * the worker to have been initialised because the target path is given
399
+ * explicitly by the caller.
400
+ *
401
+ * Returns 0 on success, -1 on error (message in return slot).
402
+ */
403
+ export function worker_export(ptr: number, len: number): number;
404
+
368
405
  /**
369
406
  * Runs garbage collection and invalidates all cache entries.
370
407
  *
@@ -444,6 +481,14 @@ declare namespace wasm_bindgen {
444
481
 
445
482
  /**
446
483
  * Rebuilds all database indexes.
484
+ *
485
+ * First clears the existing inverted, positional, and reference indexes via
486
+ * `db_rebuild_index`. Then re-tokenizes every stored section and re-populates
487
+ * the indexes via `rebuild_all_section_indexes`.
488
+ *
489
+ * On success the return slot holds the number of reindexed sections as a
490
+ * little-endian `u32`, and 0 is returned. On error -1 is returned and an
491
+ * error message is in the return slot.
447
492
  */
448
493
  export function worker_rebuild_indexes(): number;
449
494
 
@@ -525,6 +570,7 @@ declare interface InitOutput {
525
570
  readonly worker_add_section: (a: number, b: number) => number;
526
571
  readonly worker_check_integrity: () => number;
527
572
  readonly worker_compose: (a: number, b: number) => number;
573
+ readonly worker_export: (a: number, b: number) => number;
528
574
  readonly worker_garbage_collect: () => number;
529
575
  readonly worker_get_result: (a: number) => number;
530
576
  readonly worker_group_sections: (a: number, b: number) => number;
@@ -565,6 +611,7 @@ declare interface InitOutput {
565
611
  readonly db_add_to_index: (a: number, b: number) => number;
566
612
  readonly db_check_integrity: (a: number, b: number) => number;
567
613
  readonly db_check_version: (a: number, b: number) => number;
614
+ readonly db_export: (a: number, b: number) => number;
568
615
  readonly db_gc: (a: number, b: number) => number;
569
616
  readonly db_get_back_refs: (a: number, b: number) => number;
570
617
  readonly db_get_forward_refs: (a: number, b: number) => number;
@@ -7,7 +7,10 @@ let wasm_bindgen = (function(exports) {
7
7
  /**
8
8
  * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
9
9
  *
10
- * On success: writes encoded kbid string to return slot, returns 0.
10
+ * On success: writes an encoded `AddSectionResult` to the return slot and
11
+ * returns 0. When `params.replace` is true and a section with the same
12
+ * `source_key` exists, the superseded section's index entries are removed
13
+ * and the returned `AddSectionResult.superseded` is set to its kbid.
11
14
  * On error: writes error message to return slot, returns -1.
12
15
  * @param {number} ptr
13
16
  * @param {number} len
@@ -72,6 +75,30 @@ let wasm_bindgen = (function(exports) {
72
75
  }
73
76
  exports.db_check_version = db_check_version;
74
77
 
78
+ /**
79
+ * Exports the database to a target directory.
80
+ *
81
+ * `ptr`/`len` point to a UTF-8 string containing the target path.
82
+ *
83
+ * Copies `sections/`, `documents/`, and `catalog.toml` to the target.
84
+ * Indexes are not copied because they can be rebuilt from the data.
85
+ *
86
+ * The target path may be absolute or relative. It is an external output
87
+ * destination, not a database-internal path, so no path validation is
88
+ * applied to it.
89
+ *
90
+ * On success a summary string is placed in the return slot:
91
+ * `path={target}\nsections_exported={N}\ndocuments_exported={M}`
92
+ * @param {number} ptr
93
+ * @param {number} len
94
+ * @returns {number}
95
+ */
96
+ function db_export(ptr, len) {
97
+ const ret = wasm.db_export(ptr, len);
98
+ return ret;
99
+ }
100
+ exports.db_export = db_export;
101
+
75
102
  /**
76
103
  * Runs garbage collection. Returns 0 on success.
77
104
  * On success a summary string is placed in the return slot.
@@ -644,6 +671,10 @@ let wasm_bindgen = (function(exports) {
644
671
 
645
672
  /**
646
673
  * Adds a section. Returns 0 on success, -1 on error.
674
+ *
675
+ * On success the return slot holds the binary-encoded `AddSectionResult`
676
+ * (kbid + indexed_terms_count + elapsed_ms + superseded + warnings +
677
+ * near_duplicates) using the `Encode` trait wire format.
647
678
  * @param {number} ptr
648
679
  * @param {number} len
649
680
  * @returns {number}
@@ -684,6 +715,26 @@ let wasm_bindgen = (function(exports) {
684
715
  }
685
716
  exports.worker_compose = worker_compose;
686
717
 
718
+ /**
719
+ * Exports the database to a target directory.
720
+ *
721
+ * `ptr`/`len` point to a UTF-8 string containing the target path.
722
+ *
723
+ * Delegates directly to `db_export` in `kbdb-fs-database`. Does not require
724
+ * the worker to have been initialised because the target path is given
725
+ * explicitly by the caller.
726
+ *
727
+ * Returns 0 on success, -1 on error (message in return slot).
728
+ * @param {number} ptr
729
+ * @param {number} len
730
+ * @returns {number}
731
+ */
732
+ function worker_export(ptr, len) {
733
+ const ret = wasm.worker_export(ptr, len);
734
+ return ret;
735
+ }
736
+ exports.worker_export = worker_export;
737
+
687
738
  /**
688
739
  * Runs garbage collection and invalidates all cache entries.
689
740
  *
@@ -835,6 +886,14 @@ let wasm_bindgen = (function(exports) {
835
886
 
836
887
  /**
837
888
  * Rebuilds all database indexes.
889
+ *
890
+ * First clears the existing inverted, positional, and reference indexes via
891
+ * `db_rebuild_index`. Then re-tokenizes every stored section and re-populates
892
+ * the indexes via `rebuild_all_section_indexes`.
893
+ *
894
+ * On success the return slot holds the number of reindexed sections as a
895
+ * little-endian `u32`, and 0 is returned. On error -1 is returned and an
896
+ * error message is in the return slot.
838
897
  * @returns {number}
839
898
  */
840
899
  function worker_rebuild_indexes() {
@@ -8,6 +8,7 @@ export const set_return: (a: number, b: number) => void;
8
8
  export const worker_add_section: (a: number, b: number) => number;
9
9
  export const worker_check_integrity: () => number;
10
10
  export const worker_compose: (a: number, b: number) => number;
11
+ export const worker_export: (a: number, b: number) => number;
11
12
  export const worker_garbage_collect: () => number;
12
13
  export const worker_get_result: (a: number) => number;
13
14
  export const worker_group_sections: (a: number, b: number) => number;
@@ -48,6 +49,7 @@ export const db_add_section: (a: number, b: number) => number;
48
49
  export const db_add_to_index: (a: number, b: number) => number;
49
50
  export const db_check_integrity: (a: number, b: number) => number;
50
51
  export const db_check_version: (a: number, b: number) => number;
52
+ export const db_export: (a: number, b: number) => number;
51
53
  export const db_gc: (a: number, b: number) => number;
52
54
  export const db_get_back_refs: (a: number, b: number) => number;
53
55
  export const db_get_forward_refs: (a: number, b: number) => number;