@seanhogg/builderforce-webcontainers 2026.10.11 → 2026.10.14

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 (372) hide show
  1. package/README.md +22 -0
  2. package/dist/adaptive/controller.d.ts +39 -0
  3. package/dist/adaptive/controller.d.ts.map +1 -0
  4. package/dist/adaptive/controller.js +108 -0
  5. package/dist/adaptive/controller.js.map +1 -0
  6. package/dist/adaptive/costModel.d.ts +37 -0
  7. package/dist/adaptive/costModel.d.ts.map +1 -0
  8. package/dist/adaptive/costModel.js +102 -0
  9. package/dist/adaptive/costModel.js.map +1 -0
  10. package/dist/adaptive/planner.d.ts +22 -0
  11. package/dist/adaptive/planner.d.ts.map +1 -0
  12. package/dist/adaptive/planner.js +114 -0
  13. package/dist/adaptive/planner.js.map +1 -0
  14. package/dist/adaptive/types.d.ts +138 -0
  15. package/dist/adaptive/types.d.ts.map +1 -0
  16. package/dist/adaptive/types.js +12 -0
  17. package/dist/adaptive/types.js.map +1 -0
  18. package/dist/assets.js +2 -2
  19. package/dist/check/cachedFetch.js.map +1 -1
  20. package/dist/check/index.d.ts +6 -1
  21. package/dist/check/index.d.ts.map +1 -1
  22. package/dist/check/index.js +6 -1
  23. package/dist/check/index.js.map +1 -1
  24. package/dist/componentCompilers.d.ts.map +1 -1
  25. package/dist/componentCompilers.js.map +1 -1
  26. package/dist/esbuildWasm.js.map +1 -1
  27. package/dist/host.d.ts +11 -5
  28. package/dist/host.d.ts.map +1 -1
  29. package/dist/host.js +19 -8
  30. package/dist/host.js.map +1 -1
  31. package/dist/inference/backends/mock.d.ts +24 -0
  32. package/dist/inference/backends/mock.d.ts.map +1 -0
  33. package/dist/inference/backends/mock.js +55 -0
  34. package/dist/inference/backends/mock.js.map +1 -0
  35. package/dist/inference/backends/onnx.d.ts +33 -0
  36. package/dist/inference/backends/onnx.d.ts.map +1 -0
  37. package/dist/inference/backends/onnx.js +60 -0
  38. package/dist/inference/backends/onnx.js.map +1 -0
  39. package/dist/inference/backends/webllm.d.ts +27 -0
  40. package/dist/inference/backends/webllm.d.ts.map +1 -0
  41. package/dist/inference/backends/webllm.js +52 -0
  42. package/dist/inference/backends/webllm.js.map +1 -0
  43. package/dist/inference/backends/wllama.d.ts +29 -0
  44. package/dist/inference/backends/wllama.d.ts.map +1 -0
  45. package/dist/inference/backends/wllama.js +51 -0
  46. package/dist/inference/backends/wllama.js.map +1 -0
  47. package/dist/inference/capabilities.d.ts +20 -0
  48. package/dist/inference/capabilities.d.ts.map +1 -0
  49. package/dist/inference/capabilities.js +33 -0
  50. package/dist/inference/capabilities.js.map +1 -0
  51. package/dist/inference/client.d.ts +45 -0
  52. package/dist/inference/client.d.ts.map +1 -0
  53. package/dist/inference/client.js +201 -0
  54. package/dist/inference/client.js.map +1 -0
  55. package/dist/inference/modelCache.d.ts +71 -0
  56. package/dist/inference/modelCache.d.ts.map +1 -0
  57. package/dist/inference/modelCache.js +91 -0
  58. package/dist/inference/modelCache.js.map +1 -0
  59. package/dist/inference/protocol.d.ts +94 -0
  60. package/dist/inference/protocol.d.ts.map +1 -0
  61. package/dist/inference/protocol.js +19 -0
  62. package/dist/inference/protocol.js.map +1 -0
  63. package/dist/inference/tokenStream.d.ts +26 -0
  64. package/dist/inference/tokenStream.d.ts.map +1 -0
  65. package/dist/inference/tokenStream.js +79 -0
  66. package/dist/inference/tokenStream.js.map +1 -0
  67. package/dist/inference/types.d.ts +108 -0
  68. package/dist/inference/types.d.ts.map +1 -0
  69. package/dist/inference/types.js +8 -0
  70. package/dist/inference/types.js.map +1 -0
  71. package/dist/inference/worker.bundle.js +5 -0
  72. package/dist/inference/worker.d.ts +35 -0
  73. package/dist/inference/worker.d.ts.map +1 -0
  74. package/dist/inference/worker.js +157 -0
  75. package/dist/inference/worker.js.map +1 -0
  76. package/dist/inference/workerEntry.d.ts +15 -0
  77. package/dist/inference/workerEntry.d.ts.map +1 -0
  78. package/dist/inference/workerEntry.js +17 -0
  79. package/dist/inference/workerEntry.js.map +1 -0
  80. package/dist/kvcache/advanced.d.ts +39 -0
  81. package/dist/kvcache/advanced.d.ts.map +1 -0
  82. package/dist/kvcache/advanced.js +59 -0
  83. package/dist/kvcache/advanced.js.map +1 -0
  84. package/dist/kvcache/compatibility.d.ts +14 -0
  85. package/dist/kvcache/compatibility.d.ts.map +1 -0
  86. package/dist/kvcache/compatibility.js +44 -0
  87. package/dist/kvcache/compatibility.js.map +1 -0
  88. package/dist/kvcache/lru.d.ts +45 -0
  89. package/dist/kvcache/lru.d.ts.map +1 -0
  90. package/dist/kvcache/lru.js +91 -0
  91. package/dist/kvcache/lru.js.map +1 -0
  92. package/dist/kvcache/paged.d.ts +86 -0
  93. package/dist/kvcache/paged.d.ts.map +1 -0
  94. package/dist/kvcache/paged.js +238 -0
  95. package/dist/kvcache/paged.js.map +1 -0
  96. package/dist/kvcache/quant.d.ts +30 -0
  97. package/dist/kvcache/quant.d.ts.map +1 -0
  98. package/dist/kvcache/quant.js +73 -0
  99. package/dist/kvcache/quant.js.map +1 -0
  100. package/dist/kvcache/radix.d.ts +28 -0
  101. package/dist/kvcache/radix.d.ts.map +1 -0
  102. package/dist/kvcache/radix.js +58 -0
  103. package/dist/kvcache/radix.js.map +1 -0
  104. package/dist/kvcache/runtime.d.ts +11 -0
  105. package/dist/kvcache/runtime.d.ts.map +1 -0
  106. package/dist/kvcache/runtime.js +204 -0
  107. package/dist/kvcache/runtime.js.map +1 -0
  108. package/dist/kvcache/types.d.ts +151 -0
  109. package/dist/kvcache/types.d.ts.map +1 -0
  110. package/dist/kvcache/types.js +10 -0
  111. package/dist/kvcache/types.js.map +1 -0
  112. package/dist/learning/fingerprint.d.ts +17 -0
  113. package/dist/learning/fingerprint.d.ts.map +1 -0
  114. package/dist/learning/fingerprint.js +46 -0
  115. package/dist/learning/fingerprint.js.map +1 -0
  116. package/dist/learning/index.d.ts +5 -0
  117. package/dist/learning/index.d.ts.map +1 -0
  118. package/dist/learning/index.js +3 -0
  119. package/dist/learning/index.js.map +1 -0
  120. package/dist/learning/learner.d.ts +21 -0
  121. package/dist/learning/learner.d.ts.map +1 -0
  122. package/dist/learning/learner.js +272 -0
  123. package/dist/learning/learner.js.map +1 -0
  124. package/dist/learning/ledger.d.ts +26 -0
  125. package/dist/learning/ledger.d.ts.map +1 -0
  126. package/dist/learning/ledger.js +40 -0
  127. package/dist/learning/ledger.js.map +1 -0
  128. package/dist/learning/selection.d.ts +44 -0
  129. package/dist/learning/selection.d.ts.map +1 -0
  130. package/dist/learning/selection.js +111 -0
  131. package/dist/learning/selection.js.map +1 -0
  132. package/dist/learning/stats.d.ts +19 -0
  133. package/dist/learning/stats.d.ts.map +1 -0
  134. package/dist/learning/stats.js +31 -0
  135. package/dist/learning/stats.js.map +1 -0
  136. package/dist/learning/types.d.ts +133 -0
  137. package/dist/learning/types.d.ts.map +1 -0
  138. package/dist/learning/types.js +8 -0
  139. package/dist/learning/types.js.map +1 -0
  140. package/dist/memory/envProbe.d.ts +16 -0
  141. package/dist/memory/envProbe.d.ts.map +1 -0
  142. package/dist/memory/envProbe.js +28 -0
  143. package/dist/memory/envProbe.js.map +1 -0
  144. package/dist/memory/estimates.d.ts +46 -0
  145. package/dist/memory/estimates.d.ts.map +1 -0
  146. package/dist/memory/estimates.js +72 -0
  147. package/dist/memory/estimates.js.map +1 -0
  148. package/dist/memory/eviction.d.ts +42 -0
  149. package/dist/memory/eviction.d.ts.map +1 -0
  150. package/dist/memory/eviction.js +143 -0
  151. package/dist/memory/eviction.js.map +1 -0
  152. package/dist/memory/manager.d.ts +34 -0
  153. package/dist/memory/manager.d.ts.map +1 -0
  154. package/dist/memory/manager.js +346 -0
  155. package/dist/memory/manager.js.map +1 -0
  156. package/dist/memory/managerTypes.d.ts +49 -0
  157. package/dist/memory/managerTypes.d.ts.map +1 -0
  158. package/dist/memory/managerTypes.js +7 -0
  159. package/dist/memory/managerTypes.js.map +1 -0
  160. package/dist/memory/pressure.d.ts +56 -0
  161. package/dist/memory/pressure.d.ts.map +1 -0
  162. package/dist/memory/pressure.js +80 -0
  163. package/dist/memory/pressure.js.map +1 -0
  164. package/dist/memory/spillTier.d.ts +47 -0
  165. package/dist/memory/spillTier.d.ts.map +1 -0
  166. package/dist/memory/spillTier.js +128 -0
  167. package/dist/memory/spillTier.js.map +1 -0
  168. package/dist/memory/storageSink.d.ts +69 -0
  169. package/dist/memory/storageSink.d.ts.map +1 -0
  170. package/dist/memory/storageSink.js +221 -0
  171. package/dist/memory/storageSink.js.map +1 -0
  172. package/dist/memory/types.d.ts +202 -0
  173. package/dist/memory/types.d.ts.map +1 -0
  174. package/dist/memory/types.js +15 -0
  175. package/dist/memory/types.js.map +1 -0
  176. package/dist/memory/victims.d.ts +32 -0
  177. package/dist/memory/victims.d.ts.map +1 -0
  178. package/dist/memory/victims.js +74 -0
  179. package/dist/memory/victims.js.map +1 -0
  180. package/dist/memory/workspace.d.ts +34 -0
  181. package/dist/memory/workspace.d.ts.map +1 -0
  182. package/dist/memory/workspace.js +55 -0
  183. package/dist/memory/workspace.js.map +1 -0
  184. package/dist/memoryIntegration/index.d.ts +8 -0
  185. package/dist/memoryIntegration/index.d.ts.map +1 -0
  186. package/dist/memoryIntegration/index.js +4 -0
  187. package/dist/memoryIntegration/index.js.map +1 -0
  188. package/dist/memoryIntegration/knowledgeMemory.d.ts +43 -0
  189. package/dist/memoryIntegration/knowledgeMemory.d.ts.map +1 -0
  190. package/dist/memoryIntegration/knowledgeMemory.js +285 -0
  191. package/dist/memoryIntegration/knowledgeMemory.js.map +1 -0
  192. package/dist/memoryIntegration/persistence.d.ts +15 -0
  193. package/dist/memoryIntegration/persistence.d.ts.map +1 -0
  194. package/dist/memoryIntegration/persistence.js +43 -0
  195. package/dist/memoryIntegration/persistence.js.map +1 -0
  196. package/dist/memoryIntegration/text.d.ts +57 -0
  197. package/dist/memoryIntegration/text.d.ts.map +1 -0
  198. package/dist/memoryIntegration/text.js +179 -0
  199. package/dist/memoryIntegration/text.js.map +1 -0
  200. package/dist/memoryIntegration/types.d.ts +131 -0
  201. package/dist/memoryIntegration/types.d.ts.map +1 -0
  202. package/dist/memoryIntegration/types.js +11 -0
  203. package/dist/memoryIntegration/types.js.map +1 -0
  204. package/dist/ml.d.ts +52 -0
  205. package/dist/ml.d.ts.map +1 -0
  206. package/dist/ml.js +33 -0
  207. package/dist/ml.js.map +1 -0
  208. package/dist/node/childRelay.d.ts +10 -0
  209. package/dist/node/childRelay.d.ts.map +1 -1
  210. package/dist/node/childRelay.js +12 -2
  211. package/dist/node/childRelay.js.map +1 -1
  212. package/dist/node/index.js.map +1 -1
  213. package/dist/node/portResponder.d.ts +2 -0
  214. package/dist/node/portResponder.d.ts.map +1 -1
  215. package/dist/node/portResponder.js +3 -3
  216. package/dist/node/portResponder.js.map +1 -1
  217. package/dist/node/processHost.d.ts +4 -1
  218. package/dist/node/processHost.d.ts.map +1 -1
  219. package/dist/node/processHost.js +19 -16
  220. package/dist/node/processHost.js.map +1 -1
  221. package/dist/node/protocol.d.ts +1 -0
  222. package/dist/node/protocol.d.ts.map +1 -1
  223. package/dist/node/responseWire.d.ts.map +1 -1
  224. package/dist/node/worker.js +116 -109
  225. package/dist/node/workerProcess.js +1 -1
  226. package/dist/node/workerProcess.js.map +1 -1
  227. package/dist/prefetch/admission.d.ts +41 -0
  228. package/dist/prefetch/admission.d.ts.map +1 -0
  229. package/dist/prefetch/admission.js +49 -0
  230. package/dist/prefetch/admission.js.map +1 -0
  231. package/dist/prefetch/loadRegistry.d.ts +56 -0
  232. package/dist/prefetch/loadRegistry.d.ts.map +1 -0
  233. package/dist/prefetch/loadRegistry.js +108 -0
  234. package/dist/prefetch/loadRegistry.js.map +1 -0
  235. package/dist/prefetch/predictor.d.ts +40 -0
  236. package/dist/prefetch/predictor.d.ts.map +1 -0
  237. package/dist/prefetch/predictor.js +178 -0
  238. package/dist/prefetch/predictor.js.map +1 -0
  239. package/dist/prefetch/prefetcher.d.ts +37 -0
  240. package/dist/prefetch/prefetcher.d.ts.map +1 -0
  241. package/dist/prefetch/prefetcher.js +339 -0
  242. package/dist/prefetch/prefetcher.js.map +1 -0
  243. package/dist/prefetch/residentStore.d.ts +49 -0
  244. package/dist/prefetch/residentStore.d.ts.map +1 -0
  245. package/dist/prefetch/residentStore.js +87 -0
  246. package/dist/prefetch/residentStore.js.map +1 -0
  247. package/dist/prefetch/selfTuner.d.ts +40 -0
  248. package/dist/prefetch/selfTuner.d.ts.map +1 -0
  249. package/dist/prefetch/selfTuner.js +78 -0
  250. package/dist/prefetch/selfTuner.js.map +1 -0
  251. package/dist/prefetch/stats.d.ts +52 -0
  252. package/dist/prefetch/stats.d.ts.map +1 -0
  253. package/dist/prefetch/stats.js +72 -0
  254. package/dist/prefetch/stats.js.map +1 -0
  255. package/dist/prefetch/streaming.d.ts +132 -0
  256. package/dist/prefetch/streaming.d.ts.map +1 -0
  257. package/dist/prefetch/streaming.js +141 -0
  258. package/dist/prefetch/streaming.js.map +1 -0
  259. package/dist/prefetch/targetIndex.d.ts +18 -0
  260. package/dist/prefetch/targetIndex.d.ts.map +1 -0
  261. package/dist/prefetch/targetIndex.js +32 -0
  262. package/dist/prefetch/targetIndex.js.map +1 -0
  263. package/dist/prefetch/types.d.ts +283 -0
  264. package/dist/prefetch/types.d.ts.map +1 -0
  265. package/dist/prefetch/types.js +19 -0
  266. package/dist/prefetch/types.js.map +1 -0
  267. package/dist/previewBridge.d.ts +6 -0
  268. package/dist/previewBridge.d.ts.map +1 -1
  269. package/dist/previewBridge.js +25 -5
  270. package/dist/previewBridge.js.map +1 -1
  271. package/dist/previewMessages.d.ts +4 -3
  272. package/dist/previewMessages.d.ts.map +1 -1
  273. package/dist/previewMessages.js +12 -6
  274. package/dist/previewMessages.js.map +1 -1
  275. package/dist/process-worker.js +116 -109
  276. package/dist/relay.html +1 -1
  277. package/dist/shared/clock.d.ts +7 -0
  278. package/dist/shared/clock.d.ts.map +1 -0
  279. package/dist/shared/clock.js +10 -0
  280. package/dist/shared/clock.js.map +1 -0
  281. package/dist/shared/hardwareProbe.d.ts +26 -0
  282. package/dist/shared/hardwareProbe.d.ts.map +1 -0
  283. package/dist/shared/hardwareProbe.js +62 -0
  284. package/dist/shared/hardwareProbe.js.map +1 -0
  285. package/dist/shared/idb.d.ts +41 -0
  286. package/dist/shared/idb.d.ts.map +1 -0
  287. package/dist/shared/idb.js +184 -0
  288. package/dist/shared/idb.js.map +1 -0
  289. package/dist/shared/tokens.d.ts +7 -0
  290. package/dist/shared/tokens.d.ts.map +1 -0
  291. package/dist/shared/tokens.js +9 -0
  292. package/dist/shared/tokens.js.map +1 -0
  293. package/dist/snapshotStore.d.ts +2 -1
  294. package/dist/snapshotStore.d.ts.map +1 -1
  295. package/dist/snapshotStore.js +27 -12
  296. package/dist/snapshotStore.js.map +1 -1
  297. package/dist/styleCompilers.d.ts.map +1 -1
  298. package/dist/styleCompilers.js.map +1 -1
  299. package/dist/transport.js.map +1 -1
  300. package/package.json +11 -5
  301. package/src/adaptive/controller.ts +151 -0
  302. package/src/adaptive/costModel.ts +131 -0
  303. package/src/adaptive/planner.ts +127 -0
  304. package/src/adaptive/types.ts +137 -0
  305. package/src/check/index.ts +6 -1
  306. package/src/host.ts +33 -11
  307. package/src/inference/backends/mock.ts +77 -0
  308. package/src/inference/backends/onnx.ts +91 -0
  309. package/src/inference/backends/webllm.ts +79 -0
  310. package/src/inference/backends/wllama.ts +79 -0
  311. package/src/inference/capabilities.ts +46 -0
  312. package/src/inference/client.ts +276 -0
  313. package/src/inference/modelCache.ts +145 -0
  314. package/src/inference/protocol.ts +119 -0
  315. package/src/inference/tokenStream.ts +92 -0
  316. package/src/inference/types.ts +115 -0
  317. package/src/inference/worker.ts +191 -0
  318. package/src/inference/workerEntry.ts +18 -0
  319. package/src/kvcache/advanced.ts +86 -0
  320. package/src/kvcache/compatibility.ts +51 -0
  321. package/src/kvcache/lru.ts +100 -0
  322. package/src/kvcache/paged.ts +270 -0
  323. package/src/kvcache/quant.ts +88 -0
  324. package/src/kvcache/radix.ts +68 -0
  325. package/src/kvcache/runtime.ts +239 -0
  326. package/src/kvcache/types.ts +167 -0
  327. package/src/learning/fingerprint.ts +50 -0
  328. package/src/learning/index.ts +15 -0
  329. package/src/learning/learner.ts +304 -0
  330. package/src/learning/ledger.ts +54 -0
  331. package/src/learning/selection.ts +137 -0
  332. package/src/learning/stats.ts +39 -0
  333. package/src/learning/types.ts +142 -0
  334. package/src/memory/envProbe.ts +30 -0
  335. package/src/memory/estimates.ts +98 -0
  336. package/src/memory/eviction.ts +145 -0
  337. package/src/memory/manager.ts +380 -0
  338. package/src/memory/managerTypes.ts +61 -0
  339. package/src/memory/pressure.ts +120 -0
  340. package/src/memory/spillTier.ts +159 -0
  341. package/src/memory/storageSink.ts +289 -0
  342. package/src/memory/types.ts +217 -0
  343. package/src/memory/victims.ts +80 -0
  344. package/src/memory/workspace.ts +74 -0
  345. package/src/memoryIntegration/index.ts +7 -0
  346. package/src/memoryIntegration/knowledgeMemory.ts +339 -0
  347. package/src/memoryIntegration/persistence.ts +54 -0
  348. package/src/memoryIntegration/text.ts +185 -0
  349. package/src/memoryIntegration/types.ts +145 -0
  350. package/src/ml.ts +180 -0
  351. package/src/node/childRelay.ts +16 -3
  352. package/src/node/portResponder.ts +5 -3
  353. package/src/node/processHost.ts +16 -15
  354. package/src/node/protocol.ts +1 -1
  355. package/src/node/workerProcess.ts +1 -1
  356. package/src/prefetch/admission.ts +74 -0
  357. package/src/prefetch/loadRegistry.ts +156 -0
  358. package/src/prefetch/predictor.ts +199 -0
  359. package/src/prefetch/prefetcher.ts +369 -0
  360. package/src/prefetch/residentStore.ts +121 -0
  361. package/src/prefetch/selfTuner.ts +110 -0
  362. package/src/prefetch/stats.ts +120 -0
  363. package/src/prefetch/streaming.ts +231 -0
  364. package/src/prefetch/targetIndex.ts +40 -0
  365. package/src/prefetch/types.ts +307 -0
  366. package/src/previewBridge.ts +25 -5
  367. package/src/previewMessages.ts +11 -6
  368. package/src/shared/clock.ts +9 -0
  369. package/src/shared/hardwareProbe.ts +68 -0
  370. package/src/shared/idb.ts +203 -0
  371. package/src/shared/tokens.ts +8 -0
  372. package/src/snapshotStore.ts +25 -10
