doppler-gpu 0.2.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 (658) hide show
  1. package/CHANGELOG.md +182 -0
  2. package/README.md +20 -8
  3. package/assets/doppler.svg +1601 -0
  4. package/package.json +82 -33
  5. package/src/cli/cli-model-resolution.js +275 -0
  6. package/src/cli/cli-output.js +453 -0
  7. package/src/cli/doppler-cli.js +817 -709
  8. package/src/cli/doppler-quickstart.d.ts +7 -23
  9. package/src/cli/doppler-quickstart.js +20 -4
  10. package/src/cli/doppler-serve.js +1 -1
  11. package/src/cli/runtime-profiles.d.ts +40 -0
  12. package/src/cli/runtime-profiles.js +225 -0
  13. package/src/client/doppler-api.js +1 -6
  14. package/src/client/doppler-registry.d.ts +12 -0
  15. package/src/client/doppler-registry.js +27 -0
  16. package/src/client/doppler-registry.json +79 -5
  17. package/src/client/failure-taxonomy.js +139 -0
  18. package/src/client/fault-injection.js +30 -0
  19. package/src/client/provider.d.ts +151 -0
  20. package/src/client/provider.js +374 -0
  21. package/src/client/receipt.js +156 -0
  22. package/src/client/runtime/index.js +56 -4
  23. package/src/client/runtime/model-manager.d.ts +0 -14
  24. package/src/client/runtime/model-manager.js +2 -42
  25. package/src/client/runtime/model-session.js +33 -0
  26. package/src/client/runtime/model-source.d.ts +13 -1
  27. package/src/client/runtime/model-source.js +128 -2
  28. package/src/client/runtime/node-quickstart-cache.d.ts +22 -0
  29. package/src/client/runtime/node-quickstart-cache.js +353 -0
  30. package/src/client/runtime/source-runtime.js +1 -10
  31. package/src/client/runtime/types.d.ts +0 -60
  32. package/src/client/wrap-pipeline-handle.d.ts +20 -0
  33. package/src/client/wrap-pipeline-handle.js +84 -0
  34. package/src/config/README.md +3 -1
  35. package/src/config/conversion/README.md +23 -157
  36. package/src/config/conversion/embeddinggemma/google-embeddinggemma-300m-q4k-ehf16-af32.json +19 -4
  37. package/src/config/conversion/gemma3/gemma-3-1b-it-f16-af32.json +16 -9
  38. package/src/config/conversion/gemma3/gemma-3-1b-it-q4k-ehf16-af32.json +24 -9
  39. package/src/config/conversion/gemma3/gemma-3-270m-it-q4k-ehf16-af32.json +24 -9
  40. package/src/config/conversion/gemma3/translategemma-4b-1b-enes-q4k-ehf16-af32.json +16 -9
  41. package/src/config/conversion/gemma3/translategemma-4b-it-q4k-ehf16-af32.json +24 -9
  42. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af16.json +719 -0
  43. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af32.json +715 -0
  44. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af16-int4ple.json +589 -0
  45. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32-int4ple.json +566 -0
  46. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32.json +368 -62
  47. package/src/config/conversion/gemma4/gemma-4-moe-q4k-ehf16-af32.json +212 -55
  48. package/src/config/conversion/gpt-oss-20b-f16-xmxfp4.json +216 -57
  49. package/src/config/conversion/janus/janus-pro-1b-text-q4k-ehaf16.json +229 -57
  50. package/src/config/conversion/lfm2/lfm2.5-1.2b-instruct-q4k-ehf16-af32.json +17 -10
  51. package/src/config/conversion/qwen3/qwen-3-5-0-8b-q4k-ehaf16.json +75 -33
  52. package/src/config/conversion/qwen3/qwen-3-5-2b-q4k-ehaf16.json +91 -59
  53. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-eaf16.json +517 -0
  54. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-ehaf16.json +511 -0
  55. package/src/config/execution-contract-check.js +6 -5
  56. package/src/config/kernel-path-loader.d.ts +8 -2
  57. package/src/config/kernels/kernel-ref-digests.js +125 -122
  58. package/src/config/kernels/registry.d.ts +0 -35
  59. package/src/config/kernels/registry.js +5 -9
  60. package/src/config/kernels/registry.json +615 -368
  61. package/src/config/merge-helpers.d.ts +1 -1
  62. package/src/config/merge-helpers.js +1 -1
  63. package/src/config/merge.js +35 -7
  64. package/src/config/param-categories.d.ts +0 -9
  65. package/src/config/param-categories.js +1 -5
  66. package/src/config/param-validator.d.ts +2 -0
  67. package/src/config/param-validator.js +16 -0
  68. package/src/config/platforms/loader.d.ts +0 -27
  69. package/src/config/platforms/loader.js +0 -30
  70. package/src/config/required-inference-fields-contract-check.js +1 -7
  71. package/src/config/runtime/README.md +28 -0
  72. package/src/config/runtime/experiments/bench/gemma4-bench-q4k.json +32 -0
  73. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-batched.json +2 -2
  74. package/src/config/runtime/experiments/debug/gemma4-e2b-browser-diagnose-q4k.json +85 -0
  75. package/src/config/runtime/platform/metal-apple-q4k.json +19 -3
  76. package/src/config/runtime/profiles/gemma4-31b-f16-activations-probe.json +65 -0
  77. package/src/config/runtime/profiles/gemma4-e2b-baseline-probe.json +41 -0
  78. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-probe.json +44 -0
  79. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-test.json +19 -0
  80. package/src/config/runtime/profiles/gemma4-e2b-int4ple-baseline-probe.json +31 -0
  81. package/src/config/runtime/profiles/gemma4-e2b-int4ple-f16a-probe.json +34 -0
  82. package/src/config/runtime/profiles/gemma4-e2b-int4ple-reference-export.json +64 -0
  83. package/src/config/runtime/profiles/gemma4-e2b-int4ple-retain-q4k-probe.json +47 -0
  84. package/src/config/runtime/profiles/gemma4-e2b-prefill-profile.json +35 -0
  85. package/src/config/runtime/profiles/gemma4-e2b-throughput-probe.json +16 -0
  86. package/src/config/runtime/profiles/qwen-3-5-0-8b-prefill-profile.json +35 -0
  87. package/src/config/runtime/profiles/qwen-3-5-0-8b-throughput-probe.json +16 -0
  88. package/src/config/runtime/profiles/qwen3-6-27b-f16-activations-probe.json +62 -0
  89. package/src/config/schema/benchmark.schema.d.ts +2 -0
  90. package/src/config/schema/benchmark.schema.js +1 -0
  91. package/src/config/schema/bridge.schema.d.ts +16 -0
  92. package/src/config/schema/browser-suite-metrics.schema.d.ts +1 -0
  93. package/src/config/schema/browser-suite-metrics.schema.js +2 -0
  94. package/src/config/schema/converter.schema.d.ts +5 -0
  95. package/src/config/schema/converter.schema.js +3 -0
  96. package/src/config/schema/debug.schema.d.ts +22 -1
  97. package/src/config/schema/debug.schema.js +1 -0
  98. package/src/config/schema/distill-training.schema.d.ts +0 -1
  99. package/src/config/schema/distill-training.schema.js +1 -1
  100. package/src/config/schema/doppler.schema.d.ts +21 -3
  101. package/src/config/schema/doppler.schema.js +116 -9
  102. package/src/config/schema/emulation.schema.d.ts +3 -0
  103. package/src/config/schema/emulation.schema.js +16 -16
  104. package/src/config/schema/execution-v1.schema.d.ts +12 -1
  105. package/src/config/schema/execution-v1.schema.js +7 -1
  106. package/src/config/schema/index.d.ts +54 -1
  107. package/src/config/schema/index.js +15 -0
  108. package/src/config/schema/inference.schema.d.ts +3 -3
  109. package/src/config/schema/kernel-path.schema.d.ts +6 -27
  110. package/src/config/schema/kernel-thresholds.schema.d.ts +0 -2
  111. package/src/config/schema/kernel-thresholds.schema.js +3 -7
  112. package/src/config/schema/kvcache.schema.js +0 -9
  113. package/src/config/schema/loading.schema.d.ts +12 -0
  114. package/src/config/schema/loading.schema.js +4 -0
  115. package/src/config/schema/manifest.schema.d.ts +73 -1
  116. package/src/config/schema/manifest.schema.js +48 -2
  117. package/src/config/schema/moe.schema.js +0 -8
  118. package/src/config/schema/program-bundle.schema.d.ts +233 -0
  119. package/src/config/schema/program-bundle.schema.js +393 -0
  120. package/src/config/schema/ul-training.schema.d.ts +0 -1
  121. package/src/config/schema/ul-training.schema.js +1 -1
  122. package/src/config/source-packages/litert/gemma-4-e2b-it.json +36 -15
  123. package/src/config/supported-operations.d.ts +14 -0
  124. package/src/config/supported-operations.js +34 -0
  125. package/src/config/supported-operations.json +178 -0
  126. package/src/config/training-defaults.js +1 -7
  127. package/src/config/transforms/capability-transform-resolver.js +3 -1
  128. package/src/config/transforms/execution-graph-transforms.d.ts +55 -0
  129. package/src/config/transforms/execution-graph-transforms.js +693 -29
  130. package/src/converter/conversion-plan.js +13 -10
  131. package/src/converter/core.d.ts +57 -0
  132. package/src/converter/core.js +582 -13
  133. package/src/converter/parsers/diffusion.js +1 -33
  134. package/src/converter/quantization-info.d.ts +5 -4
  135. package/src/converter/quantization-info.js +39 -3
  136. package/src/converter/quantizer.d.ts +19 -0
  137. package/src/converter/quantizer.js +81 -4
  138. package/src/debug/config.d.ts +0 -4
  139. package/src/debug/config.js +0 -17
  140. package/src/debug/index.d.ts +28 -30
  141. package/src/debug/index.js +0 -18
  142. package/src/debug/stats.d.ts +0 -8
  143. package/src/debug/stats.js +3 -3
  144. package/src/debug/tensor.d.ts +9 -2
  145. package/src/debug/tensor.js +11 -4
  146. package/src/debug/trace.js +2 -15
  147. package/src/errors/doppler-error.js +20 -0
  148. package/src/experimental/browser/quantization.d.ts +5 -0
  149. package/src/experimental/distribution/shard-delivery.js +179 -23
  150. package/src/experimental/training/artifacts.js +1 -14
  151. package/src/experimental/training/checkpoint.js +1 -14
  152. package/src/experimental/training/datasets/token-batch.d.ts +1 -1
  153. package/src/experimental/training/datasets/token-batch.js +2 -2
  154. package/src/experimental/training/distillation/dataset.js +2 -15
  155. package/src/experimental/training/distillation/eval.js +3 -3
  156. package/src/experimental/training/distillation/runtime.js +3 -16
  157. package/src/experimental/training/distillation/student-fixture.js +6 -6
  158. package/src/experimental/training/lora-pipeline.js +1 -14
  159. package/src/experimental/training/objectives/base.d.ts +2 -2
  160. package/src/experimental/training/objectives/cross_entropy.d.ts +2 -2
  161. package/src/experimental/training/objectives/distill_kd.d.ts +2 -2
  162. package/src/experimental/training/objectives/distill_kd.js +2 -2
  163. package/src/experimental/training/objectives/distill_triplet.d.ts +2 -2
  164. package/src/experimental/training/objectives/distill_triplet.js +2 -2
  165. package/src/experimental/training/objectives/ul_stage1_joint.d.ts +2 -2
  166. package/src/experimental/training/objectives/ul_stage2_base.d.ts +2 -2
  167. package/src/experimental/training/objectives/ul_stage2_base.js +1 -1
  168. package/src/experimental/training/operator-artifacts.js +1 -14
  169. package/src/experimental/training/runner.js +1 -14
  170. package/src/experimental/training/workload-packs/registry.json +6 -6
  171. package/src/experimental/training/workloads.js +1 -1
  172. package/src/formats/gguf/types.d.ts +0 -63
  173. package/src/formats/gguf/types.js +58 -38
  174. package/src/formats/litert/types.d.ts +0 -13
  175. package/src/formats/litert/types.js +2 -2
  176. package/src/formats/rdrr/distributed/index.d.ts +34 -0
  177. package/src/formats/rdrr/distributed/index.js +3 -0
  178. package/src/formats/rdrr/distributed/parsing.d.ts +6 -0
  179. package/src/formats/rdrr/distributed/parsing.js +23 -0
  180. package/src/formats/rdrr/distributed/validation.d.ts +23 -0
  181. package/src/formats/rdrr/distributed/validation.js +131 -0
  182. package/src/formats/rdrr/groups.d.ts +1 -13
  183. package/src/formats/rdrr/groups.js +0 -34
  184. package/src/formats/rdrr/index.d.ts +9 -0
  185. package/src/formats/rdrr/index.js +9 -0
  186. package/src/formats/rdrr/integrity.d.ts +51 -0
  187. package/src/formats/rdrr/integrity.js +200 -0
  188. package/src/formats/rdrr/lowerings.d.ts +28 -0
  189. package/src/formats/rdrr/lowerings.js +112 -0
  190. package/src/formats/rdrr/manifest.d.ts +0 -14
  191. package/src/formats/rdrr/manifest.js +5 -58
  192. package/src/formats/rdrr/merkle.d.ts +24 -0
  193. package/src/formats/rdrr/merkle.js +118 -0
  194. package/src/formats/rdrr/parsing.js +4 -0
  195. package/src/formats/rdrr/slice-compiler.d.ts +29 -0
  196. package/src/formats/rdrr/slice-compiler.js +188 -0
  197. package/src/formats/rdrr/source-transform-contract.js +390 -0
  198. package/src/formats/rdrr/storage-descriptor.d.ts +36 -0
  199. package/src/formats/rdrr/storage-descriptor.js +186 -0
  200. package/src/formats/rdrr/tensor-config-validator.d.ts +0 -9
  201. package/src/formats/rdrr/tensor-config-validator.js +0 -30
  202. package/src/formats/rdrr/types.d.ts +115 -1
  203. package/src/formats/rdrr/validation.js +245 -0
  204. package/src/formats/tflite/types.d.ts +8 -31
  205. package/src/formats/tflite/types.js +50 -5
  206. package/src/gpu/command-recorder.d.ts +9 -21
  207. package/src/gpu/command-recorder.js +41 -2
  208. package/src/gpu/device.d.ts +17 -3
  209. package/src/gpu/device.js +20 -4
  210. package/src/gpu/kernel-runtime.d.ts +8 -15
  211. package/src/gpu/kernel-selection-log.d.ts +0 -8
  212. package/src/gpu/kernel-selection-log.js +0 -15
  213. package/src/gpu/kernel-tuner/cache.js +0 -3
  214. package/src/gpu/kernels/README.md +50 -18
  215. package/src/gpu/kernels/activation-static-qdq.d.ts +22 -0
  216. package/src/gpu/kernels/activation-static-qdq.js +69 -0
  217. package/src/gpu/kernels/activation_static_qdq.wgsl +25 -0
  218. package/src/gpu/kernels/attention.d.ts +28 -19
  219. package/src/gpu/kernels/attention.js +443 -9
  220. package/src/gpu/kernels/attention_decode_contiguous_turboquant_f16kv.wgsl +0 -1
  221. package/src/gpu/kernels/attention_decode_contiguous_turboquant_prod_f16kv.wgsl +0 -1
  222. package/src/gpu/kernels/attention_decode_f16.wgsl +1 -1
  223. package/src/gpu/kernels/attention_decode_f16kv.wgsl +1 -1
  224. package/src/gpu/kernels/attention_decode_online_f16.wgsl +32 -29
  225. package/src/gpu/kernels/attention_decode_online_f16kv.wgsl +1 -1
  226. package/src/gpu/kernels/attention_decode_paged_f16kv.wgsl +1 -1
  227. package/src/gpu/kernels/attention_decode_tiered_f16kv.wgsl +1 -1
  228. package/src/gpu/kernels/attention_decode_tiered_turboquant_f16kv.wgsl +0 -1
  229. package/src/gpu/kernels/attention_decode_tiered_turboquant_prod_f16kv.wgsl +0 -1
  230. package/src/gpu/kernels/attention_f16.wgsl +88 -30
  231. package/src/gpu/kernels/attention_f16kv.wgsl +45 -15
  232. package/src/gpu/kernels/attention_head512_f16.wgsl +270 -0
  233. package/src/gpu/kernels/attention_head512_f16kv.wgsl +271 -0
  234. package/src/gpu/kernels/attention_prefill_flash_head256_f16kv.wgsl +306 -0
  235. package/src/gpu/kernels/attention_prefill_flash_reduce.wgsl +101 -0
  236. package/src/gpu/kernels/attention_small_f16.wgsl +22 -20
  237. package/src/gpu/kernels/attention_small_f16kv.wgsl +1 -1
  238. package/src/gpu/kernels/attention_streaming_f16.wgsl +39 -16
  239. package/src/gpu/kernels/attention_streaming_f16kv.wgsl +22 -3
  240. package/src/gpu/kernels/backward/index.d.ts +6 -0
  241. package/src/gpu/kernels/backward/layernorm_backward.wgsl +0 -1
  242. package/src/gpu/kernels/backward/utils.d.ts +35 -0
  243. package/src/gpu/kernels/bf16_to_f32.wgsl +0 -16
  244. package/src/gpu/kernels/bias_add_f16.wgsl +1 -1
  245. package/src/gpu/kernels/cast_f32_to_f16.wgsl +0 -1
  246. package/src/gpu/kernels/codegen/patches/attention_f16.from.attention.diff +19 -215
  247. package/src/gpu/kernels/codegen/patches/attention_f16kv.from.attention.diff +8 -82
  248. package/src/gpu/kernels/codegen/patches/attention_small_f16.from.attention_small.diff +92 -59
  249. package/src/gpu/kernels/codegen/patches/attention_streaming_f16.from.attention_streaming.diff +2 -85
  250. package/src/gpu/kernels/codegen/patches/gelu_f16.from.gelu.diff +27 -24
  251. package/src/gpu/kernels/codegen/patches/residual_f16.from.residual.diff +1 -1
  252. package/src/gpu/kernels/codegen/patches/rmsnorm_f16.from.rmsnorm.diff +249 -179
  253. package/src/gpu/kernels/codegen/patches/rope_f16.from.rope.diff +133 -235
  254. package/src/gpu/kernels/codegen/patches/sample_f16.from.sample.diff +119 -90
  255. package/src/gpu/kernels/codegen/wgsl-variants.js +142 -8
  256. package/src/gpu/kernels/constants.d.ts +9 -48
  257. package/src/gpu/kernels/constants.js +0 -23
  258. package/src/gpu/kernels/conv2d.d.ts +0 -4
  259. package/src/gpu/kernels/conv2d_f16.wgsl +1 -1
  260. package/src/gpu/kernels/dequant.d.ts +0 -16
  261. package/src/gpu/kernels/dequant.js +1 -71
  262. package/src/gpu/kernels/dequant_mxfp4_expert_f16.wgsl +1 -1
  263. package/src/gpu/kernels/dequant_shared.wgsl +1 -55
  264. package/src/gpu/kernels/dispatch.d.ts +12 -97
  265. package/src/gpu/kernels/dispatch.js +0 -117
  266. package/src/gpu/kernels/energy_eval_f16.wgsl +1 -1
  267. package/src/gpu/kernels/energy_quintel_grad_f16.wgsl +1 -1
  268. package/src/gpu/kernels/energy_quintel_reduce_f16.wgsl +1 -1
  269. package/src/gpu/kernels/energy_quintel_update_f16.wgsl +1 -1
  270. package/src/gpu/kernels/energy_update_f16.wgsl +1 -1
  271. package/src/gpu/kernels/fused-gate-up-gelu.js +121 -0
  272. package/src/gpu/kernels/fused_ffn_f16.wgsl +1 -1
  273. package/src/gpu/kernels/fused_ffn_q4k.wgsl +0 -19
  274. package/src/gpu/kernels/fused_ffn_q4k_f16.wgsl +0 -18
  275. package/src/gpu/kernels/fused_gate_up_gelu_gated_f16.wgsl +124 -0
  276. package/src/gpu/kernels/fused_matmul_q4.wgsl +23 -439
  277. package/src/gpu/kernels/fused_matmul_q4_batched_f16.wgsl +1 -1
  278. package/src/gpu/kernels/fused_matmul_q4_batched_f16a.wgsl +0 -1
  279. package/src/gpu/kernels/fused_matmul_q4_batched_f16acc_f16a.wgsl +158 -0
  280. package/src/gpu/kernels/fused_matmul_q4_f16a.wgsl +0 -1
  281. package/src/gpu/kernels/fused_matmul_q4_multicol_f16.wgsl +0 -1
  282. package/src/gpu/kernels/fused_matmul_q4_multicol_f16a.wgsl +32 -33
  283. package/src/gpu/kernels/fused_matmul_q4_multicol_f16a_f32acc.wgsl +209 -0
  284. package/src/gpu/kernels/fused_matmul_q4_prefill_tiled_f16.wgsl +261 -0
  285. package/src/gpu/kernels/fused_matmul_q4_widetile.wgsl +164 -0
  286. package/src/gpu/kernels/fused_matmul_q4_widetile_f16.wgsl +198 -0
  287. package/src/gpu/kernels/fused_matmul_q4_widetile_f16a.wgsl +161 -0
  288. package/src/gpu/kernels/fused_matmul_q4_widetile_residual.wgsl +173 -0
  289. package/src/gpu/kernels/fused_matmul_rmsnorm_f16.wgsl +1 -1
  290. package/src/gpu/kernels/fused_rmsnorm_q4_widetile.wgsl +271 -0
  291. package/src/gpu/kernels/fused_swiglu_f16.wgsl +1 -1
  292. package/src/gpu/kernels/gather.d.ts +0 -7
  293. package/src/gpu/kernels/gather_f16.wgsl +1 -1
  294. package/src/gpu/kernels/gelu_f16.wgsl +14 -15
  295. package/src/gpu/kernels/groupnorm.d.ts +0 -4
  296. package/src/gpu/kernels/groupnorm_apply_f16.wgsl +1 -1
  297. package/src/gpu/kernels/groupnorm_stats_f16.wgsl +1 -1
  298. package/src/gpu/kernels/index.d.ts +13 -5
  299. package/src/gpu/kernels/index.js +9 -4
  300. package/src/gpu/kernels/kv_quantize_turboquant.wgsl +0 -2
  301. package/src/gpu/kernels/kv_quantize_turboquant_prod.wgsl +0 -2
  302. package/src/gpu/kernels/layernorm.d.ts +0 -4
  303. package/src/gpu/kernels/layernorm_f16.wgsl +1 -1
  304. package/src/gpu/kernels/{sana_linear_attention.d.ts → linear_attention.d.ts} +5 -5
  305. package/src/gpu/kernels/{sana_linear_attention.js → linear_attention.js} +16 -16
  306. package/src/gpu/kernels/logit-merge.d.ts +0 -24
  307. package/src/gpu/kernels/logit-merge.js +1 -17
  308. package/src/gpu/kernels/matmul-dispatch.js +7 -1
  309. package/src/gpu/kernels/matmul-selection.js +68 -1
  310. package/src/gpu/kernels/matmul.d.ts +0 -28
  311. package/src/gpu/kernels/matmul.js +101 -7
  312. package/src/gpu/kernels/matmul_f16_tiled.wgsl +33 -34
  313. package/src/gpu/kernels/matmul_gemv_residual_f16.wgsl +1 -1
  314. package/src/gpu/kernels/matmul_gemv_subgroup.wgsl +0 -1
  315. package/src/gpu/kernels/matmul_gemv_subgroup_f16a.wgsl +24 -25
  316. package/src/gpu/kernels/modulate_f16.wgsl +1 -1
  317. package/src/gpu/kernels/moe.d.ts +0 -56
  318. package/src/gpu/kernels/moe.js +0 -15
  319. package/src/gpu/kernels/moe_gather_f16.wgsl +1 -1
  320. package/src/gpu/kernels/pixel_shuffle_f16.wgsl +1 -1
  321. package/src/gpu/kernels/residual.d.ts +0 -12
  322. package/src/gpu/kernels/residual_f16.wgsl +2 -2
  323. package/src/gpu/kernels/residual_f16_vec4.wgsl +5 -5
  324. package/src/gpu/kernels/rmsnorm.d.ts +0 -8
  325. package/src/gpu/kernels/rmsnorm.js +17 -1
  326. package/src/gpu/kernels/rmsnorm.wgsl +5 -6
  327. package/src/gpu/kernels/rmsnorm_f16.wgsl +65 -39
  328. package/src/gpu/kernels/rope.d.ts +1 -5
  329. package/src/gpu/kernels/rope.js +12 -2
  330. package/src/gpu/kernels/rope.wgsl +33 -19
  331. package/src/gpu/kernels/rope_f16.wgsl +39 -25
  332. package/src/gpu/kernels/sample.d.ts +0 -5
  333. package/src/gpu/kernels/sample.wgsl +7 -6
  334. package/src/gpu/kernels/sample_f16.wgsl +28 -30
  335. package/src/gpu/kernels/scatter_add_dynamic_f16.wgsl +1 -1
  336. package/src/gpu/kernels/shader-cache.d.ts +13 -0
  337. package/src/gpu/kernels/shader-cache.js +27 -0
  338. package/src/gpu/kernels/silu_f16.wgsl +1 -1
  339. package/src/gpu/kernels/softmax.wgsl +4 -144
  340. package/src/gpu/kernels/split_qg_f16.wgsl +1 -1
  341. package/src/gpu/kernels/split_qkv_f16.wgsl +1 -1
  342. package/src/gpu/kernels/topk_f16.wgsl +1 -1
  343. package/src/gpu/kernels/turboquant-codebook.js +11 -40
  344. package/src/gpu/kernels/uniform-utils.d.ts +18 -0
  345. package/src/gpu/kernels/upsample2d.d.ts +0 -4
  346. package/src/gpu/kernels/upsample2d_f16.wgsl +1 -1
  347. package/src/gpu/kernels/utils.d.ts +28 -0
  348. package/src/gpu/kernels/utils.js +41 -0
  349. package/src/gpu/perf-guards.d.ts +0 -12
  350. package/src/gpu/perf-guards.js +0 -62
  351. package/src/gpu/profiler.d.ts +0 -21
  352. package/src/gpu/profiler.js +0 -34
  353. package/src/gpu/submit-tracker.d.ts +0 -57
  354. package/src/gpu/submit-tracker.js +3 -62
  355. package/src/gpu/tensor.d.ts +0 -23
  356. package/src/gpu/tensor.js +0 -41
  357. package/src/gpu/uniform-cache.d.ts +0 -11
  358. package/src/gpu/uniform-cache.js +0 -23
  359. package/src/index.d.ts +1 -0
  360. package/src/index.js +1 -0
  361. package/src/inference/browser-harness-model-helpers.d.ts +0 -9
  362. package/src/inference/browser-harness-model-helpers.js +22 -13
  363. package/src/inference/browser-harness-runtime-helpers.d.ts +0 -5
  364. package/src/inference/browser-harness-runtime-helpers.js +2 -2
  365. package/src/inference/browser-harness-suite-helpers.d.ts +4 -1
  366. package/src/inference/browser-harness-suite-helpers.js +87 -1
  367. package/src/inference/browser-harness-text-helpers.d.ts +13 -0
  368. package/src/inference/browser-harness-text-helpers.js +267 -18
  369. package/src/inference/browser-harness.d.ts +0 -29
  370. package/src/inference/browser-harness.js +271 -71
  371. package/src/inference/kv-cache/base.d.ts +6 -0
  372. package/src/inference/kv-cache/base.js +16 -1
  373. package/src/inference/kv-cache/mixed-geometry.d.ts +1 -0
  374. package/src/inference/kv-cache/mixed-geometry.js +12 -2
  375. package/src/inference/kv-cache/quantized.js +2 -0
  376. package/src/inference/kv-cache/tiered.js +7 -0
  377. package/src/inference/kv-cache/types.d.ts +2 -0
  378. package/src/inference/multi-model-network.d.ts +1 -1
  379. package/src/inference/multi-model-network.js +1 -2
  380. package/src/inference/network-evolution.d.ts +0 -12
  381. package/src/inference/network-evolution.js +2 -2
  382. package/src/inference/pipelines/context.js +21 -2
  383. package/src/inference/pipelines/diffusion/init.js +2 -2
  384. package/src/inference/pipelines/diffusion/pipeline.js +41 -96
  385. package/src/inference/pipelines/diffusion/text-encoder-gpu.d.ts +0 -5
  386. package/src/inference/pipelines/diffusion/text-encoder-gpu.js +0 -283
  387. package/src/inference/pipelines/diffusion/vae.js +4 -4
  388. package/src/inference/pipelines/energy/quintel.d.ts +15 -0
  389. package/src/inference/pipelines/structured/index.d.ts +2 -0
  390. package/src/inference/pipelines/structured/index.js +2 -0
  391. package/src/inference/pipelines/structured/json-grammar-mask.js +143 -0
  392. package/src/inference/pipelines/structured/tsv-grammar-mask.js +166 -0
  393. package/src/inference/pipelines/text/attention/attn-config.d.ts +0 -5
  394. package/src/inference/pipelines/text/attention/attn-config.js +1 -1
  395. package/src/inference/pipelines/text/attention/projections.d.ts +2 -0
  396. package/src/inference/pipelines/text/attention/projections.js +70 -23
  397. package/src/inference/pipelines/text/attention/record.js +118 -5
  398. package/src/inference/pipelines/text/attention/rmsnorm-fusion-gate.d.ts +8 -0
  399. package/src/inference/pipelines/text/attention/rmsnorm-fusion-gate.js +19 -0
  400. package/src/inference/pipelines/text/attention/run.js +97 -6
  401. package/src/inference/pipelines/text/attention/types.d.ts +2 -0
  402. package/src/inference/pipelines/text/attention/types.js +9 -4
  403. package/src/inference/pipelines/text/chat-format.d.ts +0 -10
  404. package/src/inference/pipelines/text/chat-format.js +1 -8
  405. package/src/inference/pipelines/text/config.d.ts +3 -25
  406. package/src/inference/pipelines/text/config.js +105 -3
  407. package/src/inference/pipelines/text/debug-utils/utils.js +2 -23
  408. package/src/inference/pipelines/text/drift-policy.js +1 -1
  409. package/src/inference/pipelines/text/embed.d.ts +23 -27
  410. package/src/inference/pipelines/text/embed.js +10 -43
  411. package/src/inference/pipelines/text/execution-plan.d.ts +5 -3
  412. package/src/inference/pipelines/text/execution-plan.js +15 -2
  413. package/src/inference/pipelines/text/execution-runtime-builders.d.ts +0 -4
  414. package/src/inference/pipelines/text/execution-runtime-builders.js +0 -11
  415. package/src/inference/pipelines/text/execution-v1.d.ts +18 -0
  416. package/src/inference/pipelines/text/execution-v1.js +94 -25
  417. package/src/inference/pipelines/text/ffn/dense.js +180 -3
  418. package/src/inference/pipelines/text/ffn/standard.js +40 -13
  419. package/src/inference/pipelines/text/generator-decode-policy.js +243 -0
  420. package/src/inference/pipelines/text/generator-helpers.d.ts +6 -2
  421. package/src/inference/pipelines/text/generator-helpers.js +20 -2
  422. package/src/inference/pipelines/text/generator-prefill-helpers.js +293 -0
  423. package/src/inference/pipelines/text/generator-runtime.d.ts +0 -7
  424. package/src/inference/pipelines/text/generator-runtime.js +8 -6
  425. package/src/inference/pipelines/text/generator-steps.d.ts +22 -7
  426. package/src/inference/pipelines/text/generator-steps.js +23 -9
  427. package/src/inference/pipelines/text/generator.d.ts +0 -6
  428. package/src/inference/pipelines/text/generator.js +254 -530
  429. package/src/inference/pipelines/text/init-chat-templates.js +86 -0
  430. package/src/inference/pipelines/text/init-qkv-fusion.js +201 -0
  431. package/src/inference/pipelines/text/init-rope.js +408 -0
  432. package/src/inference/pipelines/text/init.d.ts +8 -2
  433. package/src/inference/pipelines/text/init.js +190 -710
  434. package/src/inference/pipelines/text/kernel-trace.d.ts +0 -33
  435. package/src/inference/pipelines/text/kernel-trace.js +0 -33
  436. package/src/inference/pipelines/text/layer-plan-gpu.js +542 -0
  437. package/src/inference/pipelines/text/layer-plan.d.ts +0 -5
  438. package/src/inference/pipelines/text/layer-plan.js +1 -1
  439. package/src/inference/pipelines/text/layer.d.ts +70 -8
  440. package/src/inference/pipelines/text/layer.js +105 -537
  441. package/src/inference/pipelines/text/linear-attention.d.ts +2 -1
  442. package/src/inference/pipelines/text/load-errors.d.ts +21 -0
  443. package/src/inference/pipelines/text/load-errors.js +59 -0
  444. package/src/inference/pipelines/text/logits/cpu.js +2 -20
  445. package/src/inference/pipelines/text/logits/gpu.d.ts +5 -4
  446. package/src/inference/pipelines/text/logits/gpu.js +148 -11
  447. package/src/inference/pipelines/text/logits/index.d.ts +1 -1
  448. package/src/inference/pipelines/text/model-load.d.ts +5 -4
  449. package/src/inference/pipelines/text/model-load.js +74 -17
  450. package/src/inference/pipelines/text/ops.d.ts +13 -2
  451. package/src/inference/pipelines/text/ops.js +1 -1
  452. package/src/inference/pipelines/text/per-layer-inputs.js +347 -59
  453. package/src/inference/pipelines/text/probes.d.ts +3 -6
  454. package/src/inference/pipelines/text/probes.js +198 -31
  455. package/src/inference/pipelines/text/sampling.d.ts +0 -5
  456. package/src/inference/pipelines/text/sampling.js +140 -0
  457. package/src/inference/pipelines/text/stage-names.js +12 -0
  458. package/src/inference/pipelines/text/state.js +2 -0
  459. package/src/inference/pipelines/text/tsir-fixture-writer.js +409 -0
  460. package/src/inference/pipelines/text/types.d.ts +8 -78
  461. package/src/inference/pipelines/text/weights.d.ts +0 -50
  462. package/src/inference/pipelines/text/weights.js +2 -51
  463. package/src/inference/pipelines/text.d.ts +9 -1
  464. package/src/inference/pipelines/text.js +233 -29
  465. package/src/inference/pipelines/vision/index.js +0 -107
  466. package/src/inference/runtime-model.d.ts +0 -7
  467. package/src/inference/runtime-model.js +0 -23
  468. package/src/inference/test-harness.d.ts +6 -22
  469. package/src/inference/test-harness.js +97 -23
  470. package/src/inference/tokenizer.js +1 -10
  471. package/src/inference/tokenizers/sentencepiece.js +65 -15
  472. package/src/inference/tokenizers/types.d.ts +0 -21
  473. package/src/loader/doppler-loader.d.ts +3 -0
  474. package/src/loader/doppler-loader.js +90 -12
  475. package/src/loader/embedding-loader.js +30 -5
  476. package/src/loader/loader-types.d.ts +4 -0
  477. package/src/loader/manifest-config.d.ts +2 -7
  478. package/src/loader/manifest-config.js +25 -1
  479. package/src/loader/memory-monitor.d.ts +17 -5
  480. package/src/loader/per-layer-input-loader.js +114 -1
  481. package/src/loader/quantization-constants.d.ts +6 -0
  482. package/src/loader/shard-resolver.d.ts +1 -0
  483. package/src/loader/shard-resolver.js +15 -0
  484. package/src/loader/tensors/source-transform.d.ts +15 -0
  485. package/src/loader/tensors/source-transform.js +317 -34
  486. package/src/loader/tensors/tensor-loader.d.ts +2 -9
  487. package/src/loader/tensors/tensor-loader.js +84 -1
  488. package/src/loader/tensors/tensor-reader.js +28 -2
  489. package/src/memory/address-table.d.ts +1 -9
  490. package/src/memory/buffer-pool.d.ts +0 -16
  491. package/src/memory/buffer-pool.js +1 -33
  492. package/src/memory/heap-manager.d.ts +18 -43
  493. package/src/memory/unified-detect.d.ts +19 -34
  494. package/src/models/embeddinggemma.d.ts +7 -0
  495. package/src/models/embeddinggemma.js +24 -0
  496. package/src/models/family.d.ts +24 -0
  497. package/src/models/family.js +25 -0
  498. package/src/models/gemma3.d.ts +7 -0
  499. package/src/models/gemma3.js +33 -0
  500. package/src/models/gemma4.d.ts +7 -0
  501. package/src/models/gemma4.js +33 -0
  502. package/src/models/qwen3.d.ts +7 -0
  503. package/src/models/qwen3.js +36 -0
  504. package/src/rules/converter/tokenizer.rules.json +5 -0
  505. package/src/rules/execution-rules-contract-check.js +72 -3
  506. package/src/rules/inference/capability-transforms.rules.json +87 -0
  507. package/src/rules/inference/execution.rules.json +11 -1
  508. package/src/rules/inference/ffn.rules.json +6 -2
  509. package/src/rules/loader/tensor-loader.rules.json +9 -0
  510. package/src/rules/rule-registry.js +53 -75
  511. package/src/storage/artifact-storage-context.d.ts +12 -3
  512. package/src/storage/artifact-storage-context.js +389 -98
  513. package/src/storage/backends/opfs-store.js +138 -88
  514. package/src/storage/blake3.js +9 -1
  515. package/src/storage/export.js +1 -5
  516. package/src/storage/normalize-model-id.js +3 -0
  517. package/src/storage/preflight.js +22 -0
  518. package/src/storage/quickstart-downloader.js +44 -56
  519. package/src/storage/reports.js +35 -11
  520. package/src/storage/shard-manager.d.ts +8 -2
  521. package/src/storage/shard-manager.js +176 -15
  522. package/src/storage/source-artifact-store.d.ts +0 -2
  523. package/src/storage/source-artifact-store.js +3 -9
  524. package/src/sw.js +0 -3
  525. package/src/tooling/browser-command-runner.js +39 -0
  526. package/src/tooling/command-api-constants.js +1 -1
  527. package/src/tooling/command-api-family-normalizers.d.ts +1 -0
  528. package/src/tooling/command-api-family-normalizers.js +49 -7
  529. package/src/tooling/command-api-helpers.d.ts +0 -2
  530. package/src/tooling/command-api-helpers.js +6 -2
  531. package/src/tooling/command-api.d.ts +20 -1
  532. package/src/tooling/command-api.js +10 -1
  533. package/src/tooling/command-envelope.d.ts +0 -1
  534. package/src/tooling/command-envelope.js +1 -1
  535. package/src/tooling/command-runner-shared.d.ts +10 -0
  536. package/src/tooling/conversion-config-materializer.d.ts +0 -10
  537. package/src/tooling/conversion-config-materializer.js +1 -1
  538. package/src/tooling/diagnose-runner.js +1 -4
  539. package/src/tooling/hf-registry-utils.d.ts +2 -6
  540. package/src/tooling/hf-registry-utils.js +90 -19
  541. package/src/tooling/kernel-path-builder/index.js +1 -4
  542. package/src/tooling/kernel-path-builder/runtime-overlay.js +1 -3
  543. package/src/tooling/lean-execution-contract-runner.d.ts +0 -10
  544. package/src/tooling/lean-execution-contract-runner.js +2 -2
  545. package/src/tooling/litert-package-runtime.d.ts +1 -1
  546. package/src/tooling/litert-package-runtime.js +373 -21
  547. package/src/tooling/node-browser-command-runner.d.ts +15 -0
  548. package/src/tooling/node-browser-command-runner.js +97 -13
  549. package/src/tooling/node-command-runner.js +36 -0
  550. package/src/tooling/node-convert-worker-pool.js +12 -0
  551. package/src/tooling/node-convert-worker.js +10 -1
  552. package/src/tooling/node-converter.js +90 -1
  553. package/src/tooling/node-source-runtime.js +257 -150
  554. package/src/tooling/opfs-cache.js +1 -4
  555. package/src/tooling/precision-replay-math.js +174 -0
  556. package/src/tooling/program-bundle-host.d.ts +16 -0
  557. package/src/tooling/program-bundle-host.js +20 -0
  558. package/src/tooling/program-bundle-parity.d.ts +28 -0
  559. package/src/tooling/program-bundle-parity.js +210 -0
  560. package/src/tooling/program-bundle.d.ts +61 -0
  561. package/src/tooling/program-bundle.js +1119 -0
  562. package/src/tooling/rdrr-integrity-refresh.d.ts +32 -0
  563. package/src/tooling/rdrr-integrity-refresh.js +271 -0
  564. package/src/tooling/reference-verify.js +191 -0
  565. package/src/tooling/source-artifact-adapter.d.ts +0 -20
  566. package/src/tooling/source-artifact-adapter.js +4 -4
  567. package/src/tooling/source-package-profiles.js +1 -7
  568. package/src/tooling/source-runtime-bundle.d.ts +27 -0
  569. package/src/tooling/source-runtime-bundle.js +56 -23
  570. package/src/tooling/source-runtime-converter-config.d.ts +0 -5
  571. package/src/tooling/source-runtime-converter-config.js +13 -9
  572. package/src/tooling/source-runtime-materializer.js +4 -8
  573. package/src/tooling-exports/device.d.ts +11 -0
  574. package/src/tooling-exports/device.js +14 -0
  575. package/src/tooling-exports/manifest.d.ts +8 -0
  576. package/src/tooling-exports/manifest.js +11 -0
  577. package/src/tooling-exports/storage.d.ts +25 -0
  578. package/src/tooling-exports/storage.js +29 -0
  579. package/src/tooling-exports/structured.d.ts +1 -0
  580. package/src/tooling-exports/structured.js +5 -0
  581. package/src/tooling-exports.d.ts +23 -0
  582. package/src/tooling-exports.js +17 -0
  583. package/src/tooling-exports.shared.d.ts +27 -30
  584. package/src/tooling-exports.shared.js +28 -29
  585. package/src/types/index.d.ts +0 -3
  586. package/src/types/index.js +0 -3
  587. package/src/utils/array-buffer.d.ts +4 -0
  588. package/src/utils/array-buffer.js +9 -0
  589. package/src/utils/canonical-hash.d.ts +7 -0
  590. package/src/utils/canonical-hash.js +74 -0
  591. package/src/utils/clone-json.d.ts +1 -0
  592. package/src/utils/clone-json.js +7 -0
  593. package/src/utils/encode-utf8.js +5 -0
  594. package/src/utils/index.d.ts +4 -1
  595. package/src/utils/index.js +4 -1
  596. package/src/utils/runtime-env.js +7 -0
  597. package/src/utils/sha256.d.ts +1 -0
  598. package/src/utils/sha256.js +18 -4
  599. package/src/utils/stable-sort-object.d.ts +1 -0
  600. package/src/utils/stable-sort-object.js +13 -0
  601. package/src/version.js +1 -1
  602. package/tools/convert-safetensors-node.js +1 -2
  603. package/src/bootstrap.d.ts +0 -1
  604. package/src/config/conversion/sana/sana-sprint-0.6b-f16.json +0 -247
  605. package/src/config/kernels/kernel-ref.d.ts +0 -17
  606. package/src/config/kernels/kernel-ref.js +0 -75
  607. package/src/config/runtime/kernels/dequant-f16-q4k.json +0 -13
  608. package/src/config/runtime/kernels/dequant-f32-q4k.json +0 -13
  609. package/src/config/runtime/kernels/embeddinggemma-q4k-dequant-f32a.json +0 -37
  610. package/src/config/runtime/kernels/fused-q4k.json +0 -13
  611. package/src/config/runtime/kernels/gemma2-q4k-dequant-f16a.json +0 -33
  612. package/src/config/runtime/kernels/gemma2-q4k-dequant-f32a-nosubgroups.json +0 -33
  613. package/src/config/runtime/kernels/gemma2-q4k-fused-f32a.json +0 -33
  614. package/src/config/runtime/kernels/safe-q4k.json +0 -13
  615. package/src/config/runtime/overlays/debug-f32a.json +0 -3
  616. package/src/config/runtime/overlays/trace-config.json +0 -28
  617. package/src/config/runtime/profiles/gemma4-e2b-throughput.json +0 -39
  618. package/src/debug/perf.d.ts +0 -33
  619. package/src/debug/perf.js +0 -51
  620. package/src/errors/index.d.ts +0 -1
  621. package/src/errors/index.js +0 -1
  622. package/src/formats/gguf/index.d.ts +0 -8
  623. package/src/formats/gguf/index.js +0 -4
  624. package/src/formats/litert/index.d.ts +0 -1
  625. package/src/formats/litert/index.js +0 -1
  626. package/src/formats/safetensors/index.d.ts +0 -8
  627. package/src/formats/safetensors/index.js +0 -4
  628. package/src/formats/tflite/index.d.ts +0 -1
  629. package/src/formats/tflite/index.js +0 -1
  630. package/src/gpu/kernels/attention_decode_optimized.wgsl +0 -445
  631. package/src/gpu/kernels/dequant_mxfp4_vec4.wgsl +0 -116
  632. package/src/gpu/kernels/dequant_q8_0.wgsl +0 -98
  633. package/src/gpu/kernels/dequant_shared_vec4.wgsl +0 -160
  634. package/src/gpu/kernels/moe_gather_vec4.wgsl +0 -74
  635. package/src/inference/functiongemma.d.ts +0 -15
  636. package/src/inference/functiongemma.js +0 -1
  637. package/src/inference/pipelines/diffusion/sana-transformer.d.ts +0 -53
  638. package/src/inference/pipelines/diffusion/sana-transformer.js +0 -738
  639. package/src/rules/kernels/kernel-validator.d.ts +0 -24
  640. package/src/rules/kernels/kernel-validator.js +0 -160
  641. package/src/sw.d.ts +0 -1
  642. package/src/tooling/bench-runner.js +0 -64
  643. package/src/tooling/distill-runner.js +0 -56
  644. package/src/tooling/lora-runner.js +0 -37
  645. package/src/tooling/verify-runner.js +0 -63
  646. package/src/types/gpu.d.ts +0 -185
  647. package/src/types/gpu.js +0 -5
  648. package/src/types/inference.d.ts +0 -197
  649. package/src/types/inference.js +0 -5
  650. package/src/types/model.d.ts +0 -130
  651. package/src/types/model.js +0 -5
  652. package/src/utils/format-bytes.js +0 -20
  653. /package/src/config/{runtime/diagnostics → diagnostics}/drift-policies.json +0 -0
  654. /package/src/gpu/kernels/{sana_linear_attention_apply.wgsl → linear_attention_apply.wgsl} +0 -0
  655. /package/src/gpu/kernels/{sana_linear_attention_apply_f16.wgsl → linear_attention_apply_f16.wgsl} +0 -0
  656. /package/src/gpu/kernels/{sana_linear_attention_summary.wgsl → linear_attention_summary.wgsl} +0 -0
  657. /package/src/gpu/kernels/{sana_linear_attention_summary_f16.wgsl → linear_attention_summary_f16.wgsl} +0 -0
  658. /package/src/rules/kernels/{sana-linear-attention.rules.json → linear-attention.rules.json} +0 -0
