@seanhogg/builderforce-webcontainers 2026.10.12 → 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 +127 -120
  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 +127 -120
  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,167 @@
1
+ /**
2
+ * Phase 5 — Advanced Model & KV Cache Optimization: shared types.
3
+ *
4
+ * Browser-compatible only: pure TypeScript, no native code, no dependencies.
5
+ * Decoupled from `src/inference/` (which only knows HOW to run) and from
6
+ * `src/adaptive/` (which only decides WHERE/HOW). This module owns KV reuse,
7
+ * quantization-aware execution, and gated advanced decode paths.
8
+ */
9
+
10
+ /** Quantization formats Phase 5 routes on. `fp16` is local to this module. */
11
+ export type KvQuantization = 'q4' | 'q5' | 'q8' | 'fp16';
12
+
13
+ /** Backend kinds a quant plan may target. Matches Phase 1 `BackendKind`. */
14
+ export type KvBackendKind = 'onnx' | 'wllama' | 'webllm' | 'mock';
15
+
16
+ /**
17
+ * Everything that MUST match before any KV state is reused.
18
+ * Semantic / approximate retrieval is intentionally NOT a match criterion.
19
+ */
20
+ export interface CompatibilityParts {
21
+ /** Model identity (id). */
22
+ modelId: string;
23
+ /** Weight-file / checksum identity. Different weights ⇒ no reuse. */
24
+ weightsHash: string;
25
+ /** Tokenizer identity (vocab + special-token layout). */
26
+ tokenizerId: string;
27
+ /** Positional encoding config, e.g. `rope:theta=10000:scale=1`. */
28
+ positionalConfig: string;
29
+ /** Attention config, e.g. `mha:heads=32:kvHeads=8:headDim=64`. */
30
+ attentionConfig: string;
31
+ }
32
+
33
+ /** Compatibility key with a canonical string form used as a map key. */
34
+ export interface CompatibilityKey extends CompatibilityParts {
35
+ /** Canonical encoding of the five parts. */
36
+ key: string;
37
+ }
38
+
39
+ export type OptimizationFlag =
40
+ | 'prefixCache'
41
+ | 'preconvertQuant'
42
+ | 'speculativeDecoding'
43
+ | 'continuousBatching'
44
+ | 'activationSparsity';
45
+
46
+ export interface AdvancedCapabilities {
47
+ speculativeDecoding: boolean;
48
+ continuousBatching: boolean;
49
+ activationSparsity: boolean;
50
+ /** Draft model present — required for speculative decoding. */
51
+ hasDraftModel: boolean;
52
+ /** Fraction of activations that are zero/skippable (0 = dense). */
53
+ sparsityFraction: number;
54
+ /**
55
+ * Model family. Architecture-specific opts are refused on incompatible
56
+ * families (e.g. speculative decoding is decoder-transformer only).
57
+ */
58
+ architecture: string;
59
+ }
60
+
61
+ export interface QuantPlan {
62
+ native: KvQuantization;
63
+ runtime: KvQuantization;
64
+ converted: boolean;
65
+ conversionCost: number;
66
+ bytesPerParam: number;
67
+ }
68
+
69
+ export interface KvModelRef {
70
+ id: string;
71
+ quantization: KvQuantization;
72
+ paramsB?: number;
73
+ weightsHash?: string;
74
+ }
75
+
76
+ export interface KvGenerateRequest {
77
+ tokens: number[];
78
+ /** Decode steps after prefill. Default 0. */
79
+ maxNewTokens?: number;
80
+ model: KvModelRef;
81
+ tokenizerId: string;
82
+ positionalConfig: string;
83
+ attentionConfig: string;
84
+ /**
85
+ * Session identifier. Compatible sessions SHARE the cache — this is
86
+ * deliberately NOT part of the compatibility key.
87
+ */
88
+ sessionId?: string;
89
+ /** Optional text used by an injectable quality scorer. */
90
+ output?: string;
91
+ baselineOutput?: string;
92
+ }
93
+
94
+ export interface KvGenerateResult {
95
+ output: string;
96
+ compatibilityKey: string;
97
+ cachedTokens: number;
98
+ computeTokens: number;
99
+ simulatedMs: number;
100
+ bandwidthBytes: number;
101
+ qualityScore: number;
102
+ withinTolerance: boolean;
103
+ servedFromCache: boolean;
104
+ optimizationsApplied: OptimizationFlag[];
105
+ evictedPages: number;
106
+ quantPlan: QuantPlan;
107
+ }
108
+
109
+ export type QualityScorer = (input: {
110
+ output: string;
111
+ baselineOutput: string;
112
+ quantization: KvQuantization;
113
+ baselineQuantization: KvQuantization;
114
+ }) => number;
115
+
116
+ export interface KvCostModel {
117
+ cacheHitPerToken: number;
118
+ computePerToken: number;
119
+ conversionPerToken: number;
120
+ draftPerToken: number;
121
+ verifyPerToken: number;
122
+ }
123
+
124
+ export interface KvCacheStats {
125
+ hits: number;
126
+ misses: number;
127
+ pages: number;
128
+ bytes: number;
129
+ evictions: number;
130
+ /** Distinct recently seen session ids (bounded by `maxSessions`). */
131
+ sessions: number;
132
+ }
133
+
134
+ export interface KvCacheRuntimeOptions {
135
+ maxBytes?: number;
136
+ pageTokens?: number;
137
+ flags?: Partial<Record<OptimizationFlag, boolean>>;
138
+ capabilities?: Partial<AdvancedCapabilities>;
139
+ qualityScorer?: QualityScorer;
140
+ qualityBaseline?: KvQuantization;
141
+ qualityTolerance?: number;
142
+ now?: () => number;
143
+ costs?: Partial<KvCostModel>;
144
+ layers?: number;
145
+ kvDim?: number;
146
+ /** Draft-token block size when speculative decoding is active. */
147
+ draftLen?: number;
148
+ /** 0..1 fraction of draft tokens accepted (injected; tests set 1). */
149
+ draftAccuracy?: number;
150
+ /** Target format when `preconvertQuant` is on. Default `q4`. */
151
+ preconvertTo?: KvQuantization;
152
+ /**
153
+ * Distinct session ids remembered for `stats().sessions`, least recently
154
+ * seen forgotten first. Default 1024.
155
+ */
156
+ maxSessions?: number;
157
+ }
158
+
159
+ export interface KvCacheRuntime {
160
+ generate(request: KvGenerateRequest): Promise<KvGenerateResult>;
161
+ generateBatch(requests: KvGenerateRequest[]): Promise<KvGenerateResult[]>;
162
+ lookup(request: KvGenerateRequest): { matched: number; key: string };
163
+ setEnabled(flag: OptimizationFlag, enabled: boolean): void;
164
+ isEnabled(flag: OptimizationFlag): boolean;
165
+ stats(): KvCacheStats;
166
+ clear(): void;
167
+ }
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Phase 7 — workload fingerprinting.
3
+ *
4
+ * Buckets a workload into a stable signature (the learner's table key) and
5
+ * maps a Phase 2 `ExecutionOutcome` into an observation. Type-only coupling to
6
+ * the adaptive controller: nothing here imports or calls it.
7
+ */
8
+
9
+ import type { ExecutionOutcome } from '../adaptive/types.js';
10
+ import type { OutcomeObservation, WorkloadFingerprintInput } from './types.js';
11
+
12
+ function bucket(value: number, edges: readonly number[]): string {
13
+ let lower = 0;
14
+ for (const edge of edges) {
15
+ if (value < edge) return `${lower}-${edge}`;
16
+ lower = edge;
17
+ }
18
+ const last = edges[edges.length - 1] ?? 0;
19
+ return `${last}+`;
20
+ }
21
+
22
+ /** Stable signature for a workload. Same buckets always produce the same key. */
23
+ export function fingerprintWorkload(input: WorkloadFingerprintInput): string {
24
+ const params = bucket(input.paramsB ?? 0, [1, 3, 8]);
25
+ const prompt = bucket(input.promptTokens ?? 0, [128, 512, 2048]);
26
+ const decode = bucket(input.decodeTokens ?? 0, [64, 256, 1024]);
27
+ const quant = input.quantization && input.quantization.length > 0 ? input.quantization : 'unknown';
28
+ return `p${params}|q:${quant}|prompt:${prompt}|decode:${decode}`;
29
+ }
30
+
31
+ /**
32
+ * Map a Phase 2 `ExecutionOutcome` into an observation. Type-only coupling:
33
+ * this does not import the controller, and it does not apply anything.
34
+ */
35
+ export function observationFromExecution(outcome: ExecutionOutcome, correct = true): OutcomeObservation {
36
+ const workload = outcome.decision.workload;
37
+ return {
38
+ signature: fingerprintWorkload({
39
+ paramsB: workload.paramsB,
40
+ quantization: workload.quantization,
41
+ promptTokens: workload.promptTokens,
42
+ decodeTokens: workload.decodeTokens,
43
+ }),
44
+ strategy: outcome.decision.plan.strategy,
45
+ costMs: outcome.measuredCostMs,
46
+ overheadMs: outcome.overheadMs,
47
+ benefitMs: outcome.benefitMs,
48
+ correct,
49
+ };
50
+ }
@@ -0,0 +1,15 @@
1
+ export { createLearner, fingerprintWorkload, observationFromExecution } from './learner.js';
2
+ export { emptyStat, observeStat, ucb1, variance } from './stats.js';
3
+ export type { RunningStat } from './stats.js';
4
+ export type {
5
+ ConfigDeltaField,
6
+ HistoryEntry,
7
+ Learner,
8
+ LearnerConfig,
9
+ LearningStats,
10
+ ObserveResult,
11
+ OutcomeObservation,
12
+ Recommendation,
13
+ SafeStrategy,
14
+ WorkloadFingerprintInput,
15
+ } from './types.js';
@@ -0,0 +1,304 @@
1
+ /**
2
+ * Phase 7 — Online Performance Learning.
3
+ *
4
+ * Feedback-driven strategy selection. Every output is a plain-data delta plus
5
+ * a reason. Nothing in this module mutates another phase: the caller decides
6
+ * whether to apply a suggestion. Learning is limited to strategies registered
7
+ * as prevalidated, and an observation flagged incorrect is dropped so a bad
8
+ * run cannot teach a strategy that changed correctness.
9
+ *
10
+ * Default policy is epsilon-greedy over per-strategy running means (explainable).
11
+ * UCB1 is opt-in via `contextualBandit` and only consults arms that already
12
+ * have a row in the table.
13
+ *
14
+ * This file composes: selection.ts (pool, exploit/explore, UCB1, the ONE
15
+ * auto-revert rule) · ledger.ts (apply / rollback, bounded history) ·
16
+ * fingerprint.ts (workload signatures) · stats.ts (running means).
17
+ */
18
+
19
+ import { now as clockNow } from '../shared/clock.js';
20
+ import { copyDeltas, createChangeLedger } from './ledger.js';
21
+ import { banditPick, candidatePool, exploit, explore, revertCheck, type StrategyPick } from './selection.js';
22
+ import { emptyStat, observeStat, type RunningStat } from './stats.js';
23
+ import type {
24
+ HistoryEntry,
25
+ Learner,
26
+ LearnerConfig,
27
+ LearningStats,
28
+ ObserveResult,
29
+ Recommendation,
30
+ SafeStrategy,
31
+ } from './types.js';
32
+
33
+ export { fingerprintWorkload, observationFromExecution } from './fingerprint.js';
34
+
35
+ const DEFAULT_EPSILON = 0.1;
36
+ const DEFAULT_MIN_SAMPLES = 3;
37
+ const DEFAULT_UNDERPERFORM_RATIO = 1.15;
38
+ const DEFAULT_HISTORY_LIMIT = 256;
39
+
40
+ export function createLearner(config: LearnerConfig = {}): Learner {
41
+ const strategies = new Map<string, SafeStrategy>();
42
+ const table = new Map<string, Map<string, RunningStat>>();
43
+ const incumbentOf = new Map<string, string>();
44
+ const ledger = createChangeLedger(config.historyLimit ?? DEFAULT_HISTORY_LIMIT);
45
+ const rng = config.rng ?? Math.random;
46
+ const now = config.now ?? clockNow;
47
+ const clock = config.clock ?? (() => Date.now());
48
+ const epsilon = config.epsilon ?? DEFAULT_EPSILON;
49
+ const minSamples = config.minSamples ?? DEFAULT_MIN_SAMPLES;
50
+ const underperformRatio = config.underperformRatio ?? DEFAULT_UNDERPERFORM_RATIO;
51
+ const bandit = config.contextualBandit ?? false;
52
+
53
+ let disabled = config.disabled ?? false;
54
+ let observations = 0;
55
+ let ignored = 0;
56
+ let decisions = 0;
57
+ let lastOverheadMs = 0;
58
+ let totalOverheadMs = 0;
59
+ let lastRevertReason = '';
60
+ let recStart = 0;
61
+
62
+ function statFor(signature: string, strategy: string): RunningStat {
63
+ let row = table.get(signature);
64
+ if (!row) {
65
+ row = new Map();
66
+ table.set(signature, row);
67
+ }
68
+ let stat = row.get(strategy);
69
+ if (!stat) {
70
+ stat = emptyStat();
71
+ row.set(strategy, stat);
72
+ }
73
+ return stat;
74
+ }
75
+
76
+ function underPressure(): boolean {
77
+ if (config.pressure?.()) return true;
78
+ return config.thermal?.() === 'hot';
79
+ }
80
+
81
+ function finish(rec: Omit<Recommendation, 'overheadMs'>): Recommendation {
82
+ const overheadMs = Math.max(0, now() - recStart);
83
+ lastOverheadMs = overheadMs;
84
+ totalOverheadMs += overheadMs;
85
+ decisions += 1;
86
+ return { ...rec, overheadMs };
87
+ }
88
+
89
+ function revertReason(signature: string, candidate: string, baseline: string): string | undefined {
90
+ return revertCheck({ row: table.get(signature), candidate, baseline, minSamples, underperformRatio });
91
+ }
92
+
93
+ /** Revert the applied strategy for `signature` when it measurably underperforms its incumbent. */
94
+ function maybeAutoRevert(signature: string): boolean {
95
+ const current = ledger.active(signature);
96
+ const previous = incumbentOf.get(signature);
97
+ if (!current || !previous) return false;
98
+ const reason = revertReason(signature, current, previous);
99
+ if (!reason) return false;
100
+ ledger.record({
101
+ signature,
102
+ from: current,
103
+ to: previous,
104
+ reason,
105
+ deltas: copyDeltas(strategies.get(previous)?.deltas),
106
+ overheadMs: 0,
107
+ at: clock(),
108
+ auto: true,
109
+ });
110
+ lastRevertReason = reason;
111
+ return true;
112
+ }
113
+
114
+ function selectStrategy(signature: string, incumbent: string, pool: readonly string[]): StrategyPick {
115
+ const row = table.get(signature);
116
+ if (bandit) return banditPick(row, incumbent, pool);
117
+ if (rng() < epsilon) {
118
+ const explored = explore(pool, incumbent, rng);
119
+ return {
120
+ strategy: explored,
121
+ reason:
122
+ explored === incumbent
123
+ ? `epsilon-greedy explored but no alternative to ${incumbent} is available`
124
+ : `epsilon-greedy exploring prevalidated strategy ${explored} (ε=${epsilon})`,
125
+ };
126
+ }
127
+ return exploit(row, incumbent, pool, minSamples);
128
+ }
129
+
130
+ function applyPressure(picked: StrategyPick, incumbent: string, pool: readonly string[]): StrategyPick {
131
+ if (strategies.get(picked.strategy)?.pressureSensitive) {
132
+ return {
133
+ strategy: incumbent,
134
+ reason: `pressure/thermal hot — not recommending pressure-sensitive ${picked.strategy}; staying with ${incumbent}`,
135
+ };
136
+ }
137
+ if (picked.strategy !== incumbent) {
138
+ return { ...picked, reason: `${picked.reason}; pressure/thermal excluded pressure-sensitive strategies` };
139
+ }
140
+ if (pool.every((id) => id === incumbent || !strategies.get(id)?.pressureSensitive) && !picked.reason.includes('pressure')) {
141
+ return { ...picked, reason: `${picked.reason}; pressure/thermal hot, pressure-sensitive strategies excluded` };
142
+ }
143
+ return picked;
144
+ }
145
+
146
+ function recommendBody(signature: string, incumbent: string): Recommendation {
147
+ if (!incumbentOf.has(signature)) incumbentOf.set(signature, incumbent);
148
+ const passThrough = (reason: string) =>
149
+ finish({ signature, strategy: incumbent, from: incumbent, reason, deltas: [], autoReverted: false });
150
+
151
+ if (disabled) return passThrough('learning disabled — pass-through');
152
+ if (!strategies.has(incumbent)) {
153
+ return passThrough(`refusing to switch: incumbent ${incumbent} is not a registered prevalidated strategy`);
154
+ }
155
+
156
+ const reverted = maybeAutoRevert(signature);
157
+ const active = ledger.active(signature);
158
+ if (reverted && active) {
159
+ return finish({
160
+ signature,
161
+ strategy: active,
162
+ from: incumbent,
163
+ reason: lastRevertReason,
164
+ deltas: copyDeltas(strategies.get(active)?.deltas),
165
+ autoReverted: true,
166
+ });
167
+ }
168
+
169
+ const pressured = underPressure();
170
+ const pool = candidatePool(strategies, incumbent, pressured);
171
+ let picked = selectStrategy(signature, incumbent, pool);
172
+ if (pressured) picked = applyPressure(picked, incumbent, pool);
173
+
174
+ // Guard at decision time too: do not recommend a measured underperformer.
175
+ const baseId = incumbentOf.get(signature) ?? incumbent;
176
+ const revert = revertReason(signature, picked.strategy, baseId);
177
+ if (revert) {
178
+ picked = { strategy: baseId, reason: revert };
179
+ lastRevertReason = revert;
180
+ }
181
+
182
+ return finish({
183
+ signature,
184
+ strategy: picked.strategy,
185
+ from: incumbent,
186
+ reason: picked.reason,
187
+ deltas: picked.strategy === incumbent ? [] : copyDeltas(strategies.get(picked.strategy)?.deltas),
188
+ autoReverted: revert !== undefined,
189
+ });
190
+ }
191
+
192
+ const learner: Learner = {
193
+ register(strategy) {
194
+ if (strategy.validated !== true || !strategy.id) {
195
+ throw new Error(`refusing unvalidated strategy: ${strategy.id || '(missing id)'}`);
196
+ }
197
+ strategies.set(strategy.id, {
198
+ id: strategy.id,
199
+ validated: true,
200
+ deltas: copyDeltas(strategy.deltas),
201
+ pressureSensitive: strategy.pressureSensitive ?? false,
202
+ });
203
+ },
204
+
205
+ observe(observation): ObserveResult {
206
+ if (!strategies.has(observation.strategy)) {
207
+ throw new Error(`refusing observation for unregistered strategy: ${observation.strategy}`);
208
+ }
209
+ if (observation.correct === false) {
210
+ ignored += 1;
211
+ return { accepted: false, reason: 'ignored: correctness flag false — learning will not train on a run that changed correctness' };
212
+ }
213
+ if (!Number.isFinite(observation.costMs) || observation.costMs < 0) {
214
+ ignored += 1;
215
+ return { accepted: false, reason: 'ignored: costMs must be a finite non-negative number' };
216
+ }
217
+ observeStat(statFor(observation.signature, observation.strategy), observation.costMs);
218
+ observations += 1;
219
+ maybeAutoRevert(observation.signature);
220
+ return { accepted: true, reason: 'recorded' };
221
+ },
222
+
223
+ recommend(signature, incumbent) {
224
+ recStart = now();
225
+ return recommendBody(signature, incumbent);
226
+ },
227
+
228
+ apply(recommendation) {
229
+ if (disabled) return null;
230
+ if (!incumbentOf.has(recommendation.signature)) {
231
+ incumbentOf.set(recommendation.signature, recommendation.from);
232
+ }
233
+ if (recommendation.strategy === recommendation.from && !recommendation.autoReverted) {
234
+ ledger.setActive(recommendation.signature, recommendation.strategy);
235
+ return null;
236
+ }
237
+ const entry: HistoryEntry = {
238
+ signature: recommendation.signature,
239
+ from: recommendation.from,
240
+ to: recommendation.strategy,
241
+ reason: recommendation.reason,
242
+ deltas: copyDeltas(recommendation.deltas),
243
+ overheadMs: recommendation.overheadMs,
244
+ at: clock(),
245
+ auto: recommendation.autoReverted,
246
+ };
247
+ ledger.record(entry);
248
+ return entry;
249
+ },
250
+
251
+ rollback() {
252
+ const last = ledger.popLast();
253
+ if (!last) return null;
254
+ return {
255
+ signature: last.signature,
256
+ from: last.to,
257
+ to: last.from,
258
+ reason: `rollback: ${last.reason}`,
259
+ deltas: copyDeltas(strategies.get(last.from)?.deltas),
260
+ overheadMs: 0,
261
+ at: clock(),
262
+ auto: false,
263
+ };
264
+ },
265
+
266
+ history() {
267
+ return ledger.history();
268
+ },
269
+
270
+ active(signature) {
271
+ return ledger.active(signature);
272
+ },
273
+
274
+ overheadMs() {
275
+ return lastOverheadMs;
276
+ },
277
+
278
+ stats(): LearningStats {
279
+ return {
280
+ decisions,
281
+ observations,
282
+ ignored,
283
+ lastOverheadMs,
284
+ totalOverheadMs,
285
+ disabled,
286
+ meanOverheadMs: decisions === 0 ? 0 : totalOverheadMs / decisions,
287
+ };
288
+ },
289
+
290
+ disable() {
291
+ disabled = true;
292
+ },
293
+
294
+ enable() {
295
+ disabled = false;
296
+ },
297
+
298
+ get disabled() {
299
+ return disabled;
300
+ },
301
+ };
302
+
303
+ return learner;
304
+ }
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Phase 7 — the learner's apply / rollback ledger.
3
+ *
4
+ * Records which strategy is applied per signature and the bounded history of
5
+ * changes, so the last change can be rolled back. Recording a change never
6
+ * mutates another module; the deltas are copied plain data.
7
+ *
8
+ * History is capped (`limit`, oldest dropped first): rollback reaches back at
9
+ * most `limit` changes, and a long-running learner cannot grow without bound.
10
+ */
11
+
12
+ import type { ConfigDeltaField, HistoryEntry } from './types.js';
13
+
14
+ export function copyDeltas(deltas: ReadonlyArray<ConfigDeltaField> | undefined): ConfigDeltaField[] {
15
+ if (!deltas) return [];
16
+ return deltas.map((d) => ({ field: d.field, value: d.value }));
17
+ }
18
+
19
+ export interface ChangeLedger {
20
+ /** Strategy currently recorded as applied for `signature`. */
21
+ active(signature: string): string | undefined;
22
+ /** Record `strategy` as applied without a history entry (no change happened). */
23
+ setActive(signature: string, strategy: string): void;
24
+ /** Record a change: append history (bounded) and mark `entry.to` applied. */
25
+ record(entry: HistoryEntry): void;
26
+ /** Remove the last change and restore its `from`. Undefined when history is empty. */
27
+ popLast(): HistoryEntry | undefined;
28
+ /** Live, bounded history, oldest first. */
29
+ history(): readonly HistoryEntry[];
30
+ }
31
+
32
+ export function createChangeLedger(limit: number): ChangeLedger {
33
+ const cap = Math.max(1, limit);
34
+ const applied = new Map<string, string>();
35
+ const history: HistoryEntry[] = [];
36
+
37
+ return {
38
+ active: (signature) => applied.get(signature),
39
+ setActive(signature, strategy) {
40
+ applied.set(signature, strategy);
41
+ },
42
+ record(entry) {
43
+ history.push(entry);
44
+ if (history.length > cap) history.splice(0, history.length - cap);
45
+ applied.set(entry.signature, entry.to);
46
+ },
47
+ popLast() {
48
+ const last = history.pop();
49
+ if (last) applied.set(last.signature, last.from);
50
+ return last;
51
+ },
52
+ history: () => history,
53
+ };
54
+ }