@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,137 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 7 — strategy selection policies and the underperformance guard.
|
|
3
|
+
*
|
|
4
|
+
* Pure functions over one signature's row of running stats. The learner
|
|
5
|
+
* composes them; none of them records anything or applies anything.
|
|
6
|
+
* - `candidatePool` — the prevalidated strategies eligible right now.
|
|
7
|
+
* - `exploit` / `explore` — epsilon-greedy's two arms.
|
|
8
|
+
* - `banditPick` — opt-in UCB1.
|
|
9
|
+
* - `revertCheck` — the ONE auto-revert rule, used both when an observation
|
|
10
|
+
* lands and when a recommendation is about to be made.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { emptyStat, ucb1, type RunningStat } from './stats.js';
|
|
14
|
+
import type { SafeStrategy } from './types.js';
|
|
15
|
+
|
|
16
|
+
/** One signature's per-strategy stats. */
|
|
17
|
+
export type StatRow = ReadonlyMap<string, RunningStat>;
|
|
18
|
+
|
|
19
|
+
/** A selection and its human-readable why. */
|
|
20
|
+
export interface StrategyPick {
|
|
21
|
+
strategy: string;
|
|
22
|
+
reason: string;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** Strategies eligible now: every registered one, minus pressure-sensitive ones under pressure. */
|
|
26
|
+
export function candidatePool(
|
|
27
|
+
strategies: ReadonlyMap<string, SafeStrategy>,
|
|
28
|
+
incumbent: string,
|
|
29
|
+
pressured: boolean,
|
|
30
|
+
): string[] {
|
|
31
|
+
if (!strategies.has(incumbent)) return [incumbent];
|
|
32
|
+
const ids = [...strategies.keys()];
|
|
33
|
+
const filtered = pressured ? ids.filter((id) => !strategies.get(id)?.pressureSensitive) : ids;
|
|
34
|
+
return filtered.length === 0 ? [incumbent] : filtered;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Lowest mean cost among strategies with at least `minSamples` samples. */
|
|
38
|
+
export function exploit(row: StatRow | undefined, incumbent: string, pool: readonly string[], minSamples: number): StrategyPick {
|
|
39
|
+
let best: string | null = null;
|
|
40
|
+
let bestMean = Number.POSITIVE_INFINITY;
|
|
41
|
+
for (const id of pool) {
|
|
42
|
+
const stat = row?.get(id);
|
|
43
|
+
if (!stat || stat.n < minSamples) continue;
|
|
44
|
+
if (stat.mean < bestMean) {
|
|
45
|
+
bestMean = stat.mean;
|
|
46
|
+
best = id;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
if (!best) {
|
|
50
|
+
return {
|
|
51
|
+
strategy: incumbent,
|
|
52
|
+
reason: `staying with ${incumbent}: no registered strategy has ${minSamples} samples yet`,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
const inc = row?.get(incumbent);
|
|
56
|
+
const incText = inc && inc.n > 0 ? `${inc.mean.toFixed(1)}ms (n=${inc.n})` : 'no samples';
|
|
57
|
+
if (best === incumbent) {
|
|
58
|
+
return {
|
|
59
|
+
strategy: incumbent,
|
|
60
|
+
reason: `${incumbent} has the lowest mean cost (${bestMean.toFixed(1)}ms) among strategies with ≥${minSamples} samples`,
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
return {
|
|
64
|
+
strategy: best,
|
|
65
|
+
reason:
|
|
66
|
+
`${best} mean ${bestMean.toFixed(1)}ms beats incumbent ${incumbent} (${incText}) ` +
|
|
67
|
+
`after ≥${minSamples} samples`,
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Uniformly pick an alternative to the incumbent (the incumbent when there is none). */
|
|
72
|
+
export function explore(pool: readonly string[], incumbent: string, rng: () => number): string {
|
|
73
|
+
const others = pool.filter((id) => id !== incumbent);
|
|
74
|
+
if (others.length === 0) return incumbent;
|
|
75
|
+
const idx = Math.min(others.length - 1, Math.floor(rng() * others.length));
|
|
76
|
+
return others[idx] ?? incumbent;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** UCB1 over the row; holds on the incumbent until any baseline observation exists. */
|
|
80
|
+
export function banditPick(row: StatRow | undefined, incumbent: string, pool: readonly string[]): StrategyPick {
|
|
81
|
+
const totalN = row ? [...row.values()].reduce((sum, s) => sum + s.n, 0) : 0;
|
|
82
|
+
if (totalN <= 0) {
|
|
83
|
+
return {
|
|
84
|
+
strategy: incumbent,
|
|
85
|
+
reason: 'contextual bandit held: no baseline observations yet — staying with incumbent',
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
const unsampled = pool.filter((id) => (row?.get(id)?.n ?? 0) === 0);
|
|
89
|
+
const next = unsampled.find((id) => id !== incumbent);
|
|
90
|
+
if (next) {
|
|
91
|
+
return {
|
|
92
|
+
strategy: next,
|
|
93
|
+
reason: `UCB1 exploring unsampled prevalidated strategy ${next} (baseline n=${totalN})`,
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
let best = incumbent;
|
|
97
|
+
let bestScore = Number.NEGATIVE_INFINITY;
|
|
98
|
+
for (const id of pool) {
|
|
99
|
+
const score = ucb1(row?.get(id) ?? emptyStat(), totalN);
|
|
100
|
+
if (score > bestScore) {
|
|
101
|
+
bestScore = score;
|
|
102
|
+
best = id;
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
return {
|
|
106
|
+
strategy: best,
|
|
107
|
+
reason: `UCB1 selected ${best} (score ${Number.isFinite(bestScore) ? bestScore.toFixed(4) : 'inf'}) over ${pool.length} prevalidated strategies`,
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export interface RevertCheckInput {
|
|
112
|
+
row: StatRow | undefined;
|
|
113
|
+
/** The strategy in use (or about to be recommended). */
|
|
114
|
+
candidate: string;
|
|
115
|
+
/** The incumbent it is measured against. */
|
|
116
|
+
baseline: string;
|
|
117
|
+
minSamples: number;
|
|
118
|
+
underperformRatio: number;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* The auto-revert rule: once both have `minSamples` samples, a candidate whose
|
|
123
|
+
* mean cost exceeds the baseline's by more than `underperformRatio` must be
|
|
124
|
+
* reverted. Returns the reason when it must, undefined otherwise.
|
|
125
|
+
*/
|
|
126
|
+
export function revertCheck(input: RevertCheckInput): string | undefined {
|
|
127
|
+
const { row, candidate, baseline, minSamples, underperformRatio } = input;
|
|
128
|
+
if (candidate === baseline) return undefined;
|
|
129
|
+
const cur = row?.get(candidate);
|
|
130
|
+
const prev = row?.get(baseline);
|
|
131
|
+
if (!cur || !prev || cur.n < minSamples || prev.n < minSamples) return undefined;
|
|
132
|
+
if (!(cur.mean > prev.mean * underperformRatio)) return undefined;
|
|
133
|
+
return (
|
|
134
|
+
`auto-revert: ${candidate} mean ${cur.mean.toFixed(1)}ms exceeds incumbent ${baseline} ` +
|
|
135
|
+
`mean ${prev.mean.toFixed(1)}ms by more than ${Math.round((underperformRatio - 1) * 100)}%`
|
|
136
|
+
);
|
|
137
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Running mean/variance (Welford). Pure, deterministic, no allocations beyond the struct.
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
export interface RunningStat {
|
|
6
|
+
n: number;
|
|
7
|
+
mean: number;
|
|
8
|
+
/** Sum of squares of differences from the running mean (Welford M2). */
|
|
9
|
+
m2: number;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export function emptyStat(): RunningStat {
|
|
13
|
+
return { n: 0, mean: 0, m2: 0 };
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export function observeStat(stat: RunningStat, value: number): void {
|
|
17
|
+
stat.n += 1;
|
|
18
|
+
const delta = value - stat.mean;
|
|
19
|
+
stat.mean += delta / stat.n;
|
|
20
|
+
const delta2 = value - stat.mean;
|
|
21
|
+
stat.m2 += delta * delta2;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** Sample variance. 0 until two observations exist. */
|
|
25
|
+
export function variance(stat: RunningStat): number {
|
|
26
|
+
if (stat.n < 2) return 0;
|
|
27
|
+
return stat.m2 / (stat.n - 1);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* UCB1 on a reward in (0, 1], where reward = 1 / (1 + mean cost).
|
|
32
|
+
* Unsampled arms return +Infinity so they are explored before exploitation.
|
|
33
|
+
*/
|
|
34
|
+
export function ucb1(stat: RunningStat, totalN: number): number {
|
|
35
|
+
if (stat.n <= 0) return Number.POSITIVE_INFINITY;
|
|
36
|
+
const reward = 1 / (1 + Math.max(0, stat.mean));
|
|
37
|
+
const bonus = Math.sqrt((2 * Math.log(Math.max(totalN, 1))) / stat.n);
|
|
38
|
+
return reward + bonus;
|
|
39
|
+
}
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 7 — Online Performance Learning: shared types.
|
|
3
|
+
*
|
|
4
|
+
* Learning emits plain-data suggestions. It never applies them to another
|
|
5
|
+
* module, and it never changes model correctness or memory semantics.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
/** A strategy the learner is allowed to recommend. Unregistered ids are refused. */
|
|
9
|
+
export interface SafeStrategy {
|
|
10
|
+
id: string;
|
|
11
|
+
/**
|
|
12
|
+
* Must be `true`. The learner refuses a strategy that has not been marked
|
|
13
|
+
* prevalidated — it will not invent or trial an unknown execution path.
|
|
14
|
+
*/
|
|
15
|
+
validated: true;
|
|
16
|
+
/** Plain-data config this strategy implies. Copied into recommendations; never applied here. */
|
|
17
|
+
deltas?: ReadonlyArray<ConfigDeltaField>;
|
|
18
|
+
/** Heavier on memory or thermals. Skipped while pressure/thermal is hot. */
|
|
19
|
+
pressureSensitive?: boolean;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface ConfigDeltaField {
|
|
23
|
+
field: string;
|
|
24
|
+
value: string | number | boolean;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** Bucketed workload identity. Same buckets ⇒ same signature. */
|
|
28
|
+
export interface WorkloadFingerprintInput {
|
|
29
|
+
paramsB?: number;
|
|
30
|
+
quantization?: string;
|
|
31
|
+
promptTokens?: number;
|
|
32
|
+
decodeTokens?: number;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** One measured run. `correct: false` is ignored so a bad run cannot teach a strategy. */
|
|
36
|
+
export interface OutcomeObservation {
|
|
37
|
+
signature: string;
|
|
38
|
+
strategy: string;
|
|
39
|
+
/** Wall-clock cost. Lower is better. */
|
|
40
|
+
costMs: number;
|
|
41
|
+
overheadMs?: number;
|
|
42
|
+
benefitMs?: number;
|
|
43
|
+
/**
|
|
44
|
+
* When `false`, the observation is dropped. Omitted means the caller asserts
|
|
45
|
+
* the run preserved correctness (the only kind of run learning may use).
|
|
46
|
+
*/
|
|
47
|
+
correct?: boolean;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export interface Recommendation {
|
|
51
|
+
signature: string;
|
|
52
|
+
/** Strategy to use. Equals the incumbent when learning declines to switch. */
|
|
53
|
+
strategy: string;
|
|
54
|
+
/** Previous strategy, when this recommendation would change it. */
|
|
55
|
+
from: string;
|
|
56
|
+
/** Human-readable why. Always present. */
|
|
57
|
+
reason: string;
|
|
58
|
+
/** Suggestions only. Applying them is the caller's job. */
|
|
59
|
+
deltas: ConfigDeltaField[];
|
|
60
|
+
/** Time spent producing this recommendation. */
|
|
61
|
+
overheadMs: number;
|
|
62
|
+
/** True when the guard reverted an underperforming strategy. */
|
|
63
|
+
autoReverted: boolean;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export interface HistoryEntry {
|
|
67
|
+
signature: string;
|
|
68
|
+
from: string;
|
|
69
|
+
to: string;
|
|
70
|
+
reason: string;
|
|
71
|
+
deltas: ConfigDeltaField[];
|
|
72
|
+
overheadMs: number;
|
|
73
|
+
at: number;
|
|
74
|
+
auto: boolean;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export interface LearningStats {
|
|
78
|
+
decisions: number;
|
|
79
|
+
observations: number;
|
|
80
|
+
ignored: number;
|
|
81
|
+
lastOverheadMs: number;
|
|
82
|
+
totalOverheadMs: number;
|
|
83
|
+
disabled: boolean;
|
|
84
|
+
/** Mean recorded overhead per decision. */
|
|
85
|
+
meanOverheadMs: number;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export interface LearnerConfig {
|
|
89
|
+
/** When true, recommend() is a deterministic pass-through and apply() is a no-op. */
|
|
90
|
+
disabled?: boolean;
|
|
91
|
+
/** Exploration rate for epsilon-greedy. Ignored when disabled. Default 0.1. */
|
|
92
|
+
epsilon?: number;
|
|
93
|
+
/** Samples required before a strategy can win on exploit. Default 3. */
|
|
94
|
+
minSamples?: number;
|
|
95
|
+
/**
|
|
96
|
+
* Auto-revert when the applied strategy's mean cost exceeds the incumbent's
|
|
97
|
+
* by this factor. Default 1.15 (15% worse).
|
|
98
|
+
*/
|
|
99
|
+
underperformRatio?: number;
|
|
100
|
+
/**
|
|
101
|
+
* Optional. When true (and only after the table has observations), selection
|
|
102
|
+
* uses UCB1 on inverse cost instead of epsilon-greedy. Default false.
|
|
103
|
+
*/
|
|
104
|
+
contextualBandit?: boolean;
|
|
105
|
+
/** Injectable clock so tests can pin overhead accounting. Default `performance.now`. */
|
|
106
|
+
now?: () => number;
|
|
107
|
+
/** Injectable RNG in `[0, 1)`. Default `Math.random`. Never called when disabled. */
|
|
108
|
+
rng?: () => number;
|
|
109
|
+
/** Resource pressure. When true, pressure-sensitive strategies are not chosen. */
|
|
110
|
+
pressure?: () => boolean;
|
|
111
|
+
/** Thermal band. `'hot'` is treated as pressure. */
|
|
112
|
+
thermal?: () => 'ok' | 'warm' | 'hot';
|
|
113
|
+
clock?: () => number;
|
|
114
|
+
/**
|
|
115
|
+
* Applied changes kept in `history()` (and reachable by `rollback()`),
|
|
116
|
+
* oldest dropped first. Default 256.
|
|
117
|
+
*/
|
|
118
|
+
historyLimit?: number;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export interface ObserveResult {
|
|
122
|
+
accepted: boolean;
|
|
123
|
+
reason: string;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export interface Learner {
|
|
127
|
+
register(strategy: SafeStrategy): void;
|
|
128
|
+
observe(observation: OutcomeObservation): ObserveResult;
|
|
129
|
+
recommend(signature: string, incumbent: string): Recommendation;
|
|
130
|
+
/** Record a recommendation as applied. Does not mutate any other module. */
|
|
131
|
+
apply(recommendation: Recommendation): HistoryEntry | null;
|
|
132
|
+
/** Undo the last applied change. Returns the inverse entry, or null if none. */
|
|
133
|
+
rollback(): HistoryEntry | null;
|
|
134
|
+
history(): readonly HistoryEntry[];
|
|
135
|
+
/** Strategy currently recorded as applied for this signature, if any. */
|
|
136
|
+
active(signature: string): string | undefined;
|
|
137
|
+
overheadMs(): number;
|
|
138
|
+
stats(): LearningStats;
|
|
139
|
+
disable(): void;
|
|
140
|
+
enable(): void;
|
|
141
|
+
readonly disabled: boolean;
|
|
142
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 3 — environment facts the residency manager reports.
|
|
3
|
+
*
|
|
4
|
+
* Facts, never gates: every probe resolves a conservative default when the
|
|
5
|
+
* environment has no answer, and none of them throws.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { probeDeviceMemoryBytes } from '../shared/hardwareProbe.js';
|
|
9
|
+
|
|
10
|
+
/** RAM hint used when the environment reports none. */
|
|
11
|
+
export const DEFAULT_RAM_BYTES = 4 * 1024 * 1024 * 1024;
|
|
12
|
+
|
|
13
|
+
/** Probe a RAM hint. Fact, not a gate. 4 GiB when the environment has none. */
|
|
14
|
+
export function probeRamBytes(): number {
|
|
15
|
+
return probeDeviceMemoryBytes() ?? DEFAULT_RAM_BYTES;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Probe a browser-storage quota hint. Resolves 0 when the Storage API is
|
|
20
|
+
* absent (Node tests, locked-down iframes). Never throws.
|
|
21
|
+
*/
|
|
22
|
+
export async function probeStorageQuotaBytes(): Promise<number> {
|
|
23
|
+
const nav = (globalThis as { navigator?: { storage?: { estimate?: () => Promise<{ quota?: number }> } } }).navigator;
|
|
24
|
+
try {
|
|
25
|
+
const estimate = await nav?.storage?.estimate?.();
|
|
26
|
+
return typeof estimate?.quota === 'number' && estimate.quota > 0 ? estimate.quota : 0;
|
|
27
|
+
} catch {
|
|
28
|
+
return 0;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 3 — reuse-probability and reload-cost estimation.
|
|
3
|
+
*
|
|
4
|
+
* Pure functions. The manager calls these when the caller does not supply an
|
|
5
|
+
* estimate, and cost-aware eviction weighs `reuseProbability * reloadCostMs`
|
|
6
|
+
* against footprint. Nothing here touches inference or decides when to run.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import type { ResidencyTier } from './types.js';
|
|
10
|
+
|
|
11
|
+
/** Bytes per parameter by quantization bucket. Mirrors the Phase 2 controller. */
|
|
12
|
+
export function bytesPerParam(quantization: string): number {
|
|
13
|
+
switch (quantization) {
|
|
14
|
+
case 'q4':
|
|
15
|
+
return 0.5;
|
|
16
|
+
case 'q5':
|
|
17
|
+
return 0.625;
|
|
18
|
+
case 'q8':
|
|
19
|
+
return 1;
|
|
20
|
+
case 'fp16':
|
|
21
|
+
return 2;
|
|
22
|
+
default:
|
|
23
|
+
return 0.5;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Estimated weight footprint for a model, in bytes.
|
|
29
|
+
* `paramsB` is billions of parameters. Headroom (default 20%) covers KV and
|
|
30
|
+
* activations so a residency admission does not under-count.
|
|
31
|
+
*/
|
|
32
|
+
export function estimateWeightBytes(paramsB: number, quantization: string, headroom = 1.2): number {
|
|
33
|
+
const params = Number.isFinite(paramsB) && paramsB > 0 ? paramsB : 0;
|
|
34
|
+
return Math.round(params * 1e9 * bytesPerParam(quantization) * Math.max(1, headroom));
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export interface ReloadCostInput {
|
|
38
|
+
/** Footprint in bytes. */
|
|
39
|
+
bytes: number;
|
|
40
|
+
/** Where the bytes would be reloaded from. */
|
|
41
|
+
from: ResidencyTier | 'network';
|
|
42
|
+
/** Optional measured throughput in bytes/ms. Overrides the tier default. */
|
|
43
|
+
bytesPerMs?: number;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Default reload throughput by source, bytes per ms. Conservative CPU-only figures. */
|
|
47
|
+
const DEFAULT_THROUGHPUT: Record<ReloadCostInput['from'], number> = {
|
|
48
|
+
// A RAM hit is not a reload; callers should not ask. Kept non-zero for safety.
|
|
49
|
+
ram: 1_000_000,
|
|
50
|
+
// VRAM copy over the optional GPU path. Hint only.
|
|
51
|
+
vram: 200_000,
|
|
52
|
+
// IndexedDB read on a typical laptop-class disk.
|
|
53
|
+
storage: 50_000,
|
|
54
|
+
// Re-download. Slow, and the reason cost-aware keeps hot weights.
|
|
55
|
+
network: 2_000,
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Estimated milliseconds to reload `bytes` from `from`.
|
|
60
|
+
* Always >= 0. A zero-byte entry reloads in 0.
|
|
61
|
+
*/
|
|
62
|
+
export function estimateReloadCostMs(input: ReloadCostInput): number {
|
|
63
|
+
const bytes = Number.isFinite(input.bytes) && input.bytes > 0 ? input.bytes : 0;
|
|
64
|
+
const throughput = input.bytesPerMs && input.bytesPerMs > 0 ? input.bytesPerMs : DEFAULT_THROUGHPUT[input.from];
|
|
65
|
+
return bytes / throughput;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export interface ReuseObservation {
|
|
69
|
+
/** Hits recorded for this id. */
|
|
70
|
+
hits: number;
|
|
71
|
+
/** Misses (or admissions that were not hits) recorded for this id. */
|
|
72
|
+
misses: number;
|
|
73
|
+
/** Ms since the last touch. Undefined if never touched. */
|
|
74
|
+
idleMs?: number;
|
|
75
|
+
/** Half-life of recency, ms. Default 60s. */
|
|
76
|
+
halfLifeMs?: number;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Estimated probability this id is reused before the next pressure event.
|
|
81
|
+
* Combines a Laplace-smoothed hit frequency with an exponential recency decay
|
|
82
|
+
* so a hot-but-idle entry cools off. Result is in [0, 1].
|
|
83
|
+
*/
|
|
84
|
+
export function estimateReuseProbability(observation: ReuseObservation): number {
|
|
85
|
+
const hits = Math.max(0, observation.hits);
|
|
86
|
+
const misses = Math.max(0, observation.misses);
|
|
87
|
+
// Laplace smoothing: an unseen id is 0.5, not 0 or 1.
|
|
88
|
+
const frequency = (hits + 1) / (hits + misses + 2);
|
|
89
|
+
const halfLife = observation.halfLifeMs && observation.halfLifeMs > 0 ? observation.halfLifeMs : 60_000;
|
|
90
|
+
const idle = observation.idleMs && observation.idleMs > 0 ? observation.idleMs : 0;
|
|
91
|
+
const recency = Math.pow(0.5, idle / halfLife);
|
|
92
|
+
return clamp01(frequency * recency);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function clamp01(value: number): number {
|
|
96
|
+
if (Number.isNaN(value)) return 0;
|
|
97
|
+
return Math.min(1, Math.max(0, value));
|
|
98
|
+
}
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Phase 3 — pluggable eviction strategies.
|
|
3
|
+
*
|
|
4
|
+
* Each strategy ranks evictable residents from most-evictable to least.
|
|
5
|
+
* The manager walks that order until the byte budget (and quotas) fit.
|
|
6
|
+
* Strategies never mutate the manager's map, so they are swappable in tests.
|
|
7
|
+
*
|
|
8
|
+
* Cost-aware is the default: it evicts the entry with the worst
|
|
9
|
+
* (reuseProbability * reloadCostMs) / footprint score first — a large, cold,
|
|
10
|
+
* cheap-to-reload entry leaves before a small, hot, expensive one.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import type { EvictionStrategy, TrackedEntry } from './types.js';
|
|
14
|
+
|
|
15
|
+
function byNumber(pick: (entry: TrackedEntry) => number, direction: 'asc' | 'desc'): (a: TrackedEntry, b: TrackedEntry) => number {
|
|
16
|
+
const sign = direction === 'asc' ? 1 : -1;
|
|
17
|
+
return (a, b) => {
|
|
18
|
+
const delta = pick(a) - pick(b);
|
|
19
|
+
if (delta !== 0) return sign * delta;
|
|
20
|
+
// Stable tie-break: older admission leaves first.
|
|
21
|
+
return a.admittedAt - b.admittedAt;
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** Least-recently-used. Evicts the entry with the oldest `lastUsedAt` first. */
|
|
26
|
+
export function lruStrategy(): EvictionStrategy {
|
|
27
|
+
return {
|
|
28
|
+
name: 'lru',
|
|
29
|
+
rank(candidates) {
|
|
30
|
+
return [...candidates].sort(byNumber((e) => e.lastUsedAt, 'asc'));
|
|
31
|
+
},
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Least-frequently-used. Evicts the entry with the fewest hits first. */
|
|
36
|
+
export function lfuStrategy(): EvictionStrategy {
|
|
37
|
+
return {
|
|
38
|
+
name: 'lfu',
|
|
39
|
+
rank(candidates) {
|
|
40
|
+
return [...candidates].sort(byNumber((e) => e.hits, 'asc'));
|
|
41
|
+
},
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Value of keeping an entry, per byte. Higher means "keep".
|
|
47
|
+
* `reuseProbability * reloadCostMs` is the expected reload penalty of evicting
|
|
48
|
+
* it; dividing by footprint prefers dropping large cold entries.
|
|
49
|
+
* A zero-byte entry is treated as infinitely cheap to keep (never preferred).
|
|
50
|
+
*/
|
|
51
|
+
export function retentionValue(entry: TrackedEntry): number {
|
|
52
|
+
const footprint = entry.bytes > 0 ? entry.bytes : 1;
|
|
53
|
+
const expectedReload = clamp01(entry.reuseProbability) * Math.max(0, entry.reloadCostMs);
|
|
54
|
+
return expectedReload / footprint;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** Cost-aware. Evicts the lowest retention-value-per-byte entry first. */
|
|
58
|
+
export function costAwareStrategy(): EvictionStrategy {
|
|
59
|
+
return {
|
|
60
|
+
name: 'cost-aware',
|
|
61
|
+
rank(candidates) {
|
|
62
|
+
return [...candidates].sort(byNumber((e) => retentionValue(e), 'asc'));
|
|
63
|
+
},
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Adaptive Replacement Cache (Megiddo & Modha).
|
|
69
|
+
*
|
|
70
|
+
* Maintains four logical lists over the manager's tracked entries plus two
|
|
71
|
+
* ghost lists of recently evicted ids:
|
|
72
|
+
* T1 recent residents, T2 frequent residents,
|
|
73
|
+
* B1 ghost of evicted-once, B2 ghost of evicted-frequent.
|
|
74
|
+
* A hit on B1 grows the T1 target (recency is winning); a hit on B2 shrinks it
|
|
75
|
+
* (frequency is winning). Ranking evicts from the list that is over its target.
|
|
76
|
+
*
|
|
77
|
+
* Ghost ids are bounded by `ghostCapacity` (default 1024) so a sustained
|
|
78
|
+
* workload cannot grow strategy state without bound.
|
|
79
|
+
*/
|
|
80
|
+
export function arcStrategy(ghostCapacity = 1024): EvictionStrategy {
|
|
81
|
+
const b1: string[] = [];
|
|
82
|
+
const b2: string[] = [];
|
|
83
|
+
let p = 0;
|
|
84
|
+
|
|
85
|
+
const remember = (list: string[], id: string) => {
|
|
86
|
+
const existing = list.indexOf(id);
|
|
87
|
+
if (existing >= 0) list.splice(existing, 1);
|
|
88
|
+
list.push(id);
|
|
89
|
+
while (list.length > ghostCapacity) list.shift();
|
|
90
|
+
};
|
|
91
|
+
const forget = (list: string[], id: string): boolean => {
|
|
92
|
+
const existing = list.indexOf(id);
|
|
93
|
+
if (existing < 0) return false;
|
|
94
|
+
list.splice(existing, 1);
|
|
95
|
+
return true;
|
|
96
|
+
};
|
|
97
|
+
|
|
98
|
+
return {
|
|
99
|
+
name: 'arc',
|
|
100
|
+
observe(event) {
|
|
101
|
+
const id = event.entry.id;
|
|
102
|
+
if (event.kind === 'miss') {
|
|
103
|
+
// A miss that was recently evicted adapts the target.
|
|
104
|
+
if (forget(b1, id)) p = Math.min(ghostCapacity, p + Math.max(1, b2.length / Math.max(1, b1.length + 1)));
|
|
105
|
+
else if (forget(b2, id)) p = Math.max(0, p - Math.max(1, b1.length / Math.max(1, b2.length + 1)));
|
|
106
|
+
return;
|
|
107
|
+
}
|
|
108
|
+
if (event.kind === 'evict') {
|
|
109
|
+
if (event.entry.arcList === 't2' || event.entry.hits > 1) remember(b2, id);
|
|
110
|
+
else remember(b1, id);
|
|
111
|
+
}
|
|
112
|
+
},
|
|
113
|
+
rank(candidates) {
|
|
114
|
+
const t1 = candidates.filter((e) => (e.arcList ?? (e.hits <= 1 ? 't1' : 't2')) === 't1');
|
|
115
|
+
const t2 = candidates.filter((e) => (e.arcList ?? (e.hits <= 1 ? 't1' : 't2')) === 't2');
|
|
116
|
+
// Evict from whichever list is over its target. p is the T1 target.
|
|
117
|
+
const evictT1First = t1.length >= p || t2.length === 0;
|
|
118
|
+
const primary = evictT1First ? t1 : t2;
|
|
119
|
+
const secondary = evictT1First ? t2 : t1;
|
|
120
|
+
const order = byNumber((e) => e.lastUsedAt, 'asc');
|
|
121
|
+
return [...primary].sort(order).concat([...secondary].sort(order));
|
|
122
|
+
},
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** Resolve a strategy by name. Unknown names fall back to cost-aware. */
|
|
127
|
+
export function strategyByName(name: EvictionStrategy['name']): EvictionStrategy {
|
|
128
|
+
switch (name) {
|
|
129
|
+
case 'lru':
|
|
130
|
+
return lruStrategy();
|
|
131
|
+
case 'lfu':
|
|
132
|
+
return lfuStrategy();
|
|
133
|
+
case 'arc':
|
|
134
|
+
return arcStrategy();
|
|
135
|
+
case 'cost-aware':
|
|
136
|
+
return costAwareStrategy();
|
|
137
|
+
default:
|
|
138
|
+
return costAwareStrategy();
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function clamp01(value: number): number {
|
|
143
|
+
if (Number.isNaN(value)) return 0;
|
|
144
|
+
return Math.min(1, Math.max(0, value));
|
|
145
|
+
}
|