@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,346 @@
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
+ import { probeRamBytes } from './envProbe.js';
31
+ import { costAwareStrategy } from './eviction.js';
32
+ import { detectPressure } from './pressure.js';
33
+ import { createSpillTier, resolveStorageBudget } from './spillTier.js';
34
+ import { selectVictims } from './victims.js';
35
+ import { createWorkspaceController } from './workspace.js';
36
+ export { probeRamBytes, probeStorageQuotaBytes } from './envProbe.js';
37
+ const DEFAULT_PRESSURE = 0.85;
38
+ const DEFAULT_WATERMARK = 0.7;
39
+ const DEFAULT_EVENT_LIMIT = 256;
40
+ export function createMemoryManager(options) {
41
+ if (!(options.byteBudget > 0) || !Number.isFinite(options.byteBudget)) {
42
+ throw new Error('createMemoryManager: byteBudget must be a finite number > 0');
43
+ }
44
+ const byteBudget = options.byteBudget;
45
+ const strategy = options.strategy ?? costAwareStrategy();
46
+ const pressureThreshold = options.pressureThreshold ?? DEFAULT_PRESSURE;
47
+ const targetWatermark = Math.min(pressureThreshold, options.targetWatermark ?? DEFAULT_WATERMARK);
48
+ const eventLogLimit = options.eventLogLimit ?? DEFAULT_EVENT_LIMIT;
49
+ const now = options.now ?? (() => Date.now());
50
+ const ramBytes = options.ramBytes ?? probeRamBytes();
51
+ const vramBytes = Math.max(0, options.vramBudgetBytes ?? 0);
52
+ const storageQuotaBytes = options.storageQuotaBytes ?? 0;
53
+ const quotas = options.quotas ?? [];
54
+ const residents = new Map();
55
+ const log = [];
56
+ let residentTotal = 0;
57
+ let seq = 0;
58
+ let hits = 0;
59
+ let misses = 0;
60
+ let admissions = 0;
61
+ let evictions = 0;
62
+ let spills = 0;
63
+ let reloads = 0;
64
+ const spill = createSpillTier({
65
+ storage: options.storage,
66
+ budgetBytes: resolveStorageBudget(options.storageBudgetBytes, storageQuotaBytes, byteBudget),
67
+ now,
68
+ onSpill(entry, reason) {
69
+ spills += 1;
70
+ record({ kind: 'spill', id: entry.id, bytes: entry.bytes, reason });
71
+ },
72
+ });
73
+ const workspace = createWorkspaceController({
74
+ bounds: {
75
+ minBytes: Math.max(0, options.workspace?.minBytes ?? 0),
76
+ maxBytes: Math.max(0, options.workspace?.maxBytes ?? 0),
77
+ },
78
+ byteBudget,
79
+ initialBytes: options.workspace?.initialBytes,
80
+ });
81
+ function putResident(entry) {
82
+ const previous = residents.get(entry.id);
83
+ if (previous)
84
+ residentTotal -= previous.bytes;
85
+ residents.set(entry.id, entry);
86
+ residentTotal += entry.bytes;
87
+ }
88
+ function removeResident(id) {
89
+ const previous = residents.get(id);
90
+ if (!previous)
91
+ return;
92
+ residents.delete(id);
93
+ residentTotal -= previous.bytes;
94
+ }
95
+ function usedBytes() {
96
+ return residentTotal + workspace.bytes();
97
+ }
98
+ function record(event) {
99
+ log.push({ ...event, at: now() });
100
+ if (log.length > eventLogLimit)
101
+ log.splice(0, log.length - eventLogLimit);
102
+ }
103
+ function pressureNow() {
104
+ return detectPressure({
105
+ usedBytes: usedBytes(),
106
+ byteBudget,
107
+ pressureThreshold,
108
+ targetWatermark,
109
+ ramBytes,
110
+ vramBytes,
111
+ storageQuotaBytes,
112
+ });
113
+ }
114
+ function applyWorkspace(onHit) {
115
+ const change = workspace.apply({ onHit, pressure: pressureNow(), residentBytes: residentTotal });
116
+ if (change)
117
+ record(change);
118
+ }
119
+ function drop(entry, reason) {
120
+ removeResident(entry.id);
121
+ evictions += 1;
122
+ strategy.observe?.({ kind: 'evict', entry });
123
+ record({ kind: 'evict', id: entry.id, bytes: entry.bytes, reason });
124
+ }
125
+ function placeTier(entry) {
126
+ // VRAM is a hint. Only place there when a budget was configured and the
127
+ // caller asked for it. CPU-only (vramBudgetBytes = 0) always stays in RAM.
128
+ if (entry.tier === 'vram' && vramBytes > 0)
129
+ return 'vram';
130
+ return 'ram';
131
+ }
132
+ function rate() {
133
+ const total = hits + misses;
134
+ return total === 0 ? 0 : hits / total;
135
+ }
136
+ function notAdmitted(spilledOk, spilledReason, rejectedReason) {
137
+ return {
138
+ admitted: false,
139
+ spilled: spilledOk,
140
+ replaced: false,
141
+ evicted: [],
142
+ reason: spilledOk ? spilledReason : rejectedReason,
143
+ };
144
+ }
145
+ const manager = {
146
+ async admit(entry, admitOptions) {
147
+ if (!(entry.bytes >= 0) || !Number.isFinite(entry.bytes)) {
148
+ return { admitted: false, spilled: false, replaced: false, evicted: [], reason: 'invalid footprint' };
149
+ }
150
+ const wantSpill = admitOptions?.spill !== false && spill.enabled;
151
+ if (entry.bytes > byteBudget) {
152
+ const spilledOk = wantSpill && await spill.retain(entry, 'entry exceeds the hard byte budget');
153
+ return notAdmitted(spilledOk, 'spilled: entry larger than byte budget', 'rejected: entry larger than byte budget');
154
+ }
155
+ const existing = residents.get(entry.id);
156
+ const except = new Set();
157
+ if (existing)
158
+ except.add(existing.id);
159
+ const victims = selectVictims({
160
+ incoming: entry,
161
+ residents: residents.values(),
162
+ except,
163
+ strategy,
164
+ quotas,
165
+ byteBudget,
166
+ workspaceBytes: workspace.bytes(),
167
+ });
168
+ if (!victims) {
169
+ // Nothing was dropped. Spill or reject, leaving every resident intact.
170
+ const spilledOk = wantSpill && await spill.retain(entry, 'pinned residents fill the budget');
171
+ return notAdmitted(spilledOk, 'spilled: budget held by pinned residents', 'rejected: budget held by pinned residents');
172
+ }
173
+ // RAM mutations are synchronous and finish before any storage await, so a
174
+ // second admit cannot observe a half-applied eviction or an over-budget map.
175
+ const spilledVictims = [];
176
+ for (const victim of victims) {
177
+ const live = residents.get(victim.id);
178
+ if (!live)
179
+ continue;
180
+ drop(live, `make room for ${entry.id}`);
181
+ spilledVictims.push(live);
182
+ }
183
+ if (existing)
184
+ removeResident(existing.id);
185
+ const tick = ++seq;
186
+ const tracked = {
187
+ ...entry,
188
+ tier: placeTier(entry),
189
+ pinned: admitOptions?.pin === true || entry.pinned === true,
190
+ admittedAt: existing?.admittedAt ?? tick,
191
+ lastUsedAt: tick,
192
+ hits: 0,
193
+ arcList: 't1',
194
+ };
195
+ putResident(tracked);
196
+ // The index entry is dropped synchronously; the sink delete is awaited below.
197
+ const forgettingPriorSpill = spill.forget(entry.id);
198
+ admissions += 1;
199
+ strategy.observe?.({ kind: 'admit', entry: tracked });
200
+ record({
201
+ kind: 'admit',
202
+ id: entry.id,
203
+ bytes: entry.bytes,
204
+ reason: victims.length > 0 ? `admitted after evicting ${victims.length}` : 'admitted within budget',
205
+ });
206
+ await forgettingPriorSpill;
207
+ if (wantSpill) {
208
+ for (const live of spilledVictims) {
209
+ await spill.retain(live, `evicted to make room for ${entry.id}`);
210
+ }
211
+ }
212
+ const reading = pressureNow();
213
+ if (reading.pressured) {
214
+ record({
215
+ kind: 'pressure',
216
+ bytes: reading.reclaimBytes,
217
+ reason: `utilization ${(reading.utilization * 100).toFixed(1)}%`,
218
+ });
219
+ applyWorkspace(false);
220
+ }
221
+ return {
222
+ admitted: true,
223
+ spilled: false,
224
+ replaced: existing !== undefined,
225
+ evicted: victims,
226
+ reason: victims.length > 0 ? `evicted ${victims.length} to fit` : 'fit within budget',
227
+ };
228
+ },
229
+ get(id) {
230
+ const entry = residents.get(id);
231
+ if (!entry) {
232
+ misses += 1;
233
+ const spilled = spill.get(id);
234
+ const ghost = {
235
+ id,
236
+ group: spilled?.group ?? '',
237
+ component: spilled?.component,
238
+ bytes: spilled?.bytes ?? 0,
239
+ reloadCostMs: spilled?.reloadCostMs ?? 0,
240
+ reuseProbability: spilled?.reuseProbability ?? 0,
241
+ tier: 'storage',
242
+ admittedAt: 0,
243
+ lastUsedAt: 0,
244
+ hits: 0,
245
+ };
246
+ strategy.observe?.({ kind: 'miss', entry: ghost });
247
+ record({ kind: 'miss', id, reason: spilled ? 'miss: spilled to storage' : 'miss: not resident' });
248
+ return { hit: false };
249
+ }
250
+ const tick = ++seq;
251
+ const touched = {
252
+ ...entry,
253
+ lastUsedAt: tick,
254
+ hits: entry.hits + 1,
255
+ arcList: entry.hits + 1 > 1 ? 't2' : 't1',
256
+ };
257
+ putResident(touched);
258
+ hits += 1;
259
+ strategy.observe?.({ kind: 'hit', entry: touched });
260
+ record({ kind: 'hit', id, reason: `hit #${touched.hits}` });
261
+ applyWorkspace(true);
262
+ return { hit: true, entry: snapshot(touched) };
263
+ },
264
+ hitRate() {
265
+ return rate();
266
+ },
267
+ async reload(id) {
268
+ const already = residents.get(id);
269
+ if (already)
270
+ return { hit: true, entry: snapshot(already) };
271
+ const restored = spill.has(id) ? await spill.reload(id) : undefined;
272
+ if (!restored) {
273
+ misses += 1;
274
+ return { hit: false };
275
+ }
276
+ const result = await manager.admit(restored, { spill: false });
277
+ if (!result.admitted) {
278
+ misses += 1;
279
+ return { hit: false };
280
+ }
281
+ reloads += 1;
282
+ record({ kind: 'reload', id, reason: 'reloaded from browser storage' });
283
+ const entry = residents.get(id);
284
+ return entry ? { hit: true, entry: snapshot(entry) } : { hit: false };
285
+ },
286
+ pin(id) {
287
+ const entry = residents.get(id);
288
+ if (!entry)
289
+ return false;
290
+ putResident({ ...entry, pinned: true });
291
+ record({ kind: 'pin', id, reason: 'pinned' });
292
+ return true;
293
+ },
294
+ unpin(id) {
295
+ const entry = residents.get(id);
296
+ if (!entry)
297
+ return false;
298
+ putResident({ ...entry, pinned: false });
299
+ record({ kind: 'unpin', id, reason: 'unpinned' });
300
+ return true;
301
+ },
302
+ async release(id) {
303
+ const entry = residents.get(id);
304
+ if (entry) {
305
+ drop(entry, 'released');
306
+ return true;
307
+ }
308
+ return spill.forget(id);
309
+ },
310
+ pressure() {
311
+ return pressureNow();
312
+ },
313
+ stats() {
314
+ return {
315
+ hits,
316
+ misses,
317
+ admissions,
318
+ evictions,
319
+ spills,
320
+ reloads,
321
+ usedBytes: usedBytes(),
322
+ byteBudget,
323
+ workspaceBytes: workspace.bytes(),
324
+ residentCount: residents.size,
325
+ spilledCount: spill.count,
326
+ spilledBytes: spill.bytes(),
327
+ hitRate: rate(),
328
+ };
329
+ },
330
+ events() {
331
+ return log;
332
+ },
333
+ residentIds() {
334
+ return [...residents.keys()];
335
+ },
336
+ peek(id) {
337
+ const entry = residents.get(id);
338
+ return entry ? snapshot(entry) : undefined;
339
+ },
340
+ };
341
+ return manager;
342
+ }
343
+ function snapshot(entry) {
344
+ return { ...entry };
345
+ }
346
+ //# sourceMappingURL=manager.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/memory/manager.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,49 @@
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
+ import type { StorageSink } from './storageSink.js';
7
+ import type { AdmitOptions, LookupResult, MemoryManagerConfig, MemoryPressure, ResidencyEvent, ResidencyStats, ResidentEntry, TrackedEntry } from './types.js';
8
+ export interface MemoryManager {
9
+ /** Admit an entry, evicting or spilling as needed to honor the hard budget. */
10
+ admit(entry: ResidentEntry, options?: AdmitOptions): Promise<AdmitResult>;
11
+ /** Touch an entry. A hit updates recency and frequency and may grow the workspace. */
12
+ get(id: string): LookupResult;
13
+ /** hits / (hits + misses). 0 before the first lookup. */
14
+ hitRate(): number;
15
+ /** Reload a spilled entry back into RAM, charging the budget. */
16
+ reload(id: string): Promise<LookupResult>;
17
+ /** Pin an entry so eviction cannot drop it. */
18
+ pin(id: string): boolean;
19
+ /** Release a pin. */
20
+ unpin(id: string): boolean;
21
+ /** Drop one entry. Returns true if it was resident or spilled. */
22
+ release(id: string): Promise<boolean>;
23
+ /** Current pressure reading. */
24
+ pressure(): MemoryPressure;
25
+ /** Aggregate counters, including `hitRate`. */
26
+ stats(): ResidencyStats;
27
+ /** Explainable event log, oldest first, bounded by `eventLogLimit`. */
28
+ events(): readonly ResidencyEvent[];
29
+ /** Ids currently charged against the budget. */
30
+ residentIds(): string[];
31
+ /** Snapshot of one resident, for tests asserting eviction did not corrupt it. */
32
+ peek(id: string): TrackedEntry | undefined;
33
+ }
34
+ export interface AdmitResult {
35
+ /** True when the entry is now charged against the RAM/VRAM budget. */
36
+ admitted: boolean;
37
+ /** True when the incoming entry was spilled to browser storage instead. */
38
+ spilled: boolean;
39
+ /** True when a same-id resident was replaced. */
40
+ replaced: boolean;
41
+ /** Entries evicted to make room, oldest-evicted first. Snapshots, not live refs. */
42
+ evicted: TrackedEntry[];
43
+ reason: string;
44
+ }
45
+ export interface MemoryManagerOptions extends MemoryManagerConfig {
46
+ /** Spill sink. Required for storage residency; omit for a RAM-only manager. */
47
+ storage?: StorageSink;
48
+ }
49
+ //# sourceMappingURL=managerTypes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"managerTypes.d.ts","sourceRoot":"","sources":["../../src/memory/managerTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1E,sFAAsF;IACtF,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAAC;IAC9B,yDAAyD;IACzD,OAAO,IAAI,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1C,+CAA+C;IAC/C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,qBAAqB;IACrB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,kEAAkE;IAClE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,gCAAgC;IAChC,QAAQ,IAAI,cAAc,CAAC;IAC3B,+CAA+C;IAC/C,KAAK,IAAI,cAAc,CAAC;IACxB,uEAAuE;IACvE,MAAM,IAAI,SAAS,cAAc,EAAE,CAAC;IACpC,gDAAgD;IAChD,WAAW,IAAI,MAAM,EAAE,CAAC;IACxB,iFAAiF;IACjF,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,+EAA+E;IAC/E,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB"}
@@ -0,0 +1,7 @@
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
+ export {};
7
+ //# sourceMappingURL=managerTypes.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"managerTypes.js","sourceRoot":"","sources":["../../src/memory/managerTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
@@ -0,0 +1,56 @@
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
+ import type { MemoryPressure } from './types.js';
12
+ export interface PressureInput {
13
+ usedBytes: number;
14
+ byteBudget: number;
15
+ /** Utilization at or above which the system is pressured. */
16
+ pressureThreshold: number;
17
+ /** Watermark utilization eviction aims for. */
18
+ targetWatermark: number;
19
+ ramBytes: number;
20
+ vramBytes: number;
21
+ storageQuotaBytes: number;
22
+ }
23
+ /** Detect pressure against the hard budget. Never throws. */
24
+ export declare function detectPressure(input: PressureInput): MemoryPressure;
25
+ export interface WorkspaceBounds {
26
+ minBytes: number;
27
+ maxBytes: number;
28
+ }
29
+ export interface WorkspaceDecision {
30
+ /** New workspace size in bytes, always inside [min, max] and the residual budget. */
31
+ nextBytes: number;
32
+ /** Signed delta from `currentBytes`. Positive = grow, negative = shrink. */
33
+ deltaBytes: number;
34
+ reason: string;
35
+ }
36
+ /**
37
+ * Decide the next workspace size.
38
+ *
39
+ * - Under pressure: shrink toward `minBytes` by at least the reclaim request,
40
+ * and never exceed the residual budget (`byteBudget - usedBytes`).
41
+ * - With headroom and a hit: grow by `growStepBytes` up to `maxBytes`, still
42
+ * capped by the residual budget so the workspace cannot push the total over
43
+ * the hard cap.
44
+ * - Otherwise hold.
45
+ */
46
+ export declare function planWorkspace(input: {
47
+ currentBytes: number;
48
+ bounds: WorkspaceBounds;
49
+ pressure: MemoryPressure;
50
+ byteBudget: number;
51
+ usedBytes: number;
52
+ /** True when the caller just hit, which is the signal to grow. */
53
+ onHit: boolean;
54
+ growStepBytes?: number;
55
+ }): WorkspaceDecision;
56
+ //# sourceMappingURL=pressure.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pressure.d.ts","sourceRoot":"","sources":["../../src/memory/pressure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAiBnE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,eAAe,CAAC;IACxB,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,iBAAiB,CAgCpB"}
@@ -0,0 +1,80 @@
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
+ /** Detect pressure against the hard budget. Never throws. */
12
+ export function detectPressure(input) {
13
+ const budget = input.byteBudget > 0 ? input.byteBudget : 1;
14
+ const used = Math.max(0, input.usedBytes);
15
+ const utilization = used / budget;
16
+ const threshold = clamp01(input.pressureThreshold);
17
+ const watermark = Math.min(threshold, clamp01(input.targetWatermark));
18
+ const pressured = utilization >= threshold;
19
+ const targetBytes = watermark * budget;
20
+ const reclaimBytes = pressured ? Math.max(0, Math.ceil(used - targetBytes)) : 0;
21
+ return {
22
+ utilization,
23
+ pressured,
24
+ reclaimBytes,
25
+ vramBytes: Math.max(0, input.vramBytes),
26
+ ramBytes: Math.max(0, input.ramBytes),
27
+ storageQuotaBytes: Math.max(0, input.storageQuotaBytes),
28
+ };
29
+ }
30
+ /**
31
+ * Decide the next workspace size.
32
+ *
33
+ * - Under pressure: shrink toward `minBytes` by at least the reclaim request,
34
+ * and never exceed the residual budget (`byteBudget - usedBytes`).
35
+ * - With headroom and a hit: grow by `growStepBytes` up to `maxBytes`, still
36
+ * capped by the residual budget so the workspace cannot push the total over
37
+ * the hard cap.
38
+ * - Otherwise hold.
39
+ */
40
+ export function planWorkspace(input) {
41
+ const minBytes = Math.max(0, input.bounds.minBytes);
42
+ const maxBytes = Math.max(minBytes, input.bounds.maxBytes);
43
+ const current = clamp(input.currentBytes, minBytes, maxBytes);
44
+ const residual = Math.max(0, input.byteBudget - Math.max(0, input.usedBytes));
45
+ const ceiling = Math.min(maxBytes, current + residual);
46
+ if (input.pressure.pressured) {
47
+ const shrinkBy = Math.max(input.pressure.reclaimBytes, Math.ceil((current - minBytes) / 2));
48
+ const next = clamp(current - shrinkBy, minBytes, ceiling);
49
+ return {
50
+ nextBytes: next,
51
+ deltaBytes: next - current,
52
+ reason: next < current
53
+ ? `pressure at ${(input.pressure.utilization * 100).toFixed(1)}% — shrink workspace by ${current - next} bytes`
54
+ : 'pressure but workspace already at its floor',
55
+ };
56
+ }
57
+ if (input.onHit && current < ceiling) {
58
+ const step = input.growStepBytes && input.growStepBytes > 0 ? input.growStepBytes : Math.max(1, Math.ceil((maxBytes - minBytes) / 8));
59
+ const next = clamp(current + step, minBytes, ceiling);
60
+ return {
61
+ nextBytes: next,
62
+ deltaBytes: next - current,
63
+ reason: next > current
64
+ ? `headroom — grow workspace by ${next - current} bytes`
65
+ : 'workspace already at its ceiling',
66
+ };
67
+ }
68
+ return { nextBytes: current, deltaBytes: 0, reason: 'workspace held' };
69
+ }
70
+ function clamp(value, min, max) {
71
+ if (Number.isNaN(value))
72
+ return min;
73
+ return Math.min(max, Math.max(min, value));
74
+ }
75
+ function clamp01(value) {
76
+ if (Number.isNaN(value))
77
+ return 0;
78
+ return Math.min(1, Math.max(0, value));
79
+ }
80
+ //# sourceMappingURL=pressure.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pressure.js","sourceRoot":"","sources":["../../src/memory/pressure.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Phase 3 — the browser-storage spill tier of the residency manager.
3
+ *
4
+ * Owns the in-memory spill index (what is retained in the storage sink and how
5
+ * many bytes it holds) and every write to / delete from the sink. The index is
6
+ * the bound: `bytes()` never exceeds the storage budget, even under concurrent
7
+ * spills, because bytes are RESERVED synchronously before the sink write is
8
+ * awaited and released when it settles.
9
+ *
10
+ * Storage is best-effort: a failed delete never resurrects an index entry, and
11
+ * a failed write leaves nothing charged.
12
+ */
13
+ import type { SpilledRecord, StorageSink } from './storageSink.js';
14
+ import type { ResidentEntry } from './types.js';
15
+ export interface SpillTierOptions {
16
+ storage?: StorageSink;
17
+ /** Cap on bytes retained in storage. 0 disables retention. */
18
+ budgetBytes: number;
19
+ now: () => number;
20
+ /** Called once per successful spill (for the manager's event log). */
21
+ onSpill(entry: ResidentEntry, reason: string): void;
22
+ }
23
+ export interface SpillTier {
24
+ /** True when a sink is configured and the storage budget allows retention. */
25
+ readonly enabled: boolean;
26
+ get(id: string): SpilledRecord | undefined;
27
+ has(id: string): boolean;
28
+ readonly count: number;
29
+ /** Bytes committed in storage (reservations in flight are not included). */
30
+ bytes(): number;
31
+ /** Retain an entry in storage, trimming the oldest spills to make room. */
32
+ retain(entry: ResidentEntry, reason: string): Promise<boolean>;
33
+ /**
34
+ * Drop a spill. The index entry is removed synchronously (before the first
35
+ * await); the sink delete is best-effort. Returns whether a spill existed.
36
+ */
37
+ forget(id: string): Promise<boolean>;
38
+ /**
39
+ * Read a spill back from storage as a RAM-tier entry charged at the spilled
40
+ * footprint. Undefined (and the index entry dropped) when storage lost it.
41
+ */
42
+ reload(id: string): Promise<ResidentEntry | undefined>;
43
+ }
44
+ /** Storage budget: explicit > 0, else the quota hint, else 4× the RAM budget. `0` disables. */
45
+ export declare function resolveStorageBudget(configured: number | undefined, storageQuotaBytes: number, byteBudget: number): number;
46
+ export declare function createSpillTier(options: SpillTierOptions): SpillTier;
47
+ //# sourceMappingURL=spillTier.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"spillTier.d.ts","sourceRoot":"","sources":["../../src/memory/spillTier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,sEAAsE;IACtE,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC3C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,KAAK,IAAI,MAAM,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM,GACjB,MAAM,CAKR;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAmGpE"}