doppler-gpu 0.4.2 → 0.4.3

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 (645) hide show
  1. package/CHANGELOG.md +182 -0
  2. package/README.md +19 -15
  3. package/package.json +77 -29
  4. package/src/cli/cli-model-resolution.js +275 -0
  5. package/src/cli/cli-output.js +453 -0
  6. package/src/cli/doppler-cli.js +817 -709
  7. package/src/cli/doppler-quickstart.d.ts +7 -23
  8. package/src/cli/doppler-quickstart.js +4 -2
  9. package/src/cli/doppler-serve.js +1 -1
  10. package/src/cli/runtime-profiles.d.ts +40 -0
  11. package/src/cli/runtime-profiles.js +225 -0
  12. package/src/client/doppler-api.js +1 -6
  13. package/src/client/doppler-registry.d.ts +12 -0
  14. package/src/client/doppler-registry.js +27 -0
  15. package/src/client/doppler-registry.json +64 -6
  16. package/src/client/failure-taxonomy.js +139 -0
  17. package/src/client/fault-injection.js +30 -0
  18. package/src/client/provider.d.ts +151 -0
  19. package/src/client/provider.js +374 -0
  20. package/src/client/receipt.js +156 -0
  21. package/src/client/runtime/index.js +56 -4
  22. package/src/client/runtime/model-manager.d.ts +0 -14
  23. package/src/client/runtime/model-manager.js +2 -42
  24. package/src/client/runtime/model-session.js +33 -0
  25. package/src/client/runtime/model-source.d.ts +13 -1
  26. package/src/client/runtime/model-source.js +128 -2
  27. package/src/client/runtime/node-quickstart-cache.d.ts +22 -0
  28. package/src/client/runtime/node-quickstart-cache.js +353 -0
  29. package/src/client/runtime/source-runtime.js +1 -10
  30. package/src/client/runtime/types.d.ts +0 -60
  31. package/src/client/wrap-pipeline-handle.d.ts +20 -0
  32. package/src/client/wrap-pipeline-handle.js +84 -0
  33. package/src/config/README.md +3 -1
  34. package/src/config/conversion/README.md +23 -157
  35. package/src/config/conversion/embeddinggemma/google-embeddinggemma-300m-q4k-ehf16-af32.json +19 -4
  36. package/src/config/conversion/gemma3/gemma-3-1b-it-f16-af32.json +16 -9
  37. package/src/config/conversion/gemma3/gemma-3-1b-it-q4k-ehf16-af32.json +24 -9
  38. package/src/config/conversion/gemma3/gemma-3-270m-it-q4k-ehf16-af32.json +24 -9
  39. package/src/config/conversion/gemma3/translategemma-4b-1b-enes-q4k-ehf16-af32.json +16 -9
  40. package/src/config/conversion/gemma3/translategemma-4b-it-q4k-ehf16-af32.json +24 -9
  41. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af16.json +719 -0
  42. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af32.json +715 -0
  43. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af16-int4ple.json +589 -0
  44. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32-int4ple.json +566 -0
  45. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32.json +367 -61
  46. package/src/config/conversion/gemma4/gemma-4-moe-q4k-ehf16-af32.json +212 -55
  47. package/src/config/conversion/gpt-oss-20b-f16-xmxfp4.json +216 -57
  48. package/src/config/conversion/janus/janus-pro-1b-text-q4k-ehaf16.json +229 -57
  49. package/src/config/conversion/lfm2/lfm2.5-1.2b-instruct-q4k-ehf16-af32.json +17 -10
  50. package/src/config/conversion/qwen3/qwen-3-5-0-8b-q4k-ehaf16.json +75 -33
  51. package/src/config/conversion/qwen3/qwen-3-5-2b-q4k-ehaf16.json +91 -59
  52. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-eaf16.json +517 -0
  53. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-ehaf16.json +511 -0
  54. package/src/config/execution-contract-check.js +6 -5
  55. package/src/config/kernel-path-loader.d.ts +8 -2
  56. package/src/config/kernels/kernel-ref-digests.js +125 -122
  57. package/src/config/kernels/registry.d.ts +0 -35
  58. package/src/config/kernels/registry.js +5 -9
  59. package/src/config/kernels/registry.json +524 -350
  60. package/src/config/merge-helpers.d.ts +1 -1
  61. package/src/config/merge-helpers.js +1 -1
  62. package/src/config/merge.js +35 -7
  63. package/src/config/param-categories.d.ts +0 -9
  64. package/src/config/param-categories.js +1 -5
  65. package/src/config/param-validator.d.ts +2 -0
  66. package/src/config/param-validator.js +16 -0
  67. package/src/config/platforms/loader.d.ts +0 -27
  68. package/src/config/platforms/loader.js +0 -30
  69. package/src/config/required-inference-fields-contract-check.js +1 -7
  70. package/src/config/runtime/README.md +28 -0
  71. package/src/config/runtime/experiments/bench/gemma4-bench-q4k.json +1 -1
  72. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-batched.json +2 -2
  73. package/src/config/runtime/experiments/debug/gemma4-e2b-browser-diagnose-q4k.json +85 -0
  74. package/src/config/runtime/platform/metal-apple-q4k.json +19 -3
  75. package/src/config/runtime/profiles/gemma4-31b-f16-activations-probe.json +65 -0
  76. package/src/config/runtime/profiles/gemma4-e2b-baseline-probe.json +41 -0
  77. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-probe.json +44 -0
  78. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-test.json +19 -0
  79. package/src/config/runtime/profiles/gemma4-e2b-int4ple-baseline-probe.json +31 -0
  80. package/src/config/runtime/profiles/gemma4-e2b-int4ple-f16a-probe.json +34 -0
  81. package/src/config/runtime/profiles/gemma4-e2b-int4ple-reference-export.json +64 -0
  82. package/src/config/runtime/profiles/gemma4-e2b-int4ple-retain-q4k-probe.json +47 -0
  83. package/src/config/runtime/profiles/gemma4-e2b-prefill-profile.json +35 -0
  84. package/src/config/runtime/profiles/gemma4-e2b-throughput-probe.json +16 -0
  85. package/src/config/runtime/profiles/qwen-3-5-0-8b-prefill-profile.json +35 -0
  86. package/src/config/runtime/profiles/qwen-3-5-0-8b-throughput-probe.json +16 -0
  87. package/src/config/runtime/profiles/qwen3-6-27b-f16-activations-probe.json +62 -0
  88. package/src/config/schema/bridge.schema.d.ts +16 -0
  89. package/src/config/schema/browser-suite-metrics.schema.d.ts +1 -0
  90. package/src/config/schema/browser-suite-metrics.schema.js +2 -0
  91. package/src/config/schema/converter.schema.d.ts +5 -0
  92. package/src/config/schema/converter.schema.js +3 -0
  93. package/src/config/schema/debug.schema.d.ts +22 -1
  94. package/src/config/schema/debug.schema.js +1 -0
  95. package/src/config/schema/distill-training.schema.d.ts +0 -1
  96. package/src/config/schema/distill-training.schema.js +1 -1
  97. package/src/config/schema/doppler.schema.d.ts +12 -2
  98. package/src/config/schema/doppler.schema.js +108 -8
  99. package/src/config/schema/emulation.schema.d.ts +3 -0
  100. package/src/config/schema/emulation.schema.js +16 -16
  101. package/src/config/schema/execution-v1.schema.d.ts +12 -1
  102. package/src/config/schema/execution-v1.schema.js +7 -1
  103. package/src/config/schema/index.d.ts +52 -1
  104. package/src/config/schema/index.js +14 -0
  105. package/src/config/schema/inference.schema.d.ts +3 -3
  106. package/src/config/schema/kernel-path.schema.d.ts +6 -27
  107. package/src/config/schema/kernel-thresholds.schema.d.ts +0 -2
  108. package/src/config/schema/kernel-thresholds.schema.js +3 -7
  109. package/src/config/schema/kvcache.schema.js +0 -9
  110. package/src/config/schema/loading.schema.d.ts +12 -0
  111. package/src/config/schema/loading.schema.js +4 -0
  112. package/src/config/schema/manifest.schema.d.ts +68 -1
  113. package/src/config/schema/manifest.schema.js +48 -2
  114. package/src/config/schema/moe.schema.js +0 -8
  115. package/src/config/schema/program-bundle.schema.d.ts +233 -0
  116. package/src/config/schema/program-bundle.schema.js +393 -0
  117. package/src/config/schema/ul-training.schema.d.ts +0 -1
  118. package/src/config/schema/ul-training.schema.js +1 -1
  119. package/src/config/source-packages/litert/gemma-4-e2b-it.json +36 -15
  120. package/src/config/supported-operations.d.ts +14 -0
  121. package/src/config/supported-operations.js +34 -0
  122. package/src/config/supported-operations.json +178 -0
  123. package/src/config/training-defaults.js +1 -7
  124. package/src/config/transforms/capability-transform-resolver.js +3 -1
  125. package/src/config/transforms/execution-graph-transforms.d.ts +55 -0
  126. package/src/config/transforms/execution-graph-transforms.js +693 -29
  127. package/src/converter/conversion-plan.js +13 -10
  128. package/src/converter/core.d.ts +57 -0
  129. package/src/converter/core.js +582 -13
  130. package/src/converter/parsers/diffusion.js +1 -33
  131. package/src/converter/quantization-info.d.ts +5 -4
  132. package/src/converter/quantization-info.js +39 -3
  133. package/src/converter/quantizer.d.ts +19 -0
  134. package/src/converter/quantizer.js +76 -0
  135. package/src/debug/config.d.ts +0 -4
  136. package/src/debug/config.js +0 -17
  137. package/src/debug/index.d.ts +28 -30
  138. package/src/debug/index.js +0 -18
  139. package/src/debug/stats.d.ts +0 -8
  140. package/src/debug/stats.js +3 -3
  141. package/src/debug/tensor.d.ts +9 -2
  142. package/src/debug/tensor.js +11 -4
  143. package/src/debug/trace.js +2 -15
  144. package/src/errors/doppler-error.js +20 -0
  145. package/src/experimental/browser/quantization.d.ts +5 -0
  146. package/src/experimental/distribution/shard-delivery.js +179 -23
  147. package/src/experimental/training/artifacts.js +1 -14
  148. package/src/experimental/training/checkpoint.js +1 -14
  149. package/src/experimental/training/datasets/token-batch.d.ts +1 -1
  150. package/src/experimental/training/datasets/token-batch.js +2 -2
  151. package/src/experimental/training/distillation/dataset.js +2 -15
  152. package/src/experimental/training/distillation/eval.js +3 -3
  153. package/src/experimental/training/distillation/runtime.js +3 -16
  154. package/src/experimental/training/distillation/student-fixture.js +6 -6
  155. package/src/experimental/training/lora-pipeline.js +1 -14
  156. package/src/experimental/training/objectives/base.d.ts +2 -2
  157. package/src/experimental/training/objectives/cross_entropy.d.ts +2 -2
  158. package/src/experimental/training/objectives/distill_kd.d.ts +2 -2
  159. package/src/experimental/training/objectives/distill_kd.js +2 -2
  160. package/src/experimental/training/objectives/distill_triplet.d.ts +2 -2
  161. package/src/experimental/training/objectives/distill_triplet.js +2 -2
  162. package/src/experimental/training/objectives/ul_stage1_joint.d.ts +2 -2
  163. package/src/experimental/training/objectives/ul_stage2_base.d.ts +2 -2
  164. package/src/experimental/training/objectives/ul_stage2_base.js +1 -1
  165. package/src/experimental/training/operator-artifacts.js +1 -14
  166. package/src/experimental/training/runner.js +1 -14
  167. package/src/experimental/training/workload-packs/registry.json +6 -6
  168. package/src/experimental/training/workloads.js +1 -1
  169. package/src/formats/gguf/types.d.ts +0 -63
  170. package/src/formats/gguf/types.js +58 -38
  171. package/src/formats/litert/types.d.ts +0 -13
  172. package/src/formats/litert/types.js +2 -2
  173. package/src/formats/rdrr/distributed/index.d.ts +34 -0
  174. package/src/formats/rdrr/distributed/index.js +3 -0
  175. package/src/formats/rdrr/distributed/parsing.d.ts +6 -0
  176. package/src/formats/rdrr/distributed/parsing.js +23 -0
  177. package/src/formats/rdrr/distributed/validation.d.ts +23 -0
  178. package/src/formats/rdrr/distributed/validation.js +131 -0
  179. package/src/formats/rdrr/groups.d.ts +1 -13
  180. package/src/formats/rdrr/groups.js +0 -34
  181. package/src/formats/rdrr/index.d.ts +9 -0
  182. package/src/formats/rdrr/index.js +9 -0
  183. package/src/formats/rdrr/integrity.d.ts +51 -0
  184. package/src/formats/rdrr/integrity.js +200 -0
  185. package/src/formats/rdrr/lowerings.d.ts +28 -0
  186. package/src/formats/rdrr/lowerings.js +112 -0
  187. package/src/formats/rdrr/manifest.d.ts +0 -14
  188. package/src/formats/rdrr/manifest.js +5 -58
  189. package/src/formats/rdrr/merkle.d.ts +24 -0
  190. package/src/formats/rdrr/merkle.js +118 -0
  191. package/src/formats/rdrr/parsing.js +4 -0
  192. package/src/formats/rdrr/slice-compiler.d.ts +29 -0
  193. package/src/formats/rdrr/slice-compiler.js +188 -0
  194. package/src/formats/rdrr/storage-descriptor.d.ts +36 -0
  195. package/src/formats/rdrr/storage-descriptor.js +186 -0
  196. package/src/formats/rdrr/tensor-config-validator.d.ts +0 -9
  197. package/src/formats/rdrr/tensor-config-validator.js +0 -30
  198. package/src/formats/rdrr/types.d.ts +107 -0
  199. package/src/formats/rdrr/validation.js +245 -0
  200. package/src/formats/tflite/types.d.ts +0 -31
  201. package/src/formats/tflite/types.js +5 -5
  202. package/src/gpu/command-recorder.d.ts +3 -21
  203. package/src/gpu/device.d.ts +17 -3
  204. package/src/gpu/device.js +20 -4
  205. package/src/gpu/kernel-runtime.d.ts +8 -15
  206. package/src/gpu/kernel-selection-log.d.ts +0 -8
  207. package/src/gpu/kernel-selection-log.js +0 -15
  208. package/src/gpu/kernel-tuner/cache.js +0 -3
  209. package/src/gpu/kernels/README.md +50 -18
  210. package/src/gpu/kernels/activation_static_qdq.wgsl +3 -1
  211. package/src/gpu/kernels/attention.d.ts +28 -19
  212. package/src/gpu/kernels/attention.js +443 -9
  213. package/src/gpu/kernels/attention_decode_contiguous_turboquant_f16kv.wgsl +0 -1
  214. package/src/gpu/kernels/attention_decode_contiguous_turboquant_prod_f16kv.wgsl +0 -1
  215. package/src/gpu/kernels/attention_decode_f16.wgsl +1 -1
  216. package/src/gpu/kernels/attention_decode_f16kv.wgsl +1 -1
  217. package/src/gpu/kernels/attention_decode_online_f16.wgsl +32 -29
  218. package/src/gpu/kernels/attention_decode_online_f16kv.wgsl +1 -1
  219. package/src/gpu/kernels/attention_decode_paged_f16kv.wgsl +1 -1
  220. package/src/gpu/kernels/attention_decode_tiered_f16kv.wgsl +1 -1
  221. package/src/gpu/kernels/attention_decode_tiered_turboquant_f16kv.wgsl +0 -1
  222. package/src/gpu/kernels/attention_decode_tiered_turboquant_prod_f16kv.wgsl +0 -1
  223. package/src/gpu/kernels/attention_f16.wgsl +88 -30
  224. package/src/gpu/kernels/attention_f16kv.wgsl +45 -15
  225. package/src/gpu/kernels/attention_head512_f16.wgsl +270 -0
  226. package/src/gpu/kernels/attention_head512_f16kv.wgsl +271 -0
  227. package/src/gpu/kernels/attention_prefill_flash_head256_f16kv.wgsl +306 -0
  228. package/src/gpu/kernels/attention_prefill_flash_reduce.wgsl +101 -0
  229. package/src/gpu/kernels/attention_small_f16.wgsl +22 -20
  230. package/src/gpu/kernels/attention_small_f16kv.wgsl +1 -1
  231. package/src/gpu/kernels/attention_streaming_f16.wgsl +39 -16
  232. package/src/gpu/kernels/attention_streaming_f16kv.wgsl +22 -3
  233. package/src/gpu/kernels/backward/index.d.ts +6 -0
  234. package/src/gpu/kernels/backward/layernorm_backward.wgsl +0 -1
  235. package/src/gpu/kernels/backward/utils.d.ts +35 -0
  236. package/src/gpu/kernels/bf16_to_f32.wgsl +0 -16
  237. package/src/gpu/kernels/bias_add_f16.wgsl +1 -1
  238. package/src/gpu/kernels/cast_f32_to_f16.wgsl +0 -1
  239. package/src/gpu/kernels/codegen/patches/attention_f16.from.attention.diff +19 -215
  240. package/src/gpu/kernels/codegen/patches/attention_f16kv.from.attention.diff +8 -82
  241. package/src/gpu/kernels/codegen/patches/attention_small_f16.from.attention_small.diff +92 -59
  242. package/src/gpu/kernels/codegen/patches/attention_streaming_f16.from.attention_streaming.diff +2 -85
  243. package/src/gpu/kernels/codegen/patches/gelu_f16.from.gelu.diff +27 -24
  244. package/src/gpu/kernels/codegen/patches/residual_f16.from.residual.diff +1 -1
  245. package/src/gpu/kernels/codegen/patches/rmsnorm_f16.from.rmsnorm.diff +249 -179
  246. package/src/gpu/kernels/codegen/patches/rope_f16.from.rope.diff +133 -235
  247. package/src/gpu/kernels/codegen/patches/sample_f16.from.sample.diff +119 -90
  248. package/src/gpu/kernels/codegen/wgsl-variants.js +142 -8
  249. package/src/gpu/kernels/constants.d.ts +9 -48
  250. package/src/gpu/kernels/constants.js +0 -23
  251. package/src/gpu/kernels/conv2d.d.ts +0 -4
  252. package/src/gpu/kernels/conv2d_f16.wgsl +1 -1
  253. package/src/gpu/kernels/dequant.d.ts +0 -16
  254. package/src/gpu/kernels/dequant.js +1 -71
  255. package/src/gpu/kernels/dequant_mxfp4_expert_f16.wgsl +1 -1
  256. package/src/gpu/kernels/dequant_shared.wgsl +1 -55
  257. package/src/gpu/kernels/dispatch.d.ts +12 -97
  258. package/src/gpu/kernels/dispatch.js +0 -117
  259. package/src/gpu/kernels/energy_eval_f16.wgsl +1 -1
  260. package/src/gpu/kernels/energy_quintel_grad_f16.wgsl +1 -1
  261. package/src/gpu/kernels/energy_quintel_reduce_f16.wgsl +1 -1
  262. package/src/gpu/kernels/energy_quintel_update_f16.wgsl +1 -1
  263. package/src/gpu/kernels/energy_update_f16.wgsl +1 -1
  264. package/src/gpu/kernels/fused-gate-up-gelu.js +121 -0
  265. package/src/gpu/kernels/fused_ffn_f16.wgsl +1 -1
  266. package/src/gpu/kernels/fused_ffn_q4k.wgsl +0 -19
  267. package/src/gpu/kernels/fused_ffn_q4k_f16.wgsl +0 -18
  268. package/src/gpu/kernels/fused_gate_up_gelu_gated_f16.wgsl +124 -0
  269. package/src/gpu/kernels/fused_matmul_q4.wgsl +23 -439
  270. package/src/gpu/kernels/fused_matmul_q4_batched_f16.wgsl +1 -1
  271. package/src/gpu/kernels/fused_matmul_q4_batched_f16a.wgsl +0 -1
  272. package/src/gpu/kernels/fused_matmul_q4_batched_f16acc_f16a.wgsl +158 -0
  273. package/src/gpu/kernels/fused_matmul_q4_f16a.wgsl +0 -1
  274. package/src/gpu/kernels/fused_matmul_q4_multicol_f16.wgsl +0 -1
  275. package/src/gpu/kernels/fused_matmul_q4_multicol_f16a.wgsl +32 -33
  276. package/src/gpu/kernels/fused_matmul_q4_multicol_f16a_f32acc.wgsl +209 -0
  277. package/src/gpu/kernels/fused_matmul_q4_prefill_tiled_f16.wgsl +261 -0
  278. package/src/gpu/kernels/fused_matmul_q4_widetile.wgsl +164 -0
  279. package/src/gpu/kernels/fused_matmul_q4_widetile_f16.wgsl +198 -0
  280. package/src/gpu/kernels/fused_matmul_q4_widetile_f16a.wgsl +161 -0
  281. package/src/gpu/kernels/fused_matmul_q4_widetile_residual.wgsl +173 -0
  282. package/src/gpu/kernels/fused_matmul_rmsnorm_f16.wgsl +1 -1
  283. package/src/gpu/kernels/fused_rmsnorm_q4_widetile.wgsl +271 -0
  284. package/src/gpu/kernels/fused_swiglu_f16.wgsl +1 -1
  285. package/src/gpu/kernels/gather.d.ts +0 -7
  286. package/src/gpu/kernels/gather_f16.wgsl +1 -1
  287. package/src/gpu/kernels/gelu_f16.wgsl +14 -15
  288. package/src/gpu/kernels/groupnorm.d.ts +0 -4
  289. package/src/gpu/kernels/groupnorm_apply_f16.wgsl +1 -1
  290. package/src/gpu/kernels/groupnorm_stats_f16.wgsl +1 -1
  291. package/src/gpu/kernels/index.d.ts +6 -5
  292. package/src/gpu/kernels/index.js +3 -4
  293. package/src/gpu/kernels/kv_quantize_turboquant.wgsl +0 -2
  294. package/src/gpu/kernels/kv_quantize_turboquant_prod.wgsl +0 -2
  295. package/src/gpu/kernels/layernorm.d.ts +0 -4
  296. package/src/gpu/kernels/layernorm_f16.wgsl +1 -1
  297. package/src/gpu/kernels/{sana_linear_attention.d.ts → linear_attention.d.ts} +5 -5
  298. package/src/gpu/kernels/{sana_linear_attention.js → linear_attention.js} +16 -16
  299. package/src/gpu/kernels/logit-merge.d.ts +0 -24
  300. package/src/gpu/kernels/logit-merge.js +1 -17
  301. package/src/gpu/kernels/matmul-dispatch.js +7 -1
  302. package/src/gpu/kernels/matmul-selection.js +68 -1
  303. package/src/gpu/kernels/matmul.d.ts +0 -28
  304. package/src/gpu/kernels/matmul.js +101 -7
  305. package/src/gpu/kernels/matmul_f16_tiled.wgsl +33 -34
  306. package/src/gpu/kernels/matmul_gemv_residual_f16.wgsl +1 -1
  307. package/src/gpu/kernels/matmul_gemv_subgroup.wgsl +0 -1
  308. package/src/gpu/kernels/matmul_gemv_subgroup_f16a.wgsl +24 -25
  309. package/src/gpu/kernels/modulate_f16.wgsl +1 -1
  310. package/src/gpu/kernels/moe.d.ts +0 -56
  311. package/src/gpu/kernels/moe.js +0 -15
  312. package/src/gpu/kernels/moe_gather_f16.wgsl +1 -1
  313. package/src/gpu/kernels/pixel_shuffle_f16.wgsl +1 -1
  314. package/src/gpu/kernels/residual.d.ts +0 -12
  315. package/src/gpu/kernels/residual_f16.wgsl +2 -2
  316. package/src/gpu/kernels/residual_f16_vec4.wgsl +5 -5
  317. package/src/gpu/kernels/rmsnorm.d.ts +0 -8
  318. package/src/gpu/kernels/rmsnorm.js +17 -1
  319. package/src/gpu/kernels/rmsnorm.wgsl +5 -6
  320. package/src/gpu/kernels/rmsnorm_f16.wgsl +65 -39
  321. package/src/gpu/kernels/rope.d.ts +1 -5
  322. package/src/gpu/kernels/rope.js +12 -2
  323. package/src/gpu/kernels/rope.wgsl +33 -19
  324. package/src/gpu/kernels/rope_f16.wgsl +39 -25
  325. package/src/gpu/kernels/sample.d.ts +0 -5
  326. package/src/gpu/kernels/sample.wgsl +7 -6
  327. package/src/gpu/kernels/sample_f16.wgsl +28 -30
  328. package/src/gpu/kernels/scatter_add_dynamic_f16.wgsl +1 -1
  329. package/src/gpu/kernels/shader-cache.d.ts +13 -0
  330. package/src/gpu/kernels/shader-cache.js +27 -0
  331. package/src/gpu/kernels/silu_f16.wgsl +1 -1
  332. package/src/gpu/kernels/softmax.wgsl +4 -144
  333. package/src/gpu/kernels/split_qg_f16.wgsl +1 -1
  334. package/src/gpu/kernels/split_qkv_f16.wgsl +1 -1
  335. package/src/gpu/kernels/topk_f16.wgsl +1 -1
  336. package/src/gpu/kernels/turboquant-codebook.js +11 -40
  337. package/src/gpu/kernels/uniform-utils.d.ts +18 -0
  338. package/src/gpu/kernels/upsample2d.d.ts +0 -4
  339. package/src/gpu/kernels/upsample2d_f16.wgsl +1 -1
  340. package/src/gpu/kernels/utils.d.ts +28 -0
  341. package/src/gpu/kernels/utils.js +41 -0
  342. package/src/gpu/perf-guards.d.ts +0 -12
  343. package/src/gpu/perf-guards.js +0 -62
  344. package/src/gpu/profiler.d.ts +0 -21
  345. package/src/gpu/profiler.js +0 -34
  346. package/src/gpu/submit-tracker.d.ts +0 -57
  347. package/src/gpu/submit-tracker.js +3 -62
  348. package/src/gpu/tensor.d.ts +0 -23
  349. package/src/gpu/tensor.js +0 -41
  350. package/src/gpu/uniform-cache.d.ts +0 -11
  351. package/src/gpu/uniform-cache.js +0 -23
  352. package/src/index.d.ts +1 -0
  353. package/src/index.js +1 -0
  354. package/src/inference/browser-harness-model-helpers.d.ts +0 -9
  355. package/src/inference/browser-harness-model-helpers.js +22 -13
  356. package/src/inference/browser-harness-runtime-helpers.d.ts +0 -5
  357. package/src/inference/browser-harness-runtime-helpers.js +2 -2
  358. package/src/inference/browser-harness-suite-helpers.d.ts +4 -1
  359. package/src/inference/browser-harness-suite-helpers.js +87 -1
  360. package/src/inference/browser-harness-text-helpers.d.ts +12 -0
  361. package/src/inference/browser-harness-text-helpers.js +223 -14
  362. package/src/inference/browser-harness.d.ts +0 -29
  363. package/src/inference/browser-harness.js +264 -71
  364. package/src/inference/kv-cache/base.d.ts +6 -0
  365. package/src/inference/kv-cache/base.js +16 -1
  366. package/src/inference/kv-cache/mixed-geometry.d.ts +1 -0
  367. package/src/inference/kv-cache/mixed-geometry.js +12 -2
  368. package/src/inference/kv-cache/quantized.js +2 -0
  369. package/src/inference/kv-cache/tiered.js +7 -0
  370. package/src/inference/kv-cache/types.d.ts +2 -0
  371. package/src/inference/multi-model-network.d.ts +1 -1
  372. package/src/inference/multi-model-network.js +1 -2
  373. package/src/inference/network-evolution.d.ts +0 -12
  374. package/src/inference/network-evolution.js +2 -2
  375. package/src/inference/pipelines/context.js +17 -0
  376. package/src/inference/pipelines/diffusion/init.js +2 -2
  377. package/src/inference/pipelines/diffusion/pipeline.js +41 -96
  378. package/src/inference/pipelines/diffusion/text-encoder-gpu.d.ts +0 -5
  379. package/src/inference/pipelines/diffusion/text-encoder-gpu.js +0 -283
  380. package/src/inference/pipelines/diffusion/vae.js +4 -4
  381. package/src/inference/pipelines/energy/quintel.d.ts +15 -0
  382. package/src/inference/pipelines/structured/index.d.ts +2 -0
  383. package/src/inference/pipelines/structured/index.js +2 -0
  384. package/src/inference/pipelines/structured/json-grammar-mask.js +143 -0
  385. package/src/inference/pipelines/structured/tsv-grammar-mask.js +166 -0
  386. package/src/inference/pipelines/text/attention/attn-config.d.ts +0 -5
  387. package/src/inference/pipelines/text/attention/attn-config.js +1 -1
  388. package/src/inference/pipelines/text/attention/projections.d.ts +2 -0
  389. package/src/inference/pipelines/text/attention/projections.js +70 -23
  390. package/src/inference/pipelines/text/attention/record.js +118 -5
  391. package/src/inference/pipelines/text/attention/rmsnorm-fusion-gate.d.ts +8 -0
  392. package/src/inference/pipelines/text/attention/rmsnorm-fusion-gate.js +19 -0
  393. package/src/inference/pipelines/text/attention/run.js +97 -6
  394. package/src/inference/pipelines/text/attention/types.d.ts +2 -0
  395. package/src/inference/pipelines/text/chat-format.d.ts +0 -10
  396. package/src/inference/pipelines/text/chat-format.js +1 -8
  397. package/src/inference/pipelines/text/config.d.ts +3 -25
  398. package/src/inference/pipelines/text/config.js +105 -3
  399. package/src/inference/pipelines/text/debug-utils/utils.js +2 -23
  400. package/src/inference/pipelines/text/drift-policy.js +1 -1
  401. package/src/inference/pipelines/text/embed.d.ts +22 -27
  402. package/src/inference/pipelines/text/embed.js +0 -39
  403. package/src/inference/pipelines/text/execution-plan.d.ts +5 -3
  404. package/src/inference/pipelines/text/execution-plan.js +15 -2
  405. package/src/inference/pipelines/text/execution-runtime-builders.d.ts +0 -4
  406. package/src/inference/pipelines/text/execution-runtime-builders.js +0 -11
  407. package/src/inference/pipelines/text/execution-v1.d.ts +18 -0
  408. package/src/inference/pipelines/text/execution-v1.js +94 -25
  409. package/src/inference/pipelines/text/ffn/dense.js +180 -3
  410. package/src/inference/pipelines/text/ffn/standard.js +40 -13
  411. package/src/inference/pipelines/text/generator-decode-policy.js +243 -0
  412. package/src/inference/pipelines/text/generator-helpers.d.ts +0 -2
  413. package/src/inference/pipelines/text/generator-helpers.js +4 -5
  414. package/src/inference/pipelines/text/generator-prefill-helpers.js +293 -0
  415. package/src/inference/pipelines/text/generator-runtime.d.ts +0 -7
  416. package/src/inference/pipelines/text/generator-runtime.js +8 -6
  417. package/src/inference/pipelines/text/generator-steps.d.ts +22 -7
  418. package/src/inference/pipelines/text/generator-steps.js +8 -3
  419. package/src/inference/pipelines/text/generator.d.ts +0 -6
  420. package/src/inference/pipelines/text/generator.js +223 -547
  421. package/src/inference/pipelines/text/init-chat-templates.js +86 -0
  422. package/src/inference/pipelines/text/init-qkv-fusion.js +201 -0
  423. package/src/inference/pipelines/text/init-rope.js +408 -0
  424. package/src/inference/pipelines/text/init.d.ts +5 -2
  425. package/src/inference/pipelines/text/init.js +183 -724
  426. package/src/inference/pipelines/text/kernel-trace.d.ts +0 -33
  427. package/src/inference/pipelines/text/kernel-trace.js +0 -33
  428. package/src/inference/pipelines/text/layer-plan-gpu.js +542 -0
  429. package/src/inference/pipelines/text/layer-plan.d.ts +0 -5
  430. package/src/inference/pipelines/text/layer-plan.js +1 -1
  431. package/src/inference/pipelines/text/layer.d.ts +70 -8
  432. package/src/inference/pipelines/text/layer.js +105 -537
  433. package/src/inference/pipelines/text/linear-attention.d.ts +2 -1
  434. package/src/inference/pipelines/text/load-errors.d.ts +21 -0
  435. package/src/inference/pipelines/text/load-errors.js +59 -0
  436. package/src/inference/pipelines/text/logits/cpu.js +2 -20
  437. package/src/inference/pipelines/text/logits/gpu.js +2 -0
  438. package/src/inference/pipelines/text/logits/index.d.ts +1 -1
  439. package/src/inference/pipelines/text/model-load.d.ts +5 -4
  440. package/src/inference/pipelines/text/model-load.js +74 -17
  441. package/src/inference/pipelines/text/ops.d.ts +13 -2
  442. package/src/inference/pipelines/text/ops.js +1 -1
  443. package/src/inference/pipelines/text/per-layer-inputs.js +31 -6
  444. package/src/inference/pipelines/text/probes.d.ts +3 -6
  445. package/src/inference/pipelines/text/probes.js +120 -31
  446. package/src/inference/pipelines/text/sampling.d.ts +0 -5
  447. package/src/inference/pipelines/text/sampling.js +140 -0
  448. package/src/inference/pipelines/text/stage-names.js +3 -0
  449. package/src/inference/pipelines/text/state.js +2 -0
  450. package/src/inference/pipelines/text/tsir-fixture-writer.js +409 -0
  451. package/src/inference/pipelines/text/types.d.ts +8 -78
  452. package/src/inference/pipelines/text/weights.d.ts +0 -50
  453. package/src/inference/pipelines/text/weights.js +2 -51
  454. package/src/inference/pipelines/text.d.ts +9 -1
  455. package/src/inference/pipelines/text.js +223 -27
  456. package/src/inference/pipelines/vision/index.js +0 -107
  457. package/src/inference/runtime-model.d.ts +0 -7
  458. package/src/inference/runtime-model.js +0 -23
  459. package/src/inference/test-harness.d.ts +6 -22
  460. package/src/inference/test-harness.js +97 -23
  461. package/src/inference/tokenizer.js +1 -10
  462. package/src/inference/tokenizers/sentencepiece.js +65 -15
  463. package/src/inference/tokenizers/types.d.ts +0 -21
  464. package/src/loader/doppler-loader.d.ts +3 -0
  465. package/src/loader/doppler-loader.js +90 -12
  466. package/src/loader/embedding-loader.js +13 -3
  467. package/src/loader/loader-types.d.ts +2 -0
  468. package/src/loader/manifest-config.js +25 -1
  469. package/src/loader/memory-monitor.d.ts +17 -5
  470. package/src/loader/quantization-constants.d.ts +6 -0
  471. package/src/loader/shard-resolver.d.ts +1 -0
  472. package/src/loader/shard-resolver.js +15 -0
  473. package/src/loader/tensors/source-transform.js +6 -1
  474. package/src/loader/tensors/tensor-loader.d.ts +2 -9
  475. package/src/loader/tensors/tensor-loader.js +84 -1
  476. package/src/memory/address-table.d.ts +1 -9
  477. package/src/memory/buffer-pool.d.ts +0 -16
  478. package/src/memory/buffer-pool.js +1 -33
  479. package/src/memory/heap-manager.d.ts +18 -43
  480. package/src/memory/unified-detect.d.ts +19 -34
  481. package/src/models/embeddinggemma.d.ts +7 -0
  482. package/src/models/embeddinggemma.js +24 -0
  483. package/src/models/family.d.ts +24 -0
  484. package/src/models/family.js +25 -0
  485. package/src/models/gemma3.d.ts +7 -0
  486. package/src/models/gemma3.js +33 -0
  487. package/src/models/gemma4.d.ts +7 -0
  488. package/src/models/gemma4.js +33 -0
  489. package/src/models/qwen3.d.ts +7 -0
  490. package/src/models/qwen3.js +36 -0
  491. package/src/rules/converter/tokenizer.rules.json +5 -0
  492. package/src/rules/execution-rules-contract-check.js +72 -3
  493. package/src/rules/inference/capability-transforms.rules.json +87 -0
  494. package/src/rules/inference/execution.rules.json +11 -1
  495. package/src/rules/inference/ffn.rules.json +6 -2
  496. package/src/rules/loader/tensor-loader.rules.json +9 -0
  497. package/src/rules/rule-registry.js +53 -75
  498. package/src/storage/artifact-storage-context.d.ts +11 -3
  499. package/src/storage/artifact-storage-context.js +231 -26
  500. package/src/storage/backends/opfs-store.js +138 -88
  501. package/src/storage/blake3.js +9 -1
  502. package/src/storage/export.js +1 -5
  503. package/src/storage/normalize-model-id.js +3 -0
  504. package/src/storage/preflight.js +11 -0
  505. package/src/storage/quickstart-downloader.js +44 -67
  506. package/src/storage/reports.js +35 -11
  507. package/src/storage/shard-manager.d.ts +8 -2
  508. package/src/storage/shard-manager.js +176 -15
  509. package/src/storage/source-artifact-store.d.ts +0 -2
  510. package/src/storage/source-artifact-store.js +3 -9
  511. package/src/sw.js +0 -3
  512. package/src/tooling/browser-command-runner.js +39 -0
  513. package/src/tooling/command-api-constants.js +1 -1
  514. package/src/tooling/command-api-family-normalizers.d.ts +1 -0
  515. package/src/tooling/command-api-family-normalizers.js +49 -7
  516. package/src/tooling/command-api-helpers.d.ts +0 -2
  517. package/src/tooling/command-api-helpers.js +6 -2
  518. package/src/tooling/command-api.d.ts +20 -1
  519. package/src/tooling/command-api.js +10 -1
  520. package/src/tooling/command-envelope.d.ts +0 -1
  521. package/src/tooling/command-envelope.js +1 -1
  522. package/src/tooling/command-runner-shared.d.ts +10 -0
  523. package/src/tooling/conversion-config-materializer.d.ts +0 -10
  524. package/src/tooling/conversion-config-materializer.js +1 -1
  525. package/src/tooling/diagnose-runner.js +1 -4
  526. package/src/tooling/hf-registry-utils.d.ts +2 -6
  527. package/src/tooling/hf-registry-utils.js +90 -19
  528. package/src/tooling/kernel-path-builder/index.js +1 -4
  529. package/src/tooling/kernel-path-builder/runtime-overlay.js +1 -3
  530. package/src/tooling/lean-execution-contract-runner.d.ts +0 -10
  531. package/src/tooling/lean-execution-contract-runner.js +2 -2
  532. package/src/tooling/litert-package-runtime.d.ts +1 -1
  533. package/src/tooling/litert-package-runtime.js +21 -24
  534. package/src/tooling/node-browser-command-runner.d.ts +15 -0
  535. package/src/tooling/node-browser-command-runner.js +97 -13
  536. package/src/tooling/node-command-runner.js +36 -0
  537. package/src/tooling/node-convert-worker-pool.js +12 -0
  538. package/src/tooling/node-convert-worker.js +10 -1
  539. package/src/tooling/node-converter.js +90 -1
  540. package/src/tooling/node-source-runtime.js +1 -10
  541. package/src/tooling/opfs-cache.js +1 -4
  542. package/src/tooling/precision-replay-math.js +174 -0
  543. package/src/tooling/program-bundle-host.d.ts +16 -0
  544. package/src/tooling/program-bundle-host.js +20 -0
  545. package/src/tooling/program-bundle-parity.d.ts +28 -0
  546. package/src/tooling/program-bundle-parity.js +210 -0
  547. package/src/tooling/program-bundle.d.ts +61 -0
  548. package/src/tooling/program-bundle.js +1119 -0
  549. package/src/tooling/rdrr-integrity-refresh.d.ts +32 -0
  550. package/src/tooling/rdrr-integrity-refresh.js +271 -0
  551. package/src/tooling/reference-verify.js +191 -0
  552. package/src/tooling/source-artifact-adapter.d.ts +0 -20
  553. package/src/tooling/source-artifact-adapter.js +4 -4
  554. package/src/tooling/source-package-profiles.js +1 -7
  555. package/src/tooling/source-runtime-bundle.d.ts +2 -0
  556. package/src/tooling/source-runtime-bundle.js +3 -22
  557. package/src/tooling/source-runtime-converter-config.d.ts +0 -5
  558. package/src/tooling/source-runtime-converter-config.js +13 -9
  559. package/src/tooling/source-runtime-materializer.js +1 -7
  560. package/src/tooling-exports/device.d.ts +11 -0
  561. package/src/tooling-exports/device.js +14 -0
  562. package/src/tooling-exports/manifest.d.ts +8 -0
  563. package/src/tooling-exports/manifest.js +11 -0
  564. package/src/tooling-exports/storage.d.ts +25 -0
  565. package/src/tooling-exports/storage.js +29 -0
  566. package/src/tooling-exports/structured.d.ts +1 -0
  567. package/src/tooling-exports/structured.js +5 -0
  568. package/src/tooling-exports.d.ts +23 -0
  569. package/src/tooling-exports.js +17 -0
  570. package/src/tooling-exports.shared.d.ts +27 -30
  571. package/src/tooling-exports.shared.js +28 -29
  572. package/src/types/index.d.ts +0 -3
  573. package/src/types/index.js +0 -3
  574. package/src/utils/array-buffer.d.ts +4 -0
  575. package/src/utils/array-buffer.js +9 -0
  576. package/src/utils/canonical-hash.d.ts +7 -0
  577. package/src/utils/canonical-hash.js +74 -0
  578. package/src/utils/clone-json.d.ts +1 -0
  579. package/src/utils/clone-json.js +7 -0
  580. package/src/utils/encode-utf8.js +5 -0
  581. package/src/utils/index.d.ts +4 -1
  582. package/src/utils/index.js +4 -1
  583. package/src/utils/runtime-env.js +7 -0
  584. package/src/utils/sha256.d.ts +1 -0
  585. package/src/utils/sha256.js +18 -4
  586. package/src/utils/stable-sort-object.d.ts +1 -0
  587. package/src/utils/stable-sort-object.js +13 -0
  588. package/src/version.js +1 -1
  589. package/tools/convert-safetensors-node.js +1 -2
  590. package/src/bootstrap.d.ts +0 -1
  591. package/src/config/conversion/sana/sana-sprint-0.6b-f16.json +0 -247
  592. package/src/config/kernels/kernel-ref.d.ts +0 -17
  593. package/src/config/kernels/kernel-ref.js +0 -75
  594. package/src/config/runtime/kernels/dequant-f16-q4k.json +0 -13
  595. package/src/config/runtime/kernels/dequant-f32-q4k.json +0 -13
  596. package/src/config/runtime/kernels/embeddinggemma-q4k-dequant-f32a.json +0 -37
  597. package/src/config/runtime/kernels/fused-q4k.json +0 -13
  598. package/src/config/runtime/kernels/gemma2-q4k-dequant-f16a.json +0 -33
  599. package/src/config/runtime/kernels/gemma2-q4k-dequant-f32a-nosubgroups.json +0 -33
  600. package/src/config/runtime/kernels/gemma2-q4k-fused-f32a.json +0 -33
  601. package/src/config/runtime/kernels/safe-q4k.json +0 -13
  602. package/src/config/runtime/overlays/debug-f32a.json +0 -3
  603. package/src/config/runtime/overlays/trace-config.json +0 -28
  604. package/src/config/runtime/profiles/gemma4-e2b-throughput.json +0 -39
  605. package/src/debug/perf.d.ts +0 -33
  606. package/src/debug/perf.js +0 -51
  607. package/src/errors/index.d.ts +0 -1
  608. package/src/errors/index.js +0 -1
  609. package/src/formats/gguf/index.d.ts +0 -8
  610. package/src/formats/gguf/index.js +0 -4
  611. package/src/formats/litert/index.d.ts +0 -1
  612. package/src/formats/litert/index.js +0 -1
  613. package/src/formats/safetensors/index.d.ts +0 -8
  614. package/src/formats/safetensors/index.js +0 -4
  615. package/src/formats/tflite/index.d.ts +0 -1
  616. package/src/formats/tflite/index.js +0 -1
  617. package/src/gpu/kernels/attention_decode_optimized.wgsl +0 -445
  618. package/src/gpu/kernels/dequant_mxfp4_vec4.wgsl +0 -116
  619. package/src/gpu/kernels/dequant_q8_0.wgsl +0 -98
  620. package/src/gpu/kernels/dequant_shared_vec4.wgsl +0 -160
  621. package/src/gpu/kernels/moe_gather_vec4.wgsl +0 -74
  622. package/src/inference/functiongemma.d.ts +0 -15
  623. package/src/inference/functiongemma.js +0 -1
  624. package/src/inference/pipelines/diffusion/sana-transformer.d.ts +0 -53
  625. package/src/inference/pipelines/diffusion/sana-transformer.js +0 -738
  626. package/src/rules/kernels/kernel-validator.d.ts +0 -24
  627. package/src/rules/kernels/kernel-validator.js +0 -160
  628. package/src/sw.d.ts +0 -1
  629. package/src/tooling/bench-runner.js +0 -64
  630. package/src/tooling/distill-runner.js +0 -56
  631. package/src/tooling/lora-runner.js +0 -37
  632. package/src/tooling/verify-runner.js +0 -63
  633. package/src/types/gpu.d.ts +0 -185
  634. package/src/types/gpu.js +0 -5
  635. package/src/types/inference.d.ts +0 -197
  636. package/src/types/inference.js +0 -5
  637. package/src/types/model.d.ts +0 -130
  638. package/src/types/model.js +0 -5
  639. package/src/utils/format-bytes.js +0 -20
  640. /package/src/config/{runtime/diagnostics → diagnostics}/drift-policies.json +0 -0
  641. /package/src/gpu/kernels/{sana_linear_attention_apply.wgsl → linear_attention_apply.wgsl} +0 -0
  642. /package/src/gpu/kernels/{sana_linear_attention_apply_f16.wgsl → linear_attention_apply_f16.wgsl} +0 -0
  643. /package/src/gpu/kernels/{sana_linear_attention_summary.wgsl → linear_attention_summary.wgsl} +0 -0
  644. /package/src/gpu/kernels/{sana_linear_attention_summary_f16.wgsl → linear_attention_summary_f16.wgsl} +0 -0
  645. /package/src/rules/kernels/{sana-linear-attention.rules.json → linear-attention.rules.json} +0 -0
