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
package/CHANGELOG.md CHANGED
@@ -8,6 +8,15 @@ docs so the `0.1.x` line has one conventional npm-visible history surface.
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [0.4.15] - 2026-07-24
12
+
13
+ ### Added
14
+
15
+ - Added `generateWithEvidence()` to loaded model handles. The browser-safe
16
+ result binds generated token IDs, transcript, resolved generation config,
17
+ runtime profile, WebGPU backend identity, and execution-plan identity with
18
+ canonical SHA-256 hashes.
19
+
11
20
  ## [0.4.14] - 2026-07-19
12
21
 
13
22
  ### Added
package/README.md CHANGED
@@ -1,3 +1,7 @@
1
+ <p align="center">
2
+ <img src="assets/doppler-logo.svg" alt="doppler" width="190" />
3
+ </p>
4
+
1
5
  # doppler-gpu
2
6
 
3
7
  [![Build](https://img.shields.io/github/actions/workflow/status/clocksmith/doppler/check-green.yml?branch=main&label=build)](https://github.com/clocksmith/doppler/actions/workflows/check-green.yml)
@@ -6,15 +10,16 @@
6
10
  [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/clocksmith/doppler/pulls)
7
11
 
8
12
  Doppler turns inference engineering into a verifiable search problem. Optimizers
9
- edit RDRR manifests, execution plans, and kernels; parity and benchmark gates
13
+ edit JSON manifests, execution plans, and WGSL kernels; parity and benchmark gates
10
14
  accept or reject each candidate against correctness and speed.
11
15
 
12
- Today engineers use these contracts and gates to tune a JavaScript/WGSL WebGPU
16
+ These contracts and gates are used by operators to tune a configurable and pure JavaScript and WGSL sourced WebGPU
13
17
  runtime for supported
14
18
  [RDRR artifacts](https://github.com/clocksmith/doppler/blob/main/docs/rdrr-format.md)
15
- in browser and Node. Doppler runs text generation, embeddings, and reranking
16
- locally, with CLI and OpenAI-compatible server entry points. Bun WebGPU support
17
- is experimental.
19
+ in browser, Node, and Bun. Doppler runs text generation, embeddings, and reranking
20
+ locally, with CLI and OpenAI-compatible server entry points.
21
+
22
+ **Read this first:** [getting started](https://github.com/clocksmith/doppler/blob/main/docs/getting-started.md) → [Root API](https://github.com/clocksmith/doppler/blob/main/docs/api/root.md) → [open source evidence](https://github.com/clocksmith/doppler/blob/main/docs/model-competition-scoreboard.md)
18
23
 
19
24
  **[Try the live demo](https://d4da.com/doppler)** | **[npm](https://www.npmjs.com/package/doppler-gpu)** | **[docs](https://github.com/clocksmith/doppler/blob/main/docs/INDEX.md)**
20
25
 
@@ -30,16 +35,16 @@ Doppler classifies artifacts by what they consume and produce. This is
30
35
  separate from lineage (`family`), runtime implementation (`modelType`), and
31
36
  artifact-size tier.
32
37
 
33
- | Type | Input → output | Runtime-verified / cataloged | Representative lanes |
34
- | --- | --- | --- | --- |
35
- | Text generators | text → text | 12 / 14 | gemma-3-1b-it-q4k-ehf16-af32<br>gemma-3-270m-it-f16-af32<br>gemma-3-270m-it-q4k-ehf16-af32<br>+11 more |
36
- | Multimodal generators | audio + image + text → text | 3 / 3 | gemma-4-e2b-it-q4k-ehf16-af16-int4ple<br>gemma-4-e2b-it-q4k-ehf16-af32<br>gemma-4-e2b-it-q4k-ehf16-af32-int4ple |
37
- | Diffusion language models | text → text | 0 / 1 | diffusiongemma-26b-a4b-it-q4k-ehf16-af16 |
38
- | Translation specialists | text → text | 2 / 2 | translategemma-4b-1b-enes-q4k-ehf16-af32<br>translategemma-4b-it-q4k-ehf16-af32 |
39
- | Language embedders | text → pooled-embedding | 2 / 2 | google-embeddinggemma-300m-q4k-ehf16-af32<br>qwen-3-embedding-0-6b-q4k-ehf16-af32 |
40
- | Rerankers | text-pair → relevance-score | 2 / 2 | qwen-3-reranker-0-6b-f16-af32<br>qwen-3-reranker-0-6b-q4k-ehf16-af32 |
41
- | Protein encoders | protein-sequence → pooled-embedding + token-embedding + token-logits | 3 / 3 | amplify-120m-f16-af32<br>esm2-t12-35m-ur50d-f32-af32<br>esmc-300m-f32-af32 |
42
- | Nucleotide encoders | dna-sequence → pooled-embedding + token-embedding | 1 / 1 | nucleotide-transformer-v2-50m-f32-af32 |
38
+ | Type | Verified / Cataloged | What it does |
39
+ | --- | --- | --- |
40
+ | Text generators | 12 / 14 | `text → text` |
41
+ | Multimodal generators | 3 / 3 | `audio + image + text → text` |
42
+ | Diffusion language models | 0 / 1 | `text → text` |
43
+ | Translation specialists | 2 / 2 | `text → text` |
44
+ | Language embedders | 2 / 2 | `text → embedding` |
45
+ | Rerankers | 2 / 2 | `text-pair → relevance-score` |
46
+ | Protein encoders | 3 / 3 | `sequence → embedding + token outputs` |
47
+ | Nucleotide encoders | 1 / 1 | `dna-seq → embedding` |
43
48
 
44
49
  The [full model-support matrix](https://github.com/clocksmith/doppler/blob/main/docs/model-support-matrix.md)
45
50
  lists every lane and its lifecycle evidence. Classification says what an
@@ -49,22 +54,29 @@ modality.
49
54
 
50
55
  <!-- model-type-clusters:end -->
51
56
 
52
- ## Supported LoRA adapters (PEFT)
57
+ ## LoRA: runtime loading and training
53
58
 
54
- Doppler supports runtime loading and hot-swapping of LoRA adapters (in SafeTensors format) bound to specific base models.
59
+ Doppler supports:
55
60
 
56
- | Adapter ID | Base Model ID | HF Repository | Lifecycle & Purpose |
57
- | --- | --- | --- | --- |
58
- | `doppler-wgsl-qwen35-9b-v12-external20-seed11` | `qwen-3-5-9b-f16-af32` | [clocksmith/lora](https://huggingface.co/clocksmith/lora/blob/5662f8f7e3dbcf1e2ec353b5a04d0d4f2f5254ce/adapters/seed11/adapter_model.safetensors) | Preserved portable adapter (v12) |
59
- | `doppler-wgsl-qwen35-9b-v12-external20-seed29` | `qwen-3-5-9b-f16-af32` | [clocksmith/lora](https://huggingface.co/clocksmith/lora/blob/5662f8f7e3dbcf1e2ec353b5a04d0d4f2f5254ce/adapters/seed29/adapter_model.safetensors) | Candidate adapter for repair validation (v12) |
60
- | `doppler-wgsl-qwen35-9b-v12-external20-seed47` | `qwen-3-5-9b-f16-af32` | [clocksmith/lora](https://huggingface.co/clocksmith/lora/blob/5662f8f7e3dbcf1e2ec353b5a04d0d4f2f5254ce/adapters/seed47/adapter_model.safetensors) | Preserved portable adapter (v12) |
61
+ - SafeTensors LoRA loading and hot-swap at runtime.
62
+ - Experimental SFT/LoRA training in Node, Bun, and browser via `doppler-gpu/training`.
63
+ - Native packed-Q4K LoRA for `qwen-3-5-0-8b-q4k-ehaf16` in `webgpu_native` (frozen base, LoRA A/B updates only).
64
+ - External backends for other packed-Q4K training targets.
61
65
 
62
- Active adapters are registered in [models/adapters/catalog.json](models/adapters/catalog.json). See the [LoRA Format specification](docs/lora-format.md) for details on the adapter manifest schema.
66
+ ```bash
67
+ npx doppler-gpu lora --config ./workload.json --surface node
68
+ ```
69
+
70
+ Active adapters are registered in [models/adapters/catalog.json](models/adapters/catalog.json).
71
+ The training API, workload schema, and adapter families live in the
72
+ [LoRA Format specification](docs/lora-format.md),
73
+ [Training handbook](docs/training-handbook.md), and [Training API](docs/api/training.md).
63
74
 
64
75
  ## Evidence
65
76
 
66
- Doppler has higher steady-state inference throughput than Transformers.js in each
67
- of the comparable browser WebGPU results indexed below.
77
+ Doppler has higher steady-state inference throughput than Transformers.js in
78
+ accepted, throughput-comparable browser WebGPU comparisons indexed below where
79
+ the throughput gate passes.
68
80
 
69
81
  ![Metal and Vulkan browser WebGPU throughput distributions](https://raw.githubusercontent.com/clocksmith/doppler/main/assets/doppler-webgpu-evidence.svg)
70
82
 
@@ -77,33 +89,29 @@ receipt, and the [methodology](https://github.com/clocksmith/doppler/blob/main/d
77
89
 
78
90
  ## Why these lanes are faster
79
91
 
80
- Doppler authors the WGSL path and pins it in RDRR. Runtime profiles pin session
81
- cadence. The measured wins come from different mechanisms in different phases:
92
+ Doppler speedups come from specific, explicit runtime changes:
82
93
 
83
- | Lever | Affected phase | Measured receipt |
84
- | --- | --- | --- |
85
- | Fused Q4_K projection and FFN work removes separate dispatches | Text decode | [Qwen 3.5 0.8B Metal](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/compare_20260709T154633.json) |
86
- | Fixed `head_dim=128` attention avoids the generic prefill path | Retrieval attention | [embedding](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/embedding_compare_qwen-3-embedding-0-6b-q4k-ehf16-af32_20260709T180853.json), [reranking](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/rerank_compare_qwen-3-reranker-0-6b-q4k-ehf16-af32_20260709T192830.json) |
87
- | Batch-four decode amortizes one readback across four tokens | Submit and map waits | [Qwen 3.5 2B Vulkan](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/compare_20260707T161623.json) |
88
- | INT4-PLE and Q4_K layouts lower projection traffic | Text decode | [Gemma 4 Vulkan](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/compare_20260707T170557.json) |
94
+ - **Fusion:** projection + FFN path reductions reduce kernel count.
95
+ - **Attention/layout tuning:** lowers prefill overhead.
96
+ - **Batched decode:** amortizes readback overhead.
97
+ - **Packed kernels:** Q4_K + INT4-PLE reduce projection traffic.
89
98
 
90
- The Gemma 4 comparison uses its declared product-format output policy. It does
91
- not claim exact greedy token parity.
99
+ Evidence receipts:
92
100
 
93
- Parity and comparable benchmark gates decide what is retained. The
94
- [challenger framework](https://github.com/clocksmith/doppler/blob/main/docs/local-gpu-challenger-framework.md)
95
- records accepted and rejected trials, and each verdict's receipt binds it to a
96
- model, profile, workload, and device; the
97
- [negative-results findings](https://github.com/clocksmith/doppler/blob/main/docs/developer-guides/16-kernel-performance-optimization.md#what-we-ruled-out)
98
- keep the dead ends.
101
+ - [Qwen 3.5 0.8B (Metal)](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/compare_20260709T154633.json)
102
+ - [Qwen embedding + rerank](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/embedding_compare_qwen-3-embedding-0-6b-q4k-ehf16-af32_20260709T180853.json), [Qwen rerank](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/rerank_compare_qwen-3-reranker-0-6b-q4k-ehf16-af32_20260709T192830.json)
103
+ - [Qwen 3.5 2B (Vulkan)](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/compare_20260707T161623.json)
104
+ - [Gemma 4 (Vulkan)](https://github.com/clocksmith/doppler/blob/main/benchmarks/vendors/results/compare_20260707T170557.json)
105
+
106
+ Retention is gated: a lane moves forward only when both parity and benchmark
107
+ receipts pass in the
108
+ [challenger framework](https://github.com/clocksmith/doppler/blob/main/docs/local-gpu-challenger-framework.md).
99
109
 
100
110
  ### Long-term direction
101
111
 
102
- Humans run this loop today. The WGSL-distillation workload is experimental.
103
- Automated kernel generation and autotuning are directions, not shipped product
104
- paths. Doppler aims to reduce the manual steps between a new checkpoint or GPU
105
- and a verified runtime lane. Automated proposals will face the same parity and
106
- benchmark gates.
112
+ Humans run this loop today. WGSL-distillation is experimental.
113
+ Automation in kernel generation/autotuning is a roadmap item, not shipped yet.
114
+ New checkpoints and GPUs still go through the same parity and benchmark gate flow.
107
115
 
108
116
  ## How it works
109
117
 
@@ -185,6 +193,9 @@ preserve program identity for downstream backends.
185
193
  ### Browser
186
194
 
187
195
  The live demo runs locally and works offline after its first model download.
196
+ Its public API boundary, observation tiers, generated PWA shell, and independent
197
+ contract/hardware smoke receipts are documented in
198
+ [demo/README.md](demo/README.md).
188
199
 
189
200
  ### CLI
190
201
 
@@ -201,6 +212,12 @@ The `dr` facade is the primary app API. Advanced APIs use package subpaths.
201
212
  ```js
202
213
  import { dr } from 'doppler-gpu';
203
214
 
215
+ // Explicit scoped API with a stable result envelope
216
+ const session = await dr.open('qwen3-0.8b');
217
+ const result = await session.generate('Describe WebGPU briefly');
218
+ console.log(result.outputText, result.fingerprint);
219
+ await session.close();
220
+
204
221
  // Stream tokens
205
222
  const model = await dr.load('qwen3-0.8b');
206
223
  for await (const token of model.generate('Describe WebGPU briefly')) {
@@ -209,8 +226,22 @@ for await (const token of model.generate('Describe WebGPU briefly')) {
209
226
 
210
227
  // One-shot
211
228
  const text = await model.generateText('Explain WebGPU in one sentence');
229
+
230
+ // One-shot with a hash-bound execution receipt
231
+ const evidence = await model.generateWithEvidence('Explain WebGPU in one sentence', {
232
+ maxTokens: 64,
233
+ temperature: 0,
234
+ });
235
+ console.log(evidence.outputText, evidence.transcriptHash);
236
+
237
+ await model.unload();
212
238
  ```
213
239
 
240
+ `generateWithEvidence()` returns the text and token IDs together with canonical
241
+ SHA-256 hashes for the transcript, resolved generation config, runtime profile,
242
+ WebGPU backend, and execution-plan identity. The receipt records what ran; it
243
+ does not by itself establish output correctness.
244
+
214
245
  ### OpenAI-compatible server
215
246
 
216
247
  ```bash
@@ -232,12 +263,12 @@ Registry IDs resolve to hosted RDRR artifacts from `clocksmith/rdrr` by default.
232
263
 
233
264
  ## Start here
234
265
 
235
- | Reader | Entry points |
236
- | --- | --- |
237
- | Application developers | [Getting started](https://github.com/clocksmith/doppler/blob/main/docs/getting-started.md), [Root API](https://github.com/clocksmith/doppler/blob/main/docs/api/root.md), and the [OpenAI-compatible server](#openai-compatible-server) |
238
- | Model integrators | [RDRR format](https://github.com/clocksmith/doppler/blob/main/docs/rdrr-format.md), [model support](https://github.com/clocksmith/doppler/blob/main/docs/model-support-matrix.md), and [Program Bundles](https://github.com/clocksmith/doppler/blob/main/docs/integration/program-bundle.md) |
239
- | Runtime and kernel engineers | [Architecture](https://github.com/clocksmith/doppler/blob/main/docs/architecture.md), [kernel optimization](https://github.com/clocksmith/doppler/blob/main/docs/developer-guides/16-kernel-performance-optimization.md), and the [challenger framework](https://github.com/clocksmith/doppler/blob/main/docs/local-gpu-challenger-framework.md) |
240
- | Evidence reviewers | [Competition scoreboard](https://github.com/clocksmith/doppler/blob/main/docs/model-competition-scoreboard.md), [benchmark methodology](https://github.com/clocksmith/doppler/blob/main/docs/benchmark-methodology.md), and [release matrix](https://github.com/clocksmith/doppler/blob/main/docs/release-matrix.md) |
266
+ ### Pick a path
267
+
268
+ - **Application builders:** start with [getting started](https://github.com/clocksmith/doppler/blob/main/docs/getting-started.md), [Root API](https://github.com/clocksmith/doppler/blob/main/docs/api/root.md), and the [OpenAI-compatible server](#openai-compatible-server).
269
+ - **Integrators:** use the [RDRR format](https://github.com/clocksmith/doppler/blob/main/docs/rdrr-format.md), [support matrix](https://github.com/clocksmith/doppler/blob/main/docs/model-support-matrix.md), and [Program Bundles](https://github.com/clocksmith/doppler/blob/main/docs/integration/program-bundle.md).
270
+ - **Kernel/inference engineers:** follow [architecture](https://github.com/clocksmith/doppler/blob/main/docs/architecture.md), [performance optimization](https://github.com/clocksmith/doppler/blob/main/docs/developer-guides/16-kernel-performance-optimization.md), and the [challenger framework](https://github.com/clocksmith/doppler/blob/main/docs/local-gpu-challenger-framework.md).
271
+ - **Evidence reviewers:** review the [scoreboard](https://github.com/clocksmith/doppler/blob/main/docs/model-competition-scoreboard.md), [methodology](https://github.com/clocksmith/doppler/blob/main/docs/benchmark-methodology.md), and [release matrix](https://github.com/clocksmith/doppler/blob/main/docs/release-matrix.md).
241
272
 
242
273
  The [docs index](https://github.com/clocksmith/doppler/blob/main/docs/INDEX.md)
243
274
  owns the complete model, subsystem, API, architecture, and operator inventory.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "doppler-gpu",
3
- "version": "0.4.14",
3
+ "version": "0.5.1",
4
4
  "description": "Browser-native WebGPU inference engine for local intent and inference loops",
5
5
  "main": "src/index.js",
6
6
  "types": "src/index.d.ts",
@@ -71,11 +71,18 @@
71
71
  "test:coverage": "node tools/run-node-coverage.js",
72
72
  "test:coverage:report": "node tools/run-node-coverage.js --no-threshold",
73
73
  "test:gpu:browser": "node src/cli/doppler-cli.js verify --config '{\"request\":{\"workload\":\"kernels\"},\"run\":{\"surface\":\"browser\",\"browser\":{\"opfsCache\":false,\"headless\":true,\"channel\":\"chromium\",\"browserArgs\":[\"--use-angle=swiftshader\",\"--disable-vulkan-surface\"],\"console\":true}}}'",
74
+ "demo:shell:generate": "node tools/generate-demo-shell-manifest.js",
75
+ "demo:shell:check": "node tools/generate-demo-shell-manifest.js --check",
76
+ "demo:reachability:check": "node tools/check-demo-reachability.js",
77
+ "test:demo:contract": "node tools/demo-contract-smoke.js",
78
+ "test:demo:hardware": "node tools/demo-hardware-smoke.js",
74
79
  "agents:verify": "node tools/verify-agent-parity.js",
75
80
  "agents:freshness": "node tools/verify-agent-freshness.js",
76
81
  "agents:freshness:strict": "node tools/verify-agent-freshness.js --strict",
77
82
  "conflicts:check": "node tools/check-merge-markers.js",
78
83
  "config:single-source:check": "node tools/check-config-single-source.js",
84
+ "evidence:workflows:check": "node tools/check-evidence-workflow-ownership.js",
85
+ "inference:boundaries:check": "node tools/check-inference-boundaries.js",
79
86
  "capability-policy:check": "node tools/check-capability-transform-policy.js",
80
87
  "imports:check:browser": "node tools/check-browser-import-graph.js",
81
88
  "api:docs:sync": "node tools/sync-api-docs.js",
@@ -89,7 +96,7 @@
89
96
  "goals:check": "node tools/check-goal-completion.js",
90
97
  "goals:report": "node tools/render-goal-completion-summary.js",
91
98
  "commands:surface:check": "node tools/check-command-surface-contract.js",
92
- "check:green": "npm run agents:verify && npm run goals:check && npm run public:boundaries:check && npm run package:smoke && npm run commands:surface:check && npm run api:docs:check && npm run config:single-source:check && npm run capability-policy:check && npm run imports:check:browser && npm run pending:check && npm run exports:parity:check && npm run artifact:contract:check && npm run adapter-artifacts:check && npm run claims:evidence:check && npm run support:subsystems:check && npm run policy:schemas:check",
99
+ "check:green": "npm run agents:verify && npm run goals:check && npm run public:boundaries:check && npm run package:smoke && npm run commands:surface:check && npm run api:docs:check && npm run config:single-source:check && npm run evidence:workflows:check && npm run inference:boundaries:check && npm run capability-policy:check && npm run imports:check:browser && npm run pending:check && npm run exports:parity:check && npm run artifact:contract:check && npm run adapter-artifacts:check && npm run claims:evidence:check && npm run support:subsystems:check && npm run policy:schemas:check",
93
100
  "verify:model": "node src/cli/doppler-cli.js verify",
94
101
  "quickstart:sync": "node tools/sync-quickstart-registry.js",
95
102
  "quickstart:check": "node tools/sync-quickstart-registry.js --check",
@@ -100,6 +107,7 @@
100
107
  "bench:vendors:validate": "node tools/vendor-bench.js validate",
101
108
  "bench:local-gpu:challengers": "node tools/local-gpu-challengers.js",
102
109
  "bench:local-gpu:challengers:check": "node tools/local-gpu-challengers.js --check",
110
+ "optimization:index": "node tools/build-runtime-optimization-index.js",
103
111
  "bench:embeddings:compare": "node tools/compare-embeddings.js",
104
112
  "bench:rerank:compare": "node tools/compare-rerankers.js",
105
113
  "bench:rerank:compare:hf": "node tools/compare-rerankers-hf.js",
@@ -242,6 +250,14 @@
242
250
  "types": "./src/tooling-exports/manifest.d.ts",
243
251
  "import": "./src/tooling-exports/manifest.js"
244
252
  },
253
+ "./tooling/runtime": {
254
+ "types": "./src/tooling-exports/runtime.d.ts",
255
+ "import": "./src/tooling-exports/runtime.js"
256
+ },
257
+ "./tooling/evidence": {
258
+ "types": "./src/tooling-exports/evidence.d.ts",
259
+ "import": "./src/tooling-exports/evidence.js"
260
+ },
245
261
  "./structured": {
246
262
  "types": "./src/tooling-exports/structured.d.ts",
247
263
  "import": "./src/tooling-exports/structured.js"
@@ -359,6 +375,13 @@
359
375
  "playwright": "^1.58.2",
360
376
  "typescript": "^6.0.2"
361
377
  },
378
+ "overrides": {
379
+ "adm-zip": "^0.6.0",
380
+ "brace-expansion": "^5.0.8",
381
+ "glob": "^13.0.6",
382
+ "minimatch": "^10.2.5",
383
+ "sharp": "^0.35.3"
384
+ },
362
385
  "optionalDependencies": {
363
386
  "doe-gpu": "^0.4.2",
364
387
  "webgpu": "^0.4.0"