@@ -0,0 +1 @@
1
+ {"version":3,"file":"advanced.js","sourceRoot":"","sources":["../../src/kvcache/advanced.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,qBAAqB,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7F,MAAM,UAAU,SAAS,CACvB,KAA6D,EAC7D,IAAsB;IAEtB,OAAO,KAAK,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAA0B;IACvD,OAAO,CACL,IAAI,CAAC,mBAAmB;QACxB,IAAI,CAAC,aAAa;QAClB,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CACxC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAA0B;IAC3D,OAAO,IAAI,CAAC,kBAAkB,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAA0B;IAC9D,OAAO,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,gBAAgB,GAAG,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AACzG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAU1B;IACC,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,IAAI,GAAG,GAAG,KAAK,CAAC,eAAe,CAAC;IAChC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC/C,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5C,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,CAAC;IAC/C,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAC/D,yEAAyE;IACzE,oEAAoE;IACpE,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC,aAAa,CAAC;IACvD,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC;IACjD,MAAM,UAAU,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC;IACvD,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC;IAClE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,EAAE,OAAO,EAAE,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAIzB;IACC,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC5D,CAAC;IACD,uEAAuE;IACvE,6DAA6D;IAC7D,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClE,OAAO,EAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,eAAe,EAAE,OAAO,EAAE,CAAC,oBAAoB,CAAC,EAAE,CAAC;AAChF,CAAC"}
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Phase 5 — compatibility key for EXACT-prefix KV reuse.
3
+ *
4
+ * A cache hit is allowed only when model weights, tokenizer, positional
5
+ * config, attention config, AND the exact preceding token prefix all match.
6
+ * Semantic retrieval is never treated as KV reuse.
7
+ */
8
+ import type { CompatibilityKey, CompatibilityParts } from './types.js';
9
+ export declare function encodeCompatibilityKey(parts: CompatibilityParts): CompatibilityKey;
10
+ export declare function parseCompatibilityKey(key: string): CompatibilityParts;
11
+ export declare function compatibilityEquals(a: CompatibilityParts, b: CompatibilityParts): boolean;
12
+ /** Longest exact token-prefix match length. 0 when the first token differs. */
13
+ export declare function exactPrefixLength(cached: readonly number[], query: readonly number[]): number;
14
+ //# sourceMappingURL=compatibility.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../src/kvcache/compatibility.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIvE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB,CASlF;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CASrE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAQzF;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAK7F"}
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Phase 5 — compatibility key for EXACT-prefix KV reuse.
3
+ *
4
+ * A cache hit is allowed only when model weights, tokenizer, positional
5
+ * config, attention config, AND the exact preceding token prefix all match.
6
+ * Semantic retrieval is never treated as KV reuse.
7
+ */
8
+ const SEP = '\x1f';
9
+ export function encodeCompatibilityKey(parts) {
10
+ const key = [
11
+ parts.modelId,
12
+ parts.weightsHash,
13
+ parts.tokenizerId,
14
+ parts.positionalConfig,
15
+ parts.attentionConfig,
16
+ ].join(SEP);
17
+ return { ...parts, key };
18
+ }
19
+ export function parseCompatibilityKey(key) {
20
+ const [modelId, weightsHash, tokenizerId, positionalConfig, attentionConfig] = key.split(SEP);
21
+ return {
22
+ modelId: modelId ?? '',
23
+ weightsHash: weightsHash ?? '',
24
+ tokenizerId: tokenizerId ?? '',
25
+ positionalConfig: positionalConfig ?? '',
26
+ attentionConfig: attentionConfig ?? '',
27
+ };
28
+ }
29
+ export function compatibilityEquals(a, b) {
30
+ return (a.modelId === b.modelId &&
31
+ a.weightsHash === b.weightsHash &&
32
+ a.tokenizerId === b.tokenizerId &&
33
+ a.positionalConfig === b.positionalConfig &&
34
+ a.attentionConfig === b.attentionConfig);
35
+ }
36
+ /** Longest exact token-prefix match length. 0 when the first token differs. */
37
+ export function exactPrefixLength(cached, query) {
38
+ const n = Math.min(cached.length, query.length);
39
+ let i = 0;
40
+ while (i < n && cached[i] === query[i])
41
+ i++;
42
+ return i;
43
+ }
44
+ //# sourceMappingURL=compatibility.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"compatibility.js","sourceRoot":"","sources":["../../src/kvcache/compatibility.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,GAAG,GAAG,MAAM,CAAC;AAEnB,MAAM,UAAU,sBAAsB,CAAC,KAAyB;IAC9D,MAAM,GAAG,GAAG;QACV,KAAK,CAAC,OAAO;QACb,KAAK,CAAC,WAAW;QACjB,KAAK,CAAC,WAAW;QACjB,KAAK,CAAC,gBAAgB;QACtB,KAAK,CAAC,eAAe;KACtB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9F,OAAO;QACL,OAAO,EAAE,OAAO,IAAI,EAAE;QACtB,WAAW,EAAE,WAAW,IAAI,EAAE;QAC9B,WAAW,EAAE,WAAW,IAAI,EAAE;QAC9B,gBAAgB,EAAE,gBAAgB,IAAI,EAAE;QACxC,eAAe,EAAE,eAAe,IAAI,EAAE;KACvC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,CAAqB,EAAE,CAAqB;IAC9E,OAAO,CACL,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;QACvB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,gBAAgB,KAAK,CAAC,CAAC,gBAAgB;QACzC,CAAC,CAAC,eAAe,KAAK,CAAC,CAAC,eAAe,CACxC,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,iBAAiB,CAAC,MAAyB,EAAE,KAAwB;IACnF,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;QAAE,CAAC,EAAE,CAAC;IAC5C,OAAO,CAAC,CAAC;AACX,CAAC"}
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Phase 5 — byte-bounded LRU container for KV pages. Pure TypeScript.
3
+ *
4
+ * Why this is not `src/memory/eviction.ts` `lruStrategy()`: that strategy is a
5
+ * ranking POLICY — it sorts a snapshot of `TrackedEntry` records (group,
6
+ * reload cost, reuse probability, admission sequence) that the residency
7
+ * manager owns, O(n log n) per eviction. The paged KV cache needs a keyed
8
+ * CONTAINER that owns its values and evicts in O(1) on every page insert, for
9
+ * values that carry none of the residency metadata. Routing KV pages through
10
+ * the residency manager would charge them against the model-weight budget and
11
+ * make every page insert an async admission; the shapes genuinely differ.
12
+ *
13
+ * Invariant: `bytes <= maxBytes` after every call. An entry larger than
14
+ * `maxBytes` is rejected (and any previous value under its key is dropped).
15
+ * Recency is the Map's insertion order: a touch deletes and re-inserts.
16
+ */
17
+ export interface LruNode<V> {
18
+ key: string;
19
+ value: V;
20
+ bytes: number;
21
+ }
22
+ export declare class LruCache<V> {
23
+ readonly maxBytes: number;
24
+ private readonly map;
25
+ private used;
26
+ constructor(maxBytes: number);
27
+ get size(): number;
28
+ get bytes(): number;
29
+ has(key: string): boolean;
30
+ get(key: string): V | undefined;
31
+ peek(key: string): V | undefined;
32
+ /**
33
+ * Insert or replace `key`, evicting least-recently-used entries until the
34
+ * cache is back inside `maxBytes`. Returns every key that left the cache —
35
+ * including `key` itself when the new value is larger than `maxBytes` and
36
+ * replaced a resident value (a rejected NEW key is simply not inserted).
37
+ */
38
+ set(key: string, value: V, bytes: number): string[];
39
+ delete(key: string): boolean;
40
+ clear(): void;
41
+ /** Keys, least recently used first. */
42
+ keys(): string[];
43
+ private remove;
44
+ }
45
+ //# sourceMappingURL=lru.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lru.d.ts","sourceRoot":"","sources":["../../src/kvcache/lru.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,QAAQ,CAAC,CAAC;IAIT,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAHrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;IACrD,OAAO,CAAC,IAAI,CAAK;IAEjB,YAAqB,QAAQ,EAAE,MAAM,EAAI;IAEzC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExB;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAM9B;IAED,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAE/B;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBlD;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3B;IAED,KAAK,IAAI,IAAI,CAGZ;IAED,uCAAuC;IACvC,IAAI,IAAI,MAAM,EAAE,CAEf;IAED,OAAO,CAAC,MAAM;CAOf"}
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Phase 5 — byte-bounded LRU container for KV pages. Pure TypeScript.
3
+ *
4
+ * Why this is not `src/memory/eviction.ts` `lruStrategy()`: that strategy is a
5
+ * ranking POLICY — it sorts a snapshot of `TrackedEntry` records (group,
6
+ * reload cost, reuse probability, admission sequence) that the residency
7
+ * manager owns, O(n log n) per eviction. The paged KV cache needs a keyed
8
+ * CONTAINER that owns its values and evicts in O(1) on every page insert, for
9
+ * values that carry none of the residency metadata. Routing KV pages through
10
+ * the residency manager would charge them against the model-weight budget and
11
+ * make every page insert an async admission; the shapes genuinely differ.
12
+ *
13
+ * Invariant: `bytes <= maxBytes` after every call. An entry larger than
14
+ * `maxBytes` is rejected (and any previous value under its key is dropped).
15
+ * Recency is the Map's insertion order: a touch deletes and re-inserts.
16
+ */
17
+ export class LruCache {
18
+ maxBytes;
19
+ map = new Map();
20
+ used = 0;
21
+ constructor(maxBytes) {
22
+ this.maxBytes = maxBytes;
23
+ }
24
+ get size() {
25
+ return this.map.size;
26
+ }
27
+ get bytes() {
28
+ return this.used;
29
+ }
30
+ has(key) {
31
+ return this.map.has(key);
32
+ }
33
+ get(key) {
34
+ const node = this.map.get(key);
35
+ if (!node)
36
+ return undefined;
37
+ this.map.delete(key);
38
+ this.map.set(key, node);
39
+ return node.value;
40
+ }
41
+ peek(key) {
42
+ return this.map.get(key)?.value;
43
+ }
44
+ /**
45
+ * Insert or replace `key`, evicting least-recently-used entries until the
46
+ * cache is back inside `maxBytes`. Returns every key that left the cache —
47
+ * including `key` itself when the new value is larger than `maxBytes` and
48
+ * replaced a resident value (a rejected NEW key is simply not inserted).
49
+ */
50
+ set(key, value, bytes) {
51
+ const evicted = [];
52
+ const size = Number.isFinite(bytes) && bytes > 0 ? bytes : 0;
53
+ const existed = this.remove(key);
54
+ if (size > this.maxBytes) {
55
+ if (existed)
56
+ evicted.push(key);
57
+ return evicted;
58
+ }
59
+ this.map.set(key, { key, value, bytes: size });
60
+ this.used += size;
61
+ for (const victim of this.map.keys()) {
62
+ if (this.used <= this.maxBytes)
63
+ break;
64
+ if (victim === key)
65
+ continue;
66
+ this.remove(victim);
67
+ evicted.push(victim);
68
+ }
69
+ return evicted;
70
+ }
71
+ delete(key) {
72
+ return this.remove(key);
73
+ }
74
+ clear() {
75
+ this.map.clear();
76
+ this.used = 0;
77
+ }
78
+ /** Keys, least recently used first. */
79
+ keys() {
80
+ return [...this.map.keys()];
81
+ }
82
+ remove(key) {
83
+ const node = this.map.get(key);
84
+ if (!node)
85
+ return false;
86
+ this.map.delete(key);
87
+ this.used -= node.bytes;
88
+ return true;
89
+ }
90
+ }
91
+ //# sourceMappingURL=lru.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lru.js","sourceRoot":"","sources":["../../src/kvcache/lru.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,86 @@
1
+ /**
2
+ * Phase 5 — paged KV cache.
3
+ *
4
+ * Token sequences are stored as fixed-size pages keyed by a compatibility
5
+ * key. Pages form a chain: a page's id is a rolling hash of (parent page id,
6
+ * the page's own tokens), rooted at a hash of the compatibility key. So a
7
+ * page id names its whole token prefix without embedding it — ids stay a few
8
+ * dozen bytes however long the sequence is.
9
+ *
10
+ * Lookup walks the query page by page and stops at the first page that is not
11
+ * resident, which finds the longest shared PAGE-ALIGNED prefix with ANY stored
12
+ * sequence — sequences that branch after a shared prefix all reuse it. A
13
+ * trailing partial page is matched too, via the per-parent tail index.
14
+ *
15
+ * Exactness: every hop re-verifies the page's compatibility key, parent id,
16
+ * parent serial (the exact parent page object it was stored under) and
17
+ * tokens, so a hash collision can only cause a miss, never reuse of the wrong
18
+ * KV state. Semantic / approximate matching is never done.
19
+ *
20
+ * Bounds: the only state is the page LRU (charged against `maxBytes`) and the
21
+ * tail index, whose entries are removed when their page is evicted. Sessions
22
+ * that share a compatibility key reuse pages — the session id is NOT part of
23
+ * the key.
24
+ */
25
+ import type { CompatibilityParts } from './types.js';
26
+ export interface KvPage {
27
+ id: string;
28
+ compatKey: string;
29
+ /** Id of the page this one continues (the chain root for the first page). */
30
+ parentId: string;
31
+ /** Unique per inserted page. A replaced page gets a new serial, orphaning its old children. */
32
+ serial: number;
33
+ /** Serial of the exact parent page this one was stored under (0 = chain root). */
34
+ parentSerial: number;
35
+ /** Token ids this page covers (length ≤ pageTokens). */
36
+ tokens: number[];
37
+ /** Simulated KV bytes for this page. */
38
+ bytes: number;
39
+ }
40
+ export interface PrefixHit {
41
+ matched: number;
42
+ pages: KvPage[];
43
+ compatKey: string;
44
+ }
45
+ export declare class PagedKvCache {
46
+ readonly maxBytes: number;
47
+ readonly pageTokens: number;
48
+ readonly bytesPerToken: number;
49
+ private readonly lru;
50
+ /** Partial (shorter than pageTokens) pages, by parent id. Entries leave with their page. */
51
+ private readonly tails;
52
+ private readonly tailParent;
53
+ private nextSerial;
54
+ evictions: number;
55
+ hits: number;
56
+ misses: number;
57
+ constructor(maxBytes: number, pageTokens: number, bytesPerToken: number);
58
+ get pages(): number;
59
+ get bytes(): number;
60
+ lookup(compat: CompatibilityParts, tokens: readonly number[]): PrefixHit;
61
+ /**
62
+ * Store (or extend) a sequence under a compatibility key. Pages covering
63
+ * tokens already resident are reused; new pages are inserted and may
64
+ * trigger LRU eviction of the least-recently-used pages.
65
+ */
66
+ put(compat: CompatibilityParts, tokens: readonly number[]): {
67
+ evicted: number;
68
+ };
69
+ clear(): void;
70
+ /** A resident page whose identity is verified, touched as most recently used. */
71
+ private residentPage;
72
+ private childOf;
73
+ /** Longest resident partial page under `parent` whose tokens continue the query at `offset`. */
74
+ private longestTail;
75
+ private rememberTail;
76
+ private forgetTail;
77
+ /**
78
+ * Evicted pages leave every index with them. A descendant of an evicted
79
+ * page stays resident until the LRU reaches it, but is unreachable: lookup
80
+ * stops at the first missing page, so it is a miss and recompute.
81
+ */
82
+ private dropEvicted;
83
+ /** Number of tail-index entries (diagnostics / bound checks). */
84
+ get indexedTails(): number;
85
+ }
86
+ //# sourceMappingURL=paged.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"paged.d.ts","sourceRoot":"","sources":["../../src/kvcache/paged.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAyCD,qBAAa,YAAY;IAWrB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM;IAZhC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;IACvC,4FAA4F;IAC5F,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,UAAU,CAAK;IACvB,SAAS,SAAK;IACd,IAAI,SAAK;IACT,MAAM,SAAK;IAEX,YACW,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EAG/B;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CA8BvE;IAED;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAgC9E;IAED,KAAK,IAAI,IAAI,CAOZ;IAED,iFAAiF;IACjF,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,OAAO;IAIf,gGAAgG;IAChG,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,UAAU;IAUlB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAInB,iEAAiE;IACjE,IAAI,YAAY,IAAI,MAAM,CAEzB;CACF"}
@@ -0,0 +1,238 @@
1
+ /**
2
+ * Phase 5 — paged KV cache.
3
+ *
4
+ * Token sequences are stored as fixed-size pages keyed by a compatibility
5
+ * key. Pages form a chain: a page's id is a rolling hash of (parent page id,
6
+ * the page's own tokens), rooted at a hash of the compatibility key. So a
7
+ * page id names its whole token prefix without embedding it — ids stay a few
8
+ * dozen bytes however long the sequence is.
9
+ *
10
+ * Lookup walks the query page by page and stops at the first page that is not
11
+ * resident, which finds the longest shared PAGE-ALIGNED prefix with ANY stored
12
+ * sequence — sequences that branch after a shared prefix all reuse it. A
13
+ * trailing partial page is matched too, via the per-parent tail index.
14
+ *
15
+ * Exactness: every hop re-verifies the page's compatibility key, parent id,
16
+ * parent serial (the exact parent page object it was stored under) and
17
+ * tokens, so a hash collision can only cause a miss, never reuse of the wrong
18
+ * KV state. Semantic / approximate matching is never done.
19
+ *
20
+ * Bounds: the only state is the page LRU (charged against `maxBytes`) and the
21
+ * tail index, whose entries are removed when their page is evicted. Sessions
22
+ * that share a compatibility key reuse pages — the session id is NOT part of
23
+ * the key.
24
+ */
25
+ import { encodeCompatibilityKey } from './compatibility.js';
26
+ import { LruCache } from './lru.js';
27
+ const FNV_OFFSET = 0x811c9dc5;
28
+ const FNV_PRIME = 0x01000193;
29
+ const MIX_SEED = 0x9747b28c;
30
+ const MIX_PRIME = 0x5bd1e995;
31
+ /** Two independent 32-bit lanes over a string and a token run → a compact id. */
32
+ function chainHash(parent, tokens) {
33
+ let a = FNV_OFFSET;
34
+ let b = MIX_SEED ^ tokens.length;
35
+ for (let i = 0; i < parent.length; i++) {
36
+ const c = parent.charCodeAt(i);
37
+ a = Math.imul(a ^ c, FNV_PRIME);
38
+ b = Math.imul(b ^ c, MIX_PRIME);
39
+ b ^= b >>> 13;
40
+ }
41
+ for (const token of tokens) {
42
+ const t = token | 0;
43
+ for (let shift = 0; shift < 32; shift += 8) {
44
+ const byte = (t >>> shift) & 0xff;
45
+ a = Math.imul(a ^ byte, FNV_PRIME);
46
+ b = Math.imul(b ^ byte, MIX_PRIME);
47
+ b ^= b >>> 15;
48
+ }
49
+ }
50
+ return `${(a >>> 0).toString(36)}.${(b >>> 0).toString(36)}.${tokens.length}`;
51
+ }
52
+ function sameTokens(a, b) {
53
+ if (a.length !== b.length)
54
+ return false;
55
+ for (let i = 0; i < a.length; i++)
56
+ if (a[i] !== b[i])
57
+ return false;
58
+ return true;
59
+ }
60
+ function isPrefixOf(prefix, tokens, offset) {
61
+ if (offset + prefix.length > tokens.length)
62
+ return false;
63
+ for (let i = 0; i < prefix.length; i++)
64
+ if (prefix[i] !== tokens[offset + i])
65
+ return false;
66
+ return true;
67
+ }
68
+ export class PagedKvCache {
69
+ maxBytes;
70
+ pageTokens;
71
+ bytesPerToken;
72
+ lru;
73
+ /** Partial (shorter than pageTokens) pages, by parent id. Entries leave with their page. */
74
+ tails = new Map();
75
+ tailParent = new Map();
76
+ nextSerial = 1;
77
+ evictions = 0;
78
+ hits = 0;
79
+ misses = 0;
80
+ constructor(maxBytes, pageTokens, bytesPerToken) {
81
+ this.maxBytes = maxBytes;
82
+ this.pageTokens = pageTokens;
83
+ this.bytesPerToken = bytesPerToken;
84
+ this.lru = new LruCache(maxBytes);
85
+ }
86
+ get pages() {
87
+ return this.lru.size;
88
+ }
89
+ get bytes() {
90
+ return this.lru.bytes;
91
+ }
92
+ lookup(compat, tokens) {
93
+ const compatKey = encodeCompatibilityKey(compat).key;
94
+ const pages = [];
95
+ let parent = chainHash(compatKey, []);
96
+ let parentSerial = 0;
97
+ let matched = 0;
98
+ while (matched < tokens.length) {
99
+ const slice = tokens.slice(matched, matched + this.pageTokens);
100
+ const page = this.residentPage(chainHash(parent, slice), compatKey, parent, parentSerial, slice);
101
+ if (page) {
102
+ pages.push(page);
103
+ matched += page.tokens.length;
104
+ parent = page.id;
105
+ parentSerial = page.serial;
106
+ if (page.tokens.length < this.pageTokens)
107
+ break;
108
+ continue;
109
+ }
110
+ const tail = this.longestTail(parent, parentSerial, compatKey, tokens, matched);
111
+ if (tail) {
112
+ pages.push(tail);
113
+ matched += tail.tokens.length;
114
+ }
115
+ break;
116
+ }
117
+ if (matched === 0) {
118
+ this.misses++;
119
+ return { matched: 0, pages: [], compatKey };
120
+ }
121
+ this.hits++;
122
+ return { matched, pages, compatKey };
123
+ }
124
+ /**
125
+ * Store (or extend) a sequence under a compatibility key. Pages covering
126
+ * tokens already resident are reused; new pages are inserted and may
127
+ * trigger LRU eviction of the least-recently-used pages.
128
+ */
129
+ put(compat, tokens) {
130
+ const compatKey = encodeCompatibilityKey(compat).key;
131
+ let parent = chainHash(compatKey, []);
132
+ let parentSerial = 0;
133
+ let evictedThis = 0;
134
+ for (let i = 0; i < tokens.length; i += this.pageTokens) {
135
+ const slice = tokens.slice(i, i + this.pageTokens);
136
+ const id = chainHash(parent, slice);
137
+ let page = this.residentPage(id, compatKey, parent, parentSerial, slice);
138
+ if (!page) {
139
+ page = {
140
+ id,
141
+ compatKey,
142
+ parentId: parent,
143
+ serial: this.nextSerial++,
144
+ parentSerial,
145
+ tokens: slice,
146
+ bytes: slice.length * this.bytesPerToken,
147
+ };
148
+ // A stale or colliding page under this id (verification failed above) is replaced.
149
+ this.forgetTail(id);
150
+ const evicted = this.lru.set(id, page, page.bytes);
151
+ this.evictions += evicted.length;
152
+ evictedThis += evicted.length;
153
+ this.dropEvicted(evicted);
154
+ if (!this.lru.has(id))
155
+ break; // A page that cannot fit ends the chain.
156
+ if (slice.length < this.pageTokens)
157
+ this.rememberTail(parent, id);
158
+ }
159
+ parent = id;
160
+ parentSerial = page.serial;
161
+ }
162
+ return { evicted: evictedThis };
163
+ }
164
+ clear() {
165
+ this.lru.clear();
166
+ this.tails.clear();
167
+ this.tailParent.clear();
168
+ this.evictions = 0;
169
+ this.hits = 0;
170
+ this.misses = 0;
171
+ }
172
+ /** A resident page whose identity is verified, touched as most recently used. */
173
+ residentPage(id, compatKey, parent, parentSerial, slice) {
174
+ const page = this.lru.peek(id);
175
+ if (!page || !this.childOf(page, compatKey, parent, parentSerial) || !sameTokens(page.tokens, slice)) {
176
+ return undefined;
177
+ }
178
+ this.lru.get(id);
179
+ return page;
180
+ }
181
+ childOf(page, compatKey, parent, parentSerial) {
182
+ return page.compatKey === compatKey && page.parentId === parent && page.parentSerial === parentSerial;
183
+ }
184
+ /** Longest resident partial page under `parent` whose tokens continue the query at `offset`. */
185
+ longestTail(parent, parentSerial, compatKey, tokens, offset) {
186
+ const ids = this.tails.get(parent);
187
+ if (!ids)
188
+ return undefined;
189
+ let best;
190
+ for (const id of ids) {
191
+ const page = this.lru.peek(id);
192
+ if (!page || !this.childOf(page, compatKey, parent, parentSerial))
193
+ continue;
194
+ if (!isPrefixOf(page.tokens, tokens, offset))
195
+ continue;
196
+ if (!best || page.tokens.length > best.tokens.length)
197
+ best = page;
198
+ }
199
+ if (best)
200
+ this.lru.get(best.id);
201
+ return best;
202
+ }
203
+ rememberTail(parent, id) {
204
+ let ids = this.tails.get(parent);
205
+ if (!ids) {
206
+ ids = new Set();
207
+ this.tails.set(parent, ids);
208
+ }
209
+ ids.add(id);
210
+ this.tailParent.set(id, parent);
211
+ }
212
+ forgetTail(id) {
213
+ const parent = this.tailParent.get(id);
214
+ if (parent === undefined)
215
+ return;
216
+ this.tailParent.delete(id);
217
+ const ids = this.tails.get(parent);
218
+ if (!ids)
219
+ return;
220
+ ids.delete(id);
221
+ if (ids.size === 0)
222
+ this.tails.delete(parent);
223
+ }
224
+ /**
225
+ * Evicted pages leave every index with them. A descendant of an evicted
226
+ * page stays resident until the LRU reaches it, but is unreachable: lookup
227
+ * stops at the first missing page, so it is a miss and recompute.
228
+ */
229
+ dropEvicted(ids) {
230
+ for (const id of ids)
231
+ this.forgetTail(id);
232
+ }
233
+ /** Number of tail-index entries (diagnostics / bound checks). */
234
+ get indexedTails() {
235
+ return this.tailParent.size;
236
+ }
237
+ }
238
+ //# sourceMappingURL=paged.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"paged.js","sourceRoot":"","sources":["../../src/kvcache/paged.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Phase 5 — quantization-aware execution.
3
+ *
4
+ * Picks the runtime format from `ModelRef.quantization` (`q4`|`q5`|`q8`|`fp16`)
5
+ * and avoids converting unless `preconvertQuant` is opted in. Conversion is
6
+ * never implicit: the native format is used unless a flag + target justify it.
7
+ */
8
+ import type { KvBackendKind, KvQuantization, QuantPlan } from './types.js';
9
+ export declare function nativeQuality(q: KvQuantization): number;
10
+ /**
11
+ * Decide the runtime quantization. Conversion is skipped unless
12
+ * `preconvert` is true AND the target is a strictly smaller format
13
+ * (justified by a bandwidth saving).
14
+ */
15
+ export declare function planQuantization(input: {
16
+ native: KvQuantization;
17
+ backend: KvBackendKind;
18
+ preconvert: boolean;
19
+ preconvertTo?: KvQuantization;
20
+ }): QuantPlan;
21
+ export declare function backendSupports(backend: KvBackendKind, q: KvQuantization): boolean;
22
+ export declare function bandwidthBytes(params: number, plan: QuantPlan, tokens: number, kvDim: number): number;
23
+ export declare const DEFAULT_QUALITY_TOLERANCE = 0.08;
24
+ export declare function defaultQualityScorer(input: {
25
+ output: string;
26
+ baselineOutput: string;
27
+ quantization: KvQuantization;
28
+ baselineQuantization: KvQuantization;
29
+ }): number;
30
+ //# sourceMappingURL=quant.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"quant.d.ts","sourceRoot":"","sources":["../../src/kvcache/quant.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAU3E,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,cAAc,CAAC;CAC/B,GAAG,SAAS,CAqBZ;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAIlF;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrG;AAED,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,cAAc,CAAC;IAC7B,oBAAoB,EAAE,cAAc,CAAC;CACtC,GAAG,MAAM,CAYT"}