@@ -1,6 +1,245 @@
1
1
  import { validateTensorConfigConsistency } from './tensor-config-validator.js';
2
2
  import { validateManifestExecutionContract } from '../../config/execution-contract-check.js';
3
3
  import { validateManifestInference } from '../../config/schema/index.js';
4
+ import { validateTensorStorageDescriptor } from './storage-descriptor.js';
5
+
6
+ const ARTIFACT_COMPLETENESS_VALUES = new Set([
7
+ 'complete',
8
+ 'weights-ref',
9
+ 'incomplete',
10
+ ]);
11
+
12
+ const LOWERING_EXACTNESS_CLASSES = new Set([
13
+ 'bit_exact_solo',
14
+ 'algorithm_exact',
15
+ 'tolerance_bounded',
16
+ ]);
17
+
18
+ const LOWERING_NULLABLE_STRING_FIELDS = [
19
+ 'targetDescriptorCorrectnessHash',
20
+ 'frontendVersion',
21
+ 'tsirSemanticDigest',
22
+ 'tsirRealizationDigest',
23
+ 'emitterDigest',
24
+ 'compilerVersion',
25
+ ];
26
+
27
+ const LOWERING_ALGORITHM_EXACT_INVARIANTS = new Set([
28
+ 'reduction_order',
29
+ 'tree_shape',
30
+ 'accum_dtype',
31
+ 'associativity_grouping',
32
+ ]);
33
+
34
+ function isPlainObject(value) {
35
+ return value != null && typeof value === 'object' && !Array.isArray(value);
36
+ }
37
+
38
+ function validateOptionalNonEmptyString(errors, object, field, prefix) {
39
+ if (object[field] === undefined) {
40
+ return;
41
+ }
42
+ if (typeof object[field] !== 'string' || object[field].trim().length === 0) {
43
+ errors.push(`Invalid ${prefix}.${field}`);
44
+ }
45
+ }
46
+
47
+ function validateRequiredNonEmptyString(errors, object, field, prefix) {
48
+ if (typeof object[field] !== 'string' || object[field].trim().length === 0) {
49
+ errors.push(`Missing or invalid ${prefix}.${field}`);
50
+ }
51
+ }
52
+
53
+ function validateIntegrityExtensionsContract(manifest, errors) {
54
+ const integrityExtensions = manifest.integrityExtensions;
55
+ if (integrityExtensions === undefined) {
56
+ return;
57
+ }
58
+ if (!isPlainObject(integrityExtensions)) {
59
+ errors.push('Invalid integrityExtensions field');
60
+ return;
61
+ }
62
+ if (integrityExtensions.contractVersion !== 1) {
63
+ errors.push(`Invalid integrityExtensions.contractVersion: ${integrityExtensions.contractVersion}`);
64
+ }
65
+ if (!isPlainObject(integrityExtensions.blockMerkle)) {
66
+ errors.push('Invalid integrityExtensions.blockMerkle');
67
+ return;
68
+ }
69
+ const blockSize = integrityExtensions.blockMerkle.blockSize;
70
+ if (!Number.isInteger(blockSize) || blockSize <= 0) {
71
+ errors.push('Invalid integrityExtensions.blockMerkle.blockSize');
72
+ }
73
+ const roots = integrityExtensions.blockMerkle.roots;
74
+ if (!isPlainObject(roots) || Object.keys(roots).length === 0) {
75
+ errors.push('Invalid integrityExtensions.blockMerkle.roots');
76
+ return;
77
+ }
78
+ for (const [tensorId, merkleRoot] of Object.entries(roots)) {
79
+ if (typeof tensorId !== 'string' || tensorId.trim().length === 0) {
80
+ errors.push('Invalid integrityExtensions.blockMerkle.roots tensor id');
81
+ continue;
82
+ }
83
+ if (typeof merkleRoot !== 'string' || merkleRoot.trim().length === 0) {
84
+ errors.push(`Invalid integrityExtensions.blockMerkle.roots.${tensorId}`);
85
+ }
86
+ }
87
+
88
+ validateLoweringsSection(integrityExtensions.lowerings, errors);
89
+ }
90
+
91
+ function validateLoweringsSection(lowerings, errors) {
92
+ if (lowerings === undefined) {
93
+ return;
94
+ }
95
+ if (!isPlainObject(lowerings)) {
96
+ errors.push('Invalid integrityExtensions.lowerings');
97
+ return;
98
+ }
99
+ if (lowerings.contractVersion !== 1) {
100
+ errors.push(`Invalid integrityExtensions.lowerings.contractVersion: ${lowerings.contractVersion}`);
101
+ }
102
+ if (!Array.isArray(lowerings.entries)) {
103
+ errors.push('Invalid integrityExtensions.lowerings.entries');
104
+ return;
105
+ }
106
+ const seen = new Set();
107
+ lowerings.entries.forEach((entry, index) => {
108
+ const prefix = `integrityExtensions.lowerings.entries[${index}]`;
109
+ if (!isPlainObject(entry)) {
110
+ errors.push(`${prefix} must be an object`);
111
+ return;
112
+ }
113
+ if (typeof entry.kernelRef !== 'string' || entry.kernelRef.trim().length === 0) {
114
+ errors.push(`${prefix}.kernelRef must be a non-empty string`);
115
+ }
116
+ if (typeof entry.backend !== 'string' || entry.backend.trim().length === 0) {
117
+ errors.push(`${prefix}.backend must be a non-empty string`);
118
+ }
119
+ if (typeof entry.kernelRef === 'string' && typeof entry.backend === 'string') {
120
+ const key = `${entry.kernelRef}::${entry.backend}`;
121
+ if (seen.has(key)) {
122
+ errors.push(`${prefix} duplicates (kernelRef, backend) pair already declared earlier`);
123
+ }
124
+ seen.add(key);
125
+ }
126
+ for (const field of LOWERING_NULLABLE_STRING_FIELDS) {
127
+ const value = entry[field];
128
+ if (value === undefined) {
129
+ errors.push(`${prefix}.${field} is required (use null for not-applicable)`);
130
+ continue;
131
+ }
132
+ if (value === null) continue;
133
+ if (typeof value !== 'string' || value.trim().length === 0) {
134
+ errors.push(`${prefix}.${field} must be a non-empty string or null`);
135
+ }
136
+ }
137
+ if (entry.exactness === undefined) {
138
+ errors.push(`${prefix}.exactness is required (use null for rejection entries)`);
139
+ } else if (entry.exactness !== null) {
140
+ if (!isPlainObject(entry.exactness)) {
141
+ errors.push(`${prefix}.exactness must be an object or null`);
142
+ } else {
143
+ if (!LOWERING_EXACTNESS_CLASSES.has(entry.exactness.class)) {
144
+ errors.push(`${prefix}.exactness.class must be one of bit_exact_solo, algorithm_exact, tolerance_bounded`);
145
+ }
146
+ if (!Array.isArray(entry.exactness.algorithmExactInvariants)) {
147
+ errors.push(`${prefix}.exactness.algorithmExactInvariants must be an array`);
148
+ } else {
149
+ entry.exactness.algorithmExactInvariants.forEach((inv, i) => {
150
+ if (typeof inv !== 'string' || !LOWERING_ALGORITHM_EXACT_INVARIANTS.has(inv)) {
151
+ errors.push(`${prefix}.exactness.algorithmExactInvariants[${i}] must be one of reduction_order, tree_shape, accum_dtype, associativity_grouping`);
152
+ }
153
+ });
154
+ }
155
+ if (typeof entry.exactness.toleranceMetric !== 'string') {
156
+ errors.push(`${prefix}.exactness.toleranceMetric must be a string`);
157
+ }
158
+ if (typeof entry.exactness.toleranceEpsilon !== 'number') {
159
+ errors.push(`${prefix}.exactness.toleranceEpsilon must be a number`);
160
+ }
161
+ }
162
+ }
163
+ if (entry.rejectionReasons === undefined) {
164
+ errors.push(`${prefix}.rejectionReasons is required (empty array when backend honored the kernel)`);
165
+ } else if (!Array.isArray(entry.rejectionReasons)) {
166
+ errors.push(`${prefix}.rejectionReasons must be an array (empty for success)`);
167
+ } else {
168
+ entry.rejectionReasons.forEach((reason, reasonIndex) => {
169
+ if (typeof reason !== 'string' || reason.trim().length === 0) {
170
+ errors.push(`${prefix}.rejectionReasons[${reasonIndex}] must be a non-empty string`);
171
+ }
172
+ });
173
+ }
174
+
175
+ // A lowering receipt is either a success (digests populated, rejectionReasons empty)
176
+ // or a rejection (digests null, rejectionReasons non-empty). Mixed states are invalid.
177
+ const hasDigests = (
178
+ typeof entry.tsirSemanticDigest === 'string'
179
+ && typeof entry.tsirRealizationDigest === 'string'
180
+ && typeof entry.emitterDigest === 'string'
181
+ );
182
+ const allDigestsNull = (
183
+ entry.tsirSemanticDigest === null
184
+ && entry.tsirRealizationDigest === null
185
+ && entry.emitterDigest === null
186
+ );
187
+ const hasRejection = Array.isArray(entry.rejectionReasons) && entry.rejectionReasons.length > 0;
188
+ if (hasRejection && hasDigests) {
189
+ errors.push(`${prefix} has both rejectionReasons and digests; must be one or the other`);
190
+ }
191
+ if (!hasRejection && !hasDigests && !allDigestsNull) {
192
+ errors.push(`${prefix} has inconsistent digests: all must be strings (success) or all null (rejection)`);
193
+ }
194
+ if (!hasRejection && allDigestsNull && !hasDigests) {
195
+ errors.push(`${prefix} declares no state: success requires populated digests with empty rejectionReasons, rejection requires null digests with non-empty rejectionReasons`);
196
+ }
197
+ });
198
+ }
199
+
200
+ function validateArtifactIdentityContract(manifest, errors) {
201
+ const identity = manifest.artifactIdentity;
202
+ if (identity !== undefined) {
203
+ if (!isPlainObject(identity)) {
204
+ errors.push('Invalid artifactIdentity field');
205
+ } else {
206
+ for (const field of [
207
+ 'sourceCheckpointId',
208
+ 'sourceRepo',
209
+ 'sourceRevision',
210
+ 'sourceFormat',
211
+ 'conversionConfigPath',
212
+ 'conversionConfigDigest',
213
+ 'weightPackId',
214
+ 'weightPackHash',
215
+ 'shardSetHash',
216
+ 'manifestVariantId',
217
+ 'materializationProfile',
218
+ ]) {
219
+ validateOptionalNonEmptyString(errors, identity, field, 'artifactIdentity');
220
+ }
221
+ if (identity.modalitySet !== undefined) {
222
+ if (!Array.isArray(identity.modalitySet) || identity.modalitySet.some((item) => typeof item !== 'string' || item.trim().length === 0)) {
223
+ errors.push('Invalid artifactIdentity.modalitySet');
224
+ }
225
+ }
226
+ if (identity.artifactCompleteness !== undefined && !ARTIFACT_COMPLETENESS_VALUES.has(identity.artifactCompleteness)) {
227
+ errors.push(`Invalid artifactIdentity.artifactCompleteness: ${identity.artifactCompleteness}`);
228
+ }
229
+ }
230
+ }
231
+
232
+ const weightsRef = manifest.weightsRef;
233
+ if (weightsRef !== undefined) {
234
+ if (!isPlainObject(weightsRef)) {
235
+ errors.push('Invalid weightsRef field');
236
+ } else {
237
+ for (const field of ['weightPackId', 'artifactRoot', 'manifestDigest', 'shardSetHash']) {
238
+ validateRequiredNonEmptyString(errors, weightsRef, field, 'weightsRef');
239
+ }
240
+ }
241
+ }
242
+ }
4
243
 
