@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,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 4 — prefetcher counters and the bounded, explainable event log.
|
|
3
|
+
*
|
|
4
|
+
* One ledger per prefetcher. Every other prefetch module writes its counters
|
|
5
|
+
* here instead of keeping its own, so `stats()` is a pure projection.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import type { PrefetchEvent, PrefetchStats } from './types.js';
|
|
9
|
+
|
|
10
|
+
/** Mutable counters. Modules increment fields directly; `snapshot()` projects them. */
|
|
11
|
+
export interface PrefetchCounters {
|
|
12
|
+
hits: number;
|
|
13
|
+
misses: number;
|
|
14
|
+
prefetchHits: number;
|
|
15
|
+
attempts: number;
|
|
16
|
+
completed: number;
|
|
17
|
+
throttled: number;
|
|
18
|
+
cancelled: number;
|
|
19
|
+
failed: number;
|
|
20
|
+
skipped: number;
|
|
21
|
+
totalWaitMs: number;
|
|
22
|
+
waitSamples: number;
|
|
23
|
+
totalLoadMs: number;
|
|
24
|
+
loadSamples: number;
|
|
25
|
+
peakConcurrent: number;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Live values owned by other modules, folded into a stats snapshot. */
|
|
29
|
+
export interface PrefetchLiveState {
|
|
30
|
+
inFlight: number;
|
|
31
|
+
residentBytes: number;
|
|
32
|
+
selfTunedOff: boolean;
|
|
33
|
+
selfTuneTrips: number;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export interface PrefetchLedger {
|
|
37
|
+
readonly counters: PrefetchCounters;
|
|
38
|
+
/** Append an event (stamped with the clock) and forward it to `onEvent`. */
|
|
39
|
+
record(event: Omit<PrefetchEvent, 'at'>): void;
|
|
40
|
+
/** Bounded log, oldest first. */
|
|
41
|
+
events(): readonly PrefetchEvent[];
|
|
42
|
+
/** Record one caller wait sample. */
|
|
43
|
+
noteWait(waitMs: number): void;
|
|
44
|
+
/** Record one completed load's duration. */
|
|
45
|
+
noteLoad(loadMs: number): void;
|
|
46
|
+
/** Track the peak number of concurrent speculative loads. */
|
|
47
|
+
noteConcurrency(count: number): void;
|
|
48
|
+
snapshot(live: PrefetchLiveState): PrefetchStats;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export interface PrefetchLedgerOptions {
|
|
52
|
+
now: () => number;
|
|
53
|
+
eventLogLimit: number;
|
|
54
|
+
onEvent?: (event: PrefetchEvent) => void;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function createPrefetchLedger(options: PrefetchLedgerOptions): PrefetchLedger {
|
|
58
|
+
const counters: PrefetchCounters = {
|
|
59
|
+
hits: 0,
|
|
60
|
+
misses: 0,
|
|
61
|
+
prefetchHits: 0,
|
|
62
|
+
attempts: 0,
|
|
63
|
+
completed: 0,
|
|
64
|
+
throttled: 0,
|
|
65
|
+
cancelled: 0,
|
|
66
|
+
failed: 0,
|
|
67
|
+
skipped: 0,
|
|
68
|
+
totalWaitMs: 0,
|
|
69
|
+
waitSamples: 0,
|
|
70
|
+
totalLoadMs: 0,
|
|
71
|
+
loadSamples: 0,
|
|
72
|
+
peakConcurrent: 0,
|
|
73
|
+
};
|
|
74
|
+
const log: PrefetchEvent[] = [];
|
|
75
|
+
|
|
76
|
+
return {
|
|
77
|
+
counters,
|
|
78
|
+
record(event) {
|
|
79
|
+
const full: PrefetchEvent = { ...event, at: options.now() };
|
|
80
|
+
log.push(full);
|
|
81
|
+
if (log.length > options.eventLogLimit) log.splice(0, log.length - options.eventLogLimit);
|
|
82
|
+
options.onEvent?.(full);
|
|
83
|
+
},
|
|
84
|
+
events: () => log,
|
|
85
|
+
noteWait(waitMs) {
|
|
86
|
+
counters.totalWaitMs += waitMs;
|
|
87
|
+
counters.waitSamples += 1;
|
|
88
|
+
},
|
|
89
|
+
noteLoad(loadMs) {
|
|
90
|
+
counters.totalLoadMs += loadMs;
|
|
91
|
+
counters.loadSamples += 1;
|
|
92
|
+
},
|
|
93
|
+
noteConcurrency(count) {
|
|
94
|
+
if (count > counters.peakConcurrent) counters.peakConcurrent = count;
|
|
95
|
+
},
|
|
96
|
+
snapshot(live) {
|
|
97
|
+
const total = counters.hits + counters.misses;
|
|
98
|
+
return {
|
|
99
|
+
hits: counters.hits,
|
|
100
|
+
misses: counters.misses,
|
|
101
|
+
prefetchHits: counters.prefetchHits,
|
|
102
|
+
attempts: counters.attempts,
|
|
103
|
+
completed: counters.completed,
|
|
104
|
+
throttled: counters.throttled,
|
|
105
|
+
cancelled: counters.cancelled,
|
|
106
|
+
failed: counters.failed,
|
|
107
|
+
skipped: counters.skipped,
|
|
108
|
+
hitRate: total === 0 ? 0 : counters.hits / total,
|
|
109
|
+
totalWaitMs: counters.totalWaitMs,
|
|
110
|
+
waitMs: counters.waitSamples === 0 ? 0 : counters.totalWaitMs / counters.waitSamples,
|
|
111
|
+
avgLoadMs: counters.loadSamples === 0 ? 0 : counters.totalLoadMs / counters.loadSamples,
|
|
112
|
+
inFlight: live.inFlight,
|
|
113
|
+
maxConcurrent: counters.peakConcurrent,
|
|
114
|
+
residentBytes: live.residentBytes,
|
|
115
|
+
selfTunedOff: live.selfTunedOff,
|
|
116
|
+
selfTuneTrips: live.selfTuneTrips,
|
|
117
|
+
};
|
|
118
|
+
},
|
|
119
|
+
};
|
|
120
|
+
}
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 4 — Predictive Prefetching: streaming primitives.
|
|
3
|
+
*
|
|
4
|
+
* Two independent concerns live here:
|
|
5
|
+
*
|
|
6
|
+
* 1. `createDoubleBuffer` — a two-slot buffer. The slot being consumed is
|
|
7
|
+
* never the slot being filled: a producer writes into the *staged* slot
|
|
8
|
+
* while the consumer drains the *current* slot, and the swap is atomic.
|
|
9
|
+
* This is what keeps a prefetch (or a streamed chunk) from corrupting
|
|
10
|
+
* the data the consumer is actively reading.
|
|
11
|
+
*
|
|
12
|
+
* 2. `createPrefillStream` — an adapter that streams PREFILL tokens when the
|
|
13
|
+
* backend supports it, and degrades gracefully (silently skipping the
|
|
14
|
+
* prefill phase) when it does not. Support is a probed FACT, never a
|
|
15
|
+
* gate: an unsupported backend still produces the same decode tokens.
|
|
16
|
+
*
|
|
17
|
+
* Both are pure TypeScript with no dependencies and no browser-only globals
|
|
18
|
+
* beyond `AbortSignal`, which is used opaquely.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
/** A two-slot buffer: the consumed slot and the staging slot. */
|
|
22
|
+
export interface DoubleBuffer<T> {
|
|
23
|
+
/** The value currently being consumed (undefined when empty). */
|
|
24
|
+
current(): T | undefined;
|
|
25
|
+
/** The value staged for the next swap (undefined when nothing is staged). */
|
|
26
|
+
staged(): T | undefined;
|
|
27
|
+
/** True when a value is staged and ready to be swapped in. */
|
|
28
|
+
hasStaged(): boolean;
|
|
29
|
+
/** Stage the next value. Replaces any previously staged value. */
|
|
30
|
+
stage(next: T): void;
|
|
31
|
+
/**
|
|
32
|
+
* Swap the staged value into the consumed slot. Returns the value that was
|
|
33
|
+
* previously current (so the caller can release it), or undefined when
|
|
34
|
+
* nothing was staged.
|
|
35
|
+
*/
|
|
36
|
+
swap(): T | undefined;
|
|
37
|
+
/** Set the consumed slot directly (used for the very first value). */
|
|
38
|
+
setCurrent(value: T): void;
|
|
39
|
+
/** Drop the staged value without swapping (e.g. it was invalidated). */
|
|
40
|
+
discardStaged(): void;
|
|
41
|
+
/** True when nothing is staged and nothing is current. */
|
|
42
|
+
isEmpty(): boolean;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export function createDoubleBuffer<T>(initial?: T): DoubleBuffer<T> {
|
|
46
|
+
let currentValue: T | undefined = initial;
|
|
47
|
+
let stagedValue: T | undefined;
|
|
48
|
+
return {
|
|
49
|
+
current: () => currentValue,
|
|
50
|
+
staged: () => stagedValue,
|
|
51
|
+
hasStaged: () => stagedValue !== undefined,
|
|
52
|
+
stage(next: T) {
|
|
53
|
+
stagedValue = next;
|
|
54
|
+
},
|
|
55
|
+
swap() {
|
|
56
|
+
if (stagedValue === undefined) return undefined;
|
|
57
|
+
const previous = currentValue;
|
|
58
|
+
currentValue = stagedValue;
|
|
59
|
+
stagedValue = undefined;
|
|
60
|
+
return previous;
|
|
61
|
+
},
|
|
62
|
+
setCurrent(value: T) {
|
|
63
|
+
currentValue = value;
|
|
64
|
+
},
|
|
65
|
+
discardStaged() {
|
|
66
|
+
stagedValue = undefined;
|
|
67
|
+
},
|
|
68
|
+
isEmpty: () => currentValue === undefined && stagedValue === undefined,
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** A chunk produced by a streaming producer. */
|
|
73
|
+
export interface StreamChunk<T> {
|
|
74
|
+
/** The payload. */
|
|
75
|
+
value: T;
|
|
76
|
+
/** Sequence number, used to detect gaps. */
|
|
77
|
+
index: number;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Drive a producer through a double buffer so the consumer always reads a
|
|
82
|
+
* stable chunk while the next one is being produced.
|
|
83
|
+
*
|
|
84
|
+
* The producer is called with an `AbortSignal`; aborting it stops the pipeline
|
|
85
|
+
* and the consumer's iterator ends.
|
|
86
|
+
*/
|
|
87
|
+
export async function* pumpDoubleBuffer<T>(
|
|
88
|
+
produce: (signal: AbortSignal) => AsyncIterable<T>,
|
|
89
|
+
options: { signal?: AbortSignal } = {},
|
|
90
|
+
): AsyncGenerator<StreamChunk<T>> {
|
|
91
|
+
const controller = new AbortController();
|
|
92
|
+
const forwardAbort = () => controller.abort();
|
|
93
|
+
options.signal?.addEventListener('abort', forwardAbort, { once: true });
|
|
94
|
+
const buffer = createDoubleBuffer<T>();
|
|
95
|
+
let index = 0;
|
|
96
|
+
try {
|
|
97
|
+
for await (const value of produce(controller.signal)) {
|
|
98
|
+
if (controller.signal.aborted) break;
|
|
99
|
+
// Stage the freshly produced value while the consumer holds the
|
|
100
|
+
// previous one; the swap happens on the next iteration.
|
|
101
|
+
buffer.stage(value);
|
|
102
|
+
const previous = buffer.swap();
|
|
103
|
+
void previous;
|
|
104
|
+
yield { value: buffer.current() as T, index: index++ };
|
|
105
|
+
}
|
|
106
|
+
} finally {
|
|
107
|
+
options.signal?.removeEventListener('abort', forwardAbort);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** One token emitted by a prefill-capable backend. */
|
|
112
|
+
export interface PrefillToken {
|
|
113
|
+
/** The token text (may be empty for a pure progress marker). */
|
|
114
|
+
token: string;
|
|
115
|
+
/** Index within the prefill stream. */
|
|
116
|
+
index: number;
|
|
117
|
+
/** True when this is the final prefill token. */
|
|
118
|
+
done?: boolean;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Options accepted by the prefill stream adapter. */
|
|
122
|
+
export interface PrefillStreamOptions {
|
|
123
|
+
/** The prompt messages being prefilled. */
|
|
124
|
+
messages: readonly { role: 'system' | 'user' | 'assistant'; content: string }[];
|
|
125
|
+
/** Maximum tokens to prefill. */
|
|
126
|
+
maxPrefillTokens?: number;
|
|
127
|
+
/** Abort the stream. */
|
|
128
|
+
signal?: AbortSignal;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* The backend contract the prefill adapter probes for.
|
|
133
|
+
*
|
|
134
|
+
* `supportsPrefillStreaming` is optional: when it is absent the adapter
|
|
135
|
+
* assumes prefill streaming is NOT supported and degrades gracefully.
|
|
136
|
+
*/
|
|
137
|
+
export interface PrefillStreamBackend {
|
|
138
|
+
/** Probe (or state) whether prefill tokens can be streamed. */
|
|
139
|
+
supportsPrefillStreaming?(): boolean | Promise<boolean>;
|
|
140
|
+
/** Stream prefill tokens. Only called when support was reported. */
|
|
141
|
+
streamPrefill?(options: PrefillStreamOptions): AsyncIterable<PrefillToken> | Promise<AsyncIterable<PrefillToken>>;
|
|
142
|
+
/** Stream the decode phase. Always required. */
|
|
143
|
+
streamDecode?(options: PrefillStreamOptions): AsyncIterable<{ token: string }> | AsyncIterable<string>;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** What the adapter produced, for accounting. */
|
|
147
|
+
export interface PrefillStreamResult {
|
|
148
|
+
/** Prefill tokens yielded (0 when the backend cannot stream prefill). */
|
|
149
|
+
prefillTokens: number;
|
|
150
|
+
/** True when the backend streamed prefill tokens. */
|
|
151
|
+
streamedPrefill: boolean;
|
|
152
|
+
/** Decode tokens yielded. */
|
|
153
|
+
decodeTokens: number;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* A prefill/decode stream that degrades gracefully.
|
|
158
|
+
*
|
|
159
|
+
* When the backend supports prefill streaming, prefill tokens are yielded
|
|
160
|
+
* first (they are the "warm-up" of the request and let the caller render
|
|
161
|
+
* progress before the first decode token). When it does not, the adapter
|
|
162
|
+
* yields no prefill tokens and streams decode only — the caller sees the same
|
|
163
|
+
* decode tokens either way, so nothing downstream has to special-case it.
|
|
164
|
+
*/
|
|
165
|
+
export interface PrefillStream {
|
|
166
|
+
/** Iterate the combined prefill + decode stream. */
|
|
167
|
+
stream(options: PrefillStreamOptions): AsyncGenerator<PrefillToken>;
|
|
168
|
+
/** Iterate and collect the accounting. */
|
|
169
|
+
run(options: PrefillStreamOptions): Promise<PrefillStreamResult>;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* Create the prefill stream adapter.
|
|
174
|
+
*
|
|
175
|
+
* The backend's support probe is consulted once per `stream()` call, so a
|
|
176
|
+
* backend that gains support at runtime is picked up without recreating the
|
|
177
|
+
* adapter.
|
|
178
|
+
*/
|
|
179
|
+
export function createPrefillStream(backend: PrefillStreamBackend): PrefillStream {
|
|
180
|
+
async function* generate(options: PrefillStreamOptions): AsyncGenerator<PrefillToken> {
|
|
181
|
+
let streamedPrefill = false;
|
|
182
|
+
const supported = await probeSupport(backend);
|
|
183
|
+
if (supported && backend.streamPrefill) {
|
|
184
|
+
const prefill = await backend.streamPrefill(options);
|
|
185
|
+
let index = 0;
|
|
186
|
+
for await (const token of prefill) {
|
|
187
|
+
if (options.signal?.aborted) return;
|
|
188
|
+
streamedPrefill = true;
|
|
189
|
+
yield { token: token.token, index: index++, done: token.done };
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
if (!backend.streamDecode) return;
|
|
193
|
+
const decode = backend.streamDecode(options);
|
|
194
|
+
for await (const event of decode) {
|
|
195
|
+
if (options.signal?.aborted) return;
|
|
196
|
+
const token = typeof event === 'string' ? event : event.token;
|
|
197
|
+
yield { token, index: -1 };
|
|
198
|
+
}
|
|
199
|
+
void streamedPrefill;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
return {
|
|
203
|
+
stream: generate,
|
|
204
|
+
async run(options) {
|
|
205
|
+
let prefillTokens = 0;
|
|
206
|
+
let decodeTokens = 0;
|
|
207
|
+
let streamedPrefill = false;
|
|
208
|
+
for await (const token of generate(options)) {
|
|
209
|
+
if (token.index >= 0) {
|
|
210
|
+
prefillTokens += 1;
|
|
211
|
+
streamedPrefill = true;
|
|
212
|
+
} else {
|
|
213
|
+
decodeTokens += 1;
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
return { prefillTokens, decodeTokens, streamedPrefill };
|
|
217
|
+
},
|
|
218
|
+
};
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/** Probe prefill-streaming support without ever throwing. */
|
|
222
|
+
export async function probeSupport(backend: PrefillStreamBackend): Promise<boolean> {
|
|
223
|
+
if (!backend.supportsPrefillStreaming) return false;
|
|
224
|
+
if (!backend.streamPrefill) return false;
|
|
225
|
+
try {
|
|
226
|
+
const supported = await backend.supportsPrefillStreaming();
|
|
227
|
+
return supported === true;
|
|
228
|
+
} catch {
|
|
229
|
+
return false;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 4 — the bounded index of known prefetch targets.
|
|
3
|
+
*
|
|
4
|
+
* Targets declared in `config.targets` are permanent. Targets the prefetcher
|
|
5
|
+
* learns from `request` / `prefetch` calls are remembered up to a cap, oldest
|
|
6
|
+
* forgotten first, so a workload with unbounded distinct ids cannot grow the
|
|
7
|
+
* index without limit. The Map itself is what the predictors read.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import type { TargetIndex } from './predictor.js';
|
|
11
|
+
import type { PrefetchTarget } from './types.js';
|
|
12
|
+
|
|
13
|
+
export interface BoundedTargetIndex {
|
|
14
|
+
/** The live index the predictors read. */
|
|
15
|
+
readonly index: TargetIndex;
|
|
16
|
+
/** Remember a target first seen at runtime. No-op when already known. */
|
|
17
|
+
remember(target: PrefetchTarget): void;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export function createTargetIndex(declared: readonly PrefetchTarget[], maxLearned: number): BoundedTargetIndex {
|
|
21
|
+
const index: TargetIndex = new Map();
|
|
22
|
+
for (const target of declared) index.set(target.id, target);
|
|
23
|
+
const learned = new Set<string>();
|
|
24
|
+
const cap = Math.max(1, maxLearned);
|
|
25
|
+
|
|
26
|
+
return {
|
|
27
|
+
index,
|
|
28
|
+
remember(target) {
|
|
29
|
+
if (index.has(target.id)) return;
|
|
30
|
+
index.set(target.id, target);
|
|
31
|
+
learned.add(target.id);
|
|
32
|
+
while (learned.size > cap) {
|
|
33
|
+
const oldest = learned.values().next().value as string | undefined;
|
|
34
|
+
if (oldest === undefined) break;
|
|
35
|
+
learned.delete(oldest);
|
|
36
|
+
index.delete(oldest);
|
|
37
|
+
}
|
|
38
|
+
},
|
|
39
|
+
};
|
|
40
|
+
}
|
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 4 — Predictive Prefetching & Streaming: types.
|
|
3
|
+
*
|
|
4
|
+
* The prefetcher predicts WHICH data a workload will need next and loads it
|
|
5
|
+
* asynchronously, ahead of the request that needs it. It is deliberately
|
|
6
|
+
* decoupled from every other phase:
|
|
7
|
+
* - `src/inference/` only knows how to run; it never asks to prefetch.
|
|
8
|
+
* - `src/adaptive/` decides where/how to run; it never triggers a prefetch.
|
|
9
|
+
* - `src/memory/` owns residency; the prefetcher only *reads* a pressure
|
|
10
|
+
* signal from it (or an injected `shouldThrottle()`).
|
|
11
|
+
*
|
|
12
|
+
* Prefetching is an OPTIMIZATION, never a decision: a missed prediction must
|
|
13
|
+
* cost exactly what the caller would have cost anyway, and a prefetch that
|
|
14
|
+
* cannot be served is dropped, never queued behind the active request.
|
|
15
|
+
*
|
|
16
|
+
* Browser-compatible only: pure TypeScript, no native code, no dependencies.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/** How a prediction was produced. */
|
|
20
|
+
export type PrefetchStrategy =
|
|
21
|
+
/** Static dependency graph declared by the workload (e.g. "tokenizer" -> "model"). */
|
|
22
|
+
| 'static-graph'
|
|
23
|
+
/** Frequency/recency over observed accesses (Markov-ish next-item prediction). */
|
|
24
|
+
| 'history'
|
|
25
|
+
/** Derived from the caller's workload profile (model size, prompt shape, stage). */
|
|
26
|
+
| 'context';
|
|
27
|
+
|
|
28
|
+
/** One thing the prefetcher can load. */
|
|
29
|
+
export interface PrefetchTarget {
|
|
30
|
+
/** Stable key, e.g. `model:tiny-q4` or `asset:tokenizer.json`. */
|
|
31
|
+
id: string;
|
|
32
|
+
/** Estimated footprint in bytes — used for pressure accounting. */
|
|
33
|
+
bytes: number;
|
|
34
|
+
/** Optional kind hint for reporting. */
|
|
35
|
+
kind?: 'model' | 'weights' | 'tokenizer' | 'asset' | 'graph';
|
|
36
|
+
/** Extra information the loader understands (opaque to the prefetcher). */
|
|
37
|
+
meta?: Record<string, unknown>;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** A declaration of "if you need A, you will probably also need B". */
|
|
41
|
+
export interface PrefetchEdge {
|
|
42
|
+
from: string;
|
|
43
|
+
to: string;
|
|
44
|
+
/** Relative likelihood in [0, 1]. Default 1. */
|
|
45
|
+
weight?: number;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** A declared static dependency graph (edges between target ids). */
|
|
49
|
+
export interface PrefetchGraph {
|
|
50
|
+
edges: readonly PrefetchEdge[];
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** Caller-supplied context about the workload that is about to run. */
|
|
54
|
+
export interface PrefetchContext {
|
|
55
|
+
/** The workload/model that is about to be used (its primary target id). */
|
|
56
|
+
target: string;
|
|
57
|
+
/** Optional profile hints used by the context strategy. */
|
|
58
|
+
profile?: {
|
|
59
|
+
/** Model size in billions of parameters. */
|
|
60
|
+
paramsB?: number;
|
|
61
|
+
/** Quantization bucket, matching `ModelRef.quantization`. */
|
|
62
|
+
quantization?: 'q4' | 'q5' | 'q8' | 'fp16';
|
|
63
|
+
/** Stage of the workload — used to predict the NEXT stage's needs. */
|
|
64
|
+
stage?: 'prefill' | 'decode' | 'postprocess';
|
|
65
|
+
/** Free-form workload labels, e.g. `['rag', 'code']`. */
|
|
66
|
+
labels?: readonly string[];
|
|
67
|
+
/** Explicit extra ids the caller expects to need soon. */
|
|
68
|
+
expects?: readonly string[];
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** Why a prefetch was started. */
|
|
73
|
+
export type PrefetchReason =
|
|
74
|
+
| 'static-graph'
|
|
75
|
+
| 'history'
|
|
76
|
+
| 'context'
|
|
77
|
+
| 'explicit';
|
|
78
|
+
|
|
79
|
+
/** Load one target. The prefetcher never interprets the result. */
|
|
80
|
+
export type PrefetchLoader = (target: PrefetchTarget, signal: AbortSignal) => Promise<unknown>;
|
|
81
|
+
|
|
82
|
+
/** Pressure signal: return true to stop prefetching right now. */
|
|
83
|
+
export type ShouldThrottle = () => boolean;
|
|
84
|
+
|
|
85
|
+
/** Outcome of a single prefetch attempt. */
|
|
86
|
+
export type PrefetchOutcome =
|
|
87
|
+
| 'hit'
|
|
88
|
+
| 'loaded'
|
|
89
|
+
| 'throttled'
|
|
90
|
+
| 'cancelled'
|
|
91
|
+
| 'duplicate'
|
|
92
|
+
| 'failed'
|
|
93
|
+
| 'skipped';
|
|
94
|
+
|
|
95
|
+
/** Why a prefetch was skipped or dropped. */
|
|
96
|
+
export type PrefetchSkipReason =
|
|
97
|
+
| 'disabled'
|
|
98
|
+
| 'pressure'
|
|
99
|
+
| 'concurrency-limit'
|
|
100
|
+
| 'already-loading'
|
|
101
|
+
| 'already-loaded'
|
|
102
|
+
/**
|
|
103
|
+
* A prediction named an id that is not in the target index (never declared, or
|
|
104
|
+
* learned and since forgotten). Its footprint is unknown, so it is not loaded
|
|
105
|
+
* speculatively; supply it via `request(target)` / `prefetch(target)` instead.
|
|
106
|
+
*/
|
|
107
|
+
| 'unknown-target'
|
|
108
|
+
| 'cancelled';
|
|
109
|
+
|
|
110
|
+
/** One recorded prefetch event (bounded log). */
|
|
111
|
+
export interface PrefetchEvent {
|
|
112
|
+
id: string;
|
|
113
|
+
strategy: PrefetchReason;
|
|
114
|
+
outcome: PrefetchOutcome;
|
|
115
|
+
/** Wall-clock ms spent loading (0 when the load never started). */
|
|
116
|
+
durationMs: number;
|
|
117
|
+
/** Why it was skipped, when it was not loaded. */
|
|
118
|
+
skipReason?: PrefetchSkipReason;
|
|
119
|
+
at: number;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** Aggregate counters. `hitRate` is hits / (hits + misses). */
|
|
123
|
+
export interface PrefetchStats {
|
|
124
|
+
/** Number of times a requested target was already resident (prefetch win). */
|
|
125
|
+
hits: number;
|
|
126
|
+
/** Number of times a requested target had to be loaded on demand. */
|
|
127
|
+
misses: number;
|
|
128
|
+
/**
|
|
129
|
+
* Hits where the resident copy came from a SPECULATIVE prefetch (as opposed
|
|
130
|
+
* to a previous demand load). This is the number that measures whether
|
|
131
|
+
* prefetching actually paid off.
|
|
132
|
+
*/
|
|
133
|
+
prefetchHits: number;
|
|
134
|
+
/** Total prefetch attempts (loaded + skipped + failed). */
|
|
135
|
+
attempts: number;
|
|
136
|
+
/** Loads that completed successfully — speculative prefetches AND demand loads (`request` misses). */
|
|
137
|
+
completed: number;
|
|
138
|
+
/** Prefetches dropped because the environment was under pressure. */
|
|
139
|
+
throttled: number;
|
|
140
|
+
/** Prefetches aborted by an invalidating signal. */
|
|
141
|
+
cancelled: number;
|
|
142
|
+
/** Prefetches that errored. */
|
|
143
|
+
failed: number;
|
|
144
|
+
/** Prefetches skipped because the target was already in flight / resident. */
|
|
145
|
+
skipped: number;
|
|
146
|
+
/** hits / (hits + misses); 0 when nothing was requested. */
|
|
147
|
+
hitRate: number;
|
|
148
|
+
/** Total ms the caller spent WAITING for data (0 when every request was a hit). */
|
|
149
|
+
totalWaitMs: number;
|
|
150
|
+
/** Mean ms the caller waited per request (0 when nothing was requested). */
|
|
151
|
+
waitMs: number;
|
|
152
|
+
/** Mean ms a prefetch took to load. */
|
|
153
|
+
avgLoadMs: number;
|
|
154
|
+
/** Prefetches currently in flight. */
|
|
155
|
+
inFlight: number;
|
|
156
|
+
/** Peak concurrent prefetches observed. */
|
|
157
|
+
maxConcurrent: number;
|
|
158
|
+
/** Total bytes of every resident value (prefetched and demand-loaded). */
|
|
159
|
+
residentBytes: number;
|
|
160
|
+
/** Whether the self-tuner has turned prefetching off. */
|
|
161
|
+
selfTunedOff: boolean;
|
|
162
|
+
/** Number of times the self-tuner turned prefetching off. */
|
|
163
|
+
selfTuneTrips: number;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/** Self-tuner configuration. */
|
|
167
|
+
export interface PrefetchTuningConfig {
|
|
168
|
+
/**
|
|
169
|
+
* Consecutive measurements with non-positive measured benefit before
|
|
170
|
+
* prefetching is disabled. Default 3.
|
|
171
|
+
*/
|
|
172
|
+
disableAfter?: number;
|
|
173
|
+
/**
|
|
174
|
+
* Minimum number of measurements before the tuner may act. Default 3.
|
|
175
|
+
*/
|
|
176
|
+
minSamples?: number;
|
|
177
|
+
/** Re-enable automatically after this many ms. 0 disables re-enabling. Default 0. */
|
|
178
|
+
retryAfterMs?: number;
|
|
179
|
+
/**
|
|
180
|
+
* Outstanding (unclaimed) speculative loads tracked individually. Older ones
|
|
181
|
+
* still count as waste but are folded into a single total. Default 256.
|
|
182
|
+
*/
|
|
183
|
+
maxTrackedLoads?: number;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** Prefetcher configuration. */
|
|
187
|
+
export interface PrefetchConfig {
|
|
188
|
+
/** Load function. Required — the prefetcher never fetches anything itself. */
|
|
189
|
+
loader: PrefetchLoader;
|
|
190
|
+
/**
|
|
191
|
+
* Pressure gate. When it returns true, no prefetch starts and in-flight
|
|
192
|
+
* prefetches are dropped. Defaults to "never under pressure".
|
|
193
|
+
*/
|
|
194
|
+
shouldThrottle?: ShouldThrottle;
|
|
195
|
+
/**
|
|
196
|
+
* Static dependency graph. Targets reachable from a requested id are
|
|
197
|
+
* prefetched with the `static-graph` strategy.
|
|
198
|
+
*/
|
|
199
|
+
graph?: PrefetchGraph;
|
|
200
|
+
/** Known target footprints, so pressure accounting and prediction can size things. */
|
|
201
|
+
targets?: readonly PrefetchTarget[];
|
|
202
|
+
/** Maximum number of concurrent prefetches. Default 2. */
|
|
203
|
+
maxConcurrent?: number;
|
|
204
|
+
/** Maximum number of targets prefetched for one request. Default 8. */
|
|
205
|
+
maxTargetsPerRequest?: number;
|
|
206
|
+
/** History window size (number of observed accesses kept). Default 32. */
|
|
207
|
+
historyWindow?: number;
|
|
208
|
+
/** Minimum confidence (0..1) for a prediction to be acted on. Default 0.2. */
|
|
209
|
+
minConfidence?: number;
|
|
210
|
+
/** Master switch. Default true. */
|
|
211
|
+
enabled?: boolean;
|
|
212
|
+
/**
|
|
213
|
+
* Byte budget for EVERY resident value — speculative prefetches and demand
|
|
214
|
+
* loads, claimed or not. When the resident set exceeds it, unclaimed
|
|
215
|
+
* prefetches are dropped first (oldest first), then the least recently used
|
|
216
|
+
* values. Default: no byte bound (the entry cap still applies).
|
|
217
|
+
*/
|
|
218
|
+
residentBudgetBytes?: number;
|
|
219
|
+
/** Cap on the number of resident values, evicted in the same order. Default 1024. */
|
|
220
|
+
maxResidentEntries?: number;
|
|
221
|
+
/**
|
|
222
|
+
* Cap on targets remembered at runtime (supplied to `request` / `prefetch` but
|
|
223
|
+
* not declared in `targets`). Oldest forgotten first; forgetting drops only the
|
|
224
|
+
* metadata, never a resident value. Predictions do not teach the index.
|
|
225
|
+
* Default 1024.
|
|
226
|
+
*/
|
|
227
|
+
maxKnownTargets?: number;
|
|
228
|
+
/** Self-tuner configuration. */
|
|
229
|
+
tuning?: PrefetchTuningConfig;
|
|
230
|
+
/** Clock for tests. Default: the shared monotonic clock (`performance.now`, else `Date.now`). */
|
|
231
|
+
now?: () => number;
|
|
232
|
+
/** Event sink for explainability (also recorded in the bounded log). */
|
|
233
|
+
onEvent?: (event: PrefetchEvent) => void;
|
|
234
|
+
/** Log capacity. Default 128. */
|
|
235
|
+
eventLogLimit?: number;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** A prediction the prefetcher made, with its confidence and origin. */
|
|
239
|
+
export interface PrefetchPrediction {
|
|
240
|
+
target: PrefetchTarget;
|
|
241
|
+
strategy: PrefetchReason;
|
|
242
|
+
/** Confidence in [0, 1]. */
|
|
243
|
+
confidence: number;
|
|
244
|
+
/** Why it was predicted. */
|
|
245
|
+
reason: string;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/** Result of requesting data through the prefetcher. */
|
|
249
|
+
export interface PrefetchRequestResult {
|
|
250
|
+
/** True when the data was already resident (prefetch hit). */
|
|
251
|
+
hit: boolean;
|
|
252
|
+
/** The loaded value (whatever the loader returned). */
|
|
253
|
+
value: unknown;
|
|
254
|
+
/** ms spent waiting for the value (0 for a hit). */
|
|
255
|
+
waitMs: number;
|
|
256
|
+
/** Targets the prefetcher kicked off in the background for this request. */
|
|
257
|
+
predicted: PrefetchPrediction[];
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/** The public prefetcher surface. */
|
|
261
|
+
export interface Prefetcher {
|
|
262
|
+
/**
|
|
263
|
+
* Get a target, using a prefetched copy when one is resident and loading it
|
|
264
|
+
* on demand otherwise. Records hit/miss and wait-time accounting.
|
|
265
|
+
*/
|
|
266
|
+
request(target: PrefetchTarget, options?: { signal?: AbortSignal }): Promise<PrefetchRequestResult>;
|
|
267
|
+
/**
|
|
268
|
+
* Request by id; the target must be known (declared in `targets`, or learned at
|
|
269
|
+
* runtime and not yet forgotten past `maxKnownTargets`). Rejects for an unknown id
|
|
270
|
+
* — its footprint is unknown, so it could not be held to the resident byte budget;
|
|
271
|
+
* use `request(target)` to supply (and relearn) it.
|
|
272
|
+
*/
|
|
273
|
+
requestById(id: string, options?: { signal?: AbortSignal }): Promise<PrefetchRequestResult>;
|
|
274
|
+
/**
|
|
275
|
+
* Ask the prefetcher to predict and start loading what a workload will need
|
|
276
|
+
* next. Returns the predictions it acted on.
|
|
277
|
+
*/
|
|
278
|
+
predict(context: PrefetchContext, options?: { signal?: AbortSignal }): PrefetchPrediction[];
|
|
279
|
+
/** Explicitly prefetch one target (bypasses prediction, not the pressure gate). */
|
|
280
|
+
prefetch(target: PrefetchTarget, options?: { signal?: AbortSignal; strategy?: PrefetchReason }): Promise<PrefetchOutcome>;
|
|
281
|
+
/** Cancel every in-flight prefetch and release unclaimed prefetched data. */
|
|
282
|
+
cancelAll(reason?: string): void;
|
|
283
|
+
/** Cancel in-flight prefetches for one target id. */
|
|
284
|
+
cancel(targetId: string, reason?: string): void;
|
|
285
|
+
/**
|
|
286
|
+
* Drop a resident value — demand-loaded, claimed or prefetched — and its
|
|
287
|
+
* resident bookkeeping (bytes, recency). In-flight loads are not affected
|
|
288
|
+
* (use `cancel` for those). Returns whether something was dropped.
|
|
289
|
+
*/
|
|
290
|
+
release(targetId: string): boolean;
|
|
291
|
+
/** Current aggregate counters. */
|
|
292
|
+
stats(): PrefetchStats;
|
|
293
|
+
/** hits / (hits + misses). */
|
|
294
|
+
hitRate(): number;
|
|
295
|
+
/** Mean ms the caller waited for data. */
|
|
296
|
+
waitMs(): number;
|
|
297
|
+
/** Bounded, explainable event log, oldest first. */
|
|
298
|
+
events(): readonly PrefetchEvent[];
|
|
299
|
+
/** Resident target ids. */
|
|
300
|
+
residentIds(): string[];
|
|
301
|
+
/** True when the self-tuner has disabled prefetching. */
|
|
302
|
+
isEnabled(): boolean;
|
|
303
|
+
/** Turn prefetching on/off explicitly (overrides the self-tuner's decision). */
|
|
304
|
+
setEnabled(enabled: boolean): void;
|
|
305
|
+
/** Resolve once no loads are in flight (test / diagnostic helper). */
|
|
306
|
+
whenIdle(): Promise<void>;
|
|
307
|
+
}
|