mlx-bun 0.0.13 → 0.3.0

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 (427) hide show
  1. package/README.md +71 -578
  2. package/bin/mlx-bun.mjs +1 -1
  3. package/docs/README.md +91 -0
  4. package/docs/{design → archive}/hlg-sampling.md +3 -3
  5. package/docs/{design → archive/investigations}/audio-input-plan.md +4 -4
  6. package/docs/{design → archive/investigations}/colibri-glm52-port.md +1 -1
  7. package/docs/{design → archive/investigations}/diffusion-gemma-port.md +3 -3
  8. package/docs/{design → archive/investigations}/faithful-l1-consolidation.md +4 -4
  9. package/docs/{investigations → archive/investigations}/hlg-sampling-investigation.md +1 -1
  10. package/docs/{design → archive/investigations}/minicpm5-decode-megakernel.md +11 -11
  11. package/docs/{design → archive/investigations}/optimization_plan.md +1 -1
  12. package/docs/archive/investigations/pareto-specialized-runtime-findings.md +92 -0
  13. package/docs/{design → archive/investigations}/pre-colibri-stabilization.md +5 -5
  14. package/docs/{design → archive/investigations}/the-dreaming-handoff.md +2 -2
  15. package/docs/{planning → archive/planning}/chat-ui-vision.md +1 -1
  16. package/docs/{planning → archive/planning}/chunk-task-roadmap.md +1 -1
  17. package/docs/{planning → archive/planning}/curve-sampler-research-plan.md +4 -4
  18. package/docs/{planning → archive/planning}/memory-docs-and-dag-plan.md +1 -1
  19. package/docs/{planning → archive/planning}/release-notes-v0.0.9.md +1 -1
  20. package/docs/archive/planning/release-notes-v0.2.0.md +49 -0
  21. package/docs/{planning → archive/planning}/website-readme-pass-plan.md +1 -1
  22. package/docs/design/batching.md +569 -0
  23. package/docs/design/decode-speed-program.md +3178 -169
  24. package/docs/design/dreaming-nightly-pipeline.md +675 -282
  25. package/docs/design/generic-model-support.md +579 -334
  26. package/docs/design/kv-cache.md +680 -0
  27. package/docs/design/orpo-training.md +673 -1239
  28. package/docs/design/speculative-decoding.md +1627 -0
  29. package/docs/design/turboquant.md +2102 -0
  30. package/docs/design/unified-engine-frontier-plan.md +1831 -727
  31. package/docs/design/web-chat-redesign.md +666 -1083
  32. package/docs/planning/PRODUCT_ROADMAP.md +34 -1
  33. package/docs/planning/release-notes-v0.3.0.md +35 -0
  34. package/docs/planning/video-series.md +421 -0
  35. package/docs/reference/benchmarks.md +1162 -0
  36. package/docs/reference/cli.md +395 -149
  37. package/docs/reference/distribution.md +321 -181
  38. package/docs/reference/environment.md +348 -0
  39. package/docs/reference/glossary.md +39 -0
  40. package/docs/reference/library-api.md +580 -142
  41. package/docs/reference/memory.md +227 -64
  42. package/docs/reference/models.md +137 -6
  43. package/docs/reference/server-api.md +938 -422
  44. package/docs/reference/server-config.md +652 -320
  45. package/docs/reference/training.md +393 -254
  46. package/docs/reference/troubleshooting.md +166 -0
  47. package/package.json +10 -5
  48. package/src/admission-plan.ts +18 -0
  49. package/src/anthropic.ts +92 -3
  50. package/src/audio/decode.ts +2 -2
  51. package/src/audio/features.ts +2 -2
  52. package/src/backends/mlx/autoregressive.ts +108 -0
  53. package/src/backends/mlx/batch-group.ts +1646 -0
  54. package/src/backends/mlx/diffusion.ts +39 -0
  55. package/src/backends/mlx/draft-target.ts +47 -0
  56. package/src/backends/mlx/evaluation.ts +105 -0
  57. package/src/backends/mlx/fill-append.ts +45 -0
  58. package/src/backends/mlx/gateway-binding.ts +71 -0
  59. package/src/backends/mlx/graph.ts +38 -0
  60. package/src/backends/mlx/memory-client.ts +189 -0
  61. package/src/backends/mlx/memory-guard.ts +40 -0
  62. package/src/backends/mlx/methods.ts +90 -0
  63. package/src/backends/mlx/model-prompt.ts +164 -0
  64. package/src/backends/mlx/model-serving.ts +79 -0
  65. package/src/backends/mlx/prefill.ts +33 -0
  66. package/src/backends/mlx/request-policy.ts +20 -0
  67. package/src/backends/mlx/rollback.ts +51 -0
  68. package/src/backends/mlx/serial-executor.ts +273 -0
  69. package/src/backends/mlx/speculative.ts +114 -0
  70. package/src/backends/mlx/state-views.ts +26 -0
  71. package/src/backends/mlx/text-engine.ts +73 -0
  72. package/src/cli.ts +189 -61
  73. package/src/client.ts +66 -0
  74. package/src/config.ts +21 -4
  75. package/src/contracts/completion.ts +16 -0
  76. package/src/contracts/execution.ts +49 -0
  77. package/src/contracts/generation.ts +103 -0
  78. package/src/contracts/host.ts +7 -0
  79. package/src/contracts/jobs.ts +66 -0
  80. package/src/contracts/pi-provider.ts +30 -0
  81. package/src/contracts/pi.ts +259 -0
  82. package/src/contracts/resources.ts +18 -0
  83. package/src/contracts/scheduling.ts +27 -0
  84. package/src/contracts/tsconfig.json +14 -0
  85. package/src/diffusion/diffusion-generate.ts +218 -153
  86. package/src/embed.ts +1 -1
  87. package/src/engine/admission.ts +59 -0
  88. package/src/engine/cancellation.ts +38 -0
  89. package/src/engine/engine.ts +56 -0
  90. package/src/engine/execution-coordinator.ts +70 -0
  91. package/src/engine/execution-plan.ts +51 -0
  92. package/src/engine/resources.ts +42 -0
  93. package/src/engine/scheduler.ts +67 -0
  94. package/src/engine/session.ts +247 -0
  95. package/src/eval/README.md +44 -1
  96. package/src/eval/kl.ts +263 -23
  97. package/src/eval/reference-logits.ts +207 -0
  98. package/src/eval/runner.ts +10 -79
  99. package/src/eval/tasks/bfcl.ts +2 -1
  100. package/src/eval/tasks/gsm8k.ts +2 -1
  101. package/src/eval/tasks/hashhop.ts +2 -1
  102. package/src/eval/tasks/humaneval.ts +5 -4
  103. package/src/eval/tasks/ifeval.ts +2 -1
  104. package/src/eval/tasks/mmlu.ts +2 -1
  105. package/src/expert-io.ts +3 -1
  106. package/src/expert-offload.ts +3 -1
  107. package/src/fill/echo-index.ts +188 -0
  108. package/src/fill/fill-session.ts +452 -0
  109. package/src/fill/proposal.ts +68 -0
  110. package/src/fill/schema-rows.ts +506 -0
  111. package/src/fill/tool-boundary.ts +103 -0
  112. package/src/fit.ts +24 -43
  113. package/src/generate.ts +740 -337
  114. package/src/grammar.ts +14 -8
  115. package/src/harness-pi.ts +15 -34
  116. package/src/hub-rest.ts +4 -4
  117. package/src/index.ts +27 -0
  118. package/src/inference/denoising.ts +17 -0
  119. package/src/inference/graph.ts +33 -0
  120. package/src/inference/prefill.ts +39 -0
  121. package/src/inference/rollback.ts +7 -0
  122. package/src/jobs/db.ts +4 -0
  123. package/src/jobs/index.ts +2 -0
  124. package/src/jobs/job-entry.ts +15 -14
  125. package/src/jobs/runner.ts +98 -13
  126. package/src/jobs/task-client.ts +19 -0
  127. package/src/jobs/types.ts +2 -58
  128. package/src/kv-scheme.ts +199 -0
  129. package/src/kv-store.ts +459 -234
  130. package/src/lab/README.md +18 -0
  131. package/src/{assets → lab/curve}/curve-designer.html +2 -2
  132. package/src/{curve-sampler.ts → lab/curve/curve-sampler.ts} +2 -2
  133. package/src/{expert-trace.ts → lab/expert-trace/expert-trace.ts} +7 -5
  134. package/src/{model → lab/paged-kv}/paged-kv.ts +9 -6
  135. package/src/library.ts +40 -0
  136. package/src/lora.ts +18 -0
  137. package/src/media-fetch.ts +20 -4
  138. package/src/memory/article.ts +1 -1
  139. package/src/memory/chunk.ts +1 -1
  140. package/src/memory/model.ts +32 -170
  141. package/src/memory/prompts.ts +1 -1
  142. package/src/memory/rest.ts +1 -1
  143. package/src/memory/schedule.ts +1 -1
  144. package/src/memory/stages.ts +4 -1
  145. package/src/memory/vault.ts +3 -4
  146. package/src/mlx/array.ts +9 -10
  147. package/src/mlx/compile.ts +12 -2
  148. package/src/mlx/ffi.ts +66 -22
  149. package/src/mlx/materialize.ts +23 -0
  150. package/src/mlx/metal-kernel.ts +10 -11
  151. package/src/mlx/ops.ts +64 -19
  152. package/src/mlx/quantized-rows.ts +36 -0
  153. package/src/mlx/token-bitmask.ts +52 -0
  154. package/src/mlx/turboquant-kv-decode.ts +82 -0
  155. package/src/mlx/turboquant-kv-inverse.ts +122 -0
  156. package/src/mlx/turboquant-ops.ts +33 -3
  157. package/src/mlx/turboquant-tables.ts +2 -2
  158. package/src/model/batched-mask.ts +9 -3
  159. package/src/model/batched-quant.ts +2 -2
  160. package/src/model/batched-rotating-quant.ts +45 -99
  161. package/src/model/batched-rotating-state.ts +73 -0
  162. package/src/model/batched-rotating.ts +57 -106
  163. package/src/model/batched-row-storage.ts +127 -0
  164. package/src/model/compiled-decode.ts +4 -3
  165. package/src/model/diffusion-gemma.ts +8 -8
  166. package/src/model/factory.ts +87 -49
  167. package/src/model/fingerprint.ts +1 -1
  168. package/src/model/flash-attention.ts +3 -3
  169. package/src/model/gemma4-base.ts +187 -17
  170. package/src/model/gemma4.ts +6 -6
  171. package/src/model/generated/gemma4-12b.ts +52 -148
  172. package/src/model/generated/gemma4-26b.ts +34 -94
  173. package/src/model/generated/gemma4-e4b.ts +28 -76
  174. package/src/model/glm52-cache.ts +19 -9
  175. package/src/model/glm52-dsa.ts +13 -9
  176. package/src/model/glm52-memory.ts +28 -1
  177. package/src/model/implementation.ts +69 -0
  178. package/src/model/minicpm5.ts +7 -8
  179. package/src/model/profile.ts +443 -0
  180. package/src/model/qwen-append.ts +12 -0
  181. package/src/model/qwen-conv.ts +52 -0
  182. package/src/model/qwen3-delta.ts +98 -2
  183. package/src/model/qwen3-mrope.ts +252 -0
  184. package/src/model/qwen3_5-checkpoint.ts +164 -0
  185. package/src/model/qwen3_5.ts +336 -60
  186. package/src/model/support.ts +1 -1
  187. package/src/model/trellis-balanced-scatter.ts +51 -0
  188. package/src/model/trellis-linear.ts +672 -0
  189. package/src/model/trellis-shared-m.ts +151 -0
  190. package/src/model/trellis-shared-scatter.ts +144 -0
  191. package/src/model/trellis-splitk-prefill.ts +158 -0
  192. package/src/model/trellis-tiled-prefill.ts +136 -0
  193. package/src/model/trellis-vector-expand.ts +62 -0
  194. package/src/model/trellis-wide-prefill.ts +94 -0
  195. package/src/model/universal/dense.ts +1 -1
  196. package/src/model/universal/modules.ts +8 -1
  197. package/src/native/frame_extract.swift +140 -0
  198. package/src/native-pack.ts +15 -7
  199. package/src/pi-provider.ts +6 -64
  200. package/src/pi-web.ts +14 -320
  201. package/src/prompt-cache.ts +97 -54
  202. package/src/quantize/allocator.ts +1 -1
  203. package/src/quantize/atomic-output.ts +38 -0
  204. package/src/quantize/calibration.ts +2 -1
  205. package/src/quantize/config-writer.ts +16 -3
  206. package/src/quantize/index.ts +28 -1
  207. package/src/quantize/job.ts +11 -0
  208. package/src/quantize/quantizer.ts +265 -100
  209. package/src/quantize/rotate.ts +603 -0
  210. package/src/quantize/safetensors-writer.ts +79 -1
  211. package/src/quantize/sensitivity.ts +41 -59
  212. package/src/quantize/trellis.ts +586 -0
  213. package/src/quantize/weight-transform.ts +292 -0
  214. package/src/responses.ts +130 -3
  215. package/src/runtime-config.ts +81 -0
  216. package/src/sampler.ts +276 -4
  217. package/src/serve/admin-routes.ts +184 -0
  218. package/src/serve/aux-routes.ts +132 -0
  219. package/src/serve/batch-scheduler.ts +8 -1558
  220. package/src/serve/chat-request.ts +391 -0
  221. package/src/serve/chat-stage.ts +195 -0
  222. package/src/serve/checkpoint-identity.ts +64 -0
  223. package/src/serve/completion-executor.ts +354 -0
  224. package/src/serve/completion-sink.ts +157 -0
  225. package/src/serve/discovery-routes.ts +204 -0
  226. package/src/serve/generation-gateway.ts +211 -243
  227. package/src/serve/http.ts +159 -0
  228. package/src/serve/inference-request.ts +79 -0
  229. package/src/serve/isolate.ts +297 -105
  230. package/src/serve/kv-budget.ts +14 -0
  231. package/src/serve/lab-routes.ts +341 -0
  232. package/src/serve/lane-registry.ts +2 -1
  233. package/src/serve/model-admin-routes.ts +155 -0
  234. package/src/serve/model-binding.ts +43 -0
  235. package/src/serve/model-host.ts +512 -0
  236. package/src/serve/openai-wire.ts +103 -0
  237. package/src/serve/parent-application.ts +56 -0
  238. package/src/serve/pipeline.ts +33 -0
  239. package/src/serve/preparation.ts +33 -0
  240. package/src/serve/prompt-response-trace.ts +147 -0
  241. package/src/serve/request-plan.ts +162 -0
  242. package/src/serve/request-prep.ts +346 -0
  243. package/src/serve/response-lease.ts +24 -0
  244. package/src/serve/responses-client.ts +69 -0
  245. package/src/serve/session-completion-engine.ts +110 -0
  246. package/src/serve/session-search.ts +1 -1
  247. package/src/serve/static-routes.ts +101 -0
  248. package/src/serve/text-completion-stage.ts +104 -0
  249. package/src/serve/token-streams.ts +519 -0
  250. package/src/server.ts +523 -3551
  251. package/src/spec/assistant-source.ts +10 -44
  252. package/src/spec/deepspec-source.ts +6 -6
  253. package/src/spec/dflash-source.ts +9 -8
  254. package/src/spec/dspark/ab-stats.ts +3 -3
  255. package/src/spec/dspark/calibration.ts +2 -2
  256. package/src/spec/dspark/deepspec-module.ts +2 -2
  257. package/src/spec/dspark/generate-dflash.ts +2 -2
  258. package/src/spec/dspark/generate.ts +2 -2
  259. package/src/spec/dspark/loader.ts +1 -1
  260. package/src/spec/dspark/module-dflash.ts +5 -4
  261. package/src/spec/dspark/module.ts +3 -3
  262. package/src/spec/dspark/quantize-drafter.ts +1 -1
  263. package/src/spec/generate.ts +1 -1
  264. package/src/spec/glm52-mtp-source.ts +9 -1
  265. package/src/spec/ngram-source.ts +1 -1
  266. package/src/spec/prefix-state.ts +45 -0
  267. package/src/spec/qwen-mtp-source.ts +528 -0
  268. package/src/spec/serve-loop.ts +179 -213
  269. package/src/spec/source.ts +42 -10
  270. package/src/spec/two-model.ts +1 -1
  271. package/src/ssd-cache.ts +95 -24
  272. package/src/ssd-durability.ts +207 -0
  273. package/src/tool-call.ts +51 -14
  274. package/src/train/flash-cce.ts +14 -13
  275. package/src/train/forward.ts +38 -1
  276. package/src/train/loss.ts +3 -2
  277. package/src/train/prefix-shared.ts +5 -1
  278. package/src/train/segmented.ts +9 -6
  279. package/src/train/trainer.ts +9 -8
  280. package/src/vision/preprocess.ts +1 -1
  281. package/src/vision/prompt.ts +48 -2
  282. package/src/vision/qwen3vl-preprocess.ts +409 -0
  283. package/src/vision/qwen3vl-prompt.ts +196 -0
  284. package/src/vision/qwen3vl-tower.ts +555 -0
  285. package/src/vision/video-frames.ts +148 -0
  286. package/src/web/app.html +1 -1
  287. package/src/web/app.js +15 -6
  288. package/src/web/src/adapters-panel.ts +3 -3
  289. package/src/web/src/assistant.ts +2 -36
  290. package/src/web/src/chat.ts +16 -9
  291. package/src/web/src/composer.ts +4 -4
  292. package/src/web/src/hub.ts +1 -1
  293. package/src/web/src/markdown.ts +0 -0
  294. package/src/web/src/memory-panel.ts +1 -1
  295. package/src/web/src/model-picker.ts +1 -1
  296. package/src/web/src/palette.ts +1 -1
  297. package/src/web/src/protocol.ts +3 -39
  298. package/src/web/src/sessions.ts +1 -1
  299. package/src/web/src/ui-catalog.ts +4 -18
  300. package/src/web-assets.ts +47 -0
  301. package/src/weights.ts +134 -33
  302. package/docs/archive/mlx-bun-lab-report.html +0 -275
  303. package/docs/archive/wwdc-mlx-bun.html +0 -848
  304. package/docs/design/adapters-end-to-end.md +0 -205
  305. package/docs/design/batching-perf-path.md +0 -255
  306. package/docs/design/batching-v2-plan.md +0 -529
  307. package/docs/design/bucketing-stage.md +0 -197
  308. package/docs/design/compat-cli-surface-design.md +0 -230
  309. package/docs/design/docs-reorg-plan.md +0 -165
  310. package/docs/design/dspark-serving-program.md +0 -371
  311. package/docs/design/dspark-speculative-decoding.md +0 -268
  312. package/docs/design/grammar-spec-batching-integration.md +0 -301
  313. package/docs/design/memory-inference-path.md +0 -422
  314. package/docs/design/memory-synthesis.md +0 -287
  315. package/docs/design/memory-system.md +0 -237
  316. package/docs/design/mlx-lm-tool-parity-plan.md +0 -545
  317. package/docs/design/omlx-adoption-map.md +0 -98
  318. package/docs/design/orpo-dynamic-lambda.md +0 -220
  319. package/docs/design/orpo-future-enhancements.md +0 -340
  320. package/docs/design/paged-kv-cache.md +0 -214
  321. package/docs/design/parallel-slots.md +0 -567
  322. package/docs/design/parity-tier-dag.md +0 -161
  323. package/docs/design/repo-cleanup-plan.md +0 -189
  324. package/docs/design/runtime-isolation.md +0 -263
  325. package/docs/design/segmented-backward-training.md +0 -543
  326. package/docs/design/spec-decode-larger-targets.md +0 -229
  327. package/docs/design/ssd-kv-cold-tier.md +0 -288
  328. package/docs/design/structured-output.md +0 -484
  329. package/docs/design/tauri-desktop-app.md +0 -127
  330. package/docs/design/the-dreaming-master-plan.md +0 -445
  331. package/docs/design/turboquant-kv.md +0 -235
  332. package/docs/design/w4a16-compute-precision-spike.md +0 -232
  333. package/docs/design/web-chat-beat-matrix.md +0 -315
  334. package/docs/design/write-pipeline-entity.md +0 -468
  335. package/docs/investigations/curve-runs/bisector-route.json +0 -98
  336. package/docs/investigations/curve-runs/bisector-trace.json +0 -1393
  337. package/docs/investigations/curve-runs/curve-terrain.json +0 -1179
  338. package/docs/investigations/curve-runs/curve-terrain.svg +0 -42
  339. package/docs/investigations/hlg-ab.html +0 -34
  340. package/docs/investigations/hlg-explorer.html +0 -238
  341. package/docs/investigations/hlg-figs/cliff.svg +0 -1
  342. package/docs/investigations/hlg-figs/cross.svg +0 -1
  343. package/docs/investigations/hlg-figs/edges.svg +0 -1
  344. package/docs/investigations/hlg-figs/k20-grids.svg +0 -1
  345. package/docs/investigations/hlg-figs/k20-peaks.svg +0 -1
  346. package/docs/investigations/hlg-figs/lw-curve.svg +0 -1
  347. package/docs/investigations/hlg-figs/terrain.svg +0 -1
  348. package/docs/investigations/hlg-report.html +0 -262
  349. package/docs/investigations/hlg-runs/hlg-ab.json +0 -149
  350. package/docs/investigations/hlg-runs/hlg-blind-prompts.md +0 -87
  351. package/docs/investigations/hlg-runs/hlg-blind.json +0 -107
  352. package/docs/investigations/hlg-runs/hlg-cliff.json +0 -197
  353. package/docs/investigations/hlg-runs/hlg-cross.json +0 -505
  354. package/docs/investigations/hlg-runs/hlg-edge.json +0 -388
  355. package/docs/investigations/hlg-runs/hlg-eval1.json +0 -25
  356. package/docs/investigations/hlg-runs/hlg-frontier.json +0 -86
  357. package/docs/investigations/hlg-runs/hlg-grid.json +0 -242
  358. package/docs/investigations/hlg-runs/hlg-grid2.json +0 -343
  359. package/docs/investigations/hlg-runs/hlg-lw-coarse.json +0 -110
  360. package/docs/investigations/hlg-runs/hlg-map.json +0 -383
  361. package/docs/investigations/hlg-runs/run0-original.log +0 -159
  362. package/docs/investigations/hlg-runs/runA-recommended.log +0 -131
  363. package/docs/investigations/hlg-runs/runAA-cliff-cpm5.log +0 -26
  364. package/docs/investigations/hlg-runs/runAB-grid2-e4b.log +0 -18
  365. package/docs/investigations/hlg-runs/runAC-peak-e4b-partial.log +0 -25
  366. package/docs/investigations/hlg-runs/runAD-ab-samples.log +0 -8
  367. package/docs/investigations/hlg-runs/runAE-edge-e4b.log +0 -51
  368. package/docs/investigations/hlg-runs/runAF-logit-calibration.log +0 -10
  369. package/docs/investigations/hlg-runs/runAG-eval-config2.log +0 -16
  370. package/docs/investigations/hlg-runs/runB-gain-variants.log +0 -192
  371. package/docs/investigations/hlg-runs/runC-pivots.log +0 -162
  372. package/docs/investigations/hlg-runs/runD-oetf.log +0 -132
  373. package/docs/investigations/hlg-runs/runE-eotf.log +0 -162
  374. package/docs/investigations/hlg-runs/runF-shaper-working.log +0 -86
  375. package/docs/investigations/hlg-runs/runG-shaper-sweep.log +0 -101
  376. package/docs/investigations/hlg-runs/runH-wsweep.log +0 -176
  377. package/docs/investigations/hlg-runs/runI-asweep.log +0 -176
  378. package/docs/investigations/hlg-runs/runJ-knobmap.log +0 -49
  379. package/docs/investigations/hlg-runs/runK-frontier.log +0 -19
  380. package/docs/investigations/hlg-runs/runL-widemap.log +0 -65
  381. package/docs/investigations/hlg-runs/runM-frontier-emb.log +0 -15
  382. package/docs/investigations/hlg-runs/runN-verify.log +0 -116
  383. package/docs/investigations/hlg-runs/runO-frontier-seed5000.log +0 -15
  384. package/docs/investigations/hlg-runs/runP-grid-AxSm.log +0 -15
  385. package/docs/investigations/hlg-runs/runQ-grid-tgW.log +0 -15
  386. package/docs/investigations/hlg-runs/runR-blind-transcript.log +0 -79
  387. package/docs/investigations/hlg-runs/runS-cross-coherence.log +0 -33
  388. package/docs/investigations/hlg-runs/runT-cross-cpm5.log +0 -33
  389. package/docs/investigations/hlg-runs/runU-cross-12b.log +0 -33
  390. package/docs/investigations/hlg-runs/runV-lw-e4b.log +0 -22
  391. package/docs/investigations/hlg-runs/runW-lw-12b.log +0 -22
  392. package/docs/investigations/hlg-runs/runX-lw-cpm5.log +0 -22
  393. package/docs/investigations/hlg-runs/runY-cliff-e4b.log +0 -26
  394. package/docs/investigations/hlg-runs/runZ-cliff-12b.log +0 -26
  395. package/docs/planning/IDEAS.md +0 -69
  396. package/docs/reference/embedding.md +0 -197
  397. package/docs/reference/features-matrix.md +0 -100
  398. package/docs/reference/orpo-quickstart.md +0 -135
  399. package/src/flags.ts +0 -13
  400. /package/docs/{investigations → archive/investigations}/chunk-finetune-experiment.md +0 -0
  401. /package/docs/{investigations → archive/investigations}/colibri-oracle-pin.md +0 -0
  402. /package/docs/{investigations → archive/investigations}/curve-bisector-routing.md +0 -0
  403. /package/docs/{investigations → archive/investigations}/decode-roofline-lookagain.md +0 -0
  404. /package/docs/{investigations → archive/investigations}/dspark-handoff.md +0 -0
  405. /package/docs/{investigations → archive/investigations}/expert-offload-single-user-moe.md +0 -0
  406. /package/docs/{investigations → archive/investigations}/indexshare-performance-spike.md +0 -0
  407. /package/docs/{investigations → archive/investigations}/kernel-perf-review-2026-07.md +0 -0
  408. /package/docs/{investigations → archive/investigations}/lab-build-journal.md +0 -0
  409. /package/docs/{investigations → archive/investigations}/openwiki-evaluation.md +0 -0
  410. /package/docs/{investigations → archive/investigations}/orpo-base-uf-experiment-and-directions.md +0 -0
  411. /package/docs/{investigations → archive/investigations}/orpo-flash-cce-pin-leak.md +0 -0
  412. /package/docs/{investigations → archive/investigations}/orpo-uf-testing-handoff.md +0 -0
  413. /package/docs/{investigations → archive/investigations}/pi-builtin-investigation.md +0 -0
  414. /package/docs/{investigations → archive/investigations}/segmented-backward-handoff.md +0 -0
  415. /package/docs/{investigations → archive/investigations}/starter-model-port-handoff.md +0 -0
  416. /package/docs/{investigations → archive/investigations}/steel-flash-cce-handoff.md +0 -0
  417. /package/docs/{investigations → archive/investigations}/trainer-validation-experiment.md +0 -0
  418. /package/docs/{planning → archive/planning}/chat-ui-vision-memory-first.md +0 -0
  419. /package/docs/{planning → archive/planning}/journal.md +0 -0
  420. /package/docs/{planning → archive/planning}/pi-integration-review.md +0 -0
  421. /package/docs/{planning → archive/planning}/release-notes-v0.0.10.md +0 -0
  422. /package/docs/{planning → archive/planning}/release-notes-v0.0.11.md +0 -0
  423. /package/docs/{planning → archive/planning}/release-notes-v0.0.12.md +0 -0
  424. /package/docs/{planning → archive/planning}/release-notes-v0.0.13.md +0 -0
  425. /package/docs/{planning → archive/planning}/web-ui-pass-plan.md +0 -0
  426. /package/{docs/investigations → src/serve/assets}/curve-terrain.html +0 -0
  427. /package/{docs/dag → src/serve/assets}/training-inference-map.html +0 -0