5
244
  export function validateManifest(manifest) {
6
245
  const errors = [];
@@ -43,6 +282,9 @@ export function validateManifest(manifest) {
43
282
  errors.push(`Invalid hashAlgorithm: ${manifest.hashAlgorithm}`);
44
283
  }
45
284
 
285
+ validateArtifactIdentityContract(manifest, errors);
286
+ validateIntegrityExtensionsContract(manifest, errors);
287
+
46
288
  // EOS token ID (required for text models)
47
289
  const eosTokenId = manifest.eos_token_id;
48
290
  if (!isDiffusion && !isEnergy && !isEmbedding) {
@@ -129,6 +371,9 @@ export function validateManifest(manifest) {
129
371
  if (!tensor.role || typeof tensor.role !== 'string') {
130
372
  errors.push(`Tensor "${name}" missing role`);
131
373
  }
374
+ if (tensor.storage !== undefined) {
375
+ validateTensorStorageDescriptor(tensor.storage, `tensor "${name}"`, errors);
376
+ }
132
377
  }
133
378
  }
134
379
 
@@ -1,36 +1,5 @@
1
1
  export declare const TFLITE_FILE_IDENTIFIER: 'TFL3';
2
2
 
3
- export declare const TFLITE_TENSOR_TYPE: {
4
- readonly FLOAT32: 0;
5
- readonly FLOAT16: 1;
6
- readonly INT32: 2;
7
- readonly UINT8: 3;
8
- readonly INT64: 4;
9
- readonly STRING: 5;
10
- readonly BOOL: 6;
11
- readonly INT16: 7;
12
- readonly COMPLEX64: 8;
13
- readonly INT8: 9;
14
- readonly FLOAT64: 10;
15
- readonly COMPLEX128: 11;
16
- readonly UINT64: 12;
17
- readonly RESOURCE: 13;
18
- readonly VARIANT: 14;
19
- readonly UINT32: 15;
20
- readonly UINT16: 16;
21
- readonly INT4: 17;
22
- readonly BFLOAT16: 18;
23
- };
24
-
25
- export type TFLiteTensorTypeId = (typeof TFLITE_TENSOR_TYPE)[keyof typeof TFLITE_TENSOR_TYPE];
26
-
27
- export declare const TFLITE_TENSOR_TYPE_NAME: Record<number, string>;
28
-
29
- export declare const TFLITE_TENSOR_DTYPE_MAP: Record<number, 'F32' | 'F16' | 'BF16'>;
30
- export declare const TFLITE_TENSOR_SOURCE_DTYPE_MAP: Record<number, 'F32' | 'F16' | 'BF16' | 'INT8' | 'UINT8' | 'INT4'>;
31
-
32
- export declare const TFLITE_DTYPE_SIZE: Record<'F32' | 'F16' | 'BF16', number>;
33
-
34
3
  export interface TFLiteSourceTransform {
35
4
  kind: 'affine_dequant';
36
5
  scheme: 'per_tensor_affine';
@@ -3,7 +3,7 @@ const TFLITE_PAGE_BYTES = 16 * 1024;
3
3
 
4
4
  export const TFLITE_FILE_IDENTIFIER = 'TFL3';
5
5
 
6
- export const TFLITE_TENSOR_TYPE = Object.freeze({
6
+ const TFLITE_TENSOR_TYPE = Object.freeze({
7
7
  FLOAT32: 0,
8
8
  FLOAT16: 1,
9
9
  INT32: 2,
@@ -25,17 +25,17 @@ export const TFLITE_TENSOR_TYPE = Object.freeze({
25
25
  BFLOAT16: 18,
26
26
  });
27
27
 
28
- export const TFLITE_TENSOR_TYPE_NAME = Object.freeze(Object.fromEntries(
28
+ const TFLITE_TENSOR_TYPE_NAME = Object.freeze(Object.fromEntries(
29
29
  Object.entries(TFLITE_TENSOR_TYPE).map(([name, value]) => [value, name])
30
30
  ));
31
31
 
32
- export const TFLITE_TENSOR_DTYPE_MAP = Object.freeze({
32
+ const TFLITE_TENSOR_DTYPE_MAP = Object.freeze({
33
33
  [TFLITE_TENSOR_TYPE.FLOAT32]: 'F32',
34
34
  [TFLITE_TENSOR_TYPE.FLOAT16]: 'F16',
35
35
  [TFLITE_TENSOR_TYPE.BFLOAT16]: 'BF16',
36
36
  });
37
37
 
38
- export const TFLITE_TENSOR_SOURCE_DTYPE_MAP = Object.freeze({
38
+ const TFLITE_TENSOR_SOURCE_DTYPE_MAP = Object.freeze({
39
39
  [TFLITE_TENSOR_TYPE.FLOAT32]: 'F32',
40
40
  [TFLITE_TENSOR_TYPE.FLOAT16]: 'F16',
41
41
  [TFLITE_TENSOR_TYPE.BFLOAT16]: 'BF16',
@@ -44,7 +44,7 @@ export const TFLITE_TENSOR_SOURCE_DTYPE_MAP = Object.freeze({
44
44
  [TFLITE_TENSOR_TYPE.INT4]: 'INT4',
45
45
  });
46
46
 
47
- export const TFLITE_DTYPE_SIZE = Object.freeze({
47
+ const TFLITE_DTYPE_SIZE = Object.freeze({
48
48
  F32: 4,
49
49
  F16: 2,
50
50
  BF16: 2,
@@ -5,30 +5,12 @@
5
5
  * avoiding per-kernel submit overhead. Manages temporary buffers automatically.
6
6
  */
7
7
 
8
- /** Statistics about recorded operations */
9
- export interface RecorderStats {
10
- opCount: number;
11
- tempBufferCount: number;
12
- pooledBufferCount: number;
13
- submitted: boolean;
14
- }
15
-
16
8
  /** Options for CommandRecorder */
17
9
  export interface RecorderOptions {
18
10
  /** Enable GPU timestamp profiling (requires 'timestamp-query' feature) */
19
11
  profile?: boolean;
20
12
  }
21
13
 
22
- export interface RecorderSubmitOptions {
23
- /** Use `deferred` when another readback wait already proves command completion. */
24
- cleanup?: 'queue' | 'deferred';
25
- }
26
-
27
- export interface RecorderDeferredCleanupOptions {
28
- /** Discard pooled buffers instead of returning them to the pool. */
29
- discardPooled?: boolean;
30
- }
31
-
32
14
  /** Profiling result - maps kernel label to time in milliseconds */
33
15
  export type ProfileTimings = Record<string, number>;
34
16
 
@@ -123,13 +105,13 @@ export declare class CommandRecorder {
123
105
  * Submit all recorded commands and clean up temporary buffers.
124
106
  * After calling this, the recorder cannot be reused.
125
107
  */
126
- submit(options?: RecorderSubmitOptions): void;
108
+ submit(options?: { cleanup?: 'queue' | 'deferred' }): void;
127
109
 
128
110
  /**
129
111
  * Finalize a deferred-cleanup submit after another wait condition
130
112
  * has already established GPU completion.
131
113
  */
132
- completeDeferredCleanup(options?: RecorderDeferredCleanupOptions): Promise<void>;
114
+ completeDeferredCleanup(options?: { discardPooled?: boolean }): Promise<void>;
133
115
 
134
116
  /**
135
117
  * Submit and wait for GPU to complete (useful for debugging/profiling).
@@ -143,7 +125,7 @@ export declare class CommandRecorder {
143
125
  * Get statistics about recorded operations.
144
126
  * @returns Statistics object
145
127
  */
146
- getStats(): RecorderStats;
128
+ getStats(): { opCount: number; tempBufferCount: number; pooledBufferCount: number; submitted: boolean };
147
129
 
148
130
  /**
149
131
  * Get the submit completion latency in milliseconds (null if not resolved yet).
@@ -61,6 +61,14 @@ export interface DeviceLimits {
61
61
  maxComputeWorkgroupsPerDimension: number;
62
62
  }
63
63
 
64
+ export interface DeviceLossInfo {
65
+ message: string;
66
+ reason: string;
67
+ deviceEpoch: number;
68
+ timestampMs: number;
69
+ adapterInfo: AdapterInfo | null;
70
+ }
71
+
64
72
  /**
65
73
  * Feature flags detected during initialization
66
74
  */
@@ -120,10 +128,10 @@ export function getDeviceEpoch(): number;
120
128
  export function getPlatformConfig(): ResolvedPlatformConfig | null;
121
129
 
122
130
  /**
123
- * Check if platform and registry are initialized
124
- * @returns True if platform detection succeeded
131
+ * Most recent device-lost record for diagnostics, or null if no loss has been observed
132
+ * since the current device was initialized.
125
133
  */
126
- export function isPlatformInitialized(): boolean;
134
+ export function getLastDeviceLossInfo(): DeviceLossInfo | null;
127
135
 
128
136
  /**
129
137
  * Destroy the device and clear cache
@@ -142,3 +150,9 @@ export function hasFeature(feature: string): boolean;
142
150
  * @returns Device limits or null if device not initialized
143
151
  */
144
152
  export function getDeviceLimits(): DeviceLimits | null;
153
+
154
+ /**
155
+ * Reset all cached device-level state (adapter, device, features, limits).
156
+ * Used by tests and teardown paths that need a clean re-init.
157
+ */
158
+ export declare function resetDeviceState(): void;
package/src/gpu/device.js CHANGED
@@ -3,7 +3,7 @@
3
3
  import { wrapQueueForTracking, setTrackSubmits } from './submit-tracker.js';
4
4
  import { probeSubmitLatency } from './submit-probe.js';
5
5
  import { log } from '../debug/index.js';
6
- import { createDopplerError, ERROR_CODES } from '../errors/index.js';
6
+ import { createDopplerError, ERROR_CODES } from '../errors/doppler-error.js';
7
7
  import { GB } from '../config/schema/index.js';
8
8
 
9
9
  // Re-export submit tracker for convenience
@@ -18,6 +18,7 @@ let kernelCapabilities = null;
18
18
  // Cached platform config (set during initDevice)
19
19
 
20
20
  let resolvedPlatformConfig = null;
21
+ let lastDeviceLossInfo = null;
21
22
 
22
23
  // Track whether platform/registry initialization has been attempted
23
24
  let platformInitialized = false;
@@ -162,6 +163,13 @@ function registerDeviceLostHandler(device) {
162
163
  if (gpuDevice !== trackedDevice) {
163
164
  return;
164
165
  }
166
+ lastDeviceLossInfo = {
167
+ message: info?.message ?? '',
168
+ reason: info?.reason ?? 'unknown',
169
+ deviceEpoch,
170
+ timestampMs: Date.now(),
171
+ adapterInfo: kernelCapabilities?.adapterInfo ?? null,
172
+ };
165
173
  log.error('GPU', 'Device lost: ' + info.message + ', Reason: ' + info.reason);
166
174
  clearActiveDeviceState();
167
175
  advanceDeviceEpoch();
@@ -169,6 +177,13 @@ function registerDeviceLostHandler(device) {
169
177
  if (gpuDevice !== trackedDevice) {
170
178
  return;
171
179
  }
180
+ lastDeviceLossInfo = {
181
+ message: error?.message ?? String(error),
182
+ reason: 'device_lost_handler_failed',
183
+ deviceEpoch,
184
+ timestampMs: Date.now(),
185
+ adapterInfo: kernelCapabilities?.adapterInfo ?? null,
186
+ };
172
187
  log.warn('GPU', 'Device lost handler failed: ' + (error?.message ?? error));
173
188
  clearActiveDeviceState();
174
189
  advanceDeviceEpoch();
@@ -372,6 +387,7 @@ export async function initDevice() {
372
387
  if (!gpuDevice) {
373
388
  throw createDopplerError(ERROR_CODES.GPU_DEVICE_FAILED, 'Failed to create WebGPU device');
374
389
  }
390
+ lastDeviceLossInfo = null;
375
391
  ensureGpuBufferConstructor(gpuDevice);
376
392
  wrapDeviceCreateBindGroup(gpuDevice);
377
393
  registerDeviceLostHandler(gpuDevice);
@@ -426,6 +442,7 @@ export function setDevice(device, options = {}) {
426
442
  }
427
443
 
428
444
  gpuDevice = device;
445
+ lastDeviceLossInfo = null;
429
446
  ensureGpuBufferConstructor(gpuDevice);
430
447
  wrapDeviceCreateBindGroup(gpuDevice);
431
448
  registerDeviceLostHandler(gpuDevice);
@@ -490,9 +507,8 @@ export function getPlatformConfig() {
490
507
  return resolvedPlatformConfig;
491
508
  }
492
509
 
493
-
494
- export function isPlatformInitialized() {
495
- return platformInitialized && resolvedPlatformConfig !== null;
510
+ export function getLastDeviceLossInfo() {
511
+ return lastDeviceLossInfo ? { ...lastDeviceLossInfo } : null;
496
512
  }
497
513
 
498
514
 
@@ -2,19 +2,12 @@
2
2
  * Kernel runtime initialization helpers.
3
3
  */
4
4
 
5
- export interface KernelRuntimeOptions {
6
- prewarm?: boolean;
7
- prewarmMode?: 'parallel' | 'sequential';
8
- autoTune?: boolean;
9
- clearCaches?: boolean;
10
- modelConfig?: Record<string, number>;
11
- }
12
-
13
- export interface KernelRuntimeState {
14
- warmed: boolean;
15
- tuned: boolean;
16
- }
17
-
18
5
  export function prepareKernelRuntime(
19
- options?: KernelRuntimeOptions
20
- ): Promise<KernelRuntimeState>;
6
+ options?: {
7
+ prewarm?: boolean;
8
+ prewarmMode?: 'parallel' | 'sequential';
9
+ autoTune?: boolean;
10
+ clearCaches?: boolean;
11
+ modelConfig?: Record<string, number>;
12
+ }
13
+ ): Promise<{ warmed: boolean; tuned: boolean }>;
@@ -2,11 +2,3 @@ export declare function logKernelSelectionOnce(
2
2
  operation: string,
3
3
  payload: { variant?: string; reason?: string }
4
4
  ): void;
5
-
6
- export declare function resetKernelSelectionLog(): void;
7
-
8
- export declare function getKernelSelectionLog(): Array<{
9
- operation: string;
10
- variant: string;
11
- reason: string | null;
12
- }>;
@@ -1,7 +1,6 @@
1
1
  import { log } from '../debug/index.js';
2
2
 
3
3
  const loggedSelections = new Set();
4
- const selectionLog = [];
5
4
 
6
5
  export function logKernelSelectionOnce(operation, payload) {
7
6
  const key = `${operation}:${payload.variant ?? 'unknown'}`;
@@ -9,20 +8,6 @@ export function logKernelSelectionOnce(operation, payload) {
9
8
  return;
10
9
  }
11
10
  loggedSelections.add(key);
12
- selectionLog.push({
13
- operation,
14
- variant: payload.variant ?? 'unknown',
15
- reason: payload.reason ?? null,
16
- });
17
11
  const reason = payload.reason ? ` reason=${payload.reason}` : '';
18
12
  log.info('KernelSelect', `${operation} variant=${payload.variant ?? 'unknown'}${reason}`);
19
13
  }
20
-
21
- export function resetKernelSelectionLog() {
22
- loggedSelections.clear();
23
- selectionLog.length = 0;
24
- }
25
-
26
- export function getKernelSelectionLog() {
27
- return [...selectionLog];
28
- }
@@ -147,6 +147,3 @@ export function clearCacheStorage(capabilities) {
147
147
  }
148
148
 
149
149
 
150
- export function clearOnDeviceReset() {
151
- cacheDeviceEpoch = -1;
152
- }
@@ -4,8 +4,9 @@ Purpose: Catalog and guidance for Doppler's WGSL kernel library.
4
4
 
5
5
  ## Scope
6
6
 
7
- - Kernel categories, counts, and naming conventions.
7
+ - Kernel categories and entry point reuse guidance.
8
8
  - Entry points, uniforms, and reuse strategies.
9
+ - Registry-owned kernel naming and inventory pointers.
9
10
 
10
11
  The repository currently ships over 100 WebGPU compute shaders for inference and auxiliary pipelines.
11
12
 
@@ -14,20 +15,20 @@ The repository currently ships over 100 WebGPU compute shaders for inference and
14
15
  Selected duplicate dtype variants are generated from canonical kernels:
15
16
 
16
17
  - Source of truth: `src/gpu/kernels/codegen/wgsl-variants.js`
17
- - Generator: `node tools/generate-wgsl.js`
18
- - Drift check: `node tools/generate-wgsl.js --check`
18
+ - Generator: `npm run kernels:codegen:sync`
19
+ - Drift check: `npm run kernels:codegen:check`
19
20
 
20
21
  Generated targets keep the same runtime file names, so kernel-path IDs and manifest wiring stay stable.
21
22
 
22
23
  ## Categories
23
24
 
24
- | Category | Count | Examples |
25
- |----------|-------|----------|
26
- | Attention | 16 | `attention.wgsl`, `attention_decode_*.wgsl`, `attention_f16.wgsl` |
27
- | Matmul | 6 | `matmul_f16.wgsl`, `matmul_f16w_f32a.wgsl`, `matmul_gemv*.wgsl` |
28
- | Dequant | 10 | `dequant_q4k.wgsl`, `dequant_q6k.wgsl`, `dequant_mxfp4.wgsl` |
29
- | Fused | 10 | `fused_ffn.wgsl`, `fused_matmul_q4.wgsl`, `fused_matmul_q4_multicol_f16a.wgsl` |
30
- | Other | 37 | `rmsnorm.wgsl`, `rope.wgsl`, `sample.wgsl`, `silu.wgsl` |
25
+ | Category | Examples |
26
+ |----------|----------|
27
+ | Attention | `attention.wgsl`, `attention_decode_*.wgsl`, `attention_f16.wgsl` |
28
+ | Matmul | `matmul_f16.wgsl`, `matmul_f16w_f32a.wgsl`, `matmul_gemv*.wgsl` |
29
+ | Dequant | `dequant_q4k.wgsl`, `dequant_q6k.wgsl`, `dequant_mxfp4.wgsl` |
30
+ | Fused | `fused_ffn.wgsl`, `fused_matmul_q4.wgsl`, `fused_matmul_q4_multicol_f16a.wgsl` |
31
+ | Other | `rmsnorm.wgsl`, `rope.wgsl`, `sample.wgsl`, `silu.wgsl` |
31
32
 
32
33
  ## Reusability Mechanisms
33
34
 
@@ -116,12 +117,43 @@ fn main() {
116
117
  | `silu.wgsl` | 5 | SiLU activation variants (gate, split, vec4, rowsplit) |
117
118
  | `gelu.wgsl` | 3 | GeLU/GeGLU activation variants (gate, rowsplit) |
118
119
 
119
- ## Naming Conventions
120
+ ## Naming Source of Truth
120
121
 
121
- - `fused_*.wgsl` - Multiple ops in one kernel (fused_ffn, fused_matmul_rmsnorm, etc.)
122
- - `*_f16.wgsl` - F16 weights/activations
123
- - `*_f16a.wgsl` - F16 activations with quantized weights (fused Q4K)
124
- - `*_f32.wgsl` - F32 weights/activations
125
- - `*_q4*.wgsl` - Q4_K quantized
126
- - `*_subgroup.wgsl` - Uses subgroup operations
127
- - `*_decode*.wgsl` - Optimized for M=1 decode
122
+ Kernel operation IDs, variant IDs, WGSL filenames, entry points, feature
123
+ requirements, bindings, uniforms, and metadata are defined in
124
+ `src/config/kernels/registry.json`.
125
+
126
+ Use `npm run kernels:registry:check` to audit the on-disk WGSL inventory
127
+ against the registry. This README must not define separate filename suffix
128
+ rules.
129
+
130
+ ## Supported Manifest Usage
131
+
132
+ Use `npm run kernels:supported-manifests:report` to cross-reference the kernel
133
+ registry against kernels pinned by supported local manifests. The default scope
134
+ is catalog entries marked runtime active, conversion ready, and verified/pass in
135
+ `models/catalog.json`.
136
+
137
+ The report includes kernels made live by capability-transform fallbacks declared
138
+ in `src/rules/inference/capability-transforms.rules.json`. Use `--manifest-only`
139
+ for the strict manifest-pinned view, or `--include-runtime-transform-variants`
140
+ when auditing runtime-requested lanes such as f16 activation profiles.
141
+
142
+ The report separates non-live registry entries into protected and candidate
143
+ sets:
144
+
145
+ - protected by `tools/policies/kernel-usage-allowlist.json` for non-text lanes
146
+ such as training, diffusion, MoE, generation options, and format utilities
147
+ - protected by registry reachability when conversion configs or rule maps can
148
+ still select the variant
149
+ - true unused candidates when neither live usage, allowlist policy, nor
150
+ registry reachability protects the variant
151
+
152
+ Use `--no-allowlist` to inspect the raw non-live registry set, and
153
+ `--fail-on-unused-candidates` to make the command exit non-zero when true
154
+ unused candidates are present.
155
+
156
+ The report is advisory for cleanup planning. It is not part of `npm run
157
+ kernels:check` because `models/local/**` is developer-local state, not a CI
158
+ contract surface. Use `--include-untested` when inspecting active/ready local
159
+ artifacts that are not verified yet.