@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.
- package/README.md +22 -0
- package/dist/adaptive/controller.d.ts +39 -0
- package/dist/adaptive/controller.d.ts.map +1 -0
- package/dist/adaptive/controller.js +108 -0
- package/dist/adaptive/controller.js.map +1 -0
- package/dist/adaptive/costModel.d.ts +37 -0
- package/dist/adaptive/costModel.d.ts.map +1 -0
- package/dist/adaptive/costModel.js +102 -0
- package/dist/adaptive/costModel.js.map +1 -0
- package/dist/adaptive/planner.d.ts +22 -0
- package/dist/adaptive/planner.d.ts.map +1 -0
- package/dist/adaptive/planner.js +114 -0
- package/dist/adaptive/planner.js.map +1 -0
- package/dist/adaptive/types.d.ts +138 -0
- package/dist/adaptive/types.d.ts.map +1 -0
- package/dist/adaptive/types.js +12 -0
- package/dist/adaptive/types.js.map +1 -0
- package/dist/assets.js +2 -2
- package/dist/check/cachedFetch.js.map +1 -1
- package/dist/check/index.d.ts +6 -1
- package/dist/check/index.d.ts.map +1 -1
- package/dist/check/index.js +6 -1
- package/dist/check/index.js.map +1 -1
- package/dist/componentCompilers.d.ts.map +1 -1
- package/dist/componentCompilers.js.map +1 -1
- package/dist/esbuildWasm.js.map +1 -1
- package/dist/host.d.ts +11 -5
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +19 -8
- package/dist/host.js.map +1 -1
- package/dist/inference/backends/mock.d.ts +24 -0
- package/dist/inference/backends/mock.d.ts.map +1 -0
- package/dist/inference/backends/mock.js +55 -0
- package/dist/inference/backends/mock.js.map +1 -0
- package/dist/inference/backends/onnx.d.ts +33 -0
- package/dist/inference/backends/onnx.d.ts.map +1 -0
- package/dist/inference/backends/onnx.js +60 -0
- package/dist/inference/backends/onnx.js.map +1 -0
- package/dist/inference/backends/webllm.d.ts +27 -0
- package/dist/inference/backends/webllm.d.ts.map +1 -0
- package/dist/inference/backends/webllm.js +52 -0
- package/dist/inference/backends/webllm.js.map +1 -0
- package/dist/inference/backends/wllama.d.ts +29 -0
- package/dist/inference/backends/wllama.d.ts.map +1 -0
- package/dist/inference/backends/wllama.js +51 -0
- package/dist/inference/backends/wllama.js.map +1 -0
- package/dist/inference/capabilities.d.ts +20 -0
- package/dist/inference/capabilities.d.ts.map +1 -0
- package/dist/inference/capabilities.js +33 -0
- package/dist/inference/capabilities.js.map +1 -0
- package/dist/inference/client.d.ts +45 -0
- package/dist/inference/client.d.ts.map +1 -0
- package/dist/inference/client.js +201 -0
- package/dist/inference/client.js.map +1 -0
- package/dist/inference/modelCache.d.ts +71 -0
- package/dist/inference/modelCache.d.ts.map +1 -0
- package/dist/inference/modelCache.js +91 -0
- package/dist/inference/modelCache.js.map +1 -0
- package/dist/inference/protocol.d.ts +94 -0
- package/dist/inference/protocol.d.ts.map +1 -0
- package/dist/inference/protocol.js +19 -0
- package/dist/inference/protocol.js.map +1 -0
- package/dist/inference/tokenStream.d.ts +26 -0
- package/dist/inference/tokenStream.d.ts.map +1 -0
- package/dist/inference/tokenStream.js +79 -0
- package/dist/inference/tokenStream.js.map +1 -0
- package/dist/inference/types.d.ts +108 -0
- package/dist/inference/types.d.ts.map +1 -0
- package/dist/inference/types.js +8 -0
- package/dist/inference/types.js.map +1 -0
- package/dist/inference/worker.bundle.js +5 -0
- package/dist/inference/worker.d.ts +35 -0
- package/dist/inference/worker.d.ts.map +1 -0
- package/dist/inference/worker.js +157 -0
- package/dist/inference/worker.js.map +1 -0
- package/dist/inference/workerEntry.d.ts +15 -0
- package/dist/inference/workerEntry.d.ts.map +1 -0
- package/dist/inference/workerEntry.js +17 -0
- package/dist/inference/workerEntry.js.map +1 -0
- package/dist/kvcache/advanced.d.ts +39 -0
- package/dist/kvcache/advanced.d.ts.map +1 -0
- package/dist/kvcache/advanced.js +59 -0
- package/dist/kvcache/advanced.js.map +1 -0
- package/dist/kvcache/compatibility.d.ts +14 -0
- package/dist/kvcache/compatibility.d.ts.map +1 -0
- package/dist/kvcache/compatibility.js +44 -0
- package/dist/kvcache/compatibility.js.map +1 -0
- package/dist/kvcache/lru.d.ts +45 -0
- package/dist/kvcache/lru.d.ts.map +1 -0
- package/dist/kvcache/lru.js +91 -0
- package/dist/kvcache/lru.js.map +1 -0
- package/dist/kvcache/paged.d.ts +86 -0
- package/dist/kvcache/paged.d.ts.map +1 -0
- package/dist/kvcache/paged.js +238 -0
- package/dist/kvcache/paged.js.map +1 -0
- package/dist/kvcache/quant.d.ts +30 -0
- package/dist/kvcache/quant.d.ts.map +1 -0
- package/dist/kvcache/quant.js +73 -0
- package/dist/kvcache/quant.js.map +1 -0
- package/dist/kvcache/radix.d.ts +28 -0
- package/dist/kvcache/radix.d.ts.map +1 -0
- package/dist/kvcache/radix.js +58 -0
- package/dist/kvcache/radix.js.map +1 -0
- package/dist/kvcache/runtime.d.ts +11 -0
- package/dist/kvcache/runtime.d.ts.map +1 -0
- package/dist/kvcache/runtime.js +204 -0
- package/dist/kvcache/runtime.js.map +1 -0
- package/dist/kvcache/types.d.ts +151 -0
- package/dist/kvcache/types.d.ts.map +1 -0
- package/dist/kvcache/types.js +10 -0
- package/dist/kvcache/types.js.map +1 -0
- package/dist/learning/fingerprint.d.ts +17 -0
- package/dist/learning/fingerprint.d.ts.map +1 -0
- package/dist/learning/fingerprint.js +46 -0
- package/dist/learning/fingerprint.js.map +1 -0
- package/dist/learning/index.d.ts +5 -0
- package/dist/learning/index.d.ts.map +1 -0
- package/dist/learning/index.js +3 -0
- package/dist/learning/index.js.map +1 -0
- package/dist/learning/learner.d.ts +21 -0
- package/dist/learning/learner.d.ts.map +1 -0
- package/dist/learning/learner.js +272 -0
- package/dist/learning/learner.js.map +1 -0
- package/dist/learning/ledger.d.ts +26 -0
- package/dist/learning/ledger.d.ts.map +1 -0
- package/dist/learning/ledger.js +40 -0
- package/dist/learning/ledger.js.map +1 -0
- package/dist/learning/selection.d.ts +44 -0
- package/dist/learning/selection.d.ts.map +1 -0
- package/dist/learning/selection.js +111 -0
- package/dist/learning/selection.js.map +1 -0
- package/dist/learning/stats.d.ts +19 -0
- package/dist/learning/stats.d.ts.map +1 -0
- package/dist/learning/stats.js +31 -0
- package/dist/learning/stats.js.map +1 -0
- package/dist/learning/types.d.ts +133 -0
- package/dist/learning/types.d.ts.map +1 -0
- package/dist/learning/types.js +8 -0
- package/dist/learning/types.js.map +1 -0
- package/dist/memory/envProbe.d.ts +16 -0
- package/dist/memory/envProbe.d.ts.map +1 -0
- package/dist/memory/envProbe.js +28 -0
- package/dist/memory/envProbe.js.map +1 -0
- package/dist/memory/estimates.d.ts +46 -0
- package/dist/memory/estimates.d.ts.map +1 -0
- package/dist/memory/estimates.js +72 -0
- package/dist/memory/estimates.js.map +1 -0
- package/dist/memory/eviction.d.ts +42 -0
- package/dist/memory/eviction.d.ts.map +1 -0
- package/dist/memory/eviction.js +143 -0
- package/dist/memory/eviction.js.map +1 -0
- package/dist/memory/manager.d.ts +34 -0
- package/dist/memory/manager.d.ts.map +1 -0
- package/dist/memory/manager.js +346 -0
- package/dist/memory/manager.js.map +1 -0
- package/dist/memory/managerTypes.d.ts +49 -0
- package/dist/memory/managerTypes.d.ts.map +1 -0
- package/dist/memory/managerTypes.js +7 -0
- package/dist/memory/managerTypes.js.map +1 -0
- package/dist/memory/pressure.d.ts +56 -0
- package/dist/memory/pressure.d.ts.map +1 -0
- package/dist/memory/pressure.js +80 -0
- package/dist/memory/pressure.js.map +1 -0
- package/dist/memory/spillTier.d.ts +47 -0
- package/dist/memory/spillTier.d.ts.map +1 -0
- package/dist/memory/spillTier.js +128 -0
- package/dist/memory/spillTier.js.map +1 -0
- package/dist/memory/storageSink.d.ts +69 -0
- package/dist/memory/storageSink.d.ts.map +1 -0
- package/dist/memory/storageSink.js +221 -0
- package/dist/memory/storageSink.js.map +1 -0
- package/dist/memory/types.d.ts +202 -0
- package/dist/memory/types.d.ts.map +1 -0
- package/dist/memory/types.js +15 -0
- package/dist/memory/types.js.map +1 -0
- package/dist/memory/victims.d.ts +32 -0
- package/dist/memory/victims.d.ts.map +1 -0
- package/dist/memory/victims.js +74 -0
- package/dist/memory/victims.js.map +1 -0
- package/dist/memory/workspace.d.ts +34 -0
- package/dist/memory/workspace.d.ts.map +1 -0
- package/dist/memory/workspace.js +55 -0
- package/dist/memory/workspace.js.map +1 -0
- package/dist/memoryIntegration/index.d.ts +8 -0
- package/dist/memoryIntegration/index.d.ts.map +1 -0
- package/dist/memoryIntegration/index.js +4 -0
- package/dist/memoryIntegration/index.js.map +1 -0
- package/dist/memoryIntegration/knowledgeMemory.d.ts +43 -0
- package/dist/memoryIntegration/knowledgeMemory.d.ts.map +1 -0
- package/dist/memoryIntegration/knowledgeMemory.js +285 -0
- package/dist/memoryIntegration/knowledgeMemory.js.map +1 -0
- package/dist/memoryIntegration/persistence.d.ts +15 -0
- package/dist/memoryIntegration/persistence.d.ts.map +1 -0
- package/dist/memoryIntegration/persistence.js +43 -0
- package/dist/memoryIntegration/persistence.js.map +1 -0
- package/dist/memoryIntegration/text.d.ts +57 -0
- package/dist/memoryIntegration/text.d.ts.map +1 -0
- package/dist/memoryIntegration/text.js +179 -0
- package/dist/memoryIntegration/text.js.map +1 -0
- package/dist/memoryIntegration/types.d.ts +131 -0
- package/dist/memoryIntegration/types.d.ts.map +1 -0
- package/dist/memoryIntegration/types.js +11 -0
- package/dist/memoryIntegration/types.js.map +1 -0
- package/dist/ml.d.ts +52 -0
- package/dist/ml.d.ts.map +1 -0
- package/dist/ml.js +33 -0
- package/dist/ml.js.map +1 -0
- package/dist/node/childRelay.d.ts +10 -0
- package/dist/node/childRelay.d.ts.map +1 -1
- package/dist/node/childRelay.js +12 -2
- package/dist/node/childRelay.js.map +1 -1
- package/dist/node/index.js.map +1 -1
- package/dist/node/portResponder.d.ts +2 -0
- package/dist/node/portResponder.d.ts.map +1 -1
- package/dist/node/portResponder.js +3 -3
- package/dist/node/portResponder.js.map +1 -1
- package/dist/node/processHost.d.ts +4 -1
- package/dist/node/processHost.d.ts.map +1 -1
- package/dist/node/processHost.js +19 -16
- package/dist/node/processHost.js.map +1 -1
- package/dist/node/protocol.d.ts +1 -0
- package/dist/node/protocol.d.ts.map +1 -1
- package/dist/node/responseWire.d.ts.map +1 -1
- package/dist/node/worker.js +116 -109
- package/dist/node/workerProcess.js +1 -1
- package/dist/node/workerProcess.js.map +1 -1
- package/dist/prefetch/admission.d.ts +41 -0
- package/dist/prefetch/admission.d.ts.map +1 -0
- package/dist/prefetch/admission.js +49 -0
- package/dist/prefetch/admission.js.map +1 -0
- package/dist/prefetch/loadRegistry.d.ts +56 -0
- package/dist/prefetch/loadRegistry.d.ts.map +1 -0
- package/dist/prefetch/loadRegistry.js +108 -0
- package/dist/prefetch/loadRegistry.js.map +1 -0
- package/dist/prefetch/predictor.d.ts +40 -0
- package/dist/prefetch/predictor.d.ts.map +1 -0
- package/dist/prefetch/predictor.js +178 -0
- package/dist/prefetch/predictor.js.map +1 -0
- package/dist/prefetch/prefetcher.d.ts +37 -0
- package/dist/prefetch/prefetcher.d.ts.map +1 -0
- package/dist/prefetch/prefetcher.js +339 -0
- package/dist/prefetch/prefetcher.js.map +1 -0
- package/dist/prefetch/residentStore.d.ts +49 -0
- package/dist/prefetch/residentStore.d.ts.map +1 -0
- package/dist/prefetch/residentStore.js +87 -0
- package/dist/prefetch/residentStore.js.map +1 -0
- package/dist/prefetch/selfTuner.d.ts +40 -0
- package/dist/prefetch/selfTuner.d.ts.map +1 -0
- package/dist/prefetch/selfTuner.js +78 -0
- package/dist/prefetch/selfTuner.js.map +1 -0
- package/dist/prefetch/stats.d.ts +52 -0
- package/dist/prefetch/stats.d.ts.map +1 -0
- package/dist/prefetch/stats.js +72 -0
- package/dist/prefetch/stats.js.map +1 -0
- package/dist/prefetch/streaming.d.ts +132 -0
- package/dist/prefetch/streaming.d.ts.map +1 -0
- package/dist/prefetch/streaming.js +141 -0
- package/dist/prefetch/streaming.js.map +1 -0
- package/dist/prefetch/targetIndex.d.ts +18 -0
- package/dist/prefetch/targetIndex.d.ts.map +1 -0
- package/dist/prefetch/targetIndex.js +32 -0
- package/dist/prefetch/targetIndex.js.map +1 -0
- package/dist/prefetch/types.d.ts +283 -0
- package/dist/prefetch/types.d.ts.map +1 -0
- package/dist/prefetch/types.js +19 -0
- package/dist/prefetch/types.js.map +1 -0
- package/dist/previewBridge.d.ts +6 -0
- package/dist/previewBridge.d.ts.map +1 -1
- package/dist/previewBridge.js +25 -5
- package/dist/previewBridge.js.map +1 -1
- package/dist/previewMessages.d.ts +4 -3
- package/dist/previewMessages.d.ts.map +1 -1
- package/dist/previewMessages.js +12 -6
- package/dist/previewMessages.js.map +1 -1
- package/dist/process-worker.js +116 -109
- package/dist/relay.html +1 -1
- package/dist/shared/clock.d.ts +7 -0
- package/dist/shared/clock.d.ts.map +1 -0
- package/dist/shared/clock.js +10 -0
- package/dist/shared/clock.js.map +1 -0
- package/dist/shared/hardwareProbe.d.ts +26 -0
- package/dist/shared/hardwareProbe.d.ts.map +1 -0
- package/dist/shared/hardwareProbe.js +62 -0
- package/dist/shared/hardwareProbe.js.map +1 -0
- package/dist/shared/idb.d.ts +41 -0
- package/dist/shared/idb.d.ts.map +1 -0
- package/dist/shared/idb.js +184 -0
- package/dist/shared/idb.js.map +1 -0
- package/dist/shared/tokens.d.ts +7 -0
- package/dist/shared/tokens.d.ts.map +1 -0
- package/dist/shared/tokens.js +9 -0
- package/dist/shared/tokens.js.map +1 -0
- package/dist/snapshotStore.d.ts +2 -1
- package/dist/snapshotStore.d.ts.map +1 -1
- package/dist/snapshotStore.js +27 -12
- package/dist/snapshotStore.js.map +1 -1
- package/dist/styleCompilers.d.ts.map +1 -1
- package/dist/styleCompilers.js.map +1 -1
- package/dist/transport.js.map +1 -1
- package/package.json +11 -5
- package/src/adaptive/controller.ts +151 -0
- package/src/adaptive/costModel.ts +131 -0
- package/src/adaptive/planner.ts +127 -0
- package/src/adaptive/types.ts +137 -0
- package/src/check/index.ts +6 -1
- package/src/host.ts +33 -11
- package/src/inference/backends/mock.ts +77 -0
- package/src/inference/backends/onnx.ts +91 -0
- package/src/inference/backends/webllm.ts +79 -0
- package/src/inference/backends/wllama.ts +79 -0
- package/src/inference/capabilities.ts +46 -0
- package/src/inference/client.ts +276 -0
- package/src/inference/modelCache.ts +145 -0
- package/src/inference/protocol.ts +119 -0
- package/src/inference/tokenStream.ts +92 -0
- package/src/inference/types.ts +115 -0
- package/src/inference/worker.ts +191 -0
- package/src/inference/workerEntry.ts +18 -0
- package/src/kvcache/advanced.ts +86 -0
- package/src/kvcache/compatibility.ts +51 -0
- package/src/kvcache/lru.ts +100 -0
- package/src/kvcache/paged.ts +270 -0
- package/src/kvcache/quant.ts +88 -0
- package/src/kvcache/radix.ts +68 -0
- package/src/kvcache/runtime.ts +239 -0
- package/src/kvcache/types.ts +167 -0
- package/src/learning/fingerprint.ts +50 -0
- package/src/learning/index.ts +15 -0
- package/src/learning/learner.ts +304 -0
- package/src/learning/ledger.ts +54 -0
- package/src/learning/selection.ts +137 -0
- package/src/learning/stats.ts +39 -0
- package/src/learning/types.ts +142 -0
- package/src/memory/envProbe.ts +30 -0
- package/src/memory/estimates.ts +98 -0
- package/src/memory/eviction.ts +145 -0
- package/src/memory/manager.ts +380 -0
- package/src/memory/managerTypes.ts +61 -0
- package/src/memory/pressure.ts +120 -0
- package/src/memory/spillTier.ts +159 -0
- package/src/memory/storageSink.ts +289 -0
- package/src/memory/types.ts +217 -0
- package/src/memory/victims.ts +80 -0
- package/src/memory/workspace.ts +74 -0
- package/src/memoryIntegration/index.ts +7 -0
- package/src/memoryIntegration/knowledgeMemory.ts +339 -0
- package/src/memoryIntegration/persistence.ts +54 -0
- package/src/memoryIntegration/text.ts +185 -0
- package/src/memoryIntegration/types.ts +145 -0
- package/src/ml.ts +180 -0
- package/src/node/childRelay.ts +16 -3
- package/src/node/portResponder.ts +5 -3
- package/src/node/processHost.ts +16 -15
- package/src/node/protocol.ts +1 -1
- package/src/node/workerProcess.ts +1 -1
- package/src/prefetch/admission.ts +74 -0
- package/src/prefetch/loadRegistry.ts +156 -0
- package/src/prefetch/predictor.ts +199 -0
- package/src/prefetch/prefetcher.ts +369 -0
- package/src/prefetch/residentStore.ts +121 -0
- package/src/prefetch/selfTuner.ts +110 -0
- package/src/prefetch/stats.ts +120 -0
- package/src/prefetch/streaming.ts +231 -0
- package/src/prefetch/targetIndex.ts +40 -0
- package/src/prefetch/types.ts +307 -0
- package/src/previewBridge.ts +25 -5
- package/src/previewMessages.ts +11 -6
- package/src/shared/clock.ts +9 -0
- package/src/shared/hardwareProbe.ts +68 -0
- package/src/shared/idb.ts +203 -0
- package/src/shared/tokens.ts +8 -0
- package/src/snapshotStore.ts +25 -10
|
@@ -0,0 +1,128 @@
|
|
|
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
|
+
/** Storage budget: explicit > 0, else the quota hint, else 4× the RAM budget. `0` disables. */
|
|
14
|
+
export function resolveStorageBudget(configured, storageQuotaBytes, byteBudget) {
|
|
15
|
+
if (configured === 0)
|
|
16
|
+
return 0;
|
|
17
|
+
if (typeof configured === 'number' && Number.isFinite(configured) && configured > 0)
|
|
18
|
+
return configured;
|
|
19
|
+
if (storageQuotaBytes > 0)
|
|
20
|
+
return storageQuotaBytes;
|
|
21
|
+
return byteBudget * 4;
|
|
22
|
+
}
|
|
23
|
+
export function createSpillTier(options) {
|
|
24
|
+
const { storage, budgetBytes } = options;
|
|
25
|
+
const enabled = storage !== undefined && budgetBytes > 0;
|
|
26
|
+
const index = new Map();
|
|
27
|
+
let committed = 0;
|
|
28
|
+
let reserved = 0;
|
|
29
|
+
function setIndex(record) {
|
|
30
|
+
removeIndex(record.id);
|
|
31
|
+
index.set(record.id, record);
|
|
32
|
+
committed += record.bytes;
|
|
33
|
+
}
|
|
34
|
+
function removeIndex(id) {
|
|
35
|
+
const record = index.get(id);
|
|
36
|
+
if (!record)
|
|
37
|
+
return undefined;
|
|
38
|
+
index.delete(id);
|
|
39
|
+
committed -= record.bytes;
|
|
40
|
+
return record;
|
|
41
|
+
}
|
|
42
|
+
async function deleteQuietly(record) {
|
|
43
|
+
try {
|
|
44
|
+
await storage?.delete(record);
|
|
45
|
+
}
|
|
46
|
+
catch {
|
|
47
|
+
// Storage is best-effort. The in-memory spill index is the bound.
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
function fits(incomingBytes) {
|
|
51
|
+
return committed + reserved + incomingBytes <= budgetBytes;
|
|
52
|
+
}
|
|
53
|
+
async function trim(incomingBytes) {
|
|
54
|
+
const ordered = [...index.values()].sort((a, b) => a.spilledAt - b.spilledAt || a.id.localeCompare(b.id));
|
|
55
|
+
for (const oldest of ordered) {
|
|
56
|
+
if (fits(incomingBytes))
|
|
57
|
+
return;
|
|
58
|
+
// A concurrent call may already have dropped or replaced this record.
|
|
59
|
+
if (index.get(oldest.id) !== oldest)
|
|
60
|
+
continue;
|
|
61
|
+
removeIndex(oldest.id);
|
|
62
|
+
await deleteQuietly(oldest);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return {
|
|
66
|
+
enabled,
|
|
67
|
+
get: (id) => index.get(id),
|
|
68
|
+
has: (id) => index.has(id),
|
|
69
|
+
get count() {
|
|
70
|
+
return index.size;
|
|
71
|
+
},
|
|
72
|
+
bytes: () => committed,
|
|
73
|
+
async retain(entry, reason) {
|
|
74
|
+
if (!enabled || !storage)
|
|
75
|
+
return false;
|
|
76
|
+
if (!(entry.bytes >= 0) || entry.bytes > budgetBytes)
|
|
77
|
+
return false;
|
|
78
|
+
const previous = removeIndex(entry.id);
|
|
79
|
+
// Replacing a spill; a failed delete must not block the new write.
|
|
80
|
+
if (previous)
|
|
81
|
+
await deleteQuietly(previous);
|
|
82
|
+
await trim(entry.bytes);
|
|
83
|
+
// Check and reserve in the same synchronous step: a concurrent retain
|
|
84
|
+
// awaiting its own write can no longer push storage past the budget.
|
|
85
|
+
if (!fits(entry.bytes))
|
|
86
|
+
return false;
|
|
87
|
+
reserved += entry.bytes;
|
|
88
|
+
try {
|
|
89
|
+
const stored = await storage.spill({ ...entry, tier: 'storage' }, options.now());
|
|
90
|
+
setIndex(stored);
|
|
91
|
+
options.onSpill(entry, reason);
|
|
92
|
+
return true;
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
return false;
|
|
96
|
+
}
|
|
97
|
+
finally {
|
|
98
|
+
reserved -= entry.bytes;
|
|
99
|
+
}
|
|
100
|
+
},
|
|
101
|
+
async forget(id) {
|
|
102
|
+
const record = removeIndex(id);
|
|
103
|
+
if (!record)
|
|
104
|
+
return false;
|
|
105
|
+
await deleteQuietly(record);
|
|
106
|
+
return true;
|
|
107
|
+
},
|
|
108
|
+
async reload(id) {
|
|
109
|
+
const record = index.get(id);
|
|
110
|
+
if (!record || !storage)
|
|
111
|
+
return undefined;
|
|
112
|
+
let restored;
|
|
113
|
+
try {
|
|
114
|
+
restored = await storage.reload(record);
|
|
115
|
+
}
|
|
116
|
+
catch {
|
|
117
|
+
restored = undefined;
|
|
118
|
+
}
|
|
119
|
+
if (!restored) {
|
|
120
|
+
if (index.get(id) === record)
|
|
121
|
+
removeIndex(id);
|
|
122
|
+
return undefined;
|
|
123
|
+
}
|
|
124
|
+
return { ...restored, id, tier: 'ram', bytes: record.bytes };
|
|
125
|
+
},
|
|
126
|
+
};
|
|
127
|
+
}
|
|
128
|
+
//# sourceMappingURL=spillTier.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"spillTier.js","sourceRoot":"","sources":["../../src/memory/spillTier.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 3 — browser-storage residency sink.
|
|
3
|
+
*
|
|
4
|
+
* CPU-only environments have no VRAM. Cold weights spill to browser storage
|
|
5
|
+
* and reload from there. This sink is the residency view over the Phase 1
|
|
6
|
+
* IndexedDB `ModelCache` (`src/inference/modelCache.ts`): it does not open a
|
|
7
|
+
* second database and does not reimplement persistence. Tests inject
|
|
8
|
+
* `createMemoryModelCache()`; the browser injects `createModelCache()`.
|
|
9
|
+
*
|
|
10
|
+
* Spilled bytes are NOT charged against the RAM byte budget. A reload copies
|
|
11
|
+
* them back into a resident entry the caller admits.
|
|
12
|
+
*/
|
|
13
|
+
import type { ModelCache, ModelCacheEntry } from '../inference/modelCache.js';
|
|
14
|
+
import type { ResidentEntry } from './types.js';
|
|
15
|
+
/** A spill record. Payload bytes live in the Phase 1 model cache. */
|
|
16
|
+
export interface SpilledRecord {
|
|
17
|
+
id: string;
|
|
18
|
+
group: string;
|
|
19
|
+
component?: string;
|
|
20
|
+
bytes: number;
|
|
21
|
+
reloadCostMs: number;
|
|
22
|
+
reuseProbability: number;
|
|
23
|
+
/** Model-cache key the payload was stored under. */
|
|
24
|
+
cacheKey: string;
|
|
25
|
+
spilledAt: number;
|
|
26
|
+
}
|
|
27
|
+
export interface StorageSink {
|
|
28
|
+
/** Persist a resident's payload and return the spill record. */
|
|
29
|
+
spill(entry: ResidentEntry, now: number): Promise<SpilledRecord>;
|
|
30
|
+
/** Reload a spilled record's payload. Undefined if storage lost it. */
|
|
31
|
+
reload(record: SpilledRecord): Promise<ResidentEntry | undefined>;
|
|
32
|
+
/** Drop a spill. Best-effort. */
|
|
33
|
+
delete(record: SpilledRecord): Promise<void>;
|
|
34
|
+
/** Ids currently spilled, for diagnostics. */
|
|
35
|
+
keys(): Promise<string[]>;
|
|
36
|
+
}
|
|
37
|
+
export interface StorageSinkOptions {
|
|
38
|
+
/** Phase 1 model cache. Required — this module does not open IndexedDB itself. */
|
|
39
|
+
cache: ModelCache;
|
|
40
|
+
/**
|
|
41
|
+
* Encode an opaque payload to bytes for the model cache.
|
|
42
|
+
* Default: binary payloads (ArrayBuffer, SharedArrayBuffer, any TypedArray,
|
|
43
|
+
* DataView) are stored as their raw bytes and come back as the same type;
|
|
44
|
+
* everything else is UTF-8 JSON.
|
|
45
|
+
*/
|
|
46
|
+
encode?: (payload: unknown) => ArrayBuffer;
|
|
47
|
+
/**
|
|
48
|
+
* Inverse of `encode` for non-binary payloads. Default: UTF-8 JSON parse,
|
|
49
|
+
* falling back to the raw buffer. Binary payloads written by the default
|
|
50
|
+
* encoder never pass through here.
|
|
51
|
+
*/
|
|
52
|
+
decode?: (bytes: ArrayBuffer) => unknown;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Adapt a Phase 1 `ModelCache` into a residency spill sink.
|
|
56
|
+
* One cache key per resident id. Metadata rides in the cache entry's
|
|
57
|
+
* quantization/params fields plus a JSON header stored ahead of the payload,
|
|
58
|
+
* so a reload reconstructs the resident without a second store.
|
|
59
|
+
*/
|
|
60
|
+
export declare function createModelCacheSink(options: StorageSinkOptions): StorageSink;
|
|
61
|
+
/**
|
|
62
|
+
* In-memory sink for tests that do not want IndexedDB. Still ModelCache-shaped.
|
|
63
|
+
* The payload is kept by reference, so binary payloads (ArrayBuffer,
|
|
64
|
+
* TypedArray) reload as the very same object — nothing is serialized.
|
|
65
|
+
*/
|
|
66
|
+
export declare function createMemorySink(): StorageSink;
|
|
67
|
+
/** Re-export the Phase 1 entry type so callers need not import inference for a spill. */
|
|
68
|
+
export type { ModelCacheEntry };
|
|
69
|
+
//# sourceMappingURL=storageSink.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"storageSink.d.ts","sourceRoot":"","sources":["../../src/memory/storageSink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjE,uEAAuE;IACvE,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAClE,iCAAiC;IACjC,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,8CAA8C;IAC9C,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,WAAW,CAAC;IAC3C;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC;CAC1C;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAqD7E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CA6B9C;AA+HD,yFAAyF;AACzF,YAAY,EAAE,eAAe,EAAE,CAAC"}
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 3 — browser-storage residency sink.
|
|
3
|
+
*
|
|
4
|
+
* CPU-only environments have no VRAM. Cold weights spill to browser storage
|
|
5
|
+
* and reload from there. This sink is the residency view over the Phase 1
|
|
6
|
+
* IndexedDB `ModelCache` (`src/inference/modelCache.ts`): it does not open a
|
|
7
|
+
* second database and does not reimplement persistence. Tests inject
|
|
8
|
+
* `createMemoryModelCache()`; the browser injects `createModelCache()`.
|
|
9
|
+
*
|
|
10
|
+
* Spilled bytes are NOT charged against the RAM byte budget. A reload copies
|
|
11
|
+
* them back into a resident entry the caller admits.
|
|
12
|
+
*/
|
|
13
|
+
const CACHE_PREFIX = 'bfwc-resident:';
|
|
14
|
+
/** Copy the exact encoded bytes. `TextEncoder#encode().buffer` may be a larger pooled slab. */
|
|
15
|
+
function exactBuffer(bytes) {
|
|
16
|
+
return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Adapt a Phase 1 `ModelCache` into a residency spill sink.
|
|
20
|
+
* One cache key per resident id. Metadata rides in the cache entry's
|
|
21
|
+
* quantization/params fields plus a JSON header stored ahead of the payload,
|
|
22
|
+
* so a reload reconstructs the resident without a second store.
|
|
23
|
+
*/
|
|
24
|
+
export function createModelCacheSink(options) {
|
|
25
|
+
const decode = options.decode ?? defaultDecode;
|
|
26
|
+
const cache = options.cache;
|
|
27
|
+
return {
|
|
28
|
+
async spill(entry, now) {
|
|
29
|
+
const encoded = options.encode
|
|
30
|
+
? { encoding: 'custom', bytes: options.encode(entry.payload) }
|
|
31
|
+
: defaultEncode(entry.payload);
|
|
32
|
+
const header = encodeHeader(entry, now, encoded.encoding);
|
|
33
|
+
const bytes = concat(header, encoded.bytes);
|
|
34
|
+
await cache.put(cacheKey(entry.id), {
|
|
35
|
+
quantization: entry.component ?? 'resident',
|
|
36
|
+
paramsB: entry.bytes / 1e9,
|
|
37
|
+
bytes,
|
|
38
|
+
size: bytes.byteLength,
|
|
39
|
+
});
|
|
40
|
+
return {
|
|
41
|
+
id: entry.id,
|
|
42
|
+
group: entry.group,
|
|
43
|
+
component: entry.component,
|
|
44
|
+
bytes: entry.bytes,
|
|
45
|
+
reloadCostMs: entry.reloadCostMs,
|
|
46
|
+
reuseProbability: entry.reuseProbability,
|
|
47
|
+
cacheKey: cacheKey(entry.id),
|
|
48
|
+
spilledAt: now,
|
|
49
|
+
};
|
|
50
|
+
},
|
|
51
|
+
async reload(record) {
|
|
52
|
+
const stored = await cache.get(record.cacheKey);
|
|
53
|
+
if (!stored)
|
|
54
|
+
return undefined;
|
|
55
|
+
const split = splitHeader(stored.bytes);
|
|
56
|
+
if (!split)
|
|
57
|
+
return undefined;
|
|
58
|
+
const header = decodeHeader(split.header);
|
|
59
|
+
return {
|
|
60
|
+
id: record.id,
|
|
61
|
+
group: header?.group ?? record.group,
|
|
62
|
+
component: header?.component ?? record.component,
|
|
63
|
+
bytes: record.bytes,
|
|
64
|
+
reloadCostMs: record.reloadCostMs,
|
|
65
|
+
reuseProbability: record.reuseProbability,
|
|
66
|
+
tier: 'ram',
|
|
67
|
+
payload: decodePayload(header?.encoding, split.payload, decode),
|
|
68
|
+
};
|
|
69
|
+
},
|
|
70
|
+
async delete(record) {
|
|
71
|
+
await cache.delete(record.cacheKey);
|
|
72
|
+
},
|
|
73
|
+
async keys() {
|
|
74
|
+
const all = await cache.keys();
|
|
75
|
+
return all.filter((key) => key.startsWith(CACHE_PREFIX)).map((key) => key.slice(CACHE_PREFIX.length));
|
|
76
|
+
},
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* In-memory sink for tests that do not want IndexedDB. Still ModelCache-shaped.
|
|
81
|
+
* The payload is kept by reference, so binary payloads (ArrayBuffer,
|
|
82
|
+
* TypedArray) reload as the very same object — nothing is serialized.
|
|
83
|
+
*/
|
|
84
|
+
export function createMemorySink() {
|
|
85
|
+
const records = new Map();
|
|
86
|
+
return {
|
|
87
|
+
async spill(entry, now) {
|
|
88
|
+
const record = {
|
|
89
|
+
id: entry.id,
|
|
90
|
+
group: entry.group,
|
|
91
|
+
component: entry.component,
|
|
92
|
+
bytes: entry.bytes,
|
|
93
|
+
reloadCostMs: entry.reloadCostMs,
|
|
94
|
+
reuseProbability: entry.reuseProbability,
|
|
95
|
+
cacheKey: cacheKey(entry.id),
|
|
96
|
+
spilledAt: now,
|
|
97
|
+
};
|
|
98
|
+
records.set(entry.id, { record, entry: { ...entry, tier: 'storage' } });
|
|
99
|
+
return record;
|
|
100
|
+
},
|
|
101
|
+
async reload(record) {
|
|
102
|
+
const found = records.get(record.id);
|
|
103
|
+
if (!found)
|
|
104
|
+
return undefined;
|
|
105
|
+
return { ...found.entry, tier: 'ram' };
|
|
106
|
+
},
|
|
107
|
+
async delete(record) {
|
|
108
|
+
records.delete(record.id);
|
|
109
|
+
},
|
|
110
|
+
async keys() {
|
|
111
|
+
return [...records.keys()];
|
|
112
|
+
},
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
function cacheKey(id) {
|
|
116
|
+
return `${CACHE_PREFIX}${id}`;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Little-endian uint32 length prefix, then UTF-8 JSON. The header records how
|
|
120
|
+
* the payload was encoded so binary payloads are restored as binary. Headers
|
|
121
|
+
* written before `encoding` existed decode as JSON, as they always did.
|
|
122
|
+
*/
|
|
123
|
+
function encodeHeader(entry, now, encoding) {
|
|
124
|
+
const json = new TextEncoder().encode(JSON.stringify({
|
|
125
|
+
group: entry.group,
|
|
126
|
+
component: entry.component,
|
|
127
|
+
bytes: entry.bytes,
|
|
128
|
+
spilledAt: now,
|
|
129
|
+
encoding,
|
|
130
|
+
}));
|
|
131
|
+
const header = new Uint8Array(4 + json.byteLength);
|
|
132
|
+
new DataView(header.buffer).setUint32(0, json.byteLength, true);
|
|
133
|
+
header.set(json, 4);
|
|
134
|
+
return header;
|
|
135
|
+
}
|
|
136
|
+
function concat(header, payload) {
|
|
137
|
+
const body = new Uint8Array(payload);
|
|
138
|
+
const out = new Uint8Array(header.byteLength + body.byteLength);
|
|
139
|
+
out.set(header, 0);
|
|
140
|
+
out.set(body, header.byteLength);
|
|
141
|
+
return exactBuffer(out);
|
|
142
|
+
}
|
|
143
|
+
function splitHeader(bytes) {
|
|
144
|
+
if (bytes.byteLength < 4)
|
|
145
|
+
return undefined;
|
|
146
|
+
const length = new DataView(bytes).getUint32(0, true);
|
|
147
|
+
if (!Number.isFinite(length) || length < 0 || 4 + length > bytes.byteLength)
|
|
148
|
+
return undefined;
|
|
149
|
+
return {
|
|
150
|
+
header: new TextDecoder().decode(bytes.slice(4, 4 + length)),
|
|
151
|
+
payload: bytes.slice(4 + length),
|
|
152
|
+
};
|
|
153
|
+
}
|
|
154
|
+
function decodeHeader(header) {
|
|
155
|
+
try {
|
|
156
|
+
const parsed = JSON.parse(header);
|
|
157
|
+
return parsed;
|
|
158
|
+
}
|
|
159
|
+
catch {
|
|
160
|
+
return undefined;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
/** TypedArray constructors this realm has, by name. Resolved lazily (BigInt arrays may be absent). */
|
|
164
|
+
function typedArrayCtor(name) {
|
|
165
|
+
const known = [
|
|
166
|
+
'Int8Array', 'Uint8Array', 'Uint8ClampedArray', 'Int16Array', 'Uint16Array',
|
|
167
|
+
'Int32Array', 'Uint32Array', 'Float32Array', 'Float64Array', 'BigInt64Array', 'BigUint64Array',
|
|
168
|
+
];
|
|
169
|
+
if (!known.includes(name))
|
|
170
|
+
return undefined;
|
|
171
|
+
const ctor = globalThis[name];
|
|
172
|
+
return typeof ctor === 'function' ? ctor : undefined;
|
|
173
|
+
}
|
|
174
|
+
/** Brand check that also works across realms (workers, iframes, test environments). */
|
|
175
|
+
function tagOf(value) {
|
|
176
|
+
return Object.prototype.toString.call(value);
|
|
177
|
+
}
|
|
178
|
+
function copyBytes(view) {
|
|
179
|
+
const out = new Uint8Array(view.byteLength);
|
|
180
|
+
out.set(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
|
|
181
|
+
return out.buffer;
|
|
182
|
+
}
|
|
183
|
+
function defaultEncode(payload) {
|
|
184
|
+
const tag = tagOf(payload);
|
|
185
|
+
if (tag === '[object ArrayBuffer]' || tag === '[object SharedArrayBuffer]') {
|
|
186
|
+
const buffer = payload;
|
|
187
|
+
return { encoding: 'arraybuffer', bytes: copyBytes({ buffer, byteOffset: 0, byteLength: buffer.byteLength }) };
|
|
188
|
+
}
|
|
189
|
+
if (ArrayBuffer.isView(payload)) {
|
|
190
|
+
const bytes = copyBytes(payload);
|
|
191
|
+
if (tag === '[object DataView]')
|
|
192
|
+
return { encoding: 'dataview', bytes };
|
|
193
|
+
const name = payload.constructor?.name ?? '';
|
|
194
|
+
if (typedArrayCtor(name))
|
|
195
|
+
return { encoding: `typed:${name}`, bytes };
|
|
196
|
+
// An exotic view (a subclass): keep the bytes, restore as a plain buffer.
|
|
197
|
+
return { encoding: 'arraybuffer', bytes };
|
|
198
|
+
}
|
|
199
|
+
return { encoding: 'json', bytes: exactBuffer(new TextEncoder().encode(JSON.stringify(payload ?? null))) };
|
|
200
|
+
}
|
|
201
|
+
function decodePayload(encoding, bytes, decode) {
|
|
202
|
+
if (encoding === 'arraybuffer')
|
|
203
|
+
return bytes;
|
|
204
|
+
if (encoding === 'dataview')
|
|
205
|
+
return new DataView(bytes);
|
|
206
|
+
if (encoding?.startsWith('typed:')) {
|
|
207
|
+
const ctor = typedArrayCtor(encoding.slice('typed:'.length));
|
|
208
|
+
return ctor ? new ctor(bytes) : bytes;
|
|
209
|
+
}
|
|
210
|
+
return decode(bytes);
|
|
211
|
+
}
|
|
212
|
+
function defaultDecode(bytes) {
|
|
213
|
+
const text = new TextDecoder().decode(bytes);
|
|
214
|
+
try {
|
|
215
|
+
return JSON.parse(text);
|
|
216
|
+
}
|
|
217
|
+
catch {
|
|
218
|
+
return bytes;
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
//# sourceMappingURL=storageSink.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"storageSink.js","sourceRoot":"","sources":["../../src/memory/storageSink.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 3 — Hierarchical Memory & Residency Management: types.
|
|
3
|
+
*
|
|
4
|
+
* Owns WHERE model weights and layer components live (RAM / optional VRAM hint /
|
|
5
|
+
* browser storage) and HOW they are admitted, quoted, and evicted under a hard
|
|
6
|
+
* byte budget. It does not decide WHEN to run inference — that is the Adaptive
|
|
7
|
+
* Heterogeneous Execution Controller in `src/adaptive/`.
|
|
8
|
+
*
|
|
9
|
+
* Browser-compatible only: pure TypeScript, no native code, no dependencies.
|
|
10
|
+
* SharedArrayBuffer and WebGPU are optional probed facts, never gates.
|
|
11
|
+
* CPU-only is the primary path: residency falls back to system RAM + IndexedDB
|
|
12
|
+
* (the Phase 1 `ModelCache`) when no GPU is present.
|
|
13
|
+
*/
|
|
14
|
+
/** Where a resident entry's bytes currently live. */
|
|
15
|
+
export type ResidencyTier = 'ram' | 'vram' | 'storage';
|
|
16
|
+
/**
|
|
17
|
+
* One cacheable unit: a whole model, a layer, or a component (KV head, embedding).
|
|
18
|
+
* `bytes` is the footprint the budget accounts for. Payload is opaque — the
|
|
19
|
+
* manager never interprets it, so eviction cannot corrupt inference state.
|
|
20
|
+
*/
|
|
21
|
+
export interface ResidentEntry {
|
|
22
|
+
/** Stable id, e.g. `model:tiny-q4` or `model:tiny-q4/layer:7`. */
|
|
23
|
+
id: string;
|
|
24
|
+
/** Logical group the quota applies to (a model id, a component class). */
|
|
25
|
+
group: string;
|
|
26
|
+
/** Optional finer bucket inside the group (`layer`, `kv`, `embed`). */
|
|
27
|
+
component?: string;
|
|
28
|
+
/** Footprint in bytes. Must be >= 0. The hard budget counts this, not payload. */
|
|
29
|
+
bytes: number;
|
|
30
|
+
/** Estimated cost to reload this entry from storage or network, in ms. */
|
|
31
|
+
reloadCostMs: number;
|
|
32
|
+
/**
|
|
33
|
+
* Estimated probability this entry is reused before the next pressure event,
|
|
34
|
+
* in [0, 1]. Combined with reload cost to score eviction candidates.
|
|
35
|
+
*/
|
|
36
|
+
reuseProbability: number;
|
|
37
|
+
/** Where the bytes live. `vram` is a hint only — never required. */
|
|
38
|
+
tier: ResidencyTier;
|
|
39
|
+
/** Opaque payload. Retained so a hit returns the same object the caller put. */
|
|
40
|
+
payload?: unknown;
|
|
41
|
+
/** Optional hint that this entry is pinned and must not be evicted. */
|
|
42
|
+
pinned?: boolean;
|
|
43
|
+
}
|
|
44
|
+
/** A resident entry plus the bookkeeping the strategies and stats read. */
|
|
45
|
+
export interface TrackedEntry extends ResidentEntry {
|
|
46
|
+
/** Monotonic admission sequence (LRU recency, ARC MRU). */
|
|
47
|
+
admittedAt: number;
|
|
48
|
+
/** Last successful touch sequence. */
|
|
49
|
+
lastUsedAt: number;
|
|
50
|
+
/** Touch count since admission (LFU). */
|
|
51
|
+
hits: number;
|
|
52
|
+
/** ARC list membership. Absent for non-ARC strategies. */
|
|
53
|
+
arcList?: 't1' | 't2' | 'b1' | 'b2';
|
|
54
|
+
}
|
|
55
|
+
/** Result of a `get`. A miss is `{ hit: false }` — never throws for absence. */
|
|
56
|
+
export interface LookupResult {
|
|
57
|
+
hit: boolean;
|
|
58
|
+
entry?: TrackedEntry;
|
|
59
|
+
}
|
|
60
|
+
/** Why an admission or eviction happened. Explainable, for audit and Phase 4. */
|
|
61
|
+
export type ResidencyEventKind = 'admit' | 'hit' | 'miss' | 'evict' | 'pin' | 'unpin' | 'pressure' | 'workspace-grow' | 'workspace-shrink' | 'spill' | 'reload';
|
|
62
|
+
export interface ResidencyEvent {
|
|
63
|
+
kind: ResidencyEventKind;
|
|
64
|
+
/** Entry the event concerns, when there is one. */
|
|
65
|
+
id?: string;
|
|
66
|
+
/** Bytes freed (evict/shrink) or consumed (admit/grow). */
|
|
67
|
+
bytes?: number;
|
|
68
|
+
/** Human-readable reason. */
|
|
69
|
+
reason: string;
|
|
70
|
+
at: number;
|
|
71
|
+
}
|
|
72
|
+
/** Aggregate counters. `hitRate` is hits / (hits + misses); 0 when unused. */
|
|
73
|
+
export interface ResidencyStats {
|
|
74
|
+
hits: number;
|
|
75
|
+
misses: number;
|
|
76
|
+
admissions: number;
|
|
77
|
+
evictions: number;
|
|
78
|
+
spills: number;
|
|
79
|
+
reloads: number;
|
|
80
|
+
/** Bytes currently charged against the hard budget (RAM + VRAM residents). */
|
|
81
|
+
usedBytes: number;
|
|
82
|
+
/** Configured hard cap. */
|
|
83
|
+
byteBudget: number;
|
|
84
|
+
/** Bytes of the dynamic workspace currently allocated. */
|
|
85
|
+
workspaceBytes: number;
|
|
86
|
+
/** Residents currently held in RAM or VRAM. */
|
|
87
|
+
residentCount: number;
|
|
88
|
+
/** Residents spilled to browser storage (not charged against the RAM budget). */
|
|
89
|
+
spilledCount: number;
|
|
90
|
+
/** Bytes retained in browser storage. Bounded by `storageBudgetBytes`. */
|
|
91
|
+
spilledBytes: number;
|
|
92
|
+
hitRate: number;
|
|
93
|
+
}
|
|
94
|
+
/** Pressure reading. Facts the manager acts on; callers may also observe them. */
|
|
95
|
+
export interface MemoryPressure {
|
|
96
|
+
/** usedBytes / byteBudget, in [0, 1+] (can exceed 1 only before eviction runs). */
|
|
97
|
+
utilization: number;
|
|
98
|
+
/** True when utilization >= the configured pressure threshold. */
|
|
99
|
+
pressured: boolean;
|
|
100
|
+
/** Bytes that must be freed to get back under the target watermark. */
|
|
101
|
+
reclaimBytes: number;
|
|
102
|
+
/** Optional VRAM hint in bytes. 0 when no GPU was probed. */
|
|
103
|
+
vramBytes: number;
|
|
104
|
+
/** System RAM hint in bytes (navigator.deviceMemory when present). */
|
|
105
|
+
ramBytes: number;
|
|
106
|
+
/** Browser storage quota hint in bytes, when the environment reports one. */
|
|
107
|
+
storageQuotaBytes: number;
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Pluggable eviction strategy. The manager owns the map; the strategy only
|
|
111
|
+
* decides order. Strategies must be pure over the snapshot they are given so
|
|
112
|
+
* they stay swappable and unit-testable without a manager.
|
|
113
|
+
*/
|
|
114
|
+
export interface EvictionStrategy {
|
|
115
|
+
readonly name: 'lru' | 'lfu' | 'arc' | 'cost-aware' | (string & {});
|
|
116
|
+
/**
|
|
117
|
+
* Rank `candidates` (already filtered to evictable, unpinned residents)
|
|
118
|
+
* from most-evictable to least. Return a new array; do not mutate inputs.
|
|
119
|
+
*/
|
|
120
|
+
rank(candidates: readonly TrackedEntry[]): TrackedEntry[];
|
|
121
|
+
/**
|
|
122
|
+
* Optional hook so ARC (and similar) can record a hit/miss against its
|
|
123
|
+
* ghost lists. Default strategies ignore this.
|
|
124
|
+
*/
|
|
125
|
+
observe?(event: {
|
|
126
|
+
kind: 'hit' | 'miss' | 'admit' | 'evict';
|
|
127
|
+
entry: TrackedEntry;
|
|
128
|
+
}): void;
|
|
129
|
+
}
|
|
130
|
+
/** Per-group and optional per-component byte quotas. */
|
|
131
|
+
export interface Quota {
|
|
132
|
+
/** Group these bytes belong to (usually a model id). */
|
|
133
|
+
group: string;
|
|
134
|
+
/** Optional component bucket inside the group. Omit for a group-wide cap. */
|
|
135
|
+
component?: string;
|
|
136
|
+
/** Hard cap in bytes for this group (or group+component). */
|
|
137
|
+
byteCap: number;
|
|
138
|
+
}
|
|
139
|
+
export interface MemoryManagerConfig {
|
|
140
|
+
/**
|
|
141
|
+
* Hard byte budget for RAM+VRAM residents. Eviction runs until
|
|
142
|
+
* `usedBytes + incoming <= byteBudget`. Required — there is no implicit
|
|
143
|
+
* unbounded default.
|
|
144
|
+
*/
|
|
145
|
+
byteBudget: number;
|
|
146
|
+
/** Eviction strategy. Default: cost-aware. */
|
|
147
|
+
strategy?: EvictionStrategy;
|
|
148
|
+
/** Per-layer / per-component quotas. Enforced on admission, before the global budget. */
|
|
149
|
+
quotas?: readonly Quota[];
|
|
150
|
+
/**
|
|
151
|
+
* Utilization at or above which the manager reports pressure and shrinks
|
|
152
|
+
* the workspace. Default 0.85.
|
|
153
|
+
*/
|
|
154
|
+
pressureThreshold?: number;
|
|
155
|
+
/**
|
|
156
|
+
* After pressure eviction, utilization is brought down to this watermark.
|
|
157
|
+
* Default 0.7. Must be <= pressureThreshold.
|
|
158
|
+
*/
|
|
159
|
+
targetWatermark?: number;
|
|
160
|
+
/**
|
|
161
|
+
* Dynamic workspace bounds. The workspace grows on hits while headroom
|
|
162
|
+
* remains and shrinks under pressure, always inside [min, max] and always
|
|
163
|
+
* inside the residual byte budget.
|
|
164
|
+
*/
|
|
165
|
+
workspace?: {
|
|
166
|
+
minBytes: number;
|
|
167
|
+
maxBytes: number;
|
|
168
|
+
initialBytes?: number;
|
|
169
|
+
};
|
|
170
|
+
/**
|
|
171
|
+
* Optional VRAM budget hint in bytes. 0 (default) means CPU-only: no entry
|
|
172
|
+
* is placed in `vram`, and the hint is reported as a fact.
|
|
173
|
+
*/
|
|
174
|
+
vramBudgetBytes?: number;
|
|
175
|
+
/** System RAM hint. Default: probed `navigator.deviceMemory`, else 4 GiB. */
|
|
176
|
+
ramBytes?: number;
|
|
177
|
+
/** Browser storage quota hint. Default: probed `navigator.storage.estimate`, else 0. */
|
|
178
|
+
storageQuotaBytes?: number;
|
|
179
|
+
/**
|
|
180
|
+
* Cap on bytes retained in the browser-storage sink. Evicted RAM residents
|
|
181
|
+
* spill here until this cap, then the oldest spills are dropped. Default:
|
|
182
|
+
* `storageQuotaBytes` when it is set, otherwise `4 * byteBudget`. `0`
|
|
183
|
+
* disables retention (a spill is not kept).
|
|
184
|
+
*/
|
|
185
|
+
storageBudgetBytes?: number;
|
|
186
|
+
/** Retain at most this many explainable events. Default 256. */
|
|
187
|
+
eventLogLimit?: number;
|
|
188
|
+
/** Clock for tests. Default `Date.now`. */
|
|
189
|
+
now?: () => number;
|
|
190
|
+
}
|
|
191
|
+
/** Options for a single admission. */
|
|
192
|
+
export interface AdmitOptions {
|
|
193
|
+
/**
|
|
194
|
+
* When the budget cannot fit this entry even after evicting every unpinned
|
|
195
|
+
* resident, spill it to browser storage instead of rejecting. Default true
|
|
196
|
+
* when a storage sink is configured, false otherwise.
|
|
197
|
+
*/
|
|
198
|
+
spill?: boolean;
|
|
199
|
+
/** Pin on admission so later eviction cannot drop it. */
|
|
200
|
+
pin?: boolean;
|
|
201
|
+
}
|
|
202
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 3 — Hierarchical Memory & Residency Management: types.
|
|
3
|
+
*
|
|
4
|
+
* Owns WHERE model weights and layer components live (RAM / optional VRAM hint /
|
|
5
|
+
* browser storage) and HOW they are admitted, quoted, and evicted under a hard
|
|
6
|
+
* byte budget. It does not decide WHEN to run inference — that is the Adaptive
|
|
7
|
+
* Heterogeneous Execution Controller in `src/adaptive/`.
|
|
8
|
+
*
|
|
9
|
+
* Browser-compatible only: pure TypeScript, no native code, no dependencies.
|
|
10
|
+
* SharedArrayBuffer and WebGPU are optional probed facts, never gates.
|
|
11
|
+
* CPU-only is the primary path: residency falls back to system RAM + IndexedDB
|
|
12
|
+
* (the Phase 1 `ModelCache`) when no GPU is present.
|
|
13
|
+
*/
|
|
14
|
+
export {};
|
|
15
|
+
//# sourceMappingURL=types.js.map
|