doppler-gpu 0.4.14 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (222) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +83 -52
  3. package/package.json +25 -2
  4. package/src/cli/doppler-cli.js +253 -94
  5. package/src/cli/runtime-profiles.js +3 -7
  6. package/src/client/doppler-api.d.ts +28 -0
  7. package/src/client/doppler-api.js +2 -0
  8. package/src/client/inspection.d.ts +122 -0
  9. package/src/client/inspection.js +343 -0
  10. package/src/client/runtime/index.d.ts +54 -0
  11. package/src/client/runtime/index.js +190 -18
  12. package/src/client/runtime/model-manager.d.ts +0 -4
  13. package/src/client/runtime/model-manager.js +0 -28
  14. package/src/client/runtime/model-session.d.ts +116 -1
  15. package/src/client/runtime/model-session.js +351 -1
  16. package/src/client/runtime/model-source.d.ts +10 -1
  17. package/src/client/runtime/scoped-session.d.ts +117 -0
  18. package/src/client/runtime/scoped-session.js +257 -0
  19. package/src/client/runtime/types.d.ts +0 -1
  20. package/src/client/runtime/types.js +0 -1
  21. package/src/config/evidence/boundary-evidence-policy.json +54 -0
  22. package/src/config/evidence/source-intake-policy.json +122 -0
  23. package/src/config/inspection/observation-policies.json +80 -0
  24. package/src/config/param-validator.js +21 -36
  25. package/src/config/runtime/compute/f16-activations.json +1 -0
  26. package/src/config/runtime/compute/f16-batched.json +1 -0
  27. package/src/config/runtime/default.json +1 -0
  28. package/src/config/runtime/diagnostics/debug-logits.json +1 -0
  29. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-alt.json +1 -0
  30. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-batched.json +1 -0
  31. package/src/config/runtime/experiments/bench/gemma3-bench-q4k.json +1 -0
  32. package/src/config/runtime/experiments/bench/gemma4-bench-q4k.json +1 -0
  33. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-alt.json +1 -0
  34. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-batched.json +1 -0
  35. package/src/config/runtime/experiments/debug/gemma3-browser-diagnose-q4k.json +1 -1
  36. package/src/config/runtime/experiments/debug/gemma3-debug-q4k.json +1 -3
  37. package/src/config/runtime/experiments/debug/gemma4-e2b-browser-diagnose-q4k.json +1 -1
  38. package/src/config/runtime/experiments/debug/qwen35-browser-diagnose-q4k.json +1 -1
  39. package/src/config/runtime/experiments/verify/gemma3-verify.json +1 -3
  40. package/src/config/runtime/experiments/verify/gemma4-e2b-verify.json +1 -3
  41. package/src/config/runtime/experiments/verify/lfm2-verify.json +1 -3
  42. package/src/config/runtime/experiments/verify/translategemma-verify.json +1 -3
  43. package/src/config/runtime/model/gemma2-debug.json +1 -0
  44. package/src/config/runtime/model/gemma2-pipeline-debug.json +1 -0
  45. package/src/config/runtime/model/gemma2-pipeline.json +1 -0
  46. package/src/config/runtime/model/gemma3-layer-probe.json +1 -0
  47. package/src/config/runtime/model/qwen3-5-layer-probe.json +1 -0
  48. package/src/config/runtime/model/qwen3-5-layer3-boundary-probe.json +1 -0
  49. package/src/config/runtime/model/qwen3-5-linear-attn-debug.json +1 -0
  50. package/src/config/runtime/optimization-candidates/registry.json +5 -0
  51. package/src/config/runtime/platform/metal-apple-q4k.json +1 -0
  52. package/src/config/runtime/profiles/default.json +1 -0
  53. package/src/config/runtime/profiles/diffusiongemma-26b-a4b-throughput.json +1 -0
  54. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-overlapped-probe.json +1 -0
  55. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-probe.json +1 -0
  56. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-b4.json +1 -3
  57. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-single.json +1 -3
  58. package/src/config/runtime/profiles/gemma4-31b-f16-activations-probe.json +1 -5
  59. package/src/config/runtime/profiles/gemma4-e2b-baseline-probe.json +1 -3
  60. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-probe.json +1 -3
  61. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-test.json +1 -0
  62. package/src/config/runtime/profiles/gemma4-e2b-int4ple-baseline-probe.json +1 -5
  63. package/src/config/runtime/profiles/gemma4-e2b-int4ple-f16a-probe.json +1 -5
  64. package/src/config/runtime/profiles/gemma4-e2b-int4ple-reference-export.json +1 -3
  65. package/src/config/runtime/profiles/gemma4-e2b-int4ple-retain-q4k-probe.json +1 -5
  66. package/src/config/runtime/profiles/gemma4-e2b-low-memory.json +1 -0
  67. package/src/config/runtime/profiles/gemma4-e2b-prefill-profile.json +1 -3
  68. package/src/config/runtime/profiles/gemma4-e2b-throughput-probe.json +1 -0
  69. package/src/config/runtime/profiles/low-memory.json +1 -0
  70. package/src/config/runtime/profiles/production.json +1 -3
  71. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-attn128-candidate.json +1 -0
  72. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-maxbatch64-candidate.json +1 -0
  73. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-normed-ffn-candidate.json +1 -0
  74. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-overlap-ringtokens1-candidate.json +1 -0
  75. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-parity.json +1 -0
  76. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-sequential-candidate.json +1 -0
  77. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-throughput.json +1 -0
  78. package/src/config/runtime/profiles/qwen-3-5-0-8b-prefill-profile.json +1 -3
  79. package/src/config/runtime/profiles/qwen-3-5-0-8b-throughput-probe.json +1 -0
  80. package/src/config/runtime/profiles/qwen-3-5-2b-f16-primary-throughput.json +1 -5
  81. package/src/config/runtime/profiles/qwen-3-5-2b-metal-parity.json +1 -0
  82. package/src/config/runtime/profiles/qwen-3-5-2b-metal-throughput.json +1 -0
  83. package/src/config/runtime/profiles/qwen-3-5-9b-metal-correctness.json +1 -0
  84. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-stability.json +1 -3
  85. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-throughput.json +1 -0
  86. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-stability.json +1 -0
  87. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-throughput.json +1 -0
  88. package/src/config/runtime/profiles/qwen3-6-27b-f16-activations-probe.json +1 -5
  89. package/src/config/runtime/profiles/rerank-stability.json +1 -3
  90. package/src/config/runtime/profiles/rerank-throughput.json +1 -3
  91. package/src/config/runtime/profiles/simulation.json +1 -3
  92. package/src/config/runtime/profiles/throughput.json +1 -3
  93. package/src/config/runtime/profiles/trace-layers.json +1 -3
  94. package/src/config/runtime/profiles/translategemma-1b-nativekd2-q4k-rdna3-throughput-probe.json +1 -0
  95. package/src/config/runtime/profiles/turboquant-contiguous-prod.json +1 -0
  96. package/src/config/runtime/profiles/turboquant-contiguous.json +1 -0
  97. package/src/config/runtime/profiles/turboquant.json +1 -0
  98. package/src/config/runtime/profiles/vector-stability.json +1 -3
  99. package/src/config/runtime/profiles/vector-throughput.json +1 -0
  100. package/src/config/runtime/profiles/verbose-trace.json +1 -3
  101. package/src/config/runtime/tiers/gemma4-128gb.json +1 -0
  102. package/src/config/runtime/tiers/gemma4-16gb.json +1 -0
  103. package/src/config/runtime/tiers/gemma4-24gb.json +1 -0
  104. package/src/config/runtime/tiers/gemma4-32gb.json +1 -0
  105. package/src/config/schema/benchmark.schema.d.ts +7 -0
  106. package/src/config/schema/benchmark.schema.js +5 -0
  107. package/src/config/schema/index.d.ts +8 -16
  108. package/src/config/schema/index.js +5 -8
  109. package/src/config/schema/kernel-thresholds.schema.d.ts +0 -12
  110. package/src/config/schema/kernel-thresholds.schema.js +0 -12
  111. package/src/config/schema/kernel-warmup.schema.d.ts +1 -3
  112. package/src/config/schema/kernel-warmup.schema.js +0 -1
  113. package/src/config/schema/runtime-profile.schema.d.ts +24 -0
  114. package/src/config/schema/runtime-profile.schema.js +92 -0
  115. package/src/config/schema/shared-runtime.schema.d.ts +1 -4
  116. package/src/config/schema/shared-runtime.schema.js +0 -2
  117. package/src/config/schema/tooling.schema.d.ts +8 -5
  118. package/src/config/schema/tooling.schema.js +3 -2
  119. package/src/debug/tensor.d.ts +2 -0
  120. package/src/debug/tensor.js +21 -2
  121. package/src/gpu/command-recorder.d.ts +5 -0
  122. package/src/gpu/command-recorder.js +17 -0
  123. package/src/gpu/kernel-runtime.js +2 -10
  124. package/src/gpu/kernels/index.d.ts +0 -2
  125. package/src/gpu/kernels/index.js +0 -2
  126. package/src/gpu/kernels/kernel-prewarm.d.ts +3 -0
  127. package/src/gpu/kernels/kernel-prewarm.js +60 -0
  128. package/src/gpu/kernels/utils.d.ts +2 -4
  129. package/src/gpu/kernels/utils.js +2 -4
  130. package/src/index.d.ts +13 -1
  131. package/src/index.js +7 -1
  132. package/src/inference/browser-harness-model-helpers.js +4 -0
  133. package/src/inference/browser-harness-runtime-helpers.js +25 -10
  134. package/src/inference/browser-harness-text-helpers.js +4 -1
  135. package/src/inference/browser-harness.d.ts +4 -0
  136. package/src/inference/browser-harness.js +91 -4
  137. package/src/inference/observation-context.d.ts +22 -0
  138. package/src/inference/observation-context.js +41 -0
  139. package/src/inference/pipelines/text/attention/attn-config.js +1 -1
  140. package/src/inference/pipelines/text/attention/executor-immediate.js +42 -0
  141. package/src/inference/pipelines/text/attention/executor-recorded.js +29 -0
  142. package/src/inference/pipelines/text/attention/index.js +7 -0
  143. package/src/inference/pipelines/text/attention/interpreter.js +1334 -0
  144. package/src/inference/pipelines/text/attention/plan.d.ts +36 -0
  145. package/src/inference/pipelines/text/attention/plan.js +328 -0
  146. package/src/inference/pipelines/text/attention/receipt.js +60 -0
  147. package/src/inference/pipelines/text/attention/record.js +8 -1278
  148. package/src/inference/pipelines/text/attention/run.js +8 -1386
  149. package/src/inference/pipelines/text/generator-decode-policy.js +4 -1
  150. package/src/inference/pipelines/text/generator-helpers.js +2 -0
  151. package/src/inference/pipelines/text/generator-steps.js +32 -15
  152. package/src/inference/pipelines/text/generator.js +10 -5
  153. package/src/inference/pipelines/text/init.d.ts +3 -0
  154. package/src/inference/pipelines/text/layer-plan-gpu.js +2 -0
  155. package/src/inference/pipelines/text/layer.js +2 -0
  156. package/src/inference/pipelines/text/model-load.d.ts +0 -1
  157. package/src/inference/pipelines/text/model-load.js +2 -11
  158. package/src/inference/pipelines/text/probes.js +10 -0
  159. package/src/inference/pipelines/text/resolved-runtime-session.d.ts +56 -0
  160. package/src/inference/pipelines/text/resolved-runtime-session.js +175 -0
  161. package/src/inference/pipelines/text/state.d.ts +6 -0
  162. package/src/inference/pipelines/text/state.js +3 -0
  163. package/src/inference/pipelines/text/types.d.ts +6 -0
  164. package/src/inference/pipelines/text.js +16 -1
  165. package/src/inference/refactor-receipt.d.ts +49 -0
  166. package/src/inference/refactor-receipt.js +188 -0
  167. package/src/inference/resource-scope.d.ts +33 -0
  168. package/src/inference/resource-scope.js +168 -0
  169. package/src/inference/test-harness.d.ts +3 -0
  170. package/src/inference/test-harness.js +1 -0
  171. package/src/storage/model-cache.d.ts +53 -0
  172. package/src/storage/model-cache.js +550 -0
  173. package/src/tooling/boundary-evidence.d.ts +51 -0
  174. package/src/tooling/boundary-evidence.js +408 -0
  175. package/src/tooling/browser-command-runner.js +4 -4
  176. package/src/tooling/command-context.d.ts +25 -0
  177. package/src/tooling/command-context.js +53 -0
  178. package/src/tooling/command-runner-shared.js +22 -5
  179. package/src/tooling/demo-receipts.d.ts +56 -0
  180. package/src/tooling/demo-receipts.js +113 -0
  181. package/src/tooling/diagnose-runner.js +2 -2
  182. package/src/tooling/execution-cost-ledger.d.ts +21 -0
  183. package/src/tooling/execution-cost-ledger.js +199 -0
  184. package/src/tooling/node-command-runner.js +2 -2
  185. package/src/tooling/opfs-cache.d.ts +11 -49
  186. package/src/tooling/opfs-cache.js +4 -510
  187. package/src/tooling/precision-replay-math.d.ts +42 -0
  188. package/src/tooling/precision-replay-math.js +174 -0
  189. package/src/tooling/program-bundle-parity.d.ts +3 -0
  190. package/src/tooling/program-bundle-parity.js +8 -0
  191. package/src/tooling/program-bundle.d.ts +1 -52
  192. package/src/tooling/program-bundle.js +0 -139
  193. package/src/tooling/registered-variant-calibration.d.ts +24 -0
  194. package/src/tooling/registered-variant-calibration.js +286 -0
  195. package/src/tooling/runtime-input-composition.js +105 -53
  196. package/src/tooling/runtime-intent.js +41 -0
  197. package/src/tooling/runtime-optimization-index.d.ts +6 -0
  198. package/src/tooling/runtime-optimization-index.js +72 -0
  199. package/src/tooling/runtime-optimization.d.ts +47 -6
  200. package/src/tooling/runtime-optimization.js +559 -40
  201. package/src/tooling/source-intake.d.ts +49 -0
  202. package/src/tooling/source-intake.js +414 -0
  203. package/src/tooling-exports/evidence.d.ts +34 -0
  204. package/src/tooling-exports/evidence.js +34 -0
  205. package/src/tooling-exports/runtime.d.ts +7 -0
  206. package/src/tooling-exports/runtime.js +7 -0
  207. package/src/tooling-exports.d.ts +11 -0
  208. package/src/tooling-exports.js +6 -3
  209. package/src/tooling-exports.shared.d.ts +32 -0
  210. package/src/tooling-exports.shared.js +31 -0
  211. package/src/version.js +1 -1
  212. package/src/config/schema/tuner.schema.d.ts +0 -39
  213. package/src/config/schema/tuner.schema.js +0 -13
  214. package/src/gpu/kernel-tuner/benchmarks.js +0 -902
  215. package/src/gpu/kernel-tuner/cache.js +0 -145
  216. package/src/gpu/kernel-tuner/index.js +0 -38
  217. package/src/gpu/kernel-tuner/tuner.js +0 -247
  218. package/src/gpu/kernel-tuner.js +0 -12
  219. package/src/gpu/kernels/kernel-tuning.d.ts +0 -42
  220. package/src/gpu/kernels/kernel-tuning.js +0 -158
  221. package/src/gpu/profiler.js +0 -382
  222. package/src/inference/pipelines/text/attention/output-gate-fusion.js +0 -37