@@ -1,468 +0,0 @@
1
- # The local write pipeline — conversations → entity articles
2
-
3
- Status: **design**, 2026-06-26. Supersedes the bucket-centric routing in
4
- [memory-synthesis.md](./memory-synthesis.md) and [bucketing-stage.md](./bucketing-stage.md)
5
- on **one axis only**: how a chunk reaches an article. Everything else in those
6
- docs (capacity-by-decomposition, the conservative gate, the pointer DB, stage
7
- LoRAs, build sequence) stands. This doc is the write side recentered on the
8
- governing realization:
9
-
10
- > **Articles are THINGS (entities). Routing is entity-extraction + name-match,
11
- > Wikipedia-style. Embeddings are at most a test instrument / fallback
12
- > candidate-narrower — never the routing mechanism.** Notability is personal:
13
- > a thing is article-worthy because the user engaged with it.
14
-
15
- The cloud original (Lucien) uses **zero embeddings** and works. Wikipedia has no
16
- vector index: it routes by named entities, links, and title search. We copy that
17
- and supply the per-edit labor with local models instead of cloud calls or
18
- volunteers.
19
-
20
- ## The shift: bucket-vector routing → entity name-match
21
-
22
- Lucien's `cluster-assign-recent.ts` is the stage this doc rewrites. There, a
23
- **bucket ≈ an article**: chunks are routed to ~379 buckets by feeding their
24
- labels (25 at a time) to Opus, which reasons globally over the whole taxonomy
25
- and emits assignments. `synthesize-update.ts` then feeds an entire bucket's new
26
- chunks to one Opus call that rewrites the whole article.
27
-
28
- Two things break when we localize this:
29
-
30
- 1. **No global reasoner.** A 1B model cannot hold 379 buckets in its head and
31
- assign correctly. (bucketing-stage.md already establishes this and decomposes
32
- it into M×N binary checks.)
33
- 2. **bucket ≠ article.** The new model says an article is a **thing**
34
- ("Panasonic S5IIX", "Photography", "Donald Trump"), and a chunk is *about
35
- things*. The natural routing key is therefore **the entity name**, not a
36
- fuzzy cluster centroid. A chunk that mentions the S5IIX routes to the
37
- `Panasonic_S5IIX` article by **name match**, exactly as a Wikipedia editor
38
- files a fact under the page whose title names the thing — no vector cosine
39
- anywhere on the hot path.
40
-
41
- The "bucket" survives only as an **optional staging convenience** (a way to let
42
- thin entities accumulate before they earn a page), not as the routing
43
- substrate. The routing substrate is the **entity index**: a name→article map the
44
- pipeline maintains deterministically.
45
-
46
- ## Why the north-star query forces this
47
-
48
- > "What is the best lens that would give me REALLY long reach, but is not crazy
49
- > expensive?"
50
-
51
- To answer, the read agent must traverse: `Panasonic_S5IIX` → (infobox: Mount =
52
- L-Mount) → `L-Mount` → compatible lenses; PLUS Josh adapts M42/EF (`Lens_Mount_Adaptation`)
53
- so those qualify; he owns a `Lumix_75-300` so he wants *more* reach than that.
54
-
55
- That traversal is only possible if the write pipeline produced:
56
-
57
- - **entity articles** (the S5IIX is its own page, not a paragraph buried in
58
- "Camera Gear"),
59
- - **infobox facts** (`Mount: L-Mount` as a queryable key-value, not prose the
60
- agent has to re-read and re-extract),
61
- - **wikilinks** (`S5IIX → L-Mount → lenses`),
62
- - **See also / series** (`Part of a series on Lenses`).
63
-
64
- The existing corpus proves the gap is real: across 385 Dreaming articles there
65
- are **378 See-also blocks but 0 infoboxes, 0 series banners, 0 {{Main}} links.**
66
- Structured facts like "L-Mount" live as prose inside `Anamorphic_Lens_Adapters.md`
67
- (the S5IIX isn't even its own article — it's a bolded phrase inside
68
- `Camera_Gear_and_Lenses`). The write pipeline below makes entity-granular
69
- articles + infoboxes a first-class output, because the read side needs them.
70
-
71
- ## The pipeline (DAG)
72
-
73
- ```
74
- conversation transcripts
75
- │
76
- ▼ SEGMENT ··················· local + chunk LoRA (e4b, exists)
77
- single-topic chunks (+ label)
78
- │
79
- ▼ ENTITY-EXTRACT ············ local; "what THINGS is this chunk about?"
80
- chunk → [entity mentions] (the routing key — replaces bucket-vector)
81
- │
82
- ▼ ROUTE (name-match, deterministic + tiny binary disambiguation)
83
- each mention → existing article | CREATE new article | drop (trivial)
84
- │
85
- ▼ SECTION-ROUTE ············· M×N binary, hierarchically pruned
86
- "does chunk i update section j of article A? yes/no"
87
- all-no + substantive → new section ; no related article → new article
88
- │
89
- ▼ PATCH ····················· local + synth LoRA; one (chunk,section) pair
90
- integrate chunk into section + [^N] citation (bounded in/out)
91
- │
92
- ▼ NORMALIZE ················· deterministic code (NOT a model)
93
- footnote bijection · wikilink canonicalize · infobox key sort
94
- │
95
- ▼ WIKIFY (periodic) ········· local + editor LoRA + structural pass
96
- per-section improve · summary-style splits · series/See-also/infobox upkeep
97
- ```
98
-
99
- Compared to memory-synthesis.md's DAG, the change is **CLASSIFY→bucket** is
100
- replaced by **ENTITY-EXTRACT → ROUTE(name-match)**, and SECTION-ROUTE is lifted
101
- to a first-class M×N stage rather than a sub-step of SYNTHESIZE.
102
-
103
- ---
104
-
105
- ## Stage 1 — SEGMENT (chunk)
106
-
107
- **Single task the model performs:** *"Split this one conversation into
108
- single-topic chunks; give each a 4-10-word specific label."* Unchanged from
109
- Lucien's `chunk-recent.ts` and already the e4b chunk LoRA's job.
110
-
111
- - **Prompt shape:** one conversation in (formatted `[sender] (uuid) text`),
112
- JSON `{chunks:[{start_message_uuid,end_message_uuid,label}]}` out. Meta policy
113
- (`Chunking.md`, `Topics_to_Ignore.md`) inlined. Ignore-rule spans are simply
114
- omitted (the substance filter starts here).
115
- - **LoRA:** **`memory-chunk` (exists, e4b chunk-300).** This is the one stage
116
- with a trained adapter. Its purity is load-bearing: a chunk fusing two things
117
- pollutes every entity it routes to. Eval by boundary/label accuracy vs gold,
118
- not val loss.
119
- - **Output → DB:** pointer `chunks(id, conv, start, end, label)` (no text copy).
120
-
121
- A chunk's **label is the entity-extraction input** for the next stage — Lucien
122
- already classifies on labels, and the label is a clean ~6-word topic string.
123
-
124
- ---
125
-
126
- ## Stage 2 — ENTITY-EXTRACT (the new routing key)
127
-
128
- **Single task:** *"What things (entities) is this chunk about? List them as
129
- canonical names."* This is the stage that **replaces bucket-vector routing.**
130
-
131
- A "thing" is any nameable entity the user engaged with: a product
132
- (`Panasonic S5IIX`), a standard (`L-Mount`), a person (`Donald Trump`), a
133
- project (`Archie`), a domain (`Photography`). Broad-domain entities are legal
134
- and expected — they capture domain-level engagement; specific-thing entities
135
- capture the relationship to that exact entity. A chunk yields **0..N entities**
136
- (many-to-many at the root).
137
-
138
- - **Prompt shape (atomic, extraction-only — no routing decision here):**
139
-
140
- ```
141
- A chunk of the user's conversation is below (label + text).
142
- List the distinct THINGS (entities) it is about — products, people,
143
- standards, projects, domains. One per line, as the canonical name you'd
144
- title a wiki article. Include both specific things (e.g. "Panasonic S5IIX")
145
- and the broad domain (e.g. "Photography") when both are genuinely engaged.
146
- If it is about nothing nameable/substantive, output NONE.
147
-
148
- LABEL: {{label}}
149
- CHUNK: {{text}}
150
- ```
151
-
152
- Output: a short newline list of names. **No JSON object, no batch indices** —
153
- the failure modes the bucketing critique flagged (multi-item JSON fidelity,
154
- batch index drift) don't arise. One small list per chunk.
155
-
156
- - **Why extract is separate from route:** extraction is "read and name"
157
- (in-context, reliable for a small model); routing is "match against the
158
- existing index" (a deterministic + tiny-binary step, Stage 3). Keeping them
159
- separate keeps each task atomic — the capacity-by-decomposition rule.
160
-
161
- - **LoRA:** likely **base + policy first** (`memory-entity`, train only if the
162
- base over/under-extracts or won't canonicalize names). NER-style extraction is
163
- near the easy end for a small instruct model; the binary disambiguation in
164
- Stage 3 is where errors are cheap to catch. Decision keyed off extraction
165
- precision/recall vs a gold entity set distilled from the cloud pipeline.
166
-
167
- - **Output → DB:** `chunk_entities(chunk_id, entity_name, surface_form)` — the
168
- many-to-many root edge. `entity_name` is the canonicalized title; `surface_form`
169
- is what the chunk literally said (for the disambiguation step and for never
170
- losing the user's wording).
171
-
172
- ### Canonicalization is deterministic, with a tiny binary tiebreak
173
-
174
- Name-match must survive aliasing ("S5IIX" / "S5 IIX" / "Lumix S5IIX" / "the
175
- Panasonic"). The pipeline keeps an **entity index** — `entities(name,
176
- aliases[], article_stem)` — built from existing article titles + an `aliases`
177
- list each article's infobox/lead declares. Matching:
178
-
179
- 1. **Deterministic normalize + alias lookup (no model):** case-fold, collapse
180
- whitespace, strip articles/possessives; look up in the alias table. Exact or
181
- alias hit → routed. This is Wikipedia's redirect mechanism.
182
- 2. **Tiny binary disambiguation (model, only on miss/ambiguity):** *"Is
183
- `{{surface_form}}` (context: `{{label}}`) the same thing as the existing
184
- article `{{candidate}}` — `{{candidate lead sentence}}`? yes/no."* Run only
185
- over the few lexically-near candidates (a lexical/trigram shortlist over
186
- titles+aliases — **lexical, not vector**; embeddings are a *fallback*
187
- narrower only if lexical recall proves insufficient, measured first).
188
- 3. **No match + substantive → CREATE article** (Stage 4's create branch).
189
- No match + trivial → drop.
190
-
191
- This is the entity analogue of bucketing-stage.md's "new-bucket global gate":
192
- the disambiguation step prevents `Panasonic S5IIX` and `Lumix S5 IIX` becoming
193
- two pages. The difference from the old design is the candidate set comes from
194
- **name/alias lexical match, not centroid cosine.**
195
-
196
- ---
197
-
198
- ## Stage 3 — ROUTE: mention → article
199
-
200
- **No new model task** beyond Stage 2's disambiguation binary. Routing is the
201
- deterministic join of `chunk_entities` against the `entities` index:
202
-
203
- - mention resolves to an existing article → enqueue `(chunk, article)` for
204
- section-routing.
205
- - mention resolves to nothing, substantive → CREATE candidate (Stage 4).
206
- - mention trivial / on the ignore list → drop.
207
-
208
- A single chunk routes to **multiple articles** (it named multiple things) — this
209
- is where facet extraction falls out: the same S5IIX-anamorphic chunk lands on
210
- `Panasonic_S5IIX`, `Anamorphic_Lens_Adapters`, and `Lens_Mount_Adaptation`,
211
- each of which will keep only what's relevant to *it* at patch time.
212
-
213
- **Bucket's residual role (optional):** a thin entity (1-2 mentions, not yet
214
- page-worthy) can park its chunks in a lightweight bucket keyed by the entity
215
- name until it crosses a create-threshold. This is the only thing "buckets"
216
- still do — a staging queue for sub-notable entities — and it's optional; the
217
- default is "substantive new thing → create a {{stub}} immediately," matching
218
- Wikipedia's "a stub is legitimate; coverage earns value" (Article_Conventions.md).
219
-
220
- ---
221
-
222
- ## Stage 4 — SECTION-ROUTE (the M×N binary core)
223
-
224
- For each routed `(chunk, article)` pair, decide which **section(s)** the chunk
225
- touches. This is bucketing-stage.md's M×N binary pattern, now first-class.
226
-
227
- **Single task (one call per pair):** *"Should this chunk update THIS section?
228
- yes/no."*
229
-
230
- ```
231
- ARTICLE: {{title}}
232
- SECTION: {{heading}} — {{section's first ~2 sentences}}
233
- CHUNK (label): {{label}}
234
- CHUNK adds: {{1-line gist or the chunk text if short}}
235
- Does this chunk add or change information belonging in THIS section? yes/no.
236
- ```
237
-
238
- Run over the article's *N* TOC sections (from `parseToc`/`extractSection` in
239
- `vault.ts`). Hierarchical pruning keeps M×N small:
240
-
241
- - **Coarse gate already passed:** the chunk is here only because it named this
242
- article's entity (Stage 3), so we never run sections of unrelated articles.
243
- - **Within the article**, *N* is tiny (a handful of sections). Run all *N*
244
- binaries; optionally prune with a lexical heading match first. **No vector
245
- required** — N is small enough to brute-force, which is the whole point of
246
- local ~free inference.
247
-
248
- **The uniform growth rule (no-match → create):**
249
-
250
- - chunk gets **yes** on ≥1 section → those become PATCH pairs.
251
- - chunk gets **all-no** but is substantive → **CREATE-NEW-SECTION** task:
252
- *"Name a new section (2-5 words) for this material, or NONE if it's a trivial
253
- aside."* Mirrors new-article/new-bucket creation.
254
- - article didn't exist at all (Stage 3 create) → **CREATE-ARTICLE**: this is the
255
- cold-start flow — sub-cluster the entity's chunks into proto-sections, outline,
256
- draft each section (memory-synthesis.md's CREATE flow, unchanged), seeded with
257
- an **infobox** for the entity (below).
258
-
259
- - **LoRA:** **`memory-section` (train if base misfires).** The binary framing is
260
- much easier than multi-section JSON; base + policy may clear the bar. Decision
261
- keyed off per-(chunk,section) yes/no accuracy + per-chunk section-set Jaccard
262
- vs gold (oracle-shortlist F1 vs real, per bucketing-stage.md's eval design).
263
-
264
- - **Output → DB:** `chunk_sections(chunk_id, article, section_anchor)` — the
265
- patch worklist. `synthesized_chunk_sections` is the per-(chunk,section)
266
- idempotency ledger (fold each chunk into each section exactly once;
267
- `NOT IN` resumption like Lucien's `synthesized_bucket_chunks`).
268
-
269
- ---
270
-
271
- ## Stage 5 — PATCH (the most atomic synthesis)
272
-
273
- **Single task:** *"Integrate THIS chunk into THIS section. Add a `[^N]`
274
- citation. Change nothing else."* Bounded text in, bounded text out — the
275
- opposite of Lucien's whole-article rewrite.
276
-
277
- - **Prompt shape:** current section markdown + the chunk (with conv UUID, date,
278
- source slug in the header for the footnote) + the citation rules (the exact
279
- footnote contract from `synthesize-update.ts` / `Article_Conventions.md`,
280
- inlined). Output: the rewritten **section only**, plus any new `[^N]:`
281
- definition lines. **Everything outside the routed section stays
282
- byte-identical** — the assembler swaps just that section back into the file.
283
-
284
- - **Conservative write gate (per section, ported from Lucien):** preserve
285
- prose, ≥70% word-count floor on the section, every pre-existing `conv:`
286
- citation in that section survives, integrate-don't-overwrite. A weak local
287
- pass that shrinks/strips the section is gated to **NO-OP** (the chunk stays
288
- un-synthesized and retries next run) rather than allowed to corrupt the vault.
289
- This is the inviolable "LoRAs propose, deterministic gates dispose" rule.
290
-
291
- - **LoRA:** **`memory-synthesis`.** The single most valuable adapter to train,
292
- distilled from Lucien's cloud synthesis edits — but at **section
293
- granularity** (one (chunk,section) integration per training example), not
294
- whole-article. Signal: citation preservation, faithful integration, no
295
- hallucinated claims.
296
-
297
- - **Provisional facts (open question, flagged):** the patch should represent
298
- trajectory ("work set to begin July") so a later chunk cleanly updates it
299
- ("began", "completed"). A lightweight convention (e.g. an `as of YYYY-MM`
300
- tag in prose tied to the citation date) keeps temporal claims updatable
301
- rather than contradictory. Deferred; called out so the patch prompt can grow
302
- into it.
303
-
304
- ---
305
-
306
- ## Stage 6 — WIKIFY (periodic structural pass) + infoboxes
307
-
308
- Section-patches are greedy and local; over many of them an article drifts
309
- (sprawl, stale lead, redundant prose, missing structure). WIKIFY is the periodic
310
- global-but-decomposed pass that keeps articles *good* — and it is where the
311
- **under-explored Wikipedia conventions** the read side needs get maintained.
312
-
313
- Two parts (memory-synthesis.md's distinction holds — keep them separate from the
314
- deterministic NORMALIZE below):
315
-
316
- **(a) Per-section "improve this section" (local + `memory-editor` LoRA).**
317
- Atomic, same shape as a patch but no new chunk: *"Tighten this section: remove
318
- redundancy, keep every citation and every specific detail, don't generalize away
319
- particulars."* Gated by the same ≥70% floor.
320
-
321
- **(b) Cheap structural pass over the TOC (local, single small call per article):**
322
- this is the stage that builds the traversable structure the north-star query
323
- depends on. It performs, as **atomic sub-tasks**, the conventions Josh flagged:
324
-
325
- - **Infobox maintenance** — *"From this entity article, extract/refresh the
326
- structured key-value facts."* For `Panasonic_S5IIX`: `Type: Mirrorless camera`,
327
- `Mount: [[L-Mount]]`, `Sensor: full-frame`, `Owner-status: owned`. **This is
328
- the single most load-bearing structural output** — the infobox `Mount` field
329
- is exactly the queryable fact the lens query traverses, instead of re-reading
330
- prose. Infobox values that are themselves entities become **wikilinks**, so
331
- the infobox is part of the link graph. (Corpus today: 0 infoboxes — this stage
332
- creates them.) The infobox also declares the article's `aliases:` used by the
333
- Stage-2 entity index — closing the loop.
334
-
335
- - **Summary-style split (`{{Main}}`)** — *"Has a section outgrown the article?"*
336
- When `Camera_Gear_and_Lenses` accumulates a full section on the S5IIX, split
337
- it into a child `Panasonic_S5IIX` article and leave a summary + `{{Main:
338
- Panasonic_S5IIX}}` link. This is **how specific-thing articles are born from
339
- broad-domain ones** — the structural complement to Stage-2 entity extraction,
340
- and exactly what the corpus needs (the S5IIX is currently trapped as a phrase
341
- inside a gear article).
342
-
343
- - **Article series** — *"Does this article belong to a series?"* Emit/maintain a
344
- `Part of a series on [[Lenses]]` banner linking siblings, so the read agent
345
- can enumerate "all lens articles" by following the series, not by guessing
346
- titles.
347
-
348
- - **See also / lead refresh / re-section / split-merge signals** — reorder
349
- sections, refresh the stale lead, emit Talk-page SPLIT/MERGE/CONTRADICTION
350
- signals (these *may* use embedding silhouette as a **test/triage instrument**
351
- — the one sanctioned embedding use, never on the routing hot path).
352
-
353
- WIKIFY runs **periodically**, not per-chunk (it's the editorial sweep), and is
354
- decomposed so even the "global" pass is a series of atomic per-section /
355
- per-convention calls — local-tractable for the same reason synthesis is.
356
-
357
- ---
358
-
359
- ## Stage 7 — NORMALIZE (deterministic, no model)
360
-
361
- Pure code enforces the invariants AI can't be trusted on (the division of labor:
362
- **AI judges, code enforces**). Ported from Lucien's `normalize-footnotes.ts` /
363
- `normalize-wikilinks.ts`; `vault.ts` already has the wikilink resolver.
364
-
365
- - **Footnote bijection:** every `[^N]` marker ⇔ exactly one `[^N]:` definition;
366
- renumber 1..k contiguous in first-appearance order; merge duplicate
367
- `conv:HASH` definitions to one marker. (Patches append; this re-derives the
368
- canonical numbering.)
369
- - **Wikilink canonicalization:** resolve `[[Name]]` to the exact on-disk stem
370
- (underscores, case), repair/flag orphans, never write a spaced target that
371
- resolves to nothing. Infobox entity-values normalized the same way.
372
- - **Infobox key normalization:** stable key order/format so infoboxes are
373
- diff-clean and machine-readable for the read agent.
374
- - **Structural guards:** `## References` last, `## See also` before it,
375
- `{{stub}}` marking for thin articles, title = `# H1` = filename stem.
376
-
377
- NORMALIZE is non-fatal (logs + continues) and runs after every write, before the
378
- git commit. It cannot corrupt an article — it only canonicalizes.
379
-
380
- ---
381
-
382
- ## Stage → task → model → adapter (summary)
383
-
384
- | stage | single task the model does | prompt shape | model / adapter |
385
- |---|---|---|---|
386
- | SEGMENT | split one conv into single-topic chunks + labels | 1 conv → JSON chunks | **memory-chunk (e4b, exists)** |
387
- | ENTITY-EXTRACT | name the THINGS this chunk is about | label+text → name list | base+policy; `memory-entity` only if needed |
388
- | ROUTE | (deterministic) name/alias match; binary "same thing?" on miss | tiny yes/no per near candidate | base+policy (disambig binary) |
389
- | SECTION-ROUTE | "does chunk i update section j?" yes/no, M×N | per (chunk,section) yes/no | `memory-section` if base misfires |
390
- | PATCH | integrate THIS chunk into THIS section + cite | section+chunk → section | **memory-synthesis (highest value)** |
391
- | WIKIFY-improve | tighten THIS section | section → section | `memory-editor` |
392
- | WIKIFY-structure | infobox / split / series / see-also (atomic sub-tasks) | per-convention small calls | `memory-editor` (+ base) |
393
- | NORMALIZE | — | — | **deterministic code** |
394
-
395
- **Where a LoRA is genuinely needed vs base+policy:** PATCH (memory-synthesis)
396
- and SEGMENT (memory-chunk) are the two with the hardest judgment and the most
397
- to lose — train these. ENTITY-EXTRACT and SECTION-ROUTE are atomic enough that
398
- **base + inlined Meta policy may clear the bar**; train only on a measured miss,
399
- per the staged LoRA criteria in bucketing-stage.md (Stage 0 instrument → Stage 1
400
- base+prompt → Stage 2 train only if it misses). ROUTE's disambiguation is a tiny
401
- binary that base models do well. WIKIFY-improve/structure can share one
402
- `memory-editor` adapter or stay base+policy initially.
403
-
404
- ---
405
-
406
- ## Data model deltas (vs bucketing-stage.md / db.ts)
407
-
408
- Keep the pointer design (memory-synthesis.md). Add the entity layer; demote
409
- buckets:
410
-
411
- - **`messages`** — text once, `(conv, position)`.
412
- - **`chunks`** — pointers + `label` (no text copy).
413
- - **`entities(name, aliases, article_stem, kind)`** — the **routing index**
414
- (name→article); `kind` ∈ {thing, person, domain, project, standard}. Built
415
- from article titles + infobox-declared aliases. *This table replaces
416
- `buckets` as the routing substrate.*
417
- - **`chunk_entities(chunk_id, entity_name, surface_form)`** — M:N root edge
418
- (ENTITY-EXTRACT output), the entity analogue of `chunk_buckets`.
419
- - **`chunk_sections(chunk_id, article, section_anchor)`** — SECTION-ROUTE
420
- worklist (already planned).
421
- - **`synthesized_chunk_sections(chunk_id, article, section_anchor, at)`** —
422
- per-section idempotency ledger (Lucien's `synthesized_bucket_chunks`, at
423
- section granularity).
424
- - **`buckets` / `chunk_buckets`** — kept only as an **optional staging queue**
425
- for sub-notable entities; not on the routing path. May ship empty.
426
- - `PRAGMA foreign_keys = ON` + `ON DELETE CASCADE` (fixes Lucien's orphan
427
- edges). DB is rebuildable cache; truth = vault + git.
428
-
429
- ---
430
-
431
- ## Build sequence (cold-start first — vault is empty)
432
-
433
- 1. **SEGMENT** to the e4b chunk adapter (the one adapter in hand); verify
434
- single-topic chunks + labels on real pi sessions.
435
- 2. **ENTITY-EXTRACT** base+policy; eval entity precision/recall vs a gold entity
436
- set distilled from the Lucien corpus (article titles ≈ gold entities).
437
- 3. **ROUTE** — deterministic name/alias index + binary disambiguation; from zero
438
- every substantive entity → CREATE a {{stub}}.
439
- 4. **CREATE flow** (sub-cluster → outline → per-section draft + **seed
440
- infobox**) behind the conservative gate — gets us from zero to first entity
441
- articles, each with a queryable infobox.
442
- 5. **NORMALIZE** (deterministic footnote/wikilink/infobox) — `vault.ts` resolver
443
- exists.
444
- 6. **SECTION-ROUTE + PATCH** (steady state) once articles exist to update.
445
- 7. **WIKIFY** structural pass (infobox upkeep, summary-style splits, series,
446
- See-also) once articles accumulate enough to drift — and to retrofit the
447
- split-out of specific things (S5IIX) from broad ones (Camera Gear).
448
-
449
- Steps 1-5 are cold-start (zero → first entity articles with infoboxes); 6-7 are
450
- steady state. The **first verifiable win** is: ingest a camera conversation →
451
- get a `Panasonic_S5IIX` article whose infobox has `Mount: [[L-Mount]]`, with the
452
- read agent able to traverse that fact for the north-star lens query.
453
-
454
- ## Open questions (carried + new)
455
-
456
- - **Domain vs specific granularity:** when ENTITY-EXTRACT should emit only the
457
- broad domain vs also the specific thing (and when WIKIFY should split a thing
458
- out of a domain). Heuristic: emit both; let create-threshold + summary-style
459
- split decide what becomes its own page.
460
- - **Entity canonicalization recall:** measure lexical-shortlist recall over
461
- titles+aliases *first* (the bucketing-stage.md "measure the shortlist ceiling"
462
- discipline, applied to names); only add the embedding fallback narrower if
463
- lexical recall is insufficient.
464
- - **Create-vs-strong-model for bootstrap** (carried): is first-creation good
465
- enough local, or is bootstrap the one place a stronger model earns its cost?
466
- - **Provisional/temporal facts:** the `as of` convention for trajectory claims.
467
- - **Infobox schema per entity-kind:** a small set of templates (camera, lens,
468
- person, project) so infobox fields are consistent enough to query.
@@ -1,98 +0,0 @@
1
- [
2
- {
3
- "tag": "creative",
4
- "pol": "default",
5
- "departedPct": 1,
6
- "fr": 0.2571428571428571,
7
- "rr": 0.34375,
8
- "lr": 0,
9
- "ratio": 0.748051948051948,
10
- "cohMean": -1.0010227537330092,
11
- "cohN": 9,
12
- "cohOk": 9
13
- },
14
- {
15
- "tag": "creative",
16
- "pol": "temp0.8",
17
- "departedPct": 1,
18
- "fr": 0.06976744186046512,
19
- "rr": 0.2318840579710145,
20
- "lr": 0.022727272727272728,
21
- "ratio": 0.3008720930232558,
22
- "cohMean": -0.8618866522327556,
23
- "cohN": 3,
24
- "cohOk": 3
25
- },
26
- {
27
- "tag": "creative",
28
- "pol": "curve-id",
29
- "departedPct": 1,
30
- "fr": 0.2647058823529412,
31
- "rr": 0.34375,
32
- "lr": 0,
33
- "ratio": 0.7700534759358288,
34
- "cohMean": -1.079108765834491,
35
- "cohN": 9,
36
- "cohOk": 9
37
- },
38
- {
39
- "tag": "creative",
40
- "pol": "curve-router",
41
- "departedPct": 1,
42
- "fr": 0.43333333333333335,
43
- "rr": 0.5454545454545454,
44
- "lr": 0.03225806451612903,
45
- "ratio": 0.7944444444444445,
46
- "cohMean": -1.3585284007349332,
47
- "cohN": 13,
48
- "cohOk": 13
49
- },
50
- {
51
- "tag": "factual",
52
- "pol": "default",
53
- "departedPct": 1,
54
- "fr": 0.42105263157894735,
55
- "rr": 0.021164021164021163,
56
- "lr": 0,
57
- "ratio": 19.894736842105264,
58
- "cohMean": -0.5009498243893914,
59
- "cohN": 16,
60
- "cohOk": 16
61
- },
62
- {
63
- "tag": "factual",
64
- "pol": "temp0.8",
65
- "departedPct": 1,
66
- "fr": 0.38461538461538464,
67
- "rr": 0.02564102564102564,
68
- "lr": 0,
69
- "ratio": 15.000000000000002,
70
- "cohMean": -0.42202286759264085,
71
- "cohN": 15,
72
- "cohOk": 15
73
- },
74
- {
75
- "tag": "factual",
76
- "pol": "curve-id",
77
- "departedPct": 1,
78
- "fr": 0.40540540540540543,
79
- "rr": 0.026881720430107527,
80
- "lr": 0,
81
- "ratio": 15.081081081081082,
82
- "cohMean": -0.5881801143434967,
83
- "cohN": 15,
84
- "cohOk": 15
85
- },
86
- {
87
- "tag": "factual",
88
- "pol": "curve-router",
89
- "departedPct": 1,
90
- "fr": 0.5714285714285714,
91
- "rr": 0.0440251572327044,
92
- "lr": 0.04950495049504951,
93
- "ratio": 12.979591836734693,
94
- "cohMean": -0.770856366133446,
95
- "cohN": 8,
96
- "cohOk": 8
97
- }
98
- ]