@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,380 @@
1
+ /**
2
+ * Phase 3 — residency manager.
3
+ *
4
+ * Admits model weights and per-layer components into a hard byte budget,
5
+ * evicts with an injected strategy when the budget (or a quota) would be
6
+ * exceeded, spills cold entries to a browser-storage sink, and grows or
7
+ * shrinks a workspace under pressure.
8
+ *
9
+ * Decoupled from execution: nothing here calls an inference backend or decides
10
+ * when to run. The controller reads `pressure()` / `stats()` if it wants a
11
+ * residency hint; this module never calls the controller.
12
+ *
13
+ * Invariants:
14
+ * - `stats().usedBytes <= config.byteBudget` after every public call.
15
+ * - Eviction is transactional: entries are dropped only once the admission
16
+ * is known to fit. A rejected admission leaves every resident untouched.
17
+ * - Eviction drops whole entries. It never mutates another entry's payload,
18
+ * so an in-use entry stays consistent.
19
+ * - Pinned entries are never evicted. An admission that cannot fit even
20
+ * after evicting every unpinned resident is spilled (when a sink and a
21
+ * storage budget allow) or rejected — it is never allowed to exceed the
22
+ * RAM budget.
23
+ * - Spilled bytes (including concurrent spills), strategy ghost state, and
24
+ * the event log are all bounded.
25
+ *
26
+ * The concerns live in their own modules: victims.ts (victim selection +
27
+ * quota accounting), spillTier.ts (the storage tier), workspace.ts (the
28
+ * dynamic workspace), envProbe.ts (RAM / storage facts).
29
+ */
30
+
31
+ import type {
32
+ EvictionStrategy,
33
+ MemoryPressure,
34
+ ResidencyEvent,
35
+ ResidentEntry,
36
+ TrackedEntry,
37
+ } from './types.js';
38
+ import { probeRamBytes } from './envProbe.js';
39
+ import { costAwareStrategy } from './eviction.js';
40
+ import type { AdmitResult, MemoryManager, MemoryManagerOptions } from './managerTypes.js';
41
+ import { detectPressure } from './pressure.js';
42
+ import { createSpillTier, resolveStorageBudget } from './spillTier.js';
43
+ import { selectVictims } from './victims.js';
44
+ import { createWorkspaceController } from './workspace.js';
45
+
46
+ export { probeRamBytes, probeStorageQuotaBytes } from './envProbe.js';
47
+ export type { AdmitResult, MemoryManager, MemoryManagerOptions } from './managerTypes.js';
48
+
49
+ const DEFAULT_PRESSURE = 0.85;
50
+ const DEFAULT_WATERMARK = 0.7;
51
+ const DEFAULT_EVENT_LIMIT = 256;
52
+
53
+ export function createMemoryManager(options: MemoryManagerOptions): MemoryManager {
54
+ if (!(options.byteBudget > 0) || !Number.isFinite(options.byteBudget)) {
55
+ throw new Error('createMemoryManager: byteBudget must be a finite number > 0');
56
+ }
57
+ const byteBudget = options.byteBudget;
58
+ const strategy: EvictionStrategy = options.strategy ?? costAwareStrategy();
59
+ const pressureThreshold = options.pressureThreshold ?? DEFAULT_PRESSURE;
60
+ const targetWatermark = Math.min(pressureThreshold, options.targetWatermark ?? DEFAULT_WATERMARK);
61
+ const eventLogLimit = options.eventLogLimit ?? DEFAULT_EVENT_LIMIT;
62
+ const now = options.now ?? (() => Date.now());
63
+ const ramBytes = options.ramBytes ?? probeRamBytes();
64
+ const vramBytes = Math.max(0, options.vramBudgetBytes ?? 0);
65
+ const storageQuotaBytes = options.storageQuotaBytes ?? 0;
66
+ const quotas = options.quotas ?? [];
67
+
68
+ const residents = new Map<string, TrackedEntry>();
69
+ const log: ResidencyEvent[] = [];
70
+ let residentTotal = 0;
71
+ let seq = 0;
72
+ let hits = 0;
73
+ let misses = 0;
74
+ let admissions = 0;
75
+ let evictions = 0;
76
+ let spills = 0;
77
+ let reloads = 0;
78
+
79
+ const spill = createSpillTier({
80
+ storage: options.storage,
81
+ budgetBytes: resolveStorageBudget(options.storageBudgetBytes, storageQuotaBytes, byteBudget),
82
+ now,
83
+ onSpill(entry, reason) {
84
+ spills += 1;
85
+ record({ kind: 'spill', id: entry.id, bytes: entry.bytes, reason });
86
+ },
87
+ });
88
+ const workspace = createWorkspaceController({
89
+ bounds: {
90
+ minBytes: Math.max(0, options.workspace?.minBytes ?? 0),
91
+ maxBytes: Math.max(0, options.workspace?.maxBytes ?? 0),
92
+ },
93
+ byteBudget,
94
+ initialBytes: options.workspace?.initialBytes,
95
+ });
96
+
97
+ function putResident(entry: TrackedEntry): void {
98
+ const previous = residents.get(entry.id);
99
+ if (previous) residentTotal -= previous.bytes;
100
+ residents.set(entry.id, entry);
101
+ residentTotal += entry.bytes;
102
+ }
103
+
104
+ function removeResident(id: string): void {
105
+ const previous = residents.get(id);
106
+ if (!previous) return;
107
+ residents.delete(id);
108
+ residentTotal -= previous.bytes;
109
+ }
110
+
111
+ function usedBytes(): number {
112
+ return residentTotal + workspace.bytes();
113
+ }
114
+
115
+ function record(event: Omit<ResidencyEvent, 'at'>): void {
116
+ log.push({ ...event, at: now() });
117
+ if (log.length > eventLogLimit) log.splice(0, log.length - eventLogLimit);
118
+ }
119
+
120
+ function pressureNow(): MemoryPressure {
121
+ return detectPressure({
122
+ usedBytes: usedBytes(),
123
+ byteBudget,
124
+ pressureThreshold,
125
+ targetWatermark,
126
+ ramBytes,
127
+ vramBytes,
128
+ storageQuotaBytes,
129
+ });
130
+ }
131
+
132
+ function applyWorkspace(onHit: boolean): void {
133
+ const change = workspace.apply({ onHit, pressure: pressureNow(), residentBytes: residentTotal });
134
+ if (change) record(change);
135
+ }
136
+
137
+ function drop(entry: TrackedEntry, reason: string): void {
138
+ removeResident(entry.id);
139
+ evictions += 1;
140
+ strategy.observe?.({ kind: 'evict', entry });
141
+ record({ kind: 'evict', id: entry.id, bytes: entry.bytes, reason });
142
+ }
143
+
144
+ function placeTier(entry: ResidentEntry): ResidentEntry['tier'] {
145
+ // VRAM is a hint. Only place there when a budget was configured and the
146
+ // caller asked for it. CPU-only (vramBudgetBytes = 0) always stays in RAM.
147
+ if (entry.tier === 'vram' && vramBytes > 0) return 'vram';
148
+ return 'ram';
149
+ }
150
+
151
+ function rate(): number {
152
+ const total = hits + misses;
153
+ return total === 0 ? 0 : hits / total;
154
+ }
155
+
156
+ function notAdmitted(spilledOk: boolean, spilledReason: string, rejectedReason: string): AdmitResult {
157
+ return {
158
+ admitted: false,
159
+ spilled: spilledOk,
160
+ replaced: false,
161
+ evicted: [],
162
+ reason: spilledOk ? spilledReason : rejectedReason,
163
+ };
164
+ }
165
+
166
+ const manager: MemoryManager = {
167
+ async admit(entry, admitOptions) {
168
+ if (!(entry.bytes >= 0) || !Number.isFinite(entry.bytes)) {
169
+ return { admitted: false, spilled: false, replaced: false, evicted: [], reason: 'invalid footprint' };
170
+ }
171
+ const wantSpill = admitOptions?.spill !== false && spill.enabled;
172
+
173
+ if (entry.bytes > byteBudget) {
174
+ const spilledOk = wantSpill && await spill.retain(entry, 'entry exceeds the hard byte budget');
175
+ return notAdmitted(spilledOk, 'spilled: entry larger than byte budget', 'rejected: entry larger than byte budget');
176
+ }
177
+
178
+ const existing = residents.get(entry.id);
179
+ const except = new Set<string>();
180
+ if (existing) except.add(existing.id);
181
+ const victims = selectVictims({
182
+ incoming: entry,
183
+ residents: residents.values(),
184
+ except,
185
+ strategy,
186
+ quotas,
187
+ byteBudget,
188
+ workspaceBytes: workspace.bytes(),
189
+ });
190
+ if (!victims) {
191
+ // Nothing was dropped. Spill or reject, leaving every resident intact.
192
+ const spilledOk = wantSpill && await spill.retain(entry, 'pinned residents fill the budget');
193
+ return notAdmitted(spilledOk, 'spilled: budget held by pinned residents', 'rejected: budget held by pinned residents');
194
+ }
195
+
196
+ // RAM mutations are synchronous and finish before any storage await, so a
197
+ // second admit cannot observe a half-applied eviction or an over-budget map.
198
+ const spilledVictims: TrackedEntry[] = [];
199
+ for (const victim of victims) {
200
+ const live = residents.get(victim.id);
201
+ if (!live) continue;
202
+ drop(live, `make room for ${entry.id}`);
203
+ spilledVictims.push(live);
204
+ }
205
+ if (existing) removeResident(existing.id);
206
+
207
+ const tick = ++seq;
208
+ const tracked: TrackedEntry = {
209
+ ...entry,
210
+ tier: placeTier(entry),
211
+ pinned: admitOptions?.pin === true || entry.pinned === true,
212
+ admittedAt: existing?.admittedAt ?? tick,
213
+ lastUsedAt: tick,
214
+ hits: 0,
215
+ arcList: 't1',
216
+ };
217
+ putResident(tracked);
218
+ // The index entry is dropped synchronously; the sink delete is awaited below.
219
+ const forgettingPriorSpill = spill.forget(entry.id);
220
+ admissions += 1;
221
+ strategy.observe?.({ kind: 'admit', entry: tracked });
222
+ record({
223
+ kind: 'admit',
224
+ id: entry.id,
225
+ bytes: entry.bytes,
226
+ reason: victims.length > 0 ? `admitted after evicting ${victims.length}` : 'admitted within budget',
227
+ });
228
+
229
+ await forgettingPriorSpill;
230
+ if (wantSpill) {
231
+ for (const live of spilledVictims) {
232
+ await spill.retain(live, `evicted to make room for ${entry.id}`);
233
+ }
234
+ }
235
+
236
+ const reading = pressureNow();
237
+ if (reading.pressured) {
238
+ record({
239
+ kind: 'pressure',
240
+ bytes: reading.reclaimBytes,
241
+ reason: `utilization ${(reading.utilization * 100).toFixed(1)}%`,
242
+ });
243
+ applyWorkspace(false);
244
+ }
245
+
246
+ return {
247
+ admitted: true,
248
+ spilled: false,
249
+ replaced: existing !== undefined,
250
+ evicted: victims,
251
+ reason: victims.length > 0 ? `evicted ${victims.length} to fit` : 'fit within budget',
252
+ };
253
+ },
254
+
255
+ get(id) {
256
+ const entry = residents.get(id);
257
+ if (!entry) {
258
+ misses += 1;
259
+ const spilled = spill.get(id);
260
+ const ghost: TrackedEntry = {
261
+ id,
262
+ group: spilled?.group ?? '',
263
+ component: spilled?.component,
264
+ bytes: spilled?.bytes ?? 0,
265
+ reloadCostMs: spilled?.reloadCostMs ?? 0,
266
+ reuseProbability: spilled?.reuseProbability ?? 0,
267
+ tier: 'storage',
268
+ admittedAt: 0,
269
+ lastUsedAt: 0,
270
+ hits: 0,
271
+ };
272
+ strategy.observe?.({ kind: 'miss', entry: ghost });
273
+ record({ kind: 'miss', id, reason: spilled ? 'miss: spilled to storage' : 'miss: not resident' });
274
+ return { hit: false };
275
+ }
276
+ const tick = ++seq;
277
+ const touched: TrackedEntry = {
278
+ ...entry,
279
+ lastUsedAt: tick,
280
+ hits: entry.hits + 1,
281
+ arcList: entry.hits + 1 > 1 ? 't2' : 't1',
282
+ };
283
+ putResident(touched);
284
+ hits += 1;
285
+ strategy.observe?.({ kind: 'hit', entry: touched });
286
+ record({ kind: 'hit', id, reason: `hit #${touched.hits}` });
287
+ applyWorkspace(true);
288
+ return { hit: true, entry: snapshot(touched) };
289
+ },
290
+
291
+ hitRate() {
292
+ return rate();
293
+ },
294
+
295
+ async reload(id) {
296
+ const already = residents.get(id);
297
+ if (already) return { hit: true, entry: snapshot(already) };
298
+ const restored = spill.has(id) ? await spill.reload(id) : undefined;
299
+ if (!restored) {
300
+ misses += 1;
301
+ return { hit: false };
302
+ }
303
+ const result = await manager.admit(restored, { spill: false });
304
+ if (!result.admitted) {
305
+ misses += 1;
306
+ return { hit: false };
307
+ }
308
+ reloads += 1;
309
+ record({ kind: 'reload', id, reason: 'reloaded from browser storage' });
310
+ const entry = residents.get(id);
311
+ return entry ? { hit: true, entry: snapshot(entry) } : { hit: false };
312
+ },
313
+
314
+ pin(id) {
315
+ const entry = residents.get(id);
316
+ if (!entry) return false;
317
+ putResident({ ...entry, pinned: true });
318
+ record({ kind: 'pin', id, reason: 'pinned' });
319
+ return true;
320
+ },
321
+
322
+ unpin(id) {
323
+ const entry = residents.get(id);
324
+ if (!entry) return false;
325
+ putResident({ ...entry, pinned: false });
326
+ record({ kind: 'unpin', id, reason: 'unpinned' });
327
+ return true;
328
+ },
329
+
330
+ async release(id) {
331
+ const entry = residents.get(id);
332
+ if (entry) {
333
+ drop(entry, 'released');
334
+ return true;
335
+ }
336
+ return spill.forget(id);
337
+ },
338
+
339
+ pressure() {
340
+ return pressureNow();
341
+ },
342
+
343
+ stats() {
344
+ return {
345
+ hits,
346
+ misses,
347
+ admissions,
348
+ evictions,
349
+ spills,
350
+ reloads,
351
+ usedBytes: usedBytes(),
352
+ byteBudget,
353
+ workspaceBytes: workspace.bytes(),
354
+ residentCount: residents.size,
355
+ spilledCount: spill.count,
356
+ spilledBytes: spill.bytes(),
357
+ hitRate: rate(),
358
+ };
359
+ },
360
+
361
+ events() {
362
+ return log;
363
+ },
364
+
365
+ residentIds() {
366
+ return [...residents.keys()];
367
+ },
368
+
369
+ peek(id) {
370
+ const entry = residents.get(id);
371
+ return entry ? snapshot(entry) : undefined;
372
+ },
373
+ };
374
+
375
+ return manager;
376
+ }
377
+
378
+ function snapshot(entry: TrackedEntry): TrackedEntry {
379
+ return { ...entry };
380
+ }
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Phase 3 — the residency manager's public surface. Re-exported from
3
+ * `manager.ts`, which stays the entry file; kept here so the implementation
4
+ * file holds only behaviour.
5
+ */
6
+
7
+ import type { StorageSink } from './storageSink.js';
8
+ import type {
9
+ AdmitOptions,
10
+ LookupResult,
11
+ MemoryManagerConfig,
12
+ MemoryPressure,
13
+ ResidencyEvent,
14
+ ResidencyStats,
15
+ ResidentEntry,
16
+ TrackedEntry,
17
+ } from './types.js';
18
+
19
+ export interface MemoryManager {
20
+ /** Admit an entry, evicting or spilling as needed to honor the hard budget. */
21
+ admit(entry: ResidentEntry, options?: AdmitOptions): Promise<AdmitResult>;
22
+ /** Touch an entry. A hit updates recency and frequency and may grow the workspace. */
23
+ get(id: string): LookupResult;
24
+ /** hits / (hits + misses). 0 before the first lookup. */
25
+ hitRate(): number;
26
+ /** Reload a spilled entry back into RAM, charging the budget. */
27
+ reload(id: string): Promise<LookupResult>;
28
+ /** Pin an entry so eviction cannot drop it. */
29
+ pin(id: string): boolean;
30
+ /** Release a pin. */
31
+ unpin(id: string): boolean;
32
+ /** Drop one entry. Returns true if it was resident or spilled. */
33
+ release(id: string): Promise<boolean>;
34
+ /** Current pressure reading. */
35
+ pressure(): MemoryPressure;
36
+ /** Aggregate counters, including `hitRate`. */
37
+ stats(): ResidencyStats;
38
+ /** Explainable event log, oldest first, bounded by `eventLogLimit`. */
39
+ events(): readonly ResidencyEvent[];
40
+ /** Ids currently charged against the budget. */
41
+ residentIds(): string[];
42
+ /** Snapshot of one resident, for tests asserting eviction did not corrupt it. */
43
+ peek(id: string): TrackedEntry | undefined;
44
+ }
45
+
46
+ export interface AdmitResult {
47
+ /** True when the entry is now charged against the RAM/VRAM budget. */
48
+ admitted: boolean;
49
+ /** True when the incoming entry was spilled to browser storage instead. */
50
+ spilled: boolean;
51
+ /** True when a same-id resident was replaced. */
52
+ replaced: boolean;
53
+ /** Entries evicted to make room, oldest-evicted first. Snapshots, not live refs. */
54
+ evicted: TrackedEntry[];
55
+ reason: string;
56
+ }
57
+
58
+ export interface MemoryManagerOptions extends MemoryManagerConfig {
59
+ /** Spill sink. Required for storage residency; omit for a RAM-only manager. */
60
+ storage?: StorageSink;
61
+ }
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Phase 3 — memory pressure detection and dynamic workspace allocation.
3
+ *
4
+ * Pressure is a fact derived from used bytes vs the hard budget (and optional
5
+ * RAM / storage / VRAM hints). The workspace is a slice of that budget the
6
+ * manager grows when there is headroom and shrinks when pressure is on, so a
7
+ * sustained workload stays inside the configured byte cap.
8
+ *
9
+ * Pure: no I/O, no inference, no decision about when to run.
10
+ */
11
+
12
+ import type { MemoryPressure } from './types.js';
13
+
14
+ export interface PressureInput {
15
+ usedBytes: number;
16
+ byteBudget: number;
17
+ /** Utilization at or above which the system is pressured. */
18
+ pressureThreshold: number;
19
+ /** Watermark utilization eviction aims for. */
20
+ targetWatermark: number;
21
+ ramBytes: number;
22
+ vramBytes: number;
23
+ storageQuotaBytes: number;
24
+ }
25
+
26
+ /** Detect pressure against the hard budget. Never throws. */
27
+ export function detectPressure(input: PressureInput): MemoryPressure {
28
+ const budget = input.byteBudget > 0 ? input.byteBudget : 1;
29
+ const used = Math.max(0, input.usedBytes);
30
+ const utilization = used / budget;
31
+ const threshold = clamp01(input.pressureThreshold);
32
+ const watermark = Math.min(threshold, clamp01(input.targetWatermark));
33
+ const pressured = utilization >= threshold;
34
+ const targetBytes = watermark * budget;
35
+ const reclaimBytes = pressured ? Math.max(0, Math.ceil(used - targetBytes)) : 0;
36
+ return {
37
+ utilization,
38
+ pressured,
39
+ reclaimBytes,
40
+ vramBytes: Math.max(0, input.vramBytes),
41
+ ramBytes: Math.max(0, input.ramBytes),
42
+ storageQuotaBytes: Math.max(0, input.storageQuotaBytes),
43
+ };
44
+ }
45
+
46
+ export interface WorkspaceBounds {
47
+ minBytes: number;
48
+ maxBytes: number;
49
+ }
50
+
51
+ export interface WorkspaceDecision {
52
+ /** New workspace size in bytes, always inside [min, max] and the residual budget. */
53
+ nextBytes: number;
54
+ /** Signed delta from `currentBytes`. Positive = grow, negative = shrink. */
55
+ deltaBytes: number;
56
+ reason: string;
57
+ }
58
+
59
+ /**
60
+ * Decide the next workspace size.
61
+ *
62
+ * - Under pressure: shrink toward `minBytes` by at least the reclaim request,
63
+ * and never exceed the residual budget (`byteBudget - usedBytes`).
64
+ * - With headroom and a hit: grow by `growStepBytes` up to `maxBytes`, still
65
+ * capped by the residual budget so the workspace cannot push the total over
66
+ * the hard cap.
67
+ * - Otherwise hold.
68
+ */
69
+ export function planWorkspace(input: {
70
+ currentBytes: number;
71
+ bounds: WorkspaceBounds;
72
+ pressure: MemoryPressure;
73
+ byteBudget: number;
74
+ usedBytes: number;
75
+ /** True when the caller just hit, which is the signal to grow. */
76
+ onHit: boolean;
77
+ growStepBytes?: number;
78
+ }): WorkspaceDecision {
79
+ const minBytes = Math.max(0, input.bounds.minBytes);
80
+ const maxBytes = Math.max(minBytes, input.bounds.maxBytes);
81
+ const current = clamp(input.currentBytes, minBytes, maxBytes);
82
+ const residual = Math.max(0, input.byteBudget - Math.max(0, input.usedBytes));
83
+ const ceiling = Math.min(maxBytes, current + residual);
84
+
85
+ if (input.pressure.pressured) {
86
+ const shrinkBy = Math.max(input.pressure.reclaimBytes, Math.ceil((current - minBytes) / 2));
87
+ const next = clamp(current - shrinkBy, minBytes, ceiling);
88
+ return {
89
+ nextBytes: next,
90
+ deltaBytes: next - current,
91
+ reason: next < current
92
+ ? `pressure at ${(input.pressure.utilization * 100).toFixed(1)}% — shrink workspace by ${current - next} bytes`
93
+ : 'pressure but workspace already at its floor',
94
+ };
95
+ }
96
+
97
+ if (input.onHit && current < ceiling) {
98
+ const step = input.growStepBytes && input.growStepBytes > 0 ? input.growStepBytes : Math.max(1, Math.ceil((maxBytes - minBytes) / 8));
99
+ const next = clamp(current + step, minBytes, ceiling);
100
+ return {
101
+ nextBytes: next,
102
+ deltaBytes: next - current,
103
+ reason: next > current
104
+ ? `headroom — grow workspace by ${next - current} bytes`
105
+ : 'workspace already at its ceiling',
106
+ };
107
+ }
108
+
109
+ return { nextBytes: current, deltaBytes: 0, reason: 'workspace held' };
110
+ }
111
+
112
+ function clamp(value: number, min: number, max: number): number {
113
+ if (Number.isNaN(value)) return min;
114
+ return Math.min(max, Math.max(min, value));
115
+ }
116
+
117
+ function clamp01(value: number): number {
118
+ if (Number.isNaN(value)) return 0;
119
+ return Math.min(1, Math.max(0, value));
120
+ }