@@ -0,0 +1,550 @@
1
+ import {
2
+ modelExists,
3
+ openModelStore,
4
+ loadManifestFromStore,
5
+ saveManifest,
6
+ deleteModel,
7
+ verifyIntegrity,
8
+ computeSHA256,
9
+ } from './shard-manager.js';
10
+ import { createOpfsArtifactStorageContext } from './artifact-storage-context.js';
11
+ import { downloadModel, estimateTimeRemaining, formatSpeed } from './downloader.js';
12
+ import { isOPFSAvailable, formatBytes } from './quota.js';
13
+ import { parseManifest, getManifestUrl } from '../formats/rdrr/index.js';
14
+ import { getRuntimeConfig } from '../config/runtime.js';
15
+ import { cloneJsonValue } from '../utils/clone-json.js';
16
+ import { log } from '../debug/index.js';
17
+ import {
18
+ resolveSourceArtifact,
19
+ verifyStoredSourceArtifact,
20
+ } from './source-artifact-store.js';
21
+
22
+ const MODULE = 'OPFSCache';
23
+ let cacheOperationQueue = Promise.resolve();
24
+
25
+ function runCacheOperation(run) {
26
+ const operation = cacheOperationQueue.then(run, run);
27
+ cacheOperationQueue = operation.then(() => undefined, () => undefined);
28
+ return operation;
29
+ }
30
+
31
+ function toErrorMessage(error) {
32
+ if (error instanceof Error && typeof error.message === 'string' && error.message.length > 0) {
33
+ return error.message;
34
+ }
35
+ return String(error);
36
+ }
37
+
38
+ function normalizeExpectedManifestHash(value) {
39
+ const raw = value && typeof value === 'object'
40
+ ? value.hex ?? value.hash ?? value.digest ?? ''
41
+ : value;
42
+ const normalized = String(raw || '').trim().toLowerCase().replace(/^sha256:/, '');
43
+ if (!normalized) return null;
44
+ if (!/^[0-9a-f]{64}$/.test(normalized)) {
45
+ throw new Error('expectedManifestHash must be a SHA-256 hex digest.');
46
+ }
47
+ return normalized;
48
+ }
49
+
50
+ function manifestTotalBytes(manifest) {
51
+ const declared = Number(manifest?.totalSize);
52
+ if (Number.isFinite(declared) && declared >= 0) return Math.floor(declared);
53
+ const shards = Array.isArray(manifest?.shards) ? manifest.shards : [];
54
+ return shards.reduce((total, shard) => {
55
+ const size = Number(shard?.size);
56
+ return total + (Number.isFinite(size) && size > 0 ? Math.floor(size) : 0);
57
+ }, 0);
58
+ }
59
+
60
+ async function sha256Text(text) {
61
+ return computeSHA256(new TextEncoder().encode(String(text || '')));
62
+ }
63
+
64
+ function normalizeShardDescriptor(shard) {
65
+ return {
66
+ filename: typeof shard?.filename === 'string' ? shard.filename : null,
67
+ size: Number.isFinite(shard?.size) ? shard.size : null,
68
+ hash: typeof shard?.hash === 'string' ? shard.hash : null,
69
+ };
70
+ }
71
+
72
+ function hasSameShardSet(aManifest, bManifest) {
73
+ const aShards = Array.isArray(aManifest?.shards) ? aManifest.shards : [];
74
+ const bShards = Array.isArray(bManifest?.shards) ? bManifest.shards : [];
75
+ if (aShards.length !== bShards.length) {
76
+ return false;
77
+ }
78
+ for (let i = 0; i < aShards.length; i += 1) {
79
+ const a = normalizeShardDescriptor(aShards[i]);
80
+ const b = normalizeShardDescriptor(bShards[i]);
81
+ if (a.filename !== b.filename || a.size !== b.size || a.hash !== b.hash) {
82
+ return false;
83
+ }
84
+ }
85
+ return true;
86
+ }
87
+
88
+ function preserveCachedSourceRuntimeMetadata(remoteManifest, cachedManifest) {
89
+ const cachedSourceRuntime = cachedManifest?.metadata?.sourceRuntime;
90
+ if (!cachedSourceRuntime || typeof cachedSourceRuntime !== 'object') {
91
+ return {
92
+ manifest: remoteManifest,
93
+ changed: false,
94
+ };
95
+ }
96
+ if (resolveSourceArtifact(remoteManifest)) {
97
+ return {
98
+ manifest: remoteManifest,
99
+ changed: false,
100
+ };
101
+ }
102
+
103
+ const mergedManifest = cloneJsonValue(remoteManifest);
104
+ if (!mergedManifest || typeof mergedManifest !== 'object' || Array.isArray(mergedManifest)) {
105
+ return {
106
+ manifest: remoteManifest,
107
+ changed: false,
108
+ };
109
+ }
110
+
111
+ const metadata = (
112
+ mergedManifest.metadata
113
+ && typeof mergedManifest.metadata === 'object'
114
+ && !Array.isArray(mergedManifest.metadata)
115
+ )
116
+ ? cloneJsonValue(mergedManifest.metadata)
117
+ : {};
118
+ metadata.sourceRuntime = cloneJsonValue(cachedSourceRuntime);
119
+ mergedManifest.metadata = metadata;
120
+
121
+ return {
122
+ manifest: mergedManifest,
123
+ changed: true,
124
+ };
125
+ }
126
+
127
+ // buildManifestFingerprint compares a deliberate subset of manifest fields.
128
+ // Compared fields (partial match by design):
129
+ // - modelId, modelHash, hashAlgorithm: identity and integrity algorithm
130
+ // - quantization, quantizationInfo (weights/embeddings/compute/variantTag/layout):
131
+ // determines weight format compatibility
132
+ // - inference.layerPattern (type/globalPattern/period/offset/layerTypes):
133
+ // determines layer dispatch structure
134
+ // - shards (filename/size/hash per shard): data identity
135
+ // - sourceArtifactFingerprint: tracks direct-source asset changes
136
+ //
137
+ // NOT compared (intentionally excluded because they change without affecting
138
+ // cached shard validity):
139
+ // - manifest.version, manifest.config, manifest.architecture,
140
+ // manifest.inference.execution, manifest.tokenizer, manifest.moeConfig,
141
+ // manifest.inference.attention, manifest.inference.output
142
+ // This partial match avoids spurious re-downloads when only non-shard-affecting
143
+ // metadata changes. Cache hits still require exact manifest-text equality below;
144
+ // when text changes but shards do not, we refresh only the cached manifest.
145
+ function buildManifestFingerprint(manifest) {
146
+ const sourceArtifactFingerprint = resolveSourceArtifact(manifest)?.fingerprint ?? null;
147
+ const inference = manifest?.inference ?? {};
148
+ const layerPattern = inference?.layerPattern ?? {};
149
+ const quantizationInfo = manifest?.quantizationInfo ?? {};
150
+ const shards = Array.isArray(manifest?.shards)
151
+ ? manifest.shards.map(normalizeShardDescriptor)
152
+ : [];
153
+ return JSON.stringify({
154
+ modelId: manifest?.modelId ?? null,
155
+ modelHash: manifest?.modelHash ?? null,
156
+ hashAlgorithm: manifest?.hashAlgorithm ?? null,
157
+ quantization: manifest?.quantization ?? null,
158
+ quantizationInfo: {
159
+ weights: quantizationInfo.weights ?? null,
160
+ embeddings: quantizationInfo.embeddings ?? null,
161
+ compute: quantizationInfo.compute ?? null,
162
+ variantTag: quantizationInfo.variantTag ?? null,
163
+ layout: quantizationInfo.layout ?? null,
164
+ },
165
+ inference: {
166
+ layerPattern: {
167
+ type: layerPattern.type ?? null,
168
+ globalPattern: layerPattern.globalPattern ?? null,
169
+ period: layerPattern.period ?? null,
170
+ offset: layerPattern.offset ?? null,
171
+ layerTypes: Array.isArray(layerPattern.layerTypes)
172
+ ? [...layerPattern.layerTypes]
173
+ : null,
174
+ },
175
+ },
176
+ shards,
177
+ sourceArtifactFingerprint,
178
+ });
179
+ }
180
+
181
+ async function fetchRemoteManifest(modelBaseUrl) {
182
+ const manifestUrl = getManifestUrl(modelBaseUrl);
183
+ const response = await fetch(manifestUrl, { cache: 'no-store' });
184
+ if (!response.ok) {
185
+ throw new Error(`manifest fetch failed (${response.status})`);
186
+ }
187
+ const text = await response.text();
188
+ return { text, manifest: parseManifest(text) };
189
+ }
190
+
191
+ async function loadCachedManifest(modelId) {
192
+ await openModelStore(modelId);
193
+ const text = await loadManifestFromStore();
194
+ if (!text) {
195
+ return { text: null, manifest: null };
196
+ }
197
+ return { text, manifest: parseManifest(text) };
198
+ }
199
+
200
+ async function verifyCachedArtifact(manifest) {
201
+ if (resolveSourceArtifact(manifest)) {
202
+ return verifyStoredSourceArtifact(manifest, { checkHashes: false });
203
+ }
204
+ return verifyIntegrity({ checkHashes: false });
205
+ }
206
+
207
+ async function resolvePinnedCacheHit(modelId, expectedManifestHash, onProgress) {
208
+ if (!expectedManifestHash || !isOPFSAvailable() || !await modelExists(modelId)) {
209
+ return null;
210
+ }
211
+ try {
212
+ const cachedManifest = await loadCachedManifest(modelId);
213
+ if (!cachedManifest.text || !cachedManifest.manifest) return null;
214
+ if (await sha256Text(cachedManifest.text) !== expectedManifestHash) return null;
215
+ const integrity = await verifyCachedArtifact(cachedManifest.manifest);
216
+ if (!integrity.valid) return null;
217
+ const totalBytes = manifestTotalBytes(cachedManifest.manifest);
218
+ onProgress?.({
219
+ stage: 'cache-hit',
220
+ modelId,
221
+ message: `Verified OPFS cache hit: ${modelId}`,
222
+ percent: 100,
223
+ totalBytes,
224
+ downloadedBytes: totalBytes,
225
+ });
226
+ return {
227
+ cached: true,
228
+ fromCache: true,
229
+ cacheState: 'verified-hit',
230
+ modelId,
231
+ error: null,
232
+ manifestText: cachedManifest.text,
233
+ manifestHash: expectedManifestHash,
234
+ manifest: cachedManifest.manifest,
235
+ totalBytes,
236
+ };
237
+ } catch (error) {
238
+ log.warn(MODULE, `Pinned cache validation failed for "${modelId}": ${toErrorMessage(error)}`);
239
+ return null;
240
+ }
241
+ }
242
+
243
+ function buildDownloadProgress(progress) {
244
+ if (!progress) return null;
245
+ const totalBytes = Number.isFinite(progress.totalBytes) ? progress.totalBytes : 0;
246
+ const downloadedBytes = Number.isFinite(progress.downloadedBytes) ? progress.downloadedBytes : 0;
247
+ const speed = Number.isFinite(progress.speed) ? progress.speed : 0;
248
+ const remainingBytes = Math.max(0, totalBytes - downloadedBytes);
249
+ return {
250
+ stage: 'downloading',
251
+ modelId: progress.modelId || null,
252
+ totalShards: Number.isFinite(progress.totalShards) ? progress.totalShards : 0,
253
+ completedShards: Number.isFinite(progress.completedShards) ? progress.completedShards : 0,
254
+ totalBytes,
255
+ downloadedBytes,
256
+ percent: Number.isFinite(progress.percent) ? progress.percent : 0,
257
+ speed,
258
+ speedFormatted: speed > 0 ? formatSpeed(speed) : '',
259
+ totalFormatted: totalBytes > 0 ? formatBytes(totalBytes) : '',
260
+ downloadedFormatted: downloadedBytes > 0 ? formatBytes(downloadedBytes) : '',
261
+ eta: speed > 0 && remainingBytes > 0 ? estimateTimeRemaining(remainingBytes, speed) : '',
262
+ message: buildDownloadStatusLine(progress, speed, remainingBytes),
263
+ };
264
+ }
265
+
266
+ function buildDownloadStatusLine(progress, speed, remainingBytes) {
267
+ const parts = [];
268
+ const downloaded = Number.isFinite(progress.downloadedBytes) ? formatBytes(progress.downloadedBytes) : '0 B';
269
+ const total = Number.isFinite(progress.totalBytes) ? formatBytes(progress.totalBytes) : '?';
270
+ parts.push(`${downloaded} / ${total}`);
271
+ if (Number.isFinite(progress.completedShards) && Number.isFinite(progress.totalShards)) {
272
+ parts.push(`shard ${progress.completedShards}/${progress.totalShards}`);
273
+ }
274
+ if (speed > 0) {
275
+ parts.push(formatSpeed(speed));
276
+ }
277
+ if (speed > 0 && remainingBytes > 0) {
278
+ parts.push(`~${estimateTimeRemaining(remainingBytes, speed)} remaining`);
279
+ }
280
+ return parts.join(' | ');
281
+ }
282
+
283
+ async function ensureModelCachedUnlocked(modelId, modelBaseUrl, onProgress = null) {
284
+ if (!modelId || !modelBaseUrl) {
285
+ return {
286
+ cached: false,
287
+ fromCache: false,
288
+ cacheState: 'error',
289
+ modelId,
290
+ error: 'missing-args',
291
+ };
292
+ }
293
+
294
+ if (!isOPFSAvailable()) {
295
+ log.warn(MODULE, 'OPFS not available in this browser');
296
+ return {
297
+ cached: false,
298
+ fromCache: false,
299
+ cacheState: 'error',
300
+ modelId,
301
+ error: 'opfs-unavailable',
302
+ };
303
+ }
304
+
305
+ let needsFullImport = false;
306
+
307
+ try {
308
+ const exists = await modelExists(modelId);
309
+ if (exists) {
310
+ try {
311
+ const [{ text: remoteManifestText, manifest: remoteManifest }, { text: cachedManifestText, manifest: cachedManifest }] = await Promise.all([
312
+ fetchRemoteManifest(modelBaseUrl),
313
+ loadCachedManifest(modelId),
314
+ ]);
315
+
316
+ if (!cachedManifestText || !cachedManifest) {
317
+ log.warn(MODULE, `Cache miss: "${modelId}" has no readable manifest in OPFS; re-importing`);
318
+ needsFullImport = true;
319
+ } else {
320
+ const cachedSourceArtifact = resolveSourceArtifact(cachedManifest);
321
+ const sourceIntegrity = cachedSourceArtifact
322
+ ? await verifyStoredSourceArtifact(cachedManifest, { checkHashes: false })
323
+ : null;
324
+ const sourceIntegrityValid = !sourceIntegrity || sourceIntegrity.valid;
325
+ if (sourceIntegrity && !sourceIntegrity.valid) {
326
+ log.warn(
327
+ MODULE,
328
+ `Cache stale: "${modelId}" direct-source assets are incomplete (${sourceIntegrity.missingFiles.join(', ')})`
329
+ );
330
+ }
331
+ const cachedFingerprint = buildManifestFingerprint(cachedManifest);
332
+ const remoteFingerprint = buildManifestFingerprint(remoteManifest);
333
+ const manifestTextMatches = cachedManifestText === remoteManifestText;
334
+ if (sourceIntegrityValid && manifestTextMatches && cachedFingerprint === remoteFingerprint) {
335
+ const shardIntegrity = cachedSourceArtifact
336
+ ? sourceIntegrity
337
+ : await verifyCachedArtifact(cachedManifest);
338
+ if (shardIntegrity.valid) {
339
+ log.info(MODULE, `Cache hit: "${modelId}"`);
340
+ onProgress?.({ stage: 'cache-hit', modelId, message: `OPFS cache hit: ${modelId}`, percent: 100 });
341
+ return {
342
+ cached: true,
343
+ fromCache: true,
344
+ cacheState: 'hit',
345
+ modelId,
346
+ error: null,
347
+ };
348
+ }
349
+ log.warn(
350
+ MODULE,
351
+ `Cache incomplete: "${modelId}" is missing shards ${shardIntegrity.missingShards.join(', ')}`
352
+ );
353
+ needsFullImport = true;
354
+ }
355
+
356
+ if (!needsFullImport) {
357
+ const sameShards = hasSameShardSet(cachedManifest, remoteManifest);
358
+ const sameHashAlgorithm = (cachedManifest?.hashAlgorithm ?? null) === (remoteManifest?.hashAlgorithm ?? null);
359
+ if (sourceIntegrityValid && sameShards && sameHashAlgorithm) {
360
+ const preservedManifest = preserveCachedSourceRuntimeMetadata(remoteManifest, cachedManifest);
361
+ const manifestTextToSave = preservedManifest.changed
362
+ ? JSON.stringify(preservedManifest.manifest)
363
+ : remoteManifestText;
364
+ await openModelStore(modelId);
365
+ await saveManifest(manifestTextToSave);
366
+ const refreshMessage = preservedManifest.changed
367
+ ? `Manifest refreshed: ${modelId} (shards unchanged, preserved direct-source metadata)`
368
+ : `Manifest refreshed: ${modelId} (shards unchanged)`;
369
+ log.info(MODULE, `Cache manifest refreshed: "${modelId}"${preservedManifest.changed ? ' (preserved direct-source metadata)' : ' (shards unchanged)'}`);
370
+ onProgress?.({ stage: 'cache-refresh', modelId, message: refreshMessage, percent: 100 });
371
+ return {
372
+ cached: true,
373
+ fromCache: false,
374
+ cacheState: 'manifest-refresh',
375
+ modelId,
376
+ error: null,
377
+ };
378
+ }
379
+ }
380
+
381
+ log.info(MODULE, `Cache stale: "${modelId}" manifest/shards changed; deleting old version and re-importing`);
382
+ onProgress?.({ stage: 'cache-invalidate', modelId, message: `Purging stale OPFS cache for ${modelId}`, percent: 0 });
383
+ try {
384
+ await deleteModel(modelId);
385
+ log.info(MODULE, `Deleted stale OPFS cache for "${modelId}"`);
386
+ } catch (deleteError) {
387
+ log.warn(MODULE, `Failed to delete stale cache for "${modelId}": ${toErrorMessage(deleteError)}`);
388
+ }
389
+ needsFullImport = true;
390
+ }
391
+ } catch (error) {
392
+ const message = toErrorMessage(error);
393
+ log.warn(MODULE, `Cache validation failed (${message}); refusing cached model "${modelId}"`);
394
+ return {
395
+ cached: false,
396
+ fromCache: false,
397
+ cacheState: 'error',
398
+ modelId,
399
+ error: message,
400
+ };
401
+ }
402
+ }
403
+ } catch (error) {
404
+ const message = toErrorMessage(error);
405
+ log.warn(MODULE, `Cache check failed: ${message}`);
406
+ return {
407
+ cached: false,
408
+ fromCache: false,
409
+ cacheState: 'error',
410
+ modelId,
411
+ error: message,
412
+ };
413
+ }
414
+
415
+ if (!needsFullImport) {
416
+ log.info(MODULE, `Cache miss: "${modelId}". Triggering full model download from ${modelBaseUrl}`);
417
+ }
418
+
419
+ onProgress?.({ stage: 'download-start', modelId, message: `Downloading ${modelId}...`, percent: 0 });
420
+
421
+ try {
422
+ const success = await downloadModel(modelBaseUrl, (progress) => {
423
+ if (!progress) return;
424
+ const enriched = buildDownloadProgress(progress);
425
+ if (enriched) {
426
+ onProgress?.(enriched);
427
+ }
428
+ const shard = Number.isFinite(progress.completedShards) ? progress.completedShards : '?';
429
+ const total = Number.isFinite(progress.totalShards) ? progress.totalShards : '?';
430
+ const mb = Number.isFinite(progress.downloadedBytes)
431
+ ? (progress.downloadedBytes / (1024 * 1024)).toFixed(1)
432
+ : '?';
433
+ log.verbose(MODULE, `Shard ${shard}/${total} (${mb} MB)`);
434
+ });
435
+
436
+ if (success) {
437
+ log.info(MODULE, `Import complete: "${modelId}"`);
438
+ onProgress?.({ stage: 'download-complete', modelId, message: `Download complete: ${modelId}`, percent: 100 });
439
+ return {
440
+ cached: true,
441
+ fromCache: false,
442
+ cacheState: 'imported',
443
+ modelId,
444
+ error: null,
445
+ };
446
+ }
447
+ return {
448
+ cached: false,
449
+ fromCache: false,
450
+ cacheState: 'error',
451
+ modelId,
452
+ error: 'download-incomplete',
453
+ };
454
+ } catch (error) {
455
+ const message = toErrorMessage(error);
456
+ log.error(MODULE, `Import failed: ${message}`);
457
+ return {
458
+ cached: false,
459
+ fromCache: false,
460
+ cacheState: 'error',
461
+ modelId,
462
+ error: message,
463
+ };
464
+ }
465
+ }
466
+
467
+ export function ensureModelCached(modelId, modelBaseUrl, onProgress = null) {
468
+ return runCacheOperation(() => ensureModelCachedUnlocked(modelId, modelBaseUrl, onProgress));
469
+ }
470
+
471
+ export function ensureModelCachedSource(modelId, modelBaseUrl, onProgress = null, options = {}) {
472
+ return runCacheOperation(async () => {
473
+ const expectedManifestHash = normalizeExpectedManifestHash(options.expectedManifestHash);
474
+ const pinnedHit = await resolvePinnedCacheHit(modelId, expectedManifestHash, onProgress);
475
+ const cache = pinnedHit ?? await ensureModelCachedUnlocked(modelId, modelBaseUrl, onProgress);
476
+ if (!cache.cached) {
477
+ throw new Error(`Persistent model cache failed for "${modelId}": ${cache.error || cache.cacheState}`);
478
+ }
479
+ const cachedManifest = cache.manifest && cache.manifestText
480
+ ? { manifest: cache.manifest, text: cache.manifestText }
481
+ : await loadCachedManifest(modelId);
482
+ if (!cachedManifest.text || !cachedManifest.manifest) {
483
+ throw new Error(`Persistent model cache for "${modelId}" has no readable manifest.`);
484
+ }
485
+ const manifestHash = await sha256Text(cachedManifest.text);
486
+ if (expectedManifestHash && manifestHash !== expectedManifestHash) {
487
+ await deleteModel(modelId).catch(() => {});
488
+ throw new Error(`Persistent model cache manifest hash mismatch for "${modelId}".`);
489
+ }
490
+ const runtime = getRuntimeConfig();
491
+ const opfsPath = runtime.loading.opfsPath;
492
+ const opfs = runtime.loading.storage.backend.opfs;
493
+ const storageContext = await createOpfsArtifactStorageContext(modelId, cachedManifest.manifest, {
494
+ opfsRootDir: opfsPath.opfsRootDir,
495
+ useSyncAccessHandle: opfs.useSyncAccessHandle,
496
+ maxConcurrentHandles: opfs.maxConcurrentHandles,
497
+ verifyHashes: false,
498
+ hashesTrusted: true,
499
+ });
500
+ return {
501
+ ...cache,
502
+ manifest: cachedManifest.manifest,
503
+ manifestText: cachedManifest.text,
504
+ manifestHash,
505
+ storageContext,
506
+ storageBackend: 'opfs',
507
+ totalBytes: cache.totalBytes ?? manifestTotalBytes(cachedManifest.manifest),
508
+ };
509
+ });
510
+ }
511
+
512
+ export function loadPersistentModelSource(modelId) {
513
+ return runCacheOperation(async () => {
514
+ if (!isOPFSAvailable() || !await modelExists(modelId)) {
515
+ return null;
516
+ }
517
+ const cachedManifest = await loadCachedManifest(modelId);
518
+ if (!cachedManifest.text || !cachedManifest.manifest) {
519
+ return null;
520
+ }
521
+ const integrity = await verifyCachedArtifact(cachedManifest.manifest);
522
+ if (!integrity.valid) {
523
+ return null;
524
+ }
525
+ const manifestHash = await sha256Text(cachedManifest.text);
526
+ const runtime = getRuntimeConfig();
527
+ const opfsPath = runtime.loading.opfsPath;
528
+ const opfs = runtime.loading.storage.backend.opfs;
529
+ const storageContext = await createOpfsArtifactStorageContext(modelId, cachedManifest.manifest, {
530
+ opfsRootDir: opfsPath.opfsRootDir,
531
+ useSyncAccessHandle: opfs.useSyncAccessHandle,
532
+ maxConcurrentHandles: opfs.maxConcurrentHandles,
533
+ verifyHashes: false,
534
+ hashesTrusted: true,
535
+ });
536
+ return {
537
+ cached: true,
538
+ fromCache: true,
539
+ cacheState: 'verified-hit',
540
+ modelId,
541
+ error: null,
542
+ manifest: cachedManifest.manifest,
543
+ manifestText: cachedManifest.text,
544
+ manifestHash,
545
+ storageContext,
546
+ storageBackend: 'opfs',
547
+ totalBytes: manifestTotalBytes(cachedManifest.manifest),
548
+ };
549
+ });
550
+ }
@@ -0,0 +1,51 @@
1
+ export declare const SOURCE_BOUNDARY_PACK_SCHEMA: 'doppler.source-boundary-pack/v1';
2
+ export declare const RUNTIME_BOUNDARY_CAPTURE_SCHEMA: 'doppler.runtime-boundary-capture/v1';
3
+ export declare const BOUNDARY_COMPARISON_RECEIPT_SCHEMA:
4
+ 'doppler.boundary-comparison-receipt/v1';
5
+ export declare const DETERMINISTIC_TOKEN_EVIDENCE_SCHEMA:
6
+ 'doppler.deterministic-token-evidence/v1';
7
+ export declare const BOUNDARY_PROVIDER_CAPTURE_SCHEMA:
8
+ 'doppler.boundary-provider-capture/v1';
9
+
10
+ export interface BoundaryEvidence {
11
+ boundaryId: string;
12
+ phase: string | null;
13
+ tokenIndex: number | null;
14
+ layerIndex: number | null;
15
+ occurrence?: number;
16
+ shape: number[];
17
+ dtype: string;
18
+ samples: Array<{ coordinate: number[]; flatIndex: number; value: number }>;
19
+ fullTensorDigest: string;
20
+ statistics: Record<string, number>;
21
+ tolerancePolicyId: string;
22
+ }
23
+
24
+ export declare function buildRuntimeBoundaryCapture(options: {
25
+ report: unknown;
26
+ policy: Record<string, unknown>;
27
+ tolerancePolicyId?: string;
28
+ identity?: Record<string, unknown>;
29
+ }): Record<string, unknown>;
30
+
31
+ export declare function buildSourceBoundaryPack(options: {
32
+ identity: Record<string, unknown>;
33
+ boundaries: BoundaryEvidence[];
34
+ }): Record<string, unknown>;
35
+
36
+ export declare function buildSourceBoundaryPackFromProviderCapture(
37
+ capture: Record<string, unknown>
38
+ ): Record<string, unknown>;
39
+
40
+ export declare function buildDeterministicTokenEvidenceFromReferenceTranscript(
41
+ transcript: Record<string, unknown>
42
+ ): Record<string, unknown>;
43
+
44
+ export declare function compareBoundaryEvidence(options: {
45
+ sourcePack: Record<string, unknown>;
46
+ runtimeCapture: Record<string, unknown>;
47
+ policy: Record<string, unknown>;
48
+ artifactPrecision?: 'source' | 'quantized';
49
+ sourcePrecisionControlReceipt?: Record<string, unknown> | null;
50
+ deterministicTokenEvidence?: { exact: boolean; tokenCount: number } | null;
51
+ }): Record<string, unknown>;