@@ -0,0 +1,1119 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+ import { expandExecutionV1 } from '../config/schema/execution-v1.schema.js';
5
+ import { KERNEL_REF_CONTENT_DIGESTS } from '../config/kernels/kernel-ref-digests.js';
6
+ import {
7
+ PROGRAM_BUNDLE_SCHEMA_ID,
8
+ PROGRAM_BUNDLE_SCHEMA_VERSION,
9
+ PROGRAM_BUNDLE_HOST_SCHEMA_ID,
10
+ PROGRAM_BUNDLE_HOST_JS_SUBSET,
11
+ PROGRAM_BUNDLE_CAPTURE_PROFILE_SCHEMA_ID,
12
+ PROGRAM_BUNDLE_REFERENCE_TRANSCRIPT_SCHEMA_ID,
13
+ validateProgramBundle,
14
+ } from '../config/schema/program-bundle.schema.js';
15
+ import { sha256Hex } from '../utils/sha256.js';
16
+ import { stableSortObject } from '../utils/stable-sort-object.js';
17
+
18
+ const DEFAULT_HOST_ENTRYPOINTS = Object.freeze([
19
+ Object.freeze({
20
+ id: 'text-generation',
21
+ module: 'src/tooling/program-bundle-host.js',
22
+ export: 'createTextGenerationProgram',
23
+ role: 'model-orchestration',
24
+ }),
25
+ ]);
26
+
27
+ function stableJson(value) {
28
+ return JSON.stringify(stableSortObject(value)) ?? 'null';
29
+ }
30
+
31
+ function hashStableJson(value) {
32
+ return `sha256:${sha256Hex(stableJson(value))}`;
33
+ }
34
+
35
+ function normalizeSlash(value) {
36
+ return String(value || '').replace(/\\/g, '/');
37
+ }
38
+
39
+ function normalizeDigest(value, label) {
40
+ const raw = String(value || '').trim().toLowerCase();
41
+ const digest = raw.startsWith('sha256:') ? raw : `sha256:${raw}`;
42
+ if (!/^sha256:[0-9a-f]{64}$/.test(digest)) {
43
+ throw new Error(`program bundle export: ${label} must be a sha256 digest.`);
44
+ }
45
+ return digest;
46
+ }
47
+
48
+ function digestText(value) {
49
+ return `sha256:${sha256Hex(String(value ?? ''))}`;
50
+ }
51
+
52
+ function toRepoRelativePath(filePath, repoRoot) {
53
+ return normalizeSlash(path.relative(repoRoot, filePath));
54
+ }
55
+
56
+ function requirePlainObject(value, label) {
57
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
58
+ throw new Error(`program bundle export: ${label} must be a non-null object.`);
59
+ }
60
+ return value;
61
+ }
62
+
63
+ function requireString(value, label) {
64
+ if (typeof value !== 'string' || !value.trim()) {
65
+ throw new Error(`program bundle export: ${label} must be a non-empty string.`);
66
+ }
67
+ return value.trim();
68
+ }
69
+
70
+ async function readTextFile(filePath, label) {
71
+ try {
72
+ return await fs.readFile(filePath, 'utf8');
73
+ } catch (error) {
74
+ throw new Error(`program bundle export: failed to read ${label} at ${filePath}: ${error.message}`);
75
+ }
76
+ }
77
+
78
+ async function tryReadTextFile(filePath) {
79
+ try {
80
+ return await fs.readFile(filePath, 'utf8');
81
+ } catch {
82
+ return null;
83
+ }
84
+ }
85
+
86
+ async function readJsonFile(filePath, label) {
87
+ const raw = await readTextFile(filePath, label);
88
+ try {
89
+ return {
90
+ raw,
91
+ json: JSON.parse(raw),
92
+ };
93
+ } catch (error) {
94
+ throw new Error(`program bundle export: ${label} must contain valid JSON: ${error.message}`);
95
+ }
96
+ }
97
+
98
+ async function fileArtifact({ role, filePath, repoRoot, artifactPath = null }) {
99
+ const raw = await readTextFile(filePath, role);
100
+ const stat = await fs.stat(filePath);
101
+ return {
102
+ role,
103
+ path: artifactPath ?? toRepoRelativePath(filePath, repoRoot),
104
+ hash: `sha256:${sha256Hex(raw)}`,
105
+ sizeBytes: stat.size,
106
+ };
107
+ }
108
+
109
+ function shardArtifact(shard, modelDir, repoRoot) {
110
+ const filename = requireString(shard?.filename ?? shard?.path, 'shard filename');
111
+ const shardPath = path.resolve(modelDir, filename);
112
+ return {
113
+ role: 'weight-shard',
114
+ path: toRepoRelativePath(shardPath, repoRoot),
115
+ hash: normalizeDigest(shard.hash ?? shard.sha256, `shard ${filename} hash`),
116
+ sizeBytes: Number.isFinite(shard.size) ? Number(shard.size) : null,
117
+ };
118
+ }
119
+
120
+ function resolveWeightsRefArtifactRoot(modelDir, artifactRoot) {
121
+ const root = typeof artifactRoot === 'string' ? artifactRoot.trim() : '';
122
+ if (!root) return null;
123
+ if (/^file:\/\//i.test(root)) {
124
+ return fileURLToPath(root);
125
+ }
126
+ if (/^[a-z][a-z0-9+.-]*:\/\//iu.test(root)) {
127
+ return null;
128
+ }
129
+ return path.resolve(modelDir, root);
130
+ }
131
+
132
+ function normalizeOptionalDigest(value) {
133
+ if (typeof value !== 'string' || !value.trim()) return null;
134
+ return normalizeDigest(value, 'weightsRef digest');
135
+ }
136
+
137
+ function assertWeightsRefMatchesStorageManifest(manifest, storageManifest, storageManifestRaw, modelId) {
138
+ const weightsRef = manifest?.weightsRef;
139
+ if (!weightsRef) return;
140
+
141
+ const expectedManifestDigest = normalizeOptionalDigest(weightsRef.manifestDigest);
142
+ if (expectedManifestDigest) {
143
+ const actualManifestDigest = `sha256:${sha256Hex(storageManifestRaw)}`;
144
+ if (actualManifestDigest !== expectedManifestDigest) {
145
+ throw new Error(
146
+ `program bundle export: ${modelId} weightsRef.manifestDigest ${expectedManifestDigest} ` +
147
+ `does not match target manifest ${actualManifestDigest}.`
148
+ );
149
+ }
150
+ }
151
+
152
+ const expectedWeightPackId = typeof weightsRef.weightPackId === 'string'
153
+ ? weightsRef.weightPackId.trim()
154
+ : '';
155
+ if (expectedWeightPackId) {
156
+ const actualWeightPackId = typeof storageManifest?.artifactIdentity?.weightPackId === 'string'
157
+ ? storageManifest.artifactIdentity.weightPackId.trim()
158
+ : '';
159
+ if (actualWeightPackId !== expectedWeightPackId) {
160
+ throw new Error(
161
+ `program bundle export: ${modelId} weightsRef.weightPackId "${expectedWeightPackId}" ` +
162
+ `does not match target artifactIdentity.weightPackId "${actualWeightPackId}".`
163
+ );
164
+ }
165
+ }
166
+
167
+ const expectedShardSetHash = normalizeOptionalDigest(weightsRef.shardSetHash);
168
+ if (expectedShardSetHash) {
169
+ const actualShardSetHash = normalizeOptionalDigest(storageManifest?.artifactIdentity?.shardSetHash)
170
+ || normalizeOptionalDigest(storageManifest?.artifactIdentity?.weightPackHash);
171
+ if (actualShardSetHash !== expectedShardSetHash) {
172
+ throw new Error(
173
+ `program bundle export: ${modelId} weightsRef.shardSetHash ${expectedShardSetHash} ` +
174
+ `does not match target artifact identity ${actualShardSetHash}.`
175
+ );
176
+ }
177
+ }
178
+ }
179
+
180
+ export async function resolveProgramBundleStorageArtifact(manifest, modelDir) {
181
+ const weightsRef = manifest?.weightsRef;
182
+ if (!weightsRef) {
183
+ return {
184
+ manifest,
185
+ modelDir,
186
+ manifestPath: null,
187
+ manifestRaw: null,
188
+ };
189
+ }
190
+
191
+ const storageModelDir = resolveWeightsRefArtifactRoot(modelDir, weightsRef.artifactRoot);
192
+ if (!storageModelDir) {
193
+ return {
194
+ manifest,
195
+ modelDir,
196
+ manifestPath: null,
197
+ manifestRaw: null,
198
+ };
199
+ }
200
+
201
+ const storageManifestPath = path.join(storageModelDir, 'manifest.json');
202
+ const { raw, json: storageManifest } = await readJsonFile(
203
+ storageManifestPath,
204
+ `weightsRef target manifest ${storageManifestPath}`
205
+ );
206
+ const modelId = typeof manifest?.modelId === 'string' && manifest.modelId.trim()
207
+ ? manifest.modelId.trim()
208
+ : 'unknown-model';
209
+ assertWeightsRefMatchesStorageManifest(manifest, storageManifest, raw, modelId);
210
+
211
+ return {
212
+ manifest: storageManifest,
213
+ modelDir: storageModelDir,
214
+ manifestPath: storageManifestPath,
215
+ manifestRaw: raw,
216
+ };
217
+ }
218
+
219
+ function collectKernelRefsFromEntries(entries, section, refs) {
220
+ if (!Array.isArray(entries)) return;
221
+ for (let index = 0; index < entries.length; index += 1) {
222
+ const entry = entries[index];
223
+ if (Array.isArray(entry)) {
224
+ if (typeof entry[1] === 'string' && entry[1].trim()) {
225
+ refs.push({ id: entry[1].trim(), section, index });
226
+ }
227
+ continue;
228
+ }
229
+ if (entry && typeof entry === 'object' && Array.isArray(entry.steps)) {
230
+ collectKernelRefsFromEntries(entry.steps, section, refs);
231
+ }
232
+ }
233
+ }
234
+
235
+ function collectReachableKernelRefs(execution) {
236
+ const refs = [];
237
+ collectKernelRefsFromEntries(execution.preLayer, 'preLayer', refs);
238
+ collectKernelRefsFromEntries(execution.decode, 'decode', refs);
239
+ collectKernelRefsFromEntries(execution.prefill, 'prefill', refs);
240
+ collectKernelRefsFromEntries(execution.postLayer, 'postLayer', refs);
241
+ return refs;
242
+ }
243
+
244
+ function countExpandedStepsByPhase(expandedSteps) {
245
+ const phases = {
246
+ prefill: 0,
247
+ decode: 0,
248
+ preLayer: 0,
249
+ postLayer: 0,
250
+ };
251
+ for (const step of expandedSteps) {
252
+ if (step.section === 'preLayer') {
253
+ phases.preLayer += 1;
254
+ } else if (step.section === 'postLayer') {
255
+ phases.postLayer += 1;
256
+ } else if (step.phase === 'prefill') {
257
+ phases.prefill += 1;
258
+ } else if (step.phase === 'decode') {
259
+ phases.decode += 1;
260
+ }
261
+ }
262
+ return phases;
263
+ }
264
+
265
+ function buildKernelIdLookup(execution, modules = []) {
266
+ const lookup = new Map();
267
+ const reachableIds = new Set(modules.map((module) => module.id));
268
+ for (const [id, decl] of Object.entries(execution.kernels || {})) {
269
+ const key = `${decl.kernel}#${decl.entry}#${normalizeDigest(decl.digest, `execution.kernels.${id}.digest`)}`;
270
+ const current = lookup.get(key);
271
+ if (!current || (!reachableIds.has(current) && reachableIds.has(id))) {
272
+ lookup.set(key, id);
273
+ }
274
+ }
275
+ return lookup;
276
+ }
277
+
278
+ function normalizeLayersForStep(layers) {
279
+ if (layers === 'all') return 'all';
280
+ return Array.isArray(layers) ? layers : [];
281
+ }
282
+
283
+ function buildExecutionStepMetadata(execution, expandedSteps, modules) {
284
+ const kernelIdLookup = buildKernelIdLookup(execution, modules);
285
+ const moduleById = new Map(modules.map((module) => [module.id, module]));
286
+ const steps = expandedSteps.map((step, index) => {
287
+ const digest = normalizeDigest(step.digest, `expandedSteps[${index}].digest`);
288
+ const lookupKey = `${step.kernel}#${step.entry}#${digest}`;
289
+ const kernelId = kernelIdLookup.get(lookupKey);
290
+ if (!kernelId) {
291
+ throw new Error(
292
+ `program bundle export: expanded step ${index} ${step.op} cannot be mapped to a declared kernel id.`
293
+ );
294
+ }
295
+ const module = moduleById.get(kernelId);
296
+ const bindings = Array.isArray(module?.metadata?.bindings)
297
+ ? module.metadata.bindings.map((binding) => ({
298
+ group: binding.group,
299
+ binding: binding.binding,
300
+ name: binding.name,
301
+ addressSpace: binding.addressSpace,
302
+ access: binding.access,
303
+ }))
304
+ : [];
305
+ return {
306
+ id: `${step.section}_${step.phase}_${index}_${step.op}`,
307
+ index,
308
+ op: step.op,
309
+ phase: step.phase,
310
+ section: step.section,
311
+ layers: normalizeLayersForStep(step.layers),
312
+ src: typeof step.src === 'string' && step.src.trim() ? step.src : 'state',
313
+ dst: typeof step.dst === 'string' && step.dst.trim() ? step.dst : 'state',
314
+ kernelId,
315
+ kernel: step.kernel,
316
+ entry: step.entry,
317
+ kernelDigest: digest,
318
+ weights: step.weights ?? null,
319
+ constants: step.constants ?? null,
320
+ precision: step.precision ?? null,
321
+ dispatch: {
322
+ phase: step.phase,
323
+ workgroups: `symbolic:${step.section}:${step.phase}:${step.op}`,
324
+ bindings,
325
+ },
326
+ };
327
+ });
328
+ return {
329
+ steps,
330
+ stepMetadataHash: hashStableJson(steps),
331
+ };
332
+ }
333
+
334
+ async function resolveKernelSourceDigest(kernel, entry, kernelSourceRoot) {
335
+ const digestKey = `${kernel}#${entry}`;
336
+ const registryDigest = KERNEL_REF_CONTENT_DIGESTS[digestKey];
337
+ const kernelPath = path.resolve(kernelSourceRoot, kernel);
338
+ const source = await tryReadTextFile(kernelPath);
339
+ if (registryDigest) {
340
+ return {
341
+ digest: `sha256:${registryDigest}`,
342
+ sourcePath: normalizeSlash(path.join(kernelSourceRoot, kernel)),
343
+ sourceText: source,
344
+ source: 'registry',
345
+ };
346
+ }
347
+
348
+ if (source != null) {
349
+ const normalizedSource = source.replace(/\r\n/g, '\n');
350
+ return {
351
+ digest: `sha256:${sha256Hex(`${normalizedSource}\n@@entry:${entry}`)}`,
352
+ sourcePath: normalizeSlash(path.relative(process.cwd(), kernelPath)),
353
+ sourceText: normalizedSource,
354
+ source: 'file',
355
+ };
356
+ }
357
+
358
+ return {
359
+ digest: null,
360
+ sourcePath: null,
361
+ sourceText: null,
362
+ source: 'unresolved',
363
+ };
364
+ }
365
+
366
+ function parseWgslBindings(sourceText) {
367
+ if (typeof sourceText !== 'string') return [];
368
+ const bindings = [];
369
+ const bindingRe = /@group\((\d+)\)\s*@binding\((\d+)\)\s*var(?:<([^>]+)>)?\s+([A-Za-z_]\w*)/g;
370
+ let match;
371
+ while ((match = bindingRe.exec(sourceText)) !== null) {
372
+ const address = typeof match[3] === 'string'
373
+ ? match[3].split(',').map((part) => part.trim()).filter(Boolean)
374
+ : [];
375
+ bindings.push({
376
+ group: Number(match[1]),
377
+ binding: Number(match[2]),
378
+ addressSpace: address[0] ?? null,
379
+ access: address[1] ?? null,
380
+ name: match[4],
381
+ });
382
+ }
383
+ return bindings.sort((left, right) => (
384
+ left.group - right.group
385
+ || left.binding - right.binding
386
+ || left.name.localeCompare(right.name)
387
+ ));
388
+ }
389
+
390
+ function parseWgslOverrides(sourceText) {
391
+ if (typeof sourceText !== 'string') return [];
392
+ const overrides = [];
393
+ const overrideRe = /\boverride\s+([A-Za-z_]\w*)(?:\s*:\s*([^=;]+))?(?:\s*=\s*([^;]+))?;/g;
394
+ let match;
395
+ while ((match = overrideRe.exec(sourceText)) !== null) {
396
+ overrides.push({
397
+ name: match[1],
398
+ type: typeof match[2] === 'string' ? match[2].trim() : null,
399
+ defaultValue: typeof match[3] === 'string' ? match[3].trim() : null,
400
+ });
401
+ }
402
+ return overrides.sort((left, right) => left.name.localeCompare(right.name));
403
+ }
404
+
405
+ function parseWgslWorkgroupSize(sourceText) {
406
+ if (typeof sourceText !== 'string') return [];
407
+ const match = /@workgroup_size\(([^)]*)\)/.exec(sourceText);
408
+ if (!match) return [];
409
+ return match[1].split(',').map((part) => part.trim()).filter(Boolean);
410
+ }
411
+
412
+ function buildWgslMetadata(sourceText, entry) {
413
+ const metadata = {
414
+ entry,
415
+ bindings: parseWgslBindings(sourceText),
416
+ overrides: parseWgslOverrides(sourceText),
417
+ workgroupSize: parseWgslWorkgroupSize(sourceText),
418
+ requiresSubgroups: typeof sourceText === 'string' && /\b(subgroup|enable\s+subgroups)\b/.test(sourceText),
419
+ };
420
+ return {
421
+ ...metadata,
422
+ sourceMetadataHash: hashStableJson(metadata),
423
+ };
424
+ }
425
+
426
+ async function buildWgslClosure(execution, expandedSteps, options) {
427
+ const declaredKernelIds = Object.keys(execution.kernels || {}).sort();
428
+ const reachableRefs = collectReachableKernelRefs(execution);
429
+ const reachableKernelIds = [...new Set(reachableRefs.map((ref) => ref.id))].sort();
430
+ const undeclaredKernelRefs = reachableRefs
431
+ .filter((ref) => !execution.kernels?.[ref.id])
432
+ .map((ref) => `${ref.section}[${ref.index}]:${ref.id}`);
433
+ if (undeclaredKernelRefs.length > 0) {
434
+ throw new Error(
435
+ `program bundle export: execution graph references undeclared kernels: ${undeclaredKernelRefs.join(', ')}.`
436
+ );
437
+ }
438
+
439
+ const kernelSourceRoot = path.resolve(options.repoRoot, options.kernelSourceRoot || 'src/gpu/kernels');
440
+ const modules = [];
441
+ for (const id of reachableKernelIds) {
442
+ const decl = execution.kernels[id];
443
+ const file = requireString(decl.kernel, `execution.kernels.${id}.kernel`);
444
+ const entry = requireString(decl.entry, `execution.kernels.${id}.entry`);
445
+ const declaredDigest = normalizeDigest(decl.digest, `execution.kernels.${id}.digest`);
446
+ const sourceDigest = await resolveKernelSourceDigest(file, entry, kernelSourceRoot);
447
+ if (sourceDigest.digest && sourceDigest.digest !== declaredDigest) {
448
+ throw new Error(
449
+ `program bundle export: kernel digest mismatch for ${file}#${entry}. ` +
450
+ `execution declares ${declaredDigest}, source has ${sourceDigest.digest}.`
451
+ );
452
+ }
453
+ modules.push({
454
+ id,
455
+ file,
456
+ entry,
457
+ digest: declaredDigest,
458
+ sourcePath: sourceDigest.sourcePath
459
+ ? toRepoRelativePath(path.resolve(sourceDigest.sourcePath), options.repoRoot)
460
+ : null,
461
+ reachable: true,
462
+ metadata: buildWgslMetadata(sourceDigest.sourceText, entry),
463
+ });
464
+ }
465
+
466
+ return {
467
+ modules,
468
+ kernelClosure: {
469
+ declaredKernelIds,
470
+ reachableKernelIds,
471
+ excludedKernelIds: declaredKernelIds.filter((id) => !reachableKernelIds.includes(id)),
472
+ undeclaredKernelRefs,
473
+ expandedStepCount: expandedSteps.length,
474
+ phases: countExpandedStepsByPhase(expandedSteps),
475
+ },
476
+ };
477
+ }
478
+
479
+ function scanHostEntrypointSource(source, label) {
480
+ if (/\bimport\s*\(/.test(source)) {
481
+ throw new Error(`program bundle export: host entrypoint ${label} uses dynamic import().`);
482
+ }
483
+ if (/\b(document|window|localStorage|sessionStorage|XMLHttpRequest)\b/.test(source)) {
484
+ throw new Error(`program bundle export: host entrypoint ${label} references DOM-only globals.`);
485
+ }
486
+ return {
487
+ dynamicImport: 'none-detected',
488
+ dom: 'none-detected',
489
+ };
490
+ }
491
+
492
+ async function buildHostContract(host = {}, repoRoot) {
493
+ const rawEntrypoints = Array.isArray(host.entrypoints) && host.entrypoints.length > 0
494
+ ? host.entrypoints
495
+ : DEFAULT_HOST_ENTRYPOINTS.map((entry) => ({ ...entry }));
496
+ const entrypoints = [];
497
+ for (const entrypoint of rawEntrypoints) {
498
+ const modulePath = requireString(entrypoint.module, 'host.entrypoint.module');
499
+ const sourcePath = path.resolve(repoRoot, modulePath);
500
+ const source = await readTextFile(sourcePath, `host entrypoint ${modulePath}`);
501
+ entrypoints.push({
502
+ ...entrypoint,
503
+ sourceHash: digestText(source),
504
+ validation: scanHostEntrypointSource(source, `${modulePath}#${entrypoint.export}`),
505
+ });
506
+ }
507
+ return {
508
+ schema: PROGRAM_BUNDLE_HOST_SCHEMA_ID,
509
+ jsSubset: PROGRAM_BUNDLE_HOST_JS_SUBSET,
510
+ entrypoints,
511
+ constraints: {
512
+ dynamicImport: 'disallowed',
513
+ dom: 'disallowed-in-model-path',
514
+ filesystem: 'declared-artifacts-only',
515
+ network: 'declared-artifacts-only',
516
+ ...(host.constraints && typeof host.constraints === 'object' ? host.constraints : {}),
517
+ },
518
+ };
519
+ }
520
+
521
+ function buildCaptureProfile(captureProfile = {}, context = {}) {
522
+ const profile = {
523
+ schema: PROGRAM_BUNDLE_CAPTURE_PROFILE_SCHEMA_ID,
524
+ deterministic: true,
525
+ phases: Array.isArray(captureProfile.phases) && captureProfile.phases.length > 0
526
+ ? captureProfile.phases
527
+ : ['prefill', 'decode'],
528
+ surfaces: Array.isArray(captureProfile.surfaces) && captureProfile.surfaces.length > 0
529
+ ? captureProfile.surfaces
530
+ : ['browser-webgpu'],
531
+ adapter: context.adapter ?? {
532
+ source: 'not-captured',
533
+ surface: null,
534
+ deviceInfoHash: hashStableJson(null),
535
+ },
536
+ hashPolicy: {
537
+ graph: 'stable-json-sha256',
538
+ dispatch: 'stable-json-sha256',
539
+ transcript: 'stable-json-sha256',
540
+ },
541
+ };
542
+ return {
543
+ ...profile,
544
+ captureHash: hashStableJson({
545
+ phases: profile.phases,
546
+ surfaces: profile.surfaces,
547
+ adapter: profile.adapter,
548
+ executionGraphHash: context.executionGraphHash ?? null,
549
+ expandedStepHash: context.expandedStepHash ?? null,
550
+ wgslModuleDigests: context.wgslModuleDigests ?? [],
551
+ hostSourceHashes: context.hostSourceHashes ?? [],
552
+ }),
553
+ };
554
+ }
555
+
556
+ function extractGenerationPreview(report) {
557
+ const preview = report?.metrics?.generationDiagnostics?.preview;
558
+ return Array.isArray(preview) ? preview : [];
559
+ }
560
+
561
+ function resolvePromptPayload(report) {
562
+ const metrics = report?.metrics || {};
563
+ if (metrics.promptInput !== undefined) {
564
+ return {
565
+ identity: typeof metrics.prompt === 'string' && metrics.prompt.trim()
566
+ ? metrics.prompt
567
+ : 'metrics.promptInput',
568
+ payload: metrics.promptInput,
569
+ };
570
+ }
571
+ return {
572
+ identity: typeof metrics.prompt === 'string' && metrics.prompt.trim()
573
+ ? metrics.prompt
574
+ : 'unknown-prompt',
575
+ payload: metrics.prompt ?? null,
576
+ };
577
+ }
578
+
579
+ function buildPerStepTokenProof(tokenIds) {
580
+ return tokenIds.map((tokenId, index) => ({
581
+ index,
582
+ tokenId,
583
+ tokenHash: hashStableJson({ index, tokenId }),
584
+ }));
585
+ }
586
+
587
+ function normalizeNullableHash(value, label) {
588
+ if (typeof value !== 'string' || !value.trim()) return null;
589
+ return normalizeDigest(value, label);
590
+ }
591
+
592
+ function buildKvCacheTranscript(metrics, transcriptSeed) {
593
+ const seedKv = transcriptSeed?.kvCache && typeof transcriptSeed.kvCache === 'object'
594
+ ? transcriptSeed.kvCache
595
+ : null;
596
+ const metricKv = metrics.kvCache && typeof metrics.kvCache === 'object'
597
+ ? metrics.kvCache
598
+ : null;
599
+ const source = seedKv ?? metricKv ?? null;
600
+ const kvCache = {
601
+ mode: source ? 'stats' : 'not-captured',
602
+ layout: typeof source?.layout === 'string' ? source.layout : null,
603
+ kvDtype: typeof source?.kvDtype === 'string' ? source.kvDtype : null,
604
+ seqLen: Number.isFinite(source?.seqLen) ? source.seqLen : null,
605
+ maxSeqLen: Number.isFinite(source?.maxSeqLen) ? source.maxSeqLen : null,
606
+ usedBytes: Number.isFinite(source?.usedBytes)
607
+ ? source.usedBytes
608
+ : (Number.isFinite(source?.used) ? source.used : null),
609
+ allocatedBytes: Number.isFinite(source?.allocatedBytes)
610
+ ? source.allocatedBytes
611
+ : (Number.isFinite(source?.allocated) ? source.allocated : null),
612
+ counters: source?.counters && typeof source.counters === 'object' ? source.counters : null,
613
+ };
614
+ const byteProof = {
615
+ byteDigestMode: typeof source?.byteDigestMode === 'string' ? source.byteDigestMode : null,
616
+ byteDigest: normalizeNullableHash(source?.byteDigest, 'referenceTranscript.kvCache.byteDigest'),
617
+ byteDigests: Array.isArray(source?.byteDigests) ? source.byteDigests : null,
618
+ };
619
+ const hasByteProof = byteProof.byteDigestMode || byteProof.byteDigest || byteProof.byteDigests;
620
+ return {
621
+ ...kvCache,
622
+ ...(hasByteProof ? byteProof : {}),
623
+ ...(hasByteProof && kvCache.mode === 'stats' ? { mode: 'stats+sha256-layer-kv-bytes' } : {}),
624
+ stateHash: normalizeNullableHash(source?.stateHash, 'referenceTranscript.kvCache.stateHash')
625
+ ?? hashStableJson({ ...kvCache, ...(hasByteProof ? byteProof : {}) }),
626
+ };
627
+ }
628
+
629
+ function buildReferenceAdapterStamp(report) {
630
+ return {
631
+ source: 'reference-report',
632
+ surface: report.env?.runtime ?? (report.mode ? `browser-${report.mode}` : null),
633
+ deviceInfoHash: hashStableJson(report.deviceInfo ?? null),
634
+ deviceInfo: report.deviceInfo ?? null,
635
+ };
636
+ }
637
+
638
+ async function buildReferenceTranscript(referenceReportPath, repoRoot, executionGraphHash) {
639
+ const resolvedReportPath = path.resolve(referenceReportPath);
640
+ const reportArtifact = await fileArtifact({
641
+ role: 'reference-report',
642
+ filePath: resolvedReportPath,
643
+ repoRoot,
644
+ });
645
+ const { json: report } = await readJsonFile(resolvedReportPath, 'reference report');
646
+ requirePlainObject(report, 'reference report');
647
+ const metrics = report.metrics || {};
648
+ if (!metrics || typeof metrics !== 'object' || Array.isArray(metrics)) {
649
+ throw new Error('program bundle export: reference report must include metrics for transcript identity.');
650
+ }
651
+ const transcriptSeed = metrics.referenceTranscript && typeof metrics.referenceTranscript === 'object'
652
+ ? metrics.referenceTranscript
653
+ : null;
654
+ const prompt = transcriptSeed?.prompt?.hash && transcriptSeed?.prompt?.identity
655
+ ? {
656
+ identity: transcriptSeed.prompt.identity,
657
+ payload: transcriptSeed.prompt,
658
+ hash: transcriptSeed.prompt.hash,
659
+ }
660
+ : resolvePromptPayload(report);
661
+ const outputText = typeof report.output === 'string'
662
+ ? report.output
663
+ : (typeof metrics.generatedText === 'string' ? metrics.generatedText : '');
664
+ const preview = Array.isArray(transcriptSeed?.tokens?.preview)
665
+ ? transcriptSeed.tokens.preview
666
+ : extractGenerationPreview(report);
667
+ const fullTokenIds = Array.isArray(transcriptSeed?.tokens?.ids)
668
+ ? transcriptSeed.tokens.ids.map((value) => Number(value)).filter((value) => Number.isInteger(value))
669
+ : null;
670
+ const previewTokenIds = preview
671
+ .map((entry) => Number(entry?.id))
672
+ .filter((value) => Number.isInteger(value));
673
+ const tokenIdsForHash = fullTokenIds ?? previewTokenIds;
674
+ const tokensGenerated = Number.isInteger(transcriptSeed?.output?.tokensGenerated)
675
+ ? transcriptSeed.output.tokensGenerated
676
+ : Number.isInteger(metrics.tokensGenerated)
677
+ ? metrics.tokensGenerated
678
+ : (Number.isInteger(metrics.generationDiagnostics?.total) ? metrics.generationDiagnostics.total : previewTokenIds.length);
679
+ if (prompt.identity === 'unknown-prompt') {
680
+ throw new Error('program bundle export: reference report must include metrics.prompt or metrics.promptInput.');
681
+ }
682
+ if (tokensGenerated < 1 || tokenIdsForHash.length < 1 || !outputText) {
683
+ throw new Error(
684
+ 'program bundle export: reference report must include generated output and token diagnostics.'
685
+ );
686
+ }
687
+
688
+ return {
689
+ artifact: reportArtifact,
690
+ adapter: buildReferenceAdapterStamp(report),
691
+ transcript: {
692
+ schema: PROGRAM_BUNDLE_REFERENCE_TRANSCRIPT_SCHEMA_ID,
693
+ source: {
694
+ kind: 'browser-report',
695
+ path: reportArtifact.path,
696
+ hash: reportArtifact.hash,
697
+ },
698
+ executionGraphHash,
699
+ surface: report.env?.runtime ?? (report.mode ? `browser-${report.mode}` : null),
700
+ prompt: {
701
+ identity: prompt.identity,
702
+ hash: transcriptSeed?.prompt?.hash
703
+ ? normalizeDigest(transcriptSeed.prompt.hash, 'referenceTranscript.prompt.hash')
704
+ : hashStableJson(prompt.payload),
705
+ tokenIdsHash: normalizeNullableHash(transcriptSeed?.prompt?.tokenIdsHash, 'referenceTranscript.prompt.tokenIdsHash'),
706
+ tokenCount: Number.isFinite(transcriptSeed?.prompt?.tokenCount)
707
+ ? transcriptSeed.prompt.tokenCount
708
+ : null,
709
+ },
710
+ output: {
711
+ textHash: transcriptSeed?.output?.textHash
712
+ ? normalizeDigest(transcriptSeed.output.textHash, 'referenceTranscript.output.textHash')
713
+ : `sha256:${sha256Hex(outputText)}`,
714
+ tokensGenerated,
715
+ stopReason: typeof transcriptSeed?.output?.stopReason === 'string'
716
+ ? transcriptSeed.output.stopReason
717
+ : (typeof metrics.stopReason === 'string' ? metrics.stopReason : 'unknown'),
718
+ stopTokenId: Number.isInteger(transcriptSeed?.output?.stopTokenId)
719
+ ? transcriptSeed.output.stopTokenId
720
+ : (Number.isInteger(metrics.stopTokenId) ? metrics.stopTokenId : null),
721
+ },
722
+ tokens: {
723
+ generatedTokenIdsHash: transcriptSeed?.tokens?.generatedTokenIdsHash
724
+ ? normalizeDigest(transcriptSeed.tokens.generatedTokenIdsHash, 'referenceTranscript.tokens.generatedTokenIdsHash')
725
+ : hashStableJson(tokenIdsForHash),
726
+ generatedTextHash: transcriptSeed?.tokens?.generatedTextHash
727
+ ? normalizeDigest(transcriptSeed.tokens.generatedTextHash, 'referenceTranscript.tokens.generatedTextHash')
728
+ : `sha256:${sha256Hex(outputText)}`,
729
+ preview,
730
+ perStep: Array.isArray(transcriptSeed?.tokens?.perStep) && transcriptSeed.tokens.perStep.length > 0
731
+ ? transcriptSeed.tokens.perStep
732
+ : buildPerStepTokenProof(tokenIdsForHash),
733
+ ...(fullTokenIds ? { ids: fullTokenIds } : {}),
734
+ coverage: transcriptSeed?.tokens?.coverage && typeof transcriptSeed.tokens.coverage === 'object'
735
+ ? transcriptSeed.tokens.coverage
736
+ : {
737
+ mode: metrics.generationDiagnostics?.omitted > 0 ? 'preview' : 'complete-preview',
738
+ omitted: Number.isInteger(metrics.generationDiagnostics?.omitted)
739
+ ? metrics.generationDiagnostics.omitted
740
+ : 0,
741
+ },
742
+ },
743
+ phase: {
744
+ prefillMs: Number.isFinite(transcriptSeed?.phase?.prefillMs)
745
+ ? transcriptSeed.phase.prefillMs
746
+ : (Number.isFinite(metrics.prefillMs) ? metrics.prefillMs : null),
747
+ decodeMs: Number.isFinite(transcriptSeed?.phase?.decodeMs)
748
+ ? transcriptSeed.phase.decodeMs
749
+ : (Number.isFinite(metrics.decodeMs) ? metrics.decodeMs : null),
750
+ prefillTokens: Number.isFinite(transcriptSeed?.phase?.prefillTokens)
751
+ ? transcriptSeed.phase.prefillTokens
752
+ : (Number.isFinite(metrics.prefillTokens) ? metrics.prefillTokens : null),
753
+ decodeTokens: Number.isFinite(transcriptSeed?.phase?.decodeTokens)
754
+ ? transcriptSeed.phase.decodeTokens
755
+ : (Number.isFinite(metrics.decodeTokens) ? metrics.decodeTokens : null),
756
+ },
757
+ kvCache: buildKvCacheTranscript(metrics, transcriptSeed),
758
+ logits: transcriptSeed?.logits && typeof transcriptSeed.logits === 'object' ? transcriptSeed.logits : {
759
+ mode: 'not-captured',
760
+ reason: 'Browser reports do not persist per-step logits digests yet.',
761
+ perStepDigests: null,
762
+ },
763
+ tolerance: transcriptSeed?.tolerance && typeof transcriptSeed.tolerance === 'object' ? transcriptSeed.tolerance : {
764
+ tokenPolicy: 'exact generated token IDs when a full-token transcript is present; preview IDs are diagnostic only',
765
+ logitsPolicy: 'not captured in current browser report fixtures',
766
+ },
767
+ },
768
+ };
769
+ }
770
+
771
+ async function collectArtifacts(options, manifest, manifestArtifact, referenceReportArtifact) {
772
+ const artifacts = [manifestArtifact];
773
+ const storageArtifact = await resolveProgramBundleStorageArtifact(manifest, options.modelDir);
774
+ const storageManifest = storageArtifact.manifest;
775
+ const storageModelDir = storageArtifact.modelDir;
776
+ if (storageArtifact.manifestPath && storageArtifact.manifestRaw != null) {
777
+ artifacts.push({
778
+ role: 'source',
779
+ path: toRepoRelativePath(storageArtifact.manifestPath, options.repoRoot),
780
+ hash: `sha256:${sha256Hex(storageArtifact.manifestRaw)}`,
781
+ sizeBytes: Buffer.byteLength(storageArtifact.manifestRaw),
782
+ });
783
+ }
784
+
785
+ if (Array.isArray(storageManifest.shards)) {
786
+ for (const shard of storageManifest.shards) {
787
+ artifacts.push(shardArtifact(shard, storageModelDir, options.repoRoot));
788
+ }
789
+ }
790
+
791
+ const tokenizerFile = storageManifest.tokenizer?.file;
792
+ if (typeof tokenizerFile === 'string' && tokenizerFile.trim()) {
793
+ artifacts.push(await fileArtifact({
794
+ role: 'tokenizer',
795
+ filePath: path.resolve(storageModelDir, tokenizerFile),
796
+ repoRoot: options.repoRoot,
797
+ }));
798
+ }
799
+
800
+ if (options.conversionConfigPath) {
801
+ artifacts.push(await fileArtifact({
802
+ role: 'conversion-config',
803
+ filePath: path.resolve(options.conversionConfigPath),
804
+ repoRoot: options.repoRoot,
805
+ }));
806
+ }
807
+
808
+ if (options.runtimeConfigPath) {
809
+ artifacts.push(await fileArtifact({
810
+ role: 'runtime-config',
811
+ filePath: path.resolve(options.runtimeConfigPath),
812
+ repoRoot: options.repoRoot,
813
+ }));
814
+ }
815
+
816
+ artifacts.push(referenceReportArtifact);
817
+ return artifacts.sort((left, right) => `${left.role}:${left.path}`.localeCompare(`${right.role}:${right.path}`));
818
+ }
819
+
820
+ function resolveProgramBundleOptions(options = {}) {
821
+ const repoRoot = path.resolve(options.repoRoot || process.cwd());
822
+ const manifestPath = options.manifestPath
823
+ ? path.resolve(options.manifestPath)
824
+ : (options.modelDir ? path.resolve(options.modelDir, 'manifest.json') : null);
825
+ if (!manifestPath) {
826
+ throw new Error('program bundle export: manifestPath or modelDir is required.');
827
+ }
828
+ const modelDir = path.resolve(options.modelDir || path.dirname(manifestPath));
829
+ const referenceReportPath = options.referenceReportPath
830
+ ? path.resolve(options.referenceReportPath)
831
+ : null;
832
+ if (!referenceReportPath) {
833
+ throw new Error('program bundle export: referenceReportPath is required.');
834
+ }
835
+ return {
836
+ ...options,
837
+ repoRoot,
838
+ manifestPath,
839
+ modelDir,
840
+ referenceReportPath,
841
+ };
842
+ }
843
+
844
+ export async function exportProgramBundle(options = {}) {
845
+ const resolvedOptions = resolveProgramBundleOptions(options);
846
+ const { raw: manifestRaw, json: manifest } = await readJsonFile(resolvedOptions.manifestPath, 'manifest');
847
+ requirePlainObject(manifest, 'manifest');
848
+ const modelId = requireString(manifest.modelId, 'manifest.modelId');
849
+ const execution = manifest.inference?.execution;
850
+ requirePlainObject(execution, 'manifest.inference.execution');
851
+
852
+ const expandedSteps = expandExecutionV1(execution);
853
+ const executionGraphHash = hashStableJson(execution);
854
+ const expandedStepHash = hashStableJson(expandedSteps);
855
+ const closure = await buildWgslClosure(execution, expandedSteps, resolvedOptions);
856
+ const executionMetadata = buildExecutionStepMetadata(execution, expandedSteps, closure.modules);
857
+ const host = await buildHostContract(resolvedOptions.host, resolvedOptions.repoRoot);
858
+ const manifestArtifact = {
859
+ role: 'manifest',
860
+ path: toRepoRelativePath(resolvedOptions.manifestPath, resolvedOptions.repoRoot),
861
+ hash: `sha256:${sha256Hex(manifestRaw)}`,
862
+ sizeBytes: Buffer.byteLength(manifestRaw),
863
+ };
864
+ const reference = await buildReferenceTranscript(
865
+ resolvedOptions.referenceReportPath,
866
+ resolvedOptions.repoRoot,
867
+ executionGraphHash
868
+ );
869
+ const artifacts = await collectArtifacts(
870
+ resolvedOptions,
871
+ manifest,
872
+ manifestArtifact,
873
+ reference.artifact
874
+ );
875
+ const weightArtifacts = artifacts.filter((artifact) => artifact.role === 'weight-shard');
876
+ const conversionConfig = resolvedOptions.conversionConfigPath
877
+ ? artifacts.find((artifact) => artifact.role === 'conversion-config') ?? null
878
+ : null;
879
+
880
+ const bundle = {
881
+ schema: PROGRAM_BUNDLE_SCHEMA_ID,
882
+ schemaVersion: PROGRAM_BUNDLE_SCHEMA_VERSION,
883
+ bundleId: resolvedOptions.bundleId || `${modelId}-${executionGraphHash.slice('sha256:'.length, 'sha256:'.length + 12)}`,
884
+ modelId,
885
+ createdAtUtc: resolvedOptions.createdAtUtc || new Date().toISOString(),
886
+ sources: {
887
+ manifest: {
888
+ path: manifestArtifact.path,
889
+ hash: manifestArtifact.hash,
890
+ },
891
+ conversionConfig: conversionConfig
892
+ ? {
893
+ path: conversionConfig.path,
894
+ hash: conversionConfig.hash,
895
+ }
896
+ : null,
897
+ executionGraph: {
898
+ schema: manifest.inference?.schema ?? null,
899
+ hash: executionGraphHash,
900
+ expandedStepHash,
901
+ },
902
+ weightSetHash: hashStableJson(weightArtifacts.map((artifact) => ({
903
+ path: artifact.path,
904
+ hash: artifact.hash,
905
+ sizeBytes: artifact.sizeBytes,
906
+ }))),
907
+ artifactSetHash: hashStableJson(artifacts.map((artifact) => ({
908
+ role: artifact.role,
909
+ path: artifact.path,
910
+ hash: artifact.hash,
911
+ sizeBytes: artifact.sizeBytes,
912
+ }))),
913
+ },
914
+ host,
915
+ wgslModules: closure.modules,
916
+ execution: {
917
+ graphHash: executionGraphHash,
918
+ stepMetadataHash: executionMetadata.stepMetadataHash,
919
+ kernelClosure: closure.kernelClosure,
920
+ steps: executionMetadata.steps,
921
+ },
922
+ captureProfile: buildCaptureProfile(resolvedOptions.captureProfile, {
923
+ adapter: reference.adapter,
924
+ executionGraphHash,
925
+ expandedStepHash,
926
+ wgslModuleDigests: closure.modules.map((module) => ({
927
+ id: module.id,
928
+ digest: module.digest,
929
+ metadataHash: module.metadata.sourceMetadataHash,
930
+ })),
931
+ hostSourceHashes: host.entrypoints.map((entrypoint) => ({
932
+ id: entrypoint.id,
933
+ sourceHash: entrypoint.sourceHash,
934
+ })),
935
+ }),
936
+ artifacts,
937
+ referenceTranscript: reference.transcript,
938
+ };
939
+
940
+ return validateProgramBundle(bundle);
941
+ }
942
+
943
+ export async function writeProgramBundle(options = {}) {
944
+ const outputPath = options.outputPath ? path.resolve(options.outputPath) : null;
945
+ if (!outputPath) {
946
+ throw new Error('program bundle export: outputPath is required.');
947
+ }
948
+ const bundle = await exportProgramBundle(options);
949
+ await fs.mkdir(path.dirname(outputPath), { recursive: true });
950
+ await fs.writeFile(outputPath, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
951
+ return {
952
+ outputPath,
953
+ bundle,
954
+ };
955
+ }
956
+
957
+ export async function loadProgramBundle(bundlePath) {
958
+ const resolvedPath = path.resolve(bundlePath);
959
+ const { json } = await readJsonFile(resolvedPath, 'program bundle');
960
+ return validateProgramBundle(json);
961
+ }
962
+
963
+ export async function checkProgramBundleFile(bundlePath) {
964
+ const bundle = await loadProgramBundle(bundlePath);
965
+ return {
966
+ ok: true,
967
+ path: path.resolve(bundlePath),
968
+ modelId: bundle.modelId,
969
+ bundleId: bundle.bundleId,
970
+ artifactCount: bundle.artifacts.length,
971
+ wgslModuleCount: bundle.wgslModules.length,
972
+ executionGraphHash: bundle.sources.executionGraph.hash,
973
+ };
974
+ }
975
+
976
+ export function createProgramBundleCliDefaults(metaUrl) {
977
+ return {
978
+ repoRoot: path.resolve(path.dirname(fileURLToPath(metaUrl)), '..'),
979
+ };
980
+ }
981
+
982
+ export const REFERENCE_RECEIPT_SCHEMA_ID = 'doppler.reference-receipt/v1';
983
+
984
+ function requireTranscriptField(value, label) {
985
+ if (value === undefined || value === null) {
986
+ throw new Error(`reference receipt: ${label} is required on the referenceTranscript input.`);
987
+ }
988
+ return value;
989
+ }
990
+
991
+ function normalizeReferenceTranscriptInput(referenceTranscript, executionGraphHash) {
992
+ requirePlainObject(referenceTranscript, 'referenceTranscript');
993
+ if (referenceTranscript.schema !== PROGRAM_BUNDLE_REFERENCE_TRANSCRIPT_SCHEMA_ID) {
994
+ throw new Error(
995
+ `reference receipt: referenceTranscript.schema must be "${PROGRAM_BUNDLE_REFERENCE_TRANSCRIPT_SCHEMA_ID}".`
996
+ );
997
+ }
998
+ requirePlainObject(referenceTranscript.prompt, 'referenceTranscript.prompt');
999
+ requirePlainObject(referenceTranscript.output, 'referenceTranscript.output');
1000
+ requirePlainObject(referenceTranscript.tokens, 'referenceTranscript.tokens');
1001
+ const graphHashInTranscript = requireTranscriptField(
1002
+ referenceTranscript.executionGraphHash,
1003
+ 'executionGraphHash'
1004
+ );
1005
+ if (graphHashInTranscript !== executionGraphHash) {
1006
+ throw new Error(
1007
+ `reference receipt: referenceTranscript.executionGraphHash (${graphHashInTranscript}) ` +
1008
+ `does not match manifest executionGraphHash (${executionGraphHash}).`
1009
+ );
1010
+ }
1011
+ return referenceTranscript;
1012
+ }
1013
+
1014
+ function buildWeightSetHashFromManifest(manifest) {
1015
+ const shards = manifest?.rdrr?.shards;
1016
+ if (!Array.isArray(shards) || shards.length === 0) return null;
1017
+ const normalized = shards
1018
+ .map((shard) => ({
1019
+ filename: String(shard?.filename ?? shard?.path ?? ''),
1020
+ hash: String(shard?.hash ?? shard?.sha256 ?? ''),
1021
+ size: Number.isFinite(shard?.size) ? Number(shard.size) : null,
1022
+ }))
1023
+ .filter((entry) => entry.filename && entry.hash);
1024
+ if (normalized.length === 0) return null;
1025
+ normalized.sort((left, right) => left.filename.localeCompare(right.filename));
1026
+ return hashStableJson(normalized);
1027
+ }
1028
+
1029
+ function resolveReferenceReceiptOptions(options = {}) {
1030
+ const repoRoot = path.resolve(options.repoRoot || process.cwd());
1031
+ const manifestPath = options.manifestPath
1032
+ ? path.resolve(options.manifestPath)
1033
+ : (options.modelDir ? path.resolve(options.modelDir, 'manifest.json') : null);
1034
+ if (!manifestPath) {
1035
+ throw new Error('reference receipt: manifestPath or modelDir is required.');
1036
+ }
1037
+ const referenceTranscriptPath = options.referenceTranscriptPath
1038
+ ? path.resolve(options.referenceTranscriptPath)
1039
+ : null;
1040
+ const referenceTranscript = options.referenceTranscript ?? null;
1041
+ if (!referenceTranscriptPath && !referenceTranscript) {
1042
+ throw new Error('reference receipt: referenceTranscriptPath or referenceTranscript is required.');
1043
+ }
1044
+ return {
1045
+ ...options,
1046
+ repoRoot,
1047
+ manifestPath,
1048
+ referenceTranscriptPath,
1049
+ referenceTranscript,
1050
+ };
1051
+ }
1052
+
1053
+ export async function exportReferenceReceipt(options = {}) {
1054
+ const resolved = resolveReferenceReceiptOptions(options);
1055
+ const { raw: manifestRaw, json: manifest } = await readJsonFile(resolved.manifestPath, 'manifest');
1056
+ requirePlainObject(manifest, 'manifest');
1057
+ const modelId = requireString(manifest.modelId, 'manifest.modelId');
1058
+ const execution = manifest.inference?.execution;
1059
+ requirePlainObject(execution, 'manifest.inference.execution');
1060
+
1061
+ const expandedSteps = expandExecutionV1(execution);
1062
+ const executionGraphHash = hashStableJson(execution);
1063
+ const expandedStepHash = hashStableJson(expandedSteps);
1064
+
1065
+ let transcript = resolved.referenceTranscript;
1066
+ let transcriptSourcePath = null;
1067
+ if (!transcript) {
1068
+ const { json } = await readJsonFile(resolved.referenceTranscriptPath, 'reference transcript');
1069
+ transcript = json;
1070
+ transcriptSourcePath = toRepoRelativePath(resolved.referenceTranscriptPath, resolved.repoRoot);
1071
+ }
1072
+ const normalizedTranscript = normalizeReferenceTranscriptInput(transcript, executionGraphHash);
1073
+
1074
+ const manifestArtifact = {
1075
+ path: toRepoRelativePath(resolved.manifestPath, resolved.repoRoot),
1076
+ hash: `sha256:${sha256Hex(manifestRaw)}`,
1077
+ sizeBytes: Buffer.byteLength(manifestRaw),
1078
+ };
1079
+
1080
+ const weightSetHash = buildWeightSetHashFromManifest(manifest);
1081
+
1082
+ const receipt = {
1083
+ schema: REFERENCE_RECEIPT_SCHEMA_ID,
1084
+ receiptId:
1085
+ resolved.receiptId
1086
+ || `${modelId}-${executionGraphHash.slice('sha256:'.length, 'sha256:'.length + 12)}`,
1087
+ modelId,
1088
+ createdAtUtc: resolved.createdAtUtc || new Date().toISOString(),
1089
+ sources: {
1090
+ manifest: manifestArtifact,
1091
+ executionGraph: {
1092
+ schema: manifest.inference?.schema ?? null,
1093
+ hash: executionGraphHash,
1094
+ expandedStepHash,
1095
+ },
1096
+ weightSetHash,
1097
+ referenceTranscript: transcriptSourcePath
1098
+ ? { path: transcriptSourcePath }
1099
+ : { path: null },
1100
+ },
1101
+ referenceTranscript: normalizedTranscript,
1102
+ };
1103
+
1104
+ return receipt;
1105
+ }
1106
+
1107
+ export async function writeReferenceReceipt(options = {}) {
1108
+ const outputPath = options.outputPath ? path.resolve(options.outputPath) : null;
1109
+ if (!outputPath) {
1110
+ throw new Error('reference receipt: outputPath is required.');
1111
+ }
1112
+ const receipt = await exportReferenceReceipt(options);
1113
+ await fs.mkdir(path.dirname(outputPath), { recursive: true });
1114
+ await fs.writeFile(outputPath, `${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
1115
+ return {
1116
+ outputPath,
1117
+ receipt,
1118
+ };
1119
+ }