doppler-gpu 0.7.3 → 0.7.8

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 (776) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +9 -17
  3. package/package.json +5 -48
  4. package/src/capsule-runtime.d.ts +2 -2
  5. package/src/client/capsule-host.browser.js +4 -4
  6. package/src/client/capsule-host.d.ts +8 -8
  7. package/src/client/capsule-host.js +4 -4
  8. package/src/client/doppler-api.d.ts +2 -2
  9. package/src/client/inspection.d.ts +3 -0
  10. package/src/client/inspection.js +29 -0
  11. package/src/client/model-host/index.d.ts +5 -4
  12. package/src/client/model-host/index.js +28 -8
  13. package/src/client/model-host/model-evidence.js +2 -0
  14. package/src/client/model-host/model-session.d.ts +7 -5
  15. package/src/client/model-host/model-session.js +10 -3
  16. package/src/client/model-host/privacy-receipt.js +22 -0
  17. package/src/client/resident-partitions.d.ts +3 -3
  18. package/src/client/resident-partitions.js +2 -2
  19. package/src/client/runtime/capsule-acquisition.d.ts +3 -3
  20. package/src/client/runtime/capsule-acquisition.js +1 -1
  21. package/src/client/runtime/capsule-adapter-execution.d.ts +2 -2
  22. package/src/client/runtime/capsule-adapter-execution.js +3 -3
  23. package/src/client/runtime/capsule-embedding.d.ts +2 -2
  24. package/src/client/runtime/capsule-embedding.js +1 -1
  25. package/src/client/runtime/capsule-forecast.d.ts +2 -2
  26. package/src/client/runtime/capsule-forecast.js +1 -1
  27. package/src/client/runtime/capsule-operation-adapters.d.ts +1 -1
  28. package/src/client/runtime/capsule-operation-adapters.js +1 -1
  29. package/src/client/runtime/capsule-operation-deltas.js +1 -1
  30. package/src/client/runtime/capsule-operation-executor.d.ts +1 -1
  31. package/src/client/runtime/capsule-operation-executor.js +2 -2
  32. package/src/client/runtime/capsule-operation-stream.d.ts +1 -1
  33. package/src/client/runtime/capsule-operation-stream.js +2 -2
  34. package/src/client/runtime/capsule-piece-reader.js +1 -1
  35. package/src/client/runtime/capsule-program-adapter.js +1 -1
  36. package/src/client/runtime/capsule-release-authorization.js +1 -1
  37. package/src/client/runtime/capsule-rerank.d.ts +2 -2
  38. package/src/client/runtime/composition-root.d.ts +6 -6
  39. package/src/client/runtime/composition-root.js +6 -6
  40. package/src/client/runtime/fetch-capsule-artifact-store.d.ts +1 -1
  41. package/src/client/runtime/fetch-capsule-artifact-store.js +1 -1
  42. package/src/client/runtime/model-source.d.ts +4 -2
  43. package/src/client/runtime/model-source.js +5 -5
  44. package/src/client/runtime/scoped-session.d.ts +2 -2
  45. package/src/client/runtime/verified-capsule-artifact-store.d.ts +2 -2
  46. package/src/client/runtime/verified-capsule-artifact-store.js +1 -1
  47. package/src/config/backward-registry-loader.js +1 -1
  48. package/src/config/{capsule-adapter-policy.js → capsule/capsule-adapter-policy.js} +2 -2
  49. package/src/config/{capsule-adapters.d.ts → capsule/capsule-adapters.d.ts} +1 -1
  50. package/src/config/{capsule-adapters.js → capsule/capsule-adapters.js} +2 -2
  51. package/src/config/{capsule-loading.js → capsule/capsule-loading.js} +1 -1
  52. package/src/config/{capsule-operation.d.ts → capsule/capsule-operation.d.ts} +1 -1
  53. package/src/config/{capsule-operation.js → capsule/capsule-operation.js} +3 -3
  54. package/src/config/{capsule-release-contract.js → capsule/capsule-release-contract.js} +2 -2
  55. package/src/config/{capsule-release-events.d.ts → capsule/capsule-release-events.d.ts} +2 -1
  56. package/src/config/{capsule-release-events.js → capsule/capsule-release-events.js} +3 -2
  57. package/src/config/{capsule-sequence-receipt.js → capsule/capsule-sequence-receipt.js} +1 -1
  58. package/src/config/{capsule-token-selection.d.ts → capsule/capsule-token-selection.d.ts} +1 -1
  59. package/src/config/{capsule-token-selection.js → capsule/capsule-token-selection.js} +2 -2
  60. package/src/config/{capsule-v2.d.ts → capsule/capsule-v2.d.ts} +5 -4
  61. package/src/config/{capsule-v2.js → capsule/capsule-v2.js} +6 -6
  62. package/src/config/{capsule-v3.js → capsule/capsule-v3.js} +1 -1
  63. package/src/config/{capsule.js → capsule/capsule.js} +26 -7
  64. package/src/config/choice-scoring.js +1 -1
  65. package/src/config/conversion/amplify/amplify-120m-f16-af32.json +1 -1
  66. package/src/config/conversion/diffusiongemma/diffusiongemma-26b-a4b-it-q4k-ehf16-af16.json +1 -1
  67. package/src/config/conversion/embeddinggemma/google-embeddinggemma-300m-q4k-ehf16-af32.json +1 -1
  68. package/src/config/conversion/esm/esm2-t12-35m-ur50d-f32-af32.json +2 -2
  69. package/src/config/conversion/esmc/esmc-300m-f32-af32.json +1 -1
  70. package/src/config/conversion/gemma3/gemma-3-1b-it-f16-af32.json +1 -1
  71. package/src/config/conversion/gemma3/gemma-3-1b-it-q4k-ehf16-af32.json +1 -1
  72. package/src/config/conversion/gemma3/gemma-3-270m-it-f16-af32.json +1 -1
  73. package/src/config/conversion/gemma3/gemma-3-270m-it-q4k-ehf16-af16.json +1 -1
  74. package/src/config/conversion/gemma3/gemma-3-270m-it-q4k-ehf16-af32.json +1 -1
  75. package/src/config/conversion/gemma3/gemma-3-270m-it-w8a8-ehf16-af32.json +1 -1
  76. package/src/config/conversion/gemma3/translategemma-4b-1b-enes-q4k-ehf16-af32.json +1 -1
  77. package/src/config/conversion/gemma3/translategemma-4b-it-q4k-ehf16-af32.json +1 -1
  78. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-af16.json +8 -8
  79. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-af32.json +8 -8
  80. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-hq4k-af16.json +8 -8
  81. package/src/config/conversion/gemma4/gemma-4-12b-it-text-w4a16-ct-ehf16-af16.json +8 -8
  82. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af16.json +8 -8
  83. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af32.json +8 -8
  84. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af16-int4ple.json +8 -8
  85. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32-int4ple.json +8 -8
  86. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32.json +8 -8
  87. package/src/config/conversion/gemma4/gemma-4-moe-q4k-ehf16-af32.json +1 -1
  88. package/src/config/conversion/glmocr/glm-ocr-f16-af32.json +1 -1
  89. package/src/config/conversion/gpt-oss-20b-f16-xmxfp4.json +1 -1
  90. package/src/config/conversion/janus/janus-pro-1b-text-q4k-ehaf16.json +1 -1
  91. package/src/config/conversion/lfm2/lfm2.5-1.2b-instruct-q4k-ehf16-af32.json +1 -1
  92. package/src/config/conversion/minicpm/minicpm4-0-5b-f16-af32.json +1 -1
  93. package/src/config/conversion/muse-glimmer/muse-glimmer-30b-text-bf16-af32.json +1 -1
  94. package/src/config/conversion/muse-glimmer/muse-glimmer-30b-text-f16-af32.json +1 -1
  95. package/src/config/conversion/nucleotide-transformer/nucleotide-transformer-v2-50m-f32-af32.json +1 -1
  96. package/src/config/conversion/qwen3/qwen-3-4b-instruct-2507-q4k-ehf16-af32.json +2 -2
  97. package/src/config/conversion/qwen3/qwen-3-5-0-8b-canonical-f32.json +1 -1
  98. package/src/config/conversion/qwen3/qwen-3-5-0-8b-q4k-ehaf16.json +1 -1
  99. package/src/config/conversion/qwen3/qwen-3-5-2b-q4k-ehaf16.json +1 -1
  100. package/src/config/conversion/qwen3/qwen-3-5-9b-f16-af32.json +1 -1
  101. package/src/config/conversion/qwen3/qwen-3-5-9b-q4k-ehaf16.json +1 -1
  102. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-eaf16.json +1 -1
  103. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-ehaf16.json +1 -1
  104. package/src/config/conversion/qwen3/qwen-3-6-35b-a3b-q4_0-passthrough.json +1 -1
  105. package/src/config/conversion/qwen3/qwen-3-6-35b-a3b-text-q4k-ehf16-af32.json +1 -1
  106. package/src/config/conversion/qwen3/qwen-3-8-flash-next-text-q4k-ehf16-af32.json +25 -22
  107. package/src/config/conversion/qwen3/qwen-3-embedding-0-6b-f16-af32.json +2 -2
  108. package/src/config/conversion/qwen3/qwen-3-embedding-0-6b-q4k-ehf16-af32.json +1 -1
  109. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-f16-af32.json +1 -1
  110. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-f16-true-logit-af32.json +2 -2
  111. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-q4k-ehf16-af32.json +2 -2
  112. package/src/config/conversion/qwen3/qwen3.8-27b-q4_0-passthrough.json +1 -1
  113. package/src/config/conversion/qwen3/qwen3.8-27b-text-f16-af32.json +1 -1
  114. package/src/config/conversion/qwen3/qwen3.8-27b-text-q4k-ehaf16.json +1 -1
  115. package/src/config/conversion/qwen3/qwen4exp-gguf-source-policy.json +53 -0
  116. package/src/config/embedding-contract.d.ts +1 -1
  117. package/src/config/embedding-contract.js +1 -1
  118. package/src/config/execution-registry-contract.d.ts +5 -5
  119. package/src/config/execution-registry-contract.js +5 -5
  120. package/src/config/generation-contract.js +2 -1
  121. package/src/config/hardware-partition-plan.d.ts +32 -0
  122. package/src/config/hardware-partition-plan.js +78 -0
  123. package/src/config/inspection/observation-policies.json +1 -1
  124. package/src/config/kernel-path-loader.d.ts +1 -1
  125. package/src/config/kernel-path-loader.js +1 -1
  126. package/src/config/kernel-registry-contract.d.ts +2 -2
  127. package/src/config/kernel-registry-contract.js +1 -1
  128. package/src/config/kernels/kernel-ref-digests.js +509 -0
  129. package/src/config/kernels/registry.js +2 -2
  130. package/src/config/kernels/registry.json +2065 -1241
  131. package/src/config/layer-partition-plan.d.ts +4 -0
  132. package/src/config/layer-partition-plan.js +10 -4
  133. package/src/config/merge.js +1 -1
  134. package/src/config/model-session-declarations.js +85 -0
  135. package/src/config/param-validator.js +3 -3
  136. package/src/config/platforms/amd-rdna3.json +2 -2
  137. package/src/config/production-release-evidence.js +1 -1
  138. package/src/config/revocation-policy.js +6 -2
  139. package/src/config/revocation-registry.json +1 -1
  140. package/src/config/runtime/model-sessions.json +23 -0
  141. package/src/config/runtime/profiles/flash-next-gguf-control-gemv.json +72 -0
  142. package/src/config/runtime/profiles/flash-next-gguf-hc-inject-gemv.json +47 -0
  143. package/src/config/schema/capsule/index.d.ts +14 -0
  144. package/src/config/schema/capsule/index.js +10 -0
  145. package/src/config/schema/{program-bundle.schema.d.ts → capsule/program-bundle.schema.d.ts} +3 -3
  146. package/src/config/schema/{program-bundle.schema.js → capsule/program-bundle.schema.js} +6 -6
  147. package/src/config/schema/{execution-v1.schema.d.ts → execution/execution-v1.schema.d.ts} +2 -0
  148. package/src/config/schema/{execution-v1.schema.js → execution/execution-v1.schema.js} +2 -2
  149. package/src/config/schema/execution/index.d.ts +203 -0
  150. package/src/config/schema/execution/index.js +94 -0
  151. package/src/config/schema/{inference.schema.d.ts → execution/inference.schema.d.ts} +1 -1
  152. package/src/config/schema/{kernel-path.schema.d.ts → execution/kernel-path.schema.d.ts} +3 -0
  153. package/src/config/schema/{kernel-registry.schema.d.ts → execution/kernel-registry.schema.d.ts} +2 -2
  154. package/src/config/schema/{kernel-thresholds.schema.d.ts → execution/kernel-thresholds.schema.d.ts} +1 -1
  155. package/src/config/schema/{kernel-thresholds.schema.js → execution/kernel-thresholds.schema.js} +1 -1
  156. package/src/config/schema/{kernel-warmup.schema.d.ts → execution/kernel-warmup.schema.d.ts} +14 -0
  157. package/src/config/schema/{kernel-warmup.schema.js → execution/kernel-warmup.schema.js} +3 -0
  158. package/src/config/schema/{kvcache.schema.d.ts → execution/kvcache.schema.d.ts} +8 -2
  159. package/src/config/schema/{kvcache.schema.js → execution/kvcache.schema.js} +17 -1
  160. package/src/config/schema/{ngram-embedding.schema.d.ts → execution/ngram-embedding.schema.d.ts} +3 -1
  161. package/src/config/schema/{ngram-embedding.schema.js → execution/ngram-embedding.schema.js} +16 -1
  162. package/src/config/schema/index.d.ts +8 -897
  163. package/src/config/schema/index.js +8 -506
  164. package/src/config/schema/{converter.schema.d.ts → manifest/converter.schema.d.ts} +4 -4
  165. package/src/config/schema/{converter.schema.js → manifest/converter.schema.js} +1 -1
  166. package/src/config/schema/manifest/index.d.ts +142 -0
  167. package/src/config/schema/manifest/index.js +62 -0
  168. package/src/config/schema/manifest/manifest-inference.schema.d.ts +298 -0
  169. package/src/config/schema/{manifest.schema.d.ts → manifest/manifest.schema.d.ts} +9 -291
  170. package/src/config/schema/{manifest.schema.js → manifest/manifest.schema.js} +2 -2
  171. package/src/config/schema/{emulation.schema.d.ts → platform/emulation.schema.d.ts} +1 -1
  172. package/src/config/schema/{emulation.schema.js → platform/emulation.schema.js} +6 -6
  173. package/src/config/schema/{gpu-cache.schema.js → platform/gpu-cache.schema.js} +1 -1
  174. package/src/config/schema/platform/index.d.ts +72 -0
  175. package/src/config/schema/platform/index.js +27 -0
  176. package/src/config/schema/{memory-limits.schema.js → platform/memory-limits.schema.js} +1 -1
  177. package/src/config/schema/policy/index.d.ts +14 -0
  178. package/src/config/schema/policy/index.js +9 -0
  179. package/src/config/schema/{buffer-pool.schema.js → runtime/buffer-pool.schema.js} +2 -2
  180. package/src/config/schema/{doppler.schema.d.ts → runtime/doppler.schema.d.ts} +3 -3
  181. package/src/config/schema/{doppler.schema.js → runtime/doppler.schema.js} +12 -12
  182. package/src/config/schema/runtime/index.d.ts +238 -0
  183. package/src/config/schema/runtime/index.js +135 -0
  184. package/src/config/schema/{loading.schema.d.ts → runtime/loading.schema.d.ts} +31 -1
  185. package/src/config/schema/runtime/loading.schema.js +275 -0
  186. package/src/config/schema/{shared-runtime.schema.d.ts → runtime/shared-runtime.schema.d.ts} +5 -5
  187. package/src/config/schema/{shared-runtime.schema.js → runtime/shared-runtime.schema.js} +4 -4
  188. package/src/config/schema/{tooling.schema.d.ts → runtime/tooling.schema.d.ts} +1 -1
  189. package/src/config/schema/training/index.d.ts +63 -0
  190. package/src/config/schema/training/index.js +43 -0
  191. package/src/config/schema/{lora.schema.js → training/lora.schema.js} +1 -1
  192. package/src/config/source-packages/litert/gemma-4-e2b-it.json +1 -1
  193. package/src/config/supported-operations.json +358 -88
  194. package/src/config/target-plan.d.ts +2 -2
  195. package/src/config/target-plan.js +2 -2
  196. package/src/config/training-defaults.d.ts +2 -2
  197. package/src/config/training-defaults.js +2 -2
  198. package/src/config/transforms/execution-graph/correctness-fallback.js +86 -0
  199. package/src/config/transforms/execution-graph/prefill-attention.js +116 -0
  200. package/src/{converter → config/transforms}/execution-graph-transforms.js +5 -194
  201. package/src/converter/core.js +18 -164
  202. package/src/converter/forge-stages.js +2 -2
  203. package/src/converter/fp8-source.js +1 -1
  204. package/src/converter/gemma4/validation.js +110 -0
  205. package/src/converter/linear-norm-gate.js +1 -1
  206. package/src/converter/manifest-builder.js +2 -9
  207. package/src/converter/parsers/gguf.js +54 -4
  208. package/src/converter/quantization-info.js +2 -2
  209. package/src/converter/qwen4-exp-source-execution.js +94 -0
  210. package/src/converter/qwen4-exp-source.js +1 -201
  211. package/src/converter/tensor-transform.js +2 -9
  212. package/src/converter/tokenizer-contract.js +2 -9
  213. package/src/converter/w8a8-quantizer.js +2 -2
  214. package/src/debug/config.js +1 -1
  215. package/src/debug/perf-guards.js +1 -1
  216. package/src/errors/doppler-error.d.ts +54 -0
  217. package/src/errors/doppler-error.js +13 -5
  218. package/src/experimental/distribution/shard-delivery/receipt.js +1 -1
  219. package/src/experimental/distribution/shard-delivery/retry.js +4 -4
  220. package/src/experimental/energy/types.d.ts +1 -1
  221. package/src/experimental/logits/cpu-output.js +1 -1
  222. package/src/experimental/training/artifacts.d.ts +2 -2
  223. package/src/experimental/training/artifacts.js +2 -2
  224. package/src/experimental/training/autograd.d.ts +1 -1
  225. package/src/experimental/training/distillation/student-fixture/execution.js +1 -1
  226. package/src/experimental/training/distillation/student-fixture/model.js +1 -1
  227. package/src/experimental/training/distillation/student-fixture.js +1 -1
  228. package/src/experimental/training/loss-scaling.d.ts +1 -1
  229. package/src/experimental/training/runner/evaluation.js +1 -1
  230. package/src/experimental/training/runner.js +1 -1
  231. package/src/experimental/training/trainer.d.ts +1 -1
  232. package/src/experimental/training/workloads.js +2 -2
  233. package/src/formats/gguf/block-storage.d.ts +9 -0
  234. package/src/formats/gguf/block-storage.js +12 -3
  235. package/src/formats/gguf/qwen-source.js +5 -3
  236. package/src/formats/gguf/qwen-source.json +8 -1
  237. package/src/formats/gguf/qwen4-exp-source.js +101 -0
  238. package/src/formats/q4k-dequant.js +1 -1
  239. package/src/formats/qwen4-exp-source-contracts.js +204 -0
  240. package/src/formats/rdrr/fp8-contract.js +1 -1
  241. package/src/formats/rdrr/fp8-storage.js +1 -1
  242. package/src/formats/rdrr/q4_0-storage.js +1 -1
  243. package/src/formats/rdrr/storage-descriptor.js +1 -1
  244. package/src/formats/rdrr/tensor-config-validator.js +3 -3
  245. package/src/formats/rdrr/validation.js +1 -1
  246. package/src/formats/rdrr/w8a8-storage.js +1 -1
  247. package/src/generation/index.d.ts +1 -1
  248. package/src/generation/index.js +1 -0
  249. package/src/gpu/device.d.ts +1 -1
  250. package/src/gpu/kernels/attention/contiguous-quantized.js +252 -0
  251. package/src/gpu/kernels/attention/tiered-quantized.js +321 -0
  252. package/src/gpu/kernels/attention/tiered.js +240 -0
  253. package/src/gpu/kernels/attention.js +5 -801
  254. package/src/gpu/kernels/backward/layernorm_backward.wgsl +3 -3
  255. package/src/gpu/kernels/channel-gain.js +100 -0
  256. package/src/gpu/kernels/channel-rotation.d.ts +16 -0
  257. package/src/gpu/kernels/channel-rotation.js +47 -0
  258. package/src/gpu/kernels/channel_energy.wgsl +17 -0
  259. package/src/gpu/kernels/channel_energy_pair.wgsl +27 -0
  260. package/src/gpu/kernels/channel_gain_control.wgsl +60 -0
  261. package/src/gpu/kernels/channel_gain_derive.wgsl +40 -0
  262. package/src/gpu/kernels/channel_gain_swiglu.wgsl +64 -0
  263. package/src/gpu/kernels/channel_rotation_apply.wgsl +38 -0
  264. package/src/gpu/kernels/channel_rotation_derive.wgsl +76 -0
  265. package/src/gpu/kernels/check-finiteness-f32.js +22 -0
  266. package/src/gpu/kernels/check_finiteness.wgsl +2 -2
  267. package/src/gpu/kernels/clamp.js +2 -2
  268. package/src/gpu/kernels/dequant.js +1 -1
  269. package/src/gpu/kernels/dispatch.js +7 -0
  270. package/src/gpu/kernels/energy_quintel_grad.wgsl +7 -7
  271. package/src/gpu/kernels/energy_quintel_grad_f16.wgsl +7 -7
  272. package/src/gpu/kernels/energy_quintel_reduce.wgsl +6 -6
  273. package/src/gpu/kernels/energy_quintel_reduce_f16.wgsl +6 -6
  274. package/src/gpu/kernels/energy_quintel_update.wgsl +7 -7
  275. package/src/gpu/kernels/energy_quintel_update_f16.wgsl +7 -7
  276. package/src/gpu/kernels/fused_matmul_q4_widetile_f32.wgsl +174 -0
  277. package/src/gpu/kernels/fused_matmul_rmsnorm.wgsl +0 -49
  278. package/src/gpu/kernels/gated-delta-norm-gate.js +1 -1
  279. package/src/gpu/kernels/gated_delta_recurrent_gguf_register_prefill_sigmoid_gate.wgsl +730 -0
  280. package/src/gpu/kernels/gated_delta_recurrent_gguf_sigmoid_gate.wgsl +499 -0
  281. package/src/gpu/kernels/gather.js +16 -1
  282. package/src/gpu/kernels/gather_split4_packed_f16_vec4_f32_out.wgsl +104 -0
  283. package/src/gpu/kernels/generated/uniform-writers-0.js +7 -11
  284. package/src/gpu/kernels/generated/uniform-writers-1.js +43 -46
  285. package/src/gpu/kernels/generated/uniform-writers-2.js +80 -2
  286. package/src/gpu/kernels/generated/uniform-writers.js +33 -21
  287. package/src/gpu/kernels/hyper-connection-up.js +64 -0
  288. package/src/gpu/kernels/hyper-connection.js +15 -4
  289. package/src/gpu/kernels/hyper_connection_mix_branch.wgsl +105 -0
  290. package/src/gpu/kernels/hyper_connection_norm.wgsl +3 -3
  291. package/src/gpu/kernels/hyper_connection_up_mix_branch_q4_0.wgsl +164 -0
  292. package/src/gpu/kernels/kernel-execution.js +18 -7
  293. package/src/gpu/kernels/linear-attention-core.js +3 -4
  294. package/src/gpu/kernels/moe-route.js +14 -0
  295. package/src/gpu/kernels/moe_gather.wgsl +0 -63
  296. package/src/gpu/kernels/moe_route_q4_0_block_f32.wgsl +74 -0
  297. package/src/gpu/kernels/moe_route_q4_0_split_block_f32.wgsl +80 -0
  298. package/src/gpu/kernels/moe_route_q4_1_block_f32.wgsl +59 -0
  299. package/src/gpu/kernels/moe_route_remap.wgsl +22 -0
  300. package/src/gpu/kernels/paired-linear-attention.js +1 -1
  301. package/src/gpu/kernels/pipeline-cache.js +18 -2
  302. package/src/gpu/kernels/ple.js +11 -7
  303. package/src/gpu/kernels/ple_q4_0_to_f32.wgsl +32 -0
  304. package/src/gpu/kernels/qsa-indexer.d.ts +2 -0
  305. package/src/gpu/kernels/qsa-indexer.js +6 -4
  306. package/src/gpu/kernels/qsa_block_keys.wgsl +2 -1
  307. package/src/gpu/kernels/qsa_prepare.wgsl +2 -1
  308. package/src/gpu/kernels/relu.js +1 -1
  309. package/src/gpu/kernels/relu.wgsl +2 -2
  310. package/src/gpu/kernels/relu_f16.wgsl +2 -2
  311. package/src/gpu/kernels/residual.js +1 -1
  312. package/src/gpu/kernels/residual.wgsl +4 -4
  313. package/src/gpu/kernels/residual_f16.wgsl +2 -2
  314. package/src/gpu/kernels/residual_f16_vec4.wgsl +2 -2
  315. package/src/gpu/kernels/residual_vec4.wgsl +2 -2
  316. package/src/gpu/kernels/rope-precompute.js +1 -1
  317. package/src/gpu/kernels/scatter_add.wgsl +0 -31
  318. package/src/gpu/kernels/shader-cache.js +17 -3
  319. package/src/gpu/kernels/shader-capability-filter.js +120 -0
  320. package/src/gpu/kernels/softmax.js +10 -10
  321. package/src/gpu/kernels/topk.wgsl +0 -55
  322. package/src/gpu/kernels/transpose.js +1 -1
  323. package/src/gpu/kernels/transpose.wgsl +2 -2
  324. package/src/gpu/kernels/w8a8.js +1 -1
  325. package/src/gpu/uniform-cache.d.ts +15 -1
  326. package/src/gpu/uniform-cache.js +82 -7
  327. package/src/gpu/weight-buffer.d.ts +1 -1
  328. package/src/inference/moe-router.d.ts +1 -126
  329. package/src/inference/moe-router.js +0 -149
  330. package/src/inference/pipelines/context.js +3 -15
  331. package/src/inference/pipelines/shader-scoped-pipeline.js +10 -5
  332. package/src/inference/pipelines/text/attention/interpreter/immediate.js +4 -4
  333. package/src/inference/pipelines/text/attention/interpreter/output.js +203 -0
  334. package/src/inference/pipelines/text/attention/interpreter/recorded.js +92 -67
  335. package/src/inference/pipelines/text/attention/interpreter.js +77 -350
  336. package/src/inference/pipelines/text/attention/projection-executor.js +2 -2
  337. package/src/inference/pipelines/text/attention/projection-plan.js +1 -1
  338. package/src/inference/pipelines/text/attention/projection-precision.js +132 -0
  339. package/src/inference/pipelines/text/attention/projections.js +13 -151
  340. package/src/inference/pipelines/text/attention/recorded-health.js +83 -0
  341. package/src/inference/pipelines/text/attention/rope-observation.js +1 -1
  342. package/src/inference/pipelines/text/attention/types.js +0 -13
  343. package/src/inference/pipelines/text/config/normalization.js +2 -2
  344. package/src/inference/pipelines/text/config.d.ts +4 -4
  345. package/src/inference/pipelines/text/config.js +17 -135
  346. package/src/inference/pipelines/text/{config-components.js → configuration/config-components.js} +4 -4
  347. package/src/inference/pipelines/text/configuration/model-geometry.js +114 -0
  348. package/src/inference/pipelines/text/{resolved-runtime-session.d.ts → configuration/resolved-runtime-session.d.ts} +4 -4
  349. package/src/inference/pipelines/text/{resolved-runtime-session.js → configuration/resolved-runtime-session.js} +1 -1
  350. package/src/inference/pipelines/text/{abort-contract.js → contracts/abort-contract.js} +2 -1
  351. package/src/inference/pipelines/text/contracts/metrics.d.ts +234 -0
  352. package/src/inference/pipelines/text/{embed.js → embedding/embed.js} +15 -15
  353. package/src/inference/pipelines/text/{embedding-batch.js → embedding/embedding-batch.js} +1 -1
  354. package/src/inference/pipelines/text/{embedding-extraction.js → embedding/embedding-extraction.js} +12 -12
  355. package/src/inference/pipelines/text/{embedding-normalization.js → embedding/embedding-normalization.js} +4 -4
  356. package/src/inference/pipelines/text/{execution-plan.d.ts → execution/execution-plan.d.ts} +8 -8
  357. package/src/inference/pipelines/text/{execution-plan.js → execution/execution-plan.js} +9 -9
  358. package/src/inference/pipelines/text/{execution-runtime-builders.js → execution/execution-runtime-builders.js} +3 -3
  359. package/src/inference/pipelines/text/{execution-v1.d.ts → execution/execution-v1.d.ts} +2 -2
  360. package/src/inference/pipelines/text/{execution-v1.js → execution/execution-v1.js} +13 -183
  361. package/src/inference/pipelines/text/execution/layer-contract.js +90 -0
  362. package/src/inference/pipelines/text/{layer-execution-contract.js → execution/layer-execution-contract.js} +2 -2
  363. package/src/inference/pipelines/text/{layer-input-execution.js → execution/layer-input-execution.js} +27 -36
  364. package/src/inference/pipelines/text/{layer-partition-contract.d.ts → execution/layer-partition-contract.d.ts} +3 -3
  365. package/src/inference/pipelines/text/{layer-partition-contract.js → execution/layer-partition-contract.js} +2 -2
  366. package/src/inference/pipelines/text/{layer-plan-gpu.js → execution/layer-plan-gpu.js} +12 -12
  367. package/src/inference/pipelines/text/{layer-plan.d.ts → execution/layer-plan.d.ts} +1 -1
  368. package/src/inference/pipelines/text/{layer-plan.js → execution/layer-plan.js} +1 -1
  369. package/src/inference/pipelines/text/{layer.js → execution/layer.js} +34 -142
  370. package/src/inference/pipelines/text/{operator-identity.js → execution/operator-identity.js} +1 -1
  371. package/src/inference/pipelines/text/{ops.js → execution/ops.js} +26 -26
  372. package/src/inference/pipelines/text/{paired-execution.js → execution/paired-execution.js} +9 -9
  373. package/src/inference/pipelines/text/execution-v1/hybrid-projection-contract.js +159 -0
  374. package/src/inference/pipelines/text/expert-loading-stats.d.ts +16 -0
  375. package/src/inference/pipelines/text/expert-loading-stats.js +15 -0
  376. package/src/inference/pipelines/text/ffn/dense-executor.js +5 -4
  377. package/src/inference/pipelines/text/ffn/dense-plan.js +23 -34
  378. package/src/inference/pipelines/text/ffn/dense.js +72 -392
  379. package/src/inference/pipelines/text/ffn/fused-gate-up.js +197 -0
  380. package/src/inference/pipelines/text/ffn/moe.js +1 -1
  381. package/src/inference/pipelines/text/ffn/packed-gate-up.js +218 -0
  382. package/src/inference/pipelines/text/ffn/paired.js +3 -3
  383. package/src/inference/pipelines/text/ffn/qwen-shared-expert.js +1 -1
  384. package/src/inference/pipelines/text/ffn/sandwich.js +6 -7
  385. package/src/inference/pipelines/text/ffn/standard.js +5 -5
  386. package/src/inference/pipelines/text/ffn/types.js +6 -3
  387. package/src/inference/pipelines/text/{activity-weights.js → generator/activation/activity-weights.js} +8 -8
  388. package/src/inference/pipelines/text/generator/activation/channel-gain.d.ts +61 -0
  389. package/src/inference/pipelines/text/generator/activation/channel-gain.js +352 -0
  390. package/src/inference/pipelines/text/generator/activation/final-layer-replay.js +43 -0
  391. package/src/inference/pipelines/text/generator/{capsule-generation.js → adapters/capsule-generation.js} +5 -5
  392. package/src/inference/pipelines/text/generator/{diffusion.js → adapters/diffusion.js} +19 -19
  393. package/src/inference/pipelines/text/generator/{training.js → adapters/training.js} +21 -21
  394. package/src/inference/pipelines/text/generator/decode/advance-token.js +73 -0
  395. package/src/inference/pipelines/text/{generator-steps.js → generator/decode/batch-generation.js} +25 -288
  396. package/src/inference/pipelines/text/generator/decode/batch-readback.js +175 -0
  397. package/src/inference/pipelines/text/generator/{compiled-greedy-window.js → decode/compiled-greedy-window.js} +5 -5
  398. package/src/inference/pipelines/text/generator/{decode-components.js → decode/decode-components.js} +1 -1
  399. package/src/inference/pipelines/text/generator/{decode-runtime.js → decode/decode-loop.js} +20 -412
  400. package/src/inference/pipelines/text/generator/decode/decode-mechanics.js +288 -0
  401. package/src/inference/pipelines/text/generator/{decode-readback.js → decode/decode-readback.js} +1 -1
  402. package/src/inference/pipelines/text/generator/decode/decode-runtime.js +2 -0
  403. package/src/inference/pipelines/text/generator/{decode.js → decode/decode-step.js} +34 -313
  404. package/src/inference/pipelines/text/generator/decode/decode.js +5 -0
  405. package/src/inference/pipelines/text/generator/{greedy-head-policy.js → decode/greedy-head-policy.js} +1 -1
  406. package/src/inference/pipelines/text/generator/{recorded-step-executor.js → decode/recorded-step-executor.js} +2 -2
  407. package/src/inference/pipelines/text/generator/generator-steps.js +4 -0
  408. package/src/inference/pipelines/text/{generator.d.ts → generator/generator.d.ts} +13 -11
  409. package/src/inference/pipelines/text/{generator.js → generator/generator.js} +150 -46
  410. package/src/inference/pipelines/text/generator/{prefill-runtime.js → prefill/prefill-execution.js} +72 -278
  411. package/src/inference/pipelines/text/generator/prefill/prefill-logits.js +144 -0
  412. package/src/inference/pipelines/text/generator/{prefill-observation.js → prefill/prefill-observation.js} +2 -2
  413. package/src/inference/pipelines/text/generator/{prefill-policy.js → prefill/prefill-policy.js} +6 -1
  414. package/src/inference/pipelines/text/generator/prefill/prefill-runtime.js +2 -0
  415. package/src/inference/pipelines/text/generator/prefill/prefill-sequence.js +100 -0
  416. package/src/inference/pipelines/text/generator/{prefix-embedding.js → prefill/prefix-embedding.js} +7 -7
  417. package/src/inference/pipelines/text/{generation-request.d.ts → generator/request/generation-request.d.ts} +2 -2
  418. package/src/inference/pipelines/text/{generation-request.js → generator/request/generation-request.js} +3 -3
  419. package/src/inference/pipelines/text/generator/{prompt-input.js → request/prompt-input.js} +2 -2
  420. package/src/inference/pipelines/text/{sampling-config.d.ts → generator/sampling/sampling-config.d.ts} +1 -1
  421. package/src/inference/pipelines/text/{sampling-config.js → generator/sampling/sampling-config.js} +2 -2
  422. package/src/inference/pipelines/text/{sampling.d.ts → generator/sampling/sampling.d.ts} +15 -0
  423. package/src/inference/pipelines/text/{sampling.js → generator/sampling/sampling.js} +22 -3
  424. package/src/inference/pipelines/text/{stopping.js → generator/sampling/stopping.js} +3 -3
  425. package/src/inference/pipelines/text/generator/{token-selection.d.ts → sampling/token-selection.d.ts} +1 -1
  426. package/src/inference/pipelines/text/generator/{token-selection.js → sampling/token-selection.js} +8 -8
  427. package/src/inference/pipelines/text/generator/{activation-storage.js → session/activation-storage.js} +2 -2
  428. package/src/inference/pipelines/text/generator/{attention-lifecycle.js → session/attention-lifecycle.js} +1 -1
  429. package/src/inference/pipelines/text/generator/{diagnostic-sequence.d.ts → session/diagnostic-sequence.d.ts} +3 -3
  430. package/src/inference/pipelines/text/generator/{diagnostic-sequence.js → session/diagnostic-sequence.js} +3 -3
  431. package/src/inference/pipelines/text/generator/session/generation-runtime.js +278 -0
  432. package/src/inference/pipelines/text/{generator-runtime.d.ts → generator/session/generator-runtime.d.ts} +7 -7
  433. package/src/inference/pipelines/text/{generator-runtime.js → generator/session/generator-runtime.js} +8 -8
  434. package/src/inference/pipelines/text/generator/{recovery.js → session/recovery.js} +6 -6
  435. package/src/inference/pipelines/text/{sequence-state.d.ts → generator/session/sequence-state.d.ts} +5 -5
  436. package/src/inference/pipelines/text/{sequence-state.js → generator/session/sequence-state.js} +26 -18
  437. package/src/inference/pipelines/text/generator/{session-context.js → session/session-context.js} +12 -11
  438. package/src/inference/pipelines/text/generator/{speculative-runtime.js → session/speculative-runtime.js} +1 -1
  439. package/src/inference/pipelines/text/generator/{text.js → session/text.js} +9 -9
  440. package/src/inference/pipelines/text/{warm-generation.d.ts → generator/session/warm-generation.d.ts} +1 -1
  441. package/src/inference/pipelines/text/{warm-generation.js → generator/session/warm-generation.js} +1 -1
  442. package/src/inference/pipelines/text/generator/{whole-token-lane.js → whole-token/whole-token-lane.js} +10 -10
  443. package/src/inference/pipelines/text/generator/{whole-token-observation.d.ts → whole-token/whole-token-observation.d.ts} +2 -2
  444. package/src/inference/pipelines/text/generator/{whole-token-observation.js → whole-token/whole-token-observation.js} +5 -5
  445. package/src/inference/pipelines/text/generator/{whole-token-program.d.ts → whole-token/whole-token-program.d.ts} +3 -3
  446. package/src/inference/pipelines/text/generator/{whole-token-program.js → whole-token/whole-token-program.js} +5 -5
  447. package/src/inference/pipelines/text/hyper-connection/decoder-layer.d.ts +17 -4
  448. package/src/inference/pipelines/text/hyper-connection/decoder-layer.js +38 -14
  449. package/src/inference/pipelines/text/hyper-connection/layer-executor.js +14 -9
  450. package/src/inference/pipelines/text/hyper-connection/logits-input.js +5 -3
  451. package/src/inference/pipelines/text/hyper-connection/projection.js +52 -2
  452. package/src/inference/pipelines/text/hyper-connection/sequence-transaction.js +3 -3
  453. package/src/inference/pipelines/text/hyper-connection/session.d.ts +1 -1
  454. package/src/inference/pipelines/text/hyper-connection/session.js +9 -5
  455. package/src/inference/pipelines/text/indexed-attention/qsa-cache.d.ts +2 -1
  456. package/src/inference/pipelines/text/indexed-attention/qsa-cache.js +3 -3
  457. package/src/inference/pipelines/text/init.d.ts +4 -2
  458. package/src/inference/pipelines/text/init.js +10 -934
  459. package/src/inference/pipelines/text/initialization/init-emulation.js +76 -0
  460. package/src/inference/pipelines/text/initialization/init-kv-cache.js +547 -0
  461. package/src/inference/pipelines/text/initialization/init-moe.js +34 -0
  462. package/src/inference/pipelines/text/{init-qkv-fusion.js → initialization/init-qkv-fusion.js} +7 -7
  463. package/src/inference/pipelines/text/{init-rope.d.ts → initialization/init-rope.d.ts} +4 -4
  464. package/src/inference/pipelines/text/{init-rope.js → initialization/init-rope.js} +9 -11
  465. package/src/inference/pipelines/text/initialization/init-speculative.js +31 -0
  466. package/src/inference/pipelines/text/{init-tokenizer.js → initialization/init-tokenizer.js} +2 -2
  467. package/src/inference/pipelines/text/lifecycle.js +18 -18
  468. package/src/inference/pipelines/text/{linear-attention-ab-fusion.js → linear-attention/linear-attention-ab-fusion.js} +3 -3
  469. package/src/inference/pipelines/text/{linear-attention.d.ts → linear-attention/linear-attention.d.ts} +12 -12
  470. package/src/inference/pipelines/text/{linear-attention.js → linear-attention/linear-attention.js} +17 -17
  471. package/src/inference/pipelines/text/linear-attention/plan.js +4 -4
  472. package/src/inference/pipelines/text/linear-attention/state-checkpoint.js +1 -1
  473. package/src/inference/pipelines/text/linear-attention/state-clone.js +1 -1
  474. package/src/inference/pipelines/text/linear-attention/state-layout.js +2 -2
  475. package/src/inference/pipelines/text/loading/decode-session-config.js +295 -0
  476. package/src/inference/pipelines/text/loading/init-weights.js +254 -0
  477. package/src/inference/pipelines/text/{load-errors.js → loading/load-errors.js} +3 -3
  478. package/src/inference/pipelines/text/{model-load.js → loading/model-load.js} +14 -306
  479. package/src/inference/pipelines/text/{weight-loading-config.js → loading/weight-loading-config.js} +6 -6
  480. package/src/inference/pipelines/text/{weights.d.ts → loading/weights.d.ts} +13 -13
  481. package/src/inference/pipelines/text/{weights.js → loading/weights.js} +5 -5
  482. package/src/inference/pipelines/text/logits/gpu-executor.js +2 -2
  483. package/src/inference/pipelines/text/logits/gpu.d.ts +4 -4
  484. package/src/inference/pipelines/text/logits/gpu.js +2 -2
  485. package/src/inference/pipelines/text/{generator → logits}/hidden-projection.js +1 -1
  486. package/src/inference/pipelines/text/logits/index.d.ts +1 -1
  487. package/src/inference/pipelines/text/logits/index.js +3 -3
  488. package/src/inference/pipelines/text/{generator → logits}/logits-config.js +1 -1
  489. package/src/inference/pipelines/text/logits/output-transform.js +1 -1
  490. package/src/inference/pipelines/text/logits/precision-policy.js +1 -1
  491. package/src/inference/pipelines/text/logits/types.d.ts +2 -2
  492. package/src/inference/pipelines/text/lora-types.d.ts +1 -1
  493. package/src/inference/pipelines/text/moe/expert-loading.js +4 -1
  494. package/src/inference/pipelines/text/moe/gpu-executor.js +44 -101
  495. package/src/inference/pipelines/text/moe/grouped-prefill.js +6 -2
  496. package/src/inference/pipelines/text/moe/qwen-route-executor.d.ts +2 -2
  497. package/src/inference/pipelines/text/moe/qwen-route-executor.js +31 -2
  498. package/src/inference/pipelines/text/moe/routed-expert-chunks.js +99 -15
  499. package/src/inference/pipelines/text/moe-cache.js +11 -77
  500. package/src/inference/pipelines/text/moe-gpu.js +33 -75
  501. package/src/inference/pipelines/text/moe-impl.d.ts +3 -38
  502. package/src/inference/pipelines/text/moe-impl.js +1 -7
  503. package/src/inference/pipelines/text/ngram/ngram-addresses.d.ts +1 -1
  504. package/src/inference/pipelines/text/ngram/ngram-addresses.js +2 -2
  505. package/src/inference/pipelines/text/ngram/ngram-table.d.ts +3 -3
  506. package/src/inference/pipelines/text/ngram/ngram-table.js +5 -6
  507. package/src/inference/pipelines/text/ngram/ple-layer.d.ts +3 -3
  508. package/src/inference/pipelines/text/ngram/ple-layer.js +3 -3
  509. package/src/inference/pipelines/text/{generator-logits-observation.js → observation/generator-logits-observation.js} +4 -4
  510. package/src/inference/pipelines/text/{kernel-trace.js → observation/kernel-trace.js} +1 -1
  511. package/src/inference/pipelines/text/{operator-events.js → observation/operator-events.js} +1 -1
  512. package/src/inference/pipelines/text/{probes.js → observation/probes.js} +13 -13
  513. package/src/inference/pipelines/text/{tsir-fixture-writer.js → observation/tsir-fixture-writer.js} +3 -3
  514. package/src/inference/pipelines/text/{execution.js → operations/execution.js} +14 -14
  515. package/src/inference/pipelines/text/{image-transcription.js → operations/image-transcription.js} +8 -8
  516. package/src/inference/pipelines/text/{partition-attempt.js → partitions/partition-attempt.js} +7 -7
  517. package/src/inference/pipelines/text/{partition-execution.js → partitions/partition-execution.js} +107 -35
  518. package/src/inference/pipelines/text/partitions/partition-wire.js +50 -0
  519. package/src/inference/pipelines/text/{resident-partition-contract.d.ts → partitions/resident-partition-contract.d.ts} +10 -8
  520. package/src/inference/pipelines/text/{resident-partition-contract.js → partitions/resident-partition-contract.js} +6 -6
  521. package/src/inference/pipelines/text/partitions/resident-partition-warmup.js +67 -0
  522. package/src/inference/pipelines/text/{resident-partition.js → partitions/resident-partition.js} +27 -15
  523. package/src/inference/pipelines/text/{resident-pipeline-preparation.js → partitions/resident-pipeline-preparation.js} +32 -32
  524. package/src/inference/pipelines/text/per-layer/materialize.js +4 -4
  525. package/src/inference/pipelines/text/per-layer/per-layer-inputs.js +5 -0
  526. package/src/inference/pipelines/text/per-layer/plan.js +4 -4
  527. package/src/inference/pipelines/text/{per-layer-inputs.js → per-layer/prepare.js} +14 -280
  528. package/src/inference/pipelines/text/per-layer/projection-contract.js +79 -0
  529. package/src/inference/pipelines/text/per-layer/runtime-cache.js +183 -0
  530. package/src/inference/pipelines/text/pipeline.d.ts +13 -8
  531. package/src/inference/pipelines/text/pipeline.js +78 -22
  532. package/src/inference/pipelines/text/{drift-policy.js → policy/drift-policy.js} +1 -1
  533. package/src/inference/pipelines/text/{dtype-contract.js → policy/dtype-contract.js} +2 -2
  534. package/src/inference/pipelines/text/{finiteness-guard-status.js → policy/finiteness-guard-status.js} +2 -1
  535. package/src/inference/pipelines/text/{generator-decode-policy.js → policy/generator-decode-policy.js} +5 -5
  536. package/src/inference/pipelines/text/state.d.ts +9 -8
  537. package/src/inference/pipelines/text/state.js +1 -0
  538. package/src/inference/pipelines/text/types.d.ts +14 -218
  539. package/src/inference/pipelines/text.js +2 -0
  540. package/src/inference/tokenizers/bundled/merge.js +130 -0
  541. package/src/inference/tokenizers/bundled.js +2 -36
  542. package/src/loader/doppler-loader.d.ts +17 -7
  543. package/src/loader/doppler-loader.js +27 -29
  544. package/src/loader/embedding-limit-preflight.js +29 -1
  545. package/src/loader/embedding-loader.js +18 -4
  546. package/src/loader/experts/compact-expert-cache.js +508 -0
  547. package/src/loader/experts/expert-cache.d.ts +1 -1
  548. package/src/loader/experts/expert-dequant-cache.d.ts +9 -0
  549. package/src/loader/experts/expert-dequant-cache.js +75 -0
  550. package/src/loader/experts/expert-frequency-index.js +129 -0
  551. package/src/loader/experts/expert-loader.d.ts +4 -0
  552. package/src/loader/experts/expert-loader.js +13 -1
  553. package/src/loader/experts/expert-preparation.d.ts +1 -1
  554. package/src/loader/experts/expert-preparation.js +1 -1
  555. package/src/loader/experts/loader-bindings.js +129 -14
  556. package/src/loader/experts/mapped-expert-staging.js +393 -0
  557. package/src/loader/experts/mapped-expert-upload-cache.d.ts +61 -0
  558. package/src/loader/experts/mapped-expert-upload-cache.js +382 -0
  559. package/src/loader/experts/qwen-paging.d.ts +1 -1
  560. package/src/loader/experts/qwen-paging.js +1 -1
  561. package/src/loader/experts/routed-expert-cache.d.ts +70 -3
  562. package/src/loader/experts/routed-expert-cache.js +452 -99
  563. package/src/loader/experts/routed-expert-plan.d.ts +2 -0
  564. package/src/loader/experts/routed-expert-plan.js +14 -8
  565. package/src/loader/experts/routed-expert-prefill.js +158 -0
  566. package/src/loader/experts/routed-expert-source.js +234 -0
  567. package/src/loader/experts/routed-expert-trace.js +77 -0
  568. package/src/loader/experts/tiered-expert-cache.d.ts +12 -0
  569. package/src/loader/experts/tiered-expert-cache.js +327 -0
  570. package/src/loader/experts/tiered-expert-plan.js +74 -0
  571. package/src/loader/final-weights-loader.d.ts +1 -1
  572. package/src/loader/hyper-connection-loader.d.ts +2 -2
  573. package/src/loader/hyper-connection-loader.js +85 -13
  574. package/src/loader/layer-loader.d.ts +3 -3
  575. package/src/loader/layer-loader.js +1 -1
  576. package/src/loader/layer-tensor-aliases.js +14 -11
  577. package/src/loader/loader-types.d.ts +6 -1
  578. package/src/loader/manifest-config.js +4 -0
  579. package/src/loader/model-executor.js +18 -1
  580. package/src/loader/model-load.d.ts +1 -1
  581. package/src/loader/model-load.js +1 -1
  582. package/src/loader/ngram-table-bindings.d.ts +3 -3
  583. package/src/loader/ngram-table-bindings.js +7 -6
  584. package/src/loader/q4k-reference-weight.js +1 -1
  585. package/src/loader/shard-cache.d.ts +8 -1
  586. package/src/loader/shard-cache.js +33 -0
  587. package/src/loader/tensors/bf16-loader.js +2 -1
  588. package/src/loader/tensors/fp8-loader.js +1 -1
  589. package/src/loader/tensors/load-executor.js +10 -2
  590. package/src/loader/tensors/tensor-loader.js +1 -1
  591. package/src/loader/tensors/tensor-reader.js +18 -5
  592. package/src/loader/tensors/w8a8-loader.js +1 -1
  593. package/src/loader/weight-representation-plan.d.ts +1 -1
  594. package/src/memory/buffer-pool/readback.js +82 -0
  595. package/src/memory/buffer-pool.d.ts +11 -2
  596. package/src/memory/buffer-pool.js +12 -73
  597. package/src/partitions.d.ts +4 -3
  598. package/src/partitions.js +3 -2
  599. package/src/{converter → rules}/capability-transform-resolver.js +3 -3
  600. package/src/rules/generated/rule-bundle.json +1 -1
  601. package/src/rules/inference/capability-transforms.rules.json +95 -28
  602. package/src/rules/rule-registry.js +2 -0
  603. package/src/storage/artifact-range-loaders.js +42 -0
  604. package/src/storage/artifact-storage-context.d.ts +4 -0
  605. package/src/storage/artifact-storage-context.js +8 -18
  606. package/src/storage/backends/idb-store.js +1 -1
  607. package/src/storage/distribution-transport.js +1 -1
  608. package/src/storage/download/http-contract.js +1 -1
  609. package/src/storage/download/http-transport.js +4 -4
  610. package/src/storage/inventory.js +1 -1
  611. package/src/storage/model-cache.d.ts +2 -1
  612. package/src/storage/model-cache.js +12 -8
  613. package/src/storage/node-file-access.js +4 -0
  614. package/src/storage/quota.d.ts +2 -1
  615. package/src/storage/quota.js +2 -1
  616. package/src/storage/shard-manager.d.ts +1 -1
  617. package/src/storage/shards/integrity.js +17 -0
  618. package/src/storage/source-artifact-store.d.ts +1 -1
  619. package/src/storage/source-artifact-store.js +1 -0
  620. package/src/storage/source-storage-context.d.ts +4 -0
  621. package/src/storage/source-storage-context.js +14 -0
  622. package/src/storage/verified-piece-direct.js +153 -0
  623. package/src/storage/verified-piece-gather-lane.js +210 -0
  624. package/src/storage/verified-piece-gather-worker.js +739 -0
  625. package/src/storage/verified-piece-gather.d.ts +160 -0
  626. package/src/storage/verified-piece-gather.js +315 -0
  627. package/src/storage/verified-piece-reader.d.ts +15 -1
  628. package/src/storage/verified-piece-reader.js +85 -15
  629. package/src/storage/verified-piece-state-cache.d.ts +75 -0
  630. package/src/storage/verified-piece-state-cache.js +511 -0
  631. package/src/storage/verified-piece-storage.d.ts +22 -1
  632. package/src/storage/verified-piece-storage.js +299 -11
  633. package/src/storage/verified-piece-timings.js +25 -0
  634. package/src/tooling/browser-command-runner.js +1 -1
  635. package/src/tooling/browser-harness/benchmark-execution.js +2 -2
  636. package/src/tooling/browser-harness/benchmark-rerank.js +2 -2
  637. package/src/tooling/browser-harness/inference-execution.js +1 -1
  638. package/src/tooling/browser-harness/model-resolution.js +1 -1
  639. package/src/tooling/browser-harness/runtime-config.js +1 -1
  640. package/src/tooling/browser-harness/runtime-isolation.js +2 -5
  641. package/src/tooling/browser-harness/text-evidence.js +1 -1
  642. package/src/tooling/browser-harness-contract-helpers.js +1 -1
  643. package/src/tooling/browser-harness.js +2 -2
  644. package/src/tooling/capsule-v2.js +2 -2
  645. package/src/tooling/capsule.js +2 -2
  646. package/src/tooling/command-api-constants.js +4 -2
  647. package/src/tooling/command-api.d.ts +1 -1
  648. package/src/tooling/command-api.js +15 -21
  649. package/src/tooling/command-runtime-execution.js +1 -8
  650. package/src/tooling/diagnose-runner.js +3 -41
  651. package/src/tooling/node-browser/static-server.js +2 -2
  652. package/src/tooling/node-command-execution.js +2 -34
  653. package/src/tooling/node-converter/input.js +1 -1
  654. package/src/tooling/node-converter/output.js +2 -2
  655. package/src/tooling/node-converter.js +1 -1
  656. package/src/tooling/node-runtime-bridge.js +43 -0
  657. package/src/tooling/node-source-runtime.js +34 -35
  658. package/src/tooling/production-release.js +1 -1
  659. package/src/tooling/program-bundle/materialize.js +1 -1
  660. package/src/tooling/program-bundle-parity.d.ts +1 -1
  661. package/src/tooling/program-bundle-parity.js +1 -1
  662. package/src/tooling/program-bundle.d.ts +1 -1
  663. package/src/tooling/program-bundle.js +2 -2
  664. package/src/tooling/runtime-intent.js +1 -1
  665. package/src/tooling/source-artifact-adapter.js +3 -3
  666. package/src/tooling/source-runtime/node-loader.js +32 -5
  667. package/src/tooling/source-runtime-converter-config.js +28 -6
  668. package/src/tooling-exports.shared.d.ts +3 -3
  669. package/src/tooling-exports.shared.js +2 -2
  670. package/src/version.js +1 -1
  671. package/tests/kernels/browser/kernel-suite.js +1 -1
  672. package/tests/kernels/harness/benchmark.js +1 -1
  673. package/tools/README.md +74 -0
  674. package/src/config/runtime/profiles/qwen3-6-35b-a3b-q4_0-pooled-q8-common-diagnostic.json +0 -4407
  675. package/src/config/schema/loading.schema.js +0 -164
  676. package/src/inference/pipelines/text/moe-cpu.js +0 -20
  677. /package/src/config/{capsule-loading.d.ts → capsule/capsule-loading.d.ts} +0 -0
  678. /package/src/config/{capsule-release-contract.d.ts → capsule/capsule-release-contract.d.ts} +0 -0
  679. /package/src/config/{capsule-signature.d.ts → capsule/capsule-signature.d.ts} +0 -0
  680. /package/src/config/{capsule-signature.js → capsule/capsule-signature.js} +0 -0
  681. /package/src/config/{capsule-v3.d.ts → capsule/capsule-v3.d.ts} +0 -0
  682. /package/src/config/{capsule.d.ts → capsule/capsule.d.ts} +0 -0
  683. /package/src/config/schema/{diffusion.schema.d.ts → execution/diffusion.schema.d.ts} +0 -0
  684. /package/src/config/schema/{diffusion.schema.js → execution/diffusion.schema.js} +0 -0
  685. /package/src/config/schema/{energy.schema.d.ts → execution/energy.schema.d.ts} +0 -0
  686. /package/src/config/schema/{energy.schema.js → execution/energy.schema.js} +0 -0
  687. /package/src/config/schema/{hyper-connection-decoder.schema.d.ts → execution/hyper-connection-decoder.schema.d.ts} +0 -0
  688. /package/src/config/schema/{hyper-connection-decoder.schema.js → execution/hyper-connection-decoder.schema.js} +0 -0
  689. /package/src/config/schema/{inference.schema.js → execution/inference.schema.js} +0 -0
  690. /package/src/config/schema/{kernel-path.schema.js → execution/kernel-path.schema.js} +0 -0
  691. /package/src/config/schema/{kernel-registry.schema.js → execution/kernel-registry.schema.js} +0 -0
  692. /package/src/config/schema/{speculation-self.schema.d.ts → execution/speculation-self.schema.d.ts} +0 -0
  693. /package/src/config/schema/{speculation-self.schema.js → execution/speculation-self.schema.js} +0 -0
  694. /package/src/config/schema/{speculative.schema.d.ts → execution/speculative.schema.d.ts} +0 -0
  695. /package/src/config/schema/{speculative.schema.js → execution/speculative.schema.js} +0 -0
  696. /package/src/config/schema/{conversion-report.schema.d.ts → manifest/conversion-report.schema.d.ts} +0 -0
  697. /package/src/config/schema/{conversion-report.schema.js → manifest/conversion-report.schema.js} +0 -0
  698. /package/src/config/schema/{conversion.schema.d.ts → manifest/conversion.schema.d.ts} +0 -0
  699. /package/src/config/schema/{conversion.schema.js → manifest/conversion.schema.js} +0 -0
  700. /package/src/config/schema/{fp8.schema.d.ts → manifest/fp8.schema.d.ts} +0 -0
  701. /package/src/config/schema/{fp8.schema.js → manifest/fp8.schema.js} +0 -0
  702. /package/src/config/schema/{manifest-rope.schema.d.ts → manifest/manifest-rope.schema.d.ts} +0 -0
  703. /package/src/config/schema/{quantization-defaults.schema.d.ts → manifest/quantization-defaults.schema.d.ts} +0 -0
  704. /package/src/config/schema/{quantization-defaults.schema.js → manifest/quantization-defaults.schema.js} +0 -0
  705. /package/src/config/schema/{quantization.schema.d.ts → manifest/quantization.schema.d.ts} +0 -0
  706. /package/src/config/schema/{quantization.schema.js → manifest/quantization.schema.js} +0 -0
  707. /package/src/config/schema/{w8a8.schema.d.ts → manifest/w8a8.schema.d.ts} +0 -0
  708. /package/src/config/schema/{w8a8.schema.js → manifest/w8a8.schema.js} +0 -0
  709. /package/src/config/schema/{gpu-cache.schema.d.ts → platform/gpu-cache.schema.d.ts} +0 -0
  710. /package/src/config/schema/{memory-limits.schema.d.ts → platform/memory-limits.schema.d.ts} +0 -0
  711. /package/src/config/schema/{platform.schema.d.ts → platform/platform.schema.d.ts} +0 -0
  712. /package/src/config/schema/{support-tiers.schema.d.ts → policy/support-tiers.schema.d.ts} +0 -0
  713. /package/src/config/schema/{support-tiers.schema.js → policy/support-tiers.schema.js} +0 -0
  714. /package/src/config/schema/{adapter.schema.d.ts → runtime/adapter.schema.d.ts} +0 -0
  715. /package/src/config/schema/{adapter.schema.js → runtime/adapter.schema.js} +0 -0
  716. /package/src/config/schema/{benchmark.schema.d.ts → runtime/benchmark.schema.d.ts} +0 -0
  717. /package/src/config/schema/{benchmark.schema.js → runtime/benchmark.schema.js} +0 -0
  718. /package/src/config/schema/{bridge.schema.d.ts → runtime/bridge.schema.d.ts} +0 -0
  719. /package/src/config/schema/{bridge.schema.js → runtime/bridge.schema.js} +0 -0
  720. /package/src/config/schema/{browser-suite-metrics.schema.d.ts → runtime/browser-suite-metrics.schema.d.ts} +0 -0
  721. /package/src/config/schema/{browser-suite-metrics.schema.js → runtime/browser-suite-metrics.schema.js} +0 -0
  722. /package/src/config/schema/{buffer-pool.schema.d.ts → runtime/buffer-pool.schema.d.ts} +0 -0
  723. /package/src/config/schema/{debug.schema.d.ts → runtime/debug.schema.d.ts} +0 -0
  724. /package/src/config/schema/{debug.schema.js → runtime/debug.schema.js} +0 -0
  725. /package/src/config/schema/{distribution.schema.d.ts → runtime/distribution.schema.d.ts} +0 -0
  726. /package/src/config/schema/{distribution.schema.js → runtime/distribution.schema.js} +0 -0
  727. /package/src/config/schema/{ecosystem.schema.d.ts → runtime/ecosystem.schema.d.ts} +0 -0
  728. /package/src/config/schema/{ecosystem.schema.js → runtime/ecosystem.schema.js} +0 -0
  729. /package/src/config/schema/{harness.schema.d.ts → runtime/harness.schema.d.ts} +0 -0
  730. /package/src/config/schema/{harness.schema.js → runtime/harness.schema.js} +0 -0
  731. /package/src/config/schema/{hotswap.schema.d.ts → runtime/hotswap.schema.d.ts} +0 -0
  732. /package/src/config/schema/{hotswap.schema.js → runtime/hotswap.schema.js} +0 -0
  733. /package/src/config/schema/{intent-bundle.schema.d.ts → runtime/intent-bundle.schema.d.ts} +0 -0
  734. /package/src/config/schema/{intent-bundle.schema.js → runtime/intent-bundle.schema.js} +0 -0
  735. /package/src/config/schema/{runtime-profile.schema.d.ts → runtime/runtime-profile.schema.d.ts} +0 -0
  736. /package/src/config/schema/{runtime-profile.schema.js → runtime/runtime-profile.schema.js} +0 -0
  737. /package/src/config/schema/{storage.schema.d.ts → runtime/storage.schema.d.ts} +0 -0
  738. /package/src/config/schema/{storage.schema.js → runtime/storage.schema.js} +0 -0
  739. /package/src/config/schema/{tooling.schema.js → runtime/tooling.schema.js} +0 -0
  740. /package/src/config/schema/{units.schema.d.ts → runtime/units.schema.d.ts} +0 -0
  741. /package/src/config/schema/{units.schema.js → runtime/units.schema.js} +0 -0
  742. /package/src/config/schema/{backward-registry.schema.d.ts → training/backward-registry.schema.d.ts} +0 -0
  743. /package/src/config/schema/{backward-registry.schema.js → training/backward-registry.schema.js} +0 -0
  744. /package/src/config/schema/{distill-training.schema.d.ts → training/distill-training.schema.d.ts} +0 -0
  745. /package/src/config/schema/{distill-training.schema.js → training/distill-training.schema.js} +0 -0
  746. /package/src/config/schema/{lora.schema.d.ts → training/lora.schema.d.ts} +0 -0
  747. /package/src/config/schema/{training-metrics.schema.d.ts → training/training-metrics.schema.d.ts} +0 -0
  748. /package/src/config/schema/{training-metrics.schema.js → training/training-metrics.schema.js} +0 -0
  749. /package/src/config/schema/{training.schema.d.ts → training/training.schema.d.ts} +0 -0
  750. /package/src/config/schema/{training.schema.js → training/training.schema.js} +0 -0
  751. /package/src/config/schema/{ul-training.schema.d.ts → training/ul-training.schema.d.ts} +0 -0
  752. /package/src/config/schema/{ul-training.schema.js → training/ul-training.schema.js} +0 -0
  753. /package/src/{converter → config/transforms}/execution-graph/dtype.js +0 -0
  754. /package/src/{converter → config/transforms}/execution-graph/fusion.js +0 -0
  755. /package/src/{converter → config/transforms}/execution-graph/kv-storage.js +0 -0
  756. /package/src/{converter → config/transforms}/execution-graph/validation.js +0 -0
  757. /package/src/{converter → formats}/qwen4-exp-source-defaults.json +0 -0
  758. /package/src/inference/pipelines/text/{buffer-types.d.ts → contracts/buffer-types.d.ts} +0 -0
  759. /package/src/inference/pipelines/text/{embedding-contract.d.ts → embedding/embedding-contract.d.ts} +0 -0
  760. /package/src/inference/pipelines/text/{embedding-contract.js → embedding/embedding-contract.js} +0 -0
  761. /package/src/inference/pipelines/text/{precomputed-input-norm.js → execution/precomputed-input-norm.js} +0 -0
  762. /package/src/inference/pipelines/text/generator/{batch-retry-policy.js → decode/batch-retry-policy.js} +0 -0
  763. /package/src/inference/pipelines/text/{chat-format.d.ts → generator/request/chat-format.d.ts} +0 -0
  764. /package/src/inference/pipelines/text/{chat-format.js → generator/request/chat-format.js} +0 -0
  765. /package/src/inference/pipelines/text/generator/{recorder-stats.js → session/recorder-stats.js} +0 -0
  766. /package/src/inference/pipelines/text/generator/{whole-token-template.js → whole-token/whole-token-template.js} +0 -0
  767. /package/src/inference/pipelines/text/{init-chat-templates.js → initialization/init-chat-templates.js} +0 -0
  768. /package/src/inference/pipelines/text/{load-policy.js → loading/load-policy.js} +0 -0
  769. /package/src/inference/pipelines/text/{pipeline-load-timing.js → loading/pipeline-load-timing.js} +0 -0
  770. /package/src/inference/pipelines/text/{generator → logits}/hidden-projection.d.ts +0 -0
  771. /package/src/inference/pipelines/text/{operator-events.d.ts → observation/operator-events.d.ts} +0 -0
  772. /package/src/inference/pipelines/text/{stage-names.d.ts → observation/stage-names.d.ts} +0 -0
  773. /package/src/inference/pipelines/text/{stage-names.js → observation/stage-names.js} +0 -0
  774. /package/src/inference/pipelines/text/{tsir-fixture-writer.d.ts → observation/tsir-fixture-writer.d.ts} +0 -0
  775. /package/src/inference/pipelines/text/{generator → per-layer}/per-layer-buffer.js +0 -0
  776. /package/src/inference/pipelines/text/{finiteness-policy.js → policy/finiteness-policy.js} +0 -0
@@ -0,0 +1,160 @@
1
+ import type { VerifiedPieceReceipt } from './verified-piece-reader.js';
2
+ import type { VerifiedPieceStateCacheOptions, WorkerStateCachePayload, prepareVerifiedPieceStateCache } from './verified-piece-state-cache.js';
3
+ export type { VerifiedPieceStateCacheOptions, WorkerStateCachePayload } from './verified-piece-state-cache.js';
4
+ export interface VerifiedPieceProtectedCacheOptions {
5
+ /** Explicit absolute directory (for example on tmpfs /dev/shm) owned by the current user; symlinks are rejected. */
6
+ directory: string;
7
+ /** Maximum bytes retained across all content-addressed piece buckets. */
8
+ maxBytes: number;
9
+ /** Optional host MemAvailable floor in bytes; admissions pause when freeable reserve would dip below this floor. */
10
+ minHostAvailableBytes?: number;
11
+ /** Optional staleness horizon in milliseconds before unhit entries yield to new workloads (default 90000). */
12
+ staleAfterMs?: number;
13
+ }
14
+ export interface VerifiedPieceGatherOptions {
15
+ manifestBytes: Uint8Array<ArrayBuffer>;
16
+ indexBytes: Uint8Array<ArrayBuffer>;
17
+ indexIdentity: string;
18
+ /** Explicit approved regular files, indexed by authenticated piece-index filename.
19
+ * Resolve authorized links before passing their canonical paths; leaf symlinks are rejected. */
20
+ files: Record<string, string>;
21
+ /** Optional explicit host snapshot. Canonical path and opened descriptor must
22
+ * retain this device/inode/size through post-authentication publication checks
23
+ * for nonempty single and batched leases; complete-piece SHA still applies. */
24
+ fileIdentities?: Record<string, { device: string; inode: string; size: string }>;
25
+ maxPartBytes: number;
26
+ /** Explicit range-count bound per output, 1..32; omission preserves three. */
27
+ maxRanges?: number;
28
+ /** Explicit worker count; omission preserves one lane. */
29
+ concurrency?: number;
30
+ /** Cancels asynchronous worker admission; does not replace read signals or close ownership. */
31
+ startupSignal?: AbortSignal;
32
+ /** All outputs plus a conservative two-piece allowance per worker for generic
33
+ * piece buffers. Excludes fixed native digest state, metadata and VM overhead. */
34
+ memoryBudgetBytes: number;
35
+ /** Optional bounded host-protected cache of authenticated pieces; every cache hit is still SHA-256 verified. */
36
+ protectedCache?: VerifiedPieceProtectedCacheOptions;
37
+ /** Optional per-file-state verification record cache (`(dev, ino, size, mtimeNs, ctimeNs)`) with off-critical-path persistence. */
38
+ verificationCache?: VerifiedPieceStateCacheOptions;
39
+ /** Internal shared state cache coordinator owned by verified-piece-storage. */
40
+ sharedStateCache?: Awaited<ReturnType<typeof prepareVerifiedPieceStateCache>>;
41
+ }
42
+ /** Per-job worker observations. Async read waits and different worker jobs can overlap. */
43
+ export interface VerifiedPieceJobTimings {
44
+ workerWallMs: number;
45
+ /** Includes native I/O and callback/scheduling wait; not isolated disk time. */
46
+ readWaitMs: number;
47
+ verificationMs: number;
48
+ copyMs: number;
49
+ }
50
+ export interface VerifiedRangeLeaseTimings extends VerifiedPieceJobTimings {
51
+ /** Lane-local elapsed time from posting the owned job until its reply, not a cross-clock subtraction. */
52
+ roundTripMs: number;
53
+ }
54
+ export interface VerifiedRangeLease {
55
+ bytes: Uint8Array<ArrayBuffer>;
56
+ /** Frozen bounded scalar observations, piggybacked on the existing successful reply.
57
+ * Omission means unsupported; zero-valued fields alone do not establish coverage. */
58
+ timings?: Readonly<VerifiedRangeLeaseTimings>;
59
+ /** Idempotent. Detaches bytes; call only after the consumer has copied them. */
60
+ release(): void;
61
+ }
62
+ export interface VerifiedPieceGatherReceipt extends VerifiedPieceReceipt {
63
+ /** Successful full-piece reads directly into the worker-owned output, authenticated before transfer. */
64
+ directPieceReads: number;
65
+ directPieceBytes: number;
66
+ /** Successfully published multi-range requests, ranges and payload bytes. */
67
+ batchReads: number;
68
+ batchRanges: number;
69
+ batchBytes: number;
70
+ /** Retained receipt field; direct worker-owned SHA creates no input snapshots. */
71
+ activeDigestCopyBytes: number;
72
+ /** Retained receipt field; zero for direct worker-owned SHA. */
73
+ peakDigestCopyBytes: number;
74
+ /** Reusable owned generic piece scratch. Whole-piece reads need none. */
75
+ activeGenericScratchBytes: number;
76
+ /** Per-worker peaks are summed as a conservative aggregate upper bound. */
77
+ peakGenericScratchBytes: number;
78
+ /** Protected cache counters; zero when protectedCache is omitted. */
79
+ protectedCacheHits: number;
80
+ protectedCacheHitBytes: number;
81
+ protectedCacheMisses: number;
82
+ protectedCacheAdmissions: number;
83
+ protectedCacheAdmittedBytes: number;
84
+ protectedCacheEvictions: number;
85
+ protectedCacheEvictedBytes: number;
86
+ protectedCacheSkips: number;
87
+ /** Per-file-state verification cache counters; zero when verificationCache is omitted. */
88
+ stateCacheHits: number;
89
+ stateCacheHitBytes: number;
90
+ stateCacheMisses: number;
91
+ stateCacheAdmissions: number;
92
+ stateCacheAdmittedBytes: number;
93
+ backgroundVerifiedPieces: number;
94
+ backgroundVerificationMs: number;
95
+ /** Present when direct verified reads are bound: reads served to caller memory from already verified pieces. */
96
+ directVerifiedReads?: number;
97
+ directVerifiedBytes?: number;
98
+ /** Direct reads declined because a piece was unverified or its file no longer matched. */
99
+ directDeclinedReads?: number;
100
+ /** Reads made ahead of verification, their bytes, and how many were later confirmed verified. */
101
+ directAheadReads?: number;
102
+ directAheadBytes?: number;
103
+ directAheadConfirmed?: number;
104
+ }
105
+ export function createVerifiedPieceGather(options: VerifiedPieceGatherOptions): Promise<Readonly<{
106
+ /** At most concurrency in-flight reads or outstanding leases. Cancellation is checked before
107
+ * publishing; close rejects pending reads immediately and waits for settled worker ownership. */
108
+ readLease(path: string, offset: number, length: number, signal?: AbortSignal): Promise<VerifiedRangeLease>;
109
+ /** One concatenated owned output; positive ranges share maxPartBytes and the explicit maxRanges bound. */
110
+ readManyLease(ranges: ReadonlyArray<{ path: string; offset: number; length: number }>, signal?: AbortSignal): Promise<VerifiedRangeLease>;
111
+ /** Snapshot of worker verification evidence; requires no outstanding lease. */
112
+ getReceipt(): Promise<VerifiedPieceGatherReceipt>;
113
+ /** Stops admission permanently and awaits all I/O/hash jobs and closed descriptors
114
+ * before terminating workers. Failed retirement remains retryable.
115
+ * Published leases remain caller-owned until release, even after close. */
116
+ close(): Promise<void>;
117
+ rangeLease: VerifiedRangeLeasePort;
118
+ }>>;
119
+
120
+ export interface VerifiedRangeLeasePort {
121
+ /** True only when the worker enforces the supplied file identity snapshot. */
122
+ fileIdentitiesBound?: boolean;
123
+ /** True when workers read/admit through an explicit bounded protected piece cache. */
124
+ protectedCacheBound?: boolean;
125
+ /** True when workers record and reuse piece verification per immutable file state. */
126
+ verificationCacheBound?: boolean;
127
+ /** readMany validates every requested path and open descriptor before reads and after authentication, before publication. */
128
+ batchFileIdentityChecks?: 'before-read-after-auth/v1';
129
+ /** Omission denotes a legacy single-lane port. */
130
+ concurrency?: number;
131
+ maxPartBytes: number;
132
+ /** Omission denotes the legacy three-range batch bound. */
133
+ maxRanges?: number;
134
+ memoryBytes: number;
135
+ read(shard: number, offset: number, length: number, signal: AbortSignal): Promise<VerifiedRangeLease>;
136
+ /** Optional batch capability. One output contains ranges in caller order, without padding. */
137
+ readMany?(ranges: ReadonlyArray<{ shard: number; offset: number; length: number }>, signal: AbortSignal): Promise<VerifiedRangeLease>;
138
+ /**
139
+ * Optional: present when file identities and a verification cache are both bound. Fills caller memory
140
+ * with a range whose every piece is already verified for the file's current state and resolves true;
141
+ * resolves false (destination unusable) when a piece is unverified or the file no longer matches;
142
+ * rejects if the file changes during the read.
143
+ */
144
+ readVerifiedInto?(shard: number, offset: number, destination: Uint8Array, signal?: AbortSignal): Promise<boolean>;
145
+ /**
146
+ * Optional, with `readVerifiedInto`. Fills caller memory before the range's pieces are verified, so the
147
+ * read can run while a lane hashes them. Resolves true when the pieces were already verified, false when
148
+ * the file is not the admitted one, and otherwise a check: the bytes are unauthenticated until it
149
+ * returns true (every covering piece verified, file state unchanged), and must not be used before that.
150
+ */
151
+ readAheadInto?(shard: number, offset: number, destination: Uint8Array, signal?: AbortSignal): Promise<boolean | (() => boolean)>;
152
+ /**
153
+ * Optional: have a lane read and hash the pieces covering these ranges, waiting for a free lane instead of
154
+ * failing when all are busy. The lane's copy of the bytes is dropped. Resolves the job's timings, and
155
+ * rejects if a piece does not match its identity. Foreground reads are served ahead of these jobs.
156
+ */
157
+ verifyMany?(ranges: ReadonlyArray<{ shard: number; offset: number; length: number }>, signal?: AbortSignal): Promise<VerifiedRangeLease['timings'] | null>;
158
+ /** Optional, with `readAheadInto`: whether every piece covering the range is already verified. No I/O. */
159
+ hasVerified?(shard: number, offset: number, length: number): boolean;
160
+ }
@@ -0,0 +1,315 @@
1
+ import { createVerifiedPieceGatherLane } from './verified-piece-gather-lane.js';
2
+ import { createVerifiedDirectReader } from './verified-piece-direct.js';
3
+ import { prepareVerifiedPieceStateCache } from './verified-piece-state-cache.js';
4
+
5
+ /**
6
+ * @param {import('./verified-piece-gather.js').VerifiedPieceProtectedCacheOptions | undefined} rawPolicy
7
+ * @param {number} pieceBytes
8
+ */
9
+ async function prepareProtectedCache(rawPolicy, pieceBytes) {
10
+ if (rawPolicy === undefined) return undefined;
11
+ if (!rawPolicy || typeof rawPolicy !== 'object' || Array.isArray(rawPolicy)) {
12
+ throw new Error('Protected piece cache policy must be an explicit object.');
13
+ }
14
+ const { directory, maxBytes } = rawPolicy;
15
+ const minHostAvailableBytes = rawPolicy.minHostAvailableBytes ?? 0;
16
+ const staleAfterMs = rawPolicy.staleAfterMs ?? 90_000;
17
+ const { isAbsolute, join } = await import('node:path');
18
+ const { lstatSync, mkdirSync, readdirSync } = await import('node:fs');
19
+ if (typeof directory !== 'string' || !directory.trim() || !isAbsolute(directory)
20
+ || !Number.isSafeInteger(maxBytes) || maxBytes < pieceBytes
21
+ || !Number.isSafeInteger(minHostAvailableBytes) || minHostAvailableBytes < 0
22
+ || !Number.isSafeInteger(staleAfterMs) || staleAfterMs < 1000) {
23
+ throw new Error('Protected piece cache requires an absolute directory, maxBytes >= maxPieceBytes, and valid bounds.');
24
+ }
25
+ mkdirSync(directory, { recursive: true, mode: 0o700 });
26
+ const rootStat = lstatSync(directory);
27
+ const expectedUid = typeof process.geteuid === 'function' ? process.geteuid() : null;
28
+ if (!rootStat.isDirectory() || (expectedUid !== null && rootStat.uid !== expectedUid)) {
29
+ throw new Error('Protected piece cache directory must be an owned non-symlink directory.');
30
+ }
31
+ const rawBuckets = Math.max(1, Math.floor(maxBytes / Math.max(1, 4 * pieceBytes)));
32
+ const bucketCount = Math.max(1, Math.min(256, 1 << Math.floor(Math.log2(rawBuckets))));
33
+ const bucketMaxBytes = Math.floor(maxBytes / bucketCount);
34
+ if (bucketMaxBytes < pieceBytes) {
35
+ throw new Error('Protected piece cache bucket budget must cover at least one complete piece.');
36
+ }
37
+ const sharedBucketBytes = new SharedArrayBuffer(bucketCount * 8);
38
+ const bucketView = new BigInt64Array(sharedBucketBytes);
39
+ for (let index = 0; index < bucketCount; index++) {
40
+ const sub = join(directory, index.toString(16).padStart(2, '0'));
41
+ mkdirSync(sub, { mode: 0o700, recursive: true });
42
+ const subStat = lstatSync(sub);
43
+ if (!subStat.isDirectory() || (expectedUid !== null && subStat.uid !== expectedUid)) {
44
+ throw new Error('Protected piece cache bucket must be an owned non-symlink directory.');
45
+ }
46
+ let bytes = 0n;
47
+ for (const name of readdirSync(sub)) {
48
+ if (!name.endsWith('.piece')) continue;
49
+ try {
50
+ const st = lstatSync(join(sub, name));
51
+ if (st.isFile()) bytes += BigInt(st.size);
52
+ } catch {
53
+ // Concurrent worker cleanup is benign.
54
+ }
55
+ }
56
+ Atomics.store(bucketView, index, bytes);
57
+ }
58
+ return {
59
+ directory,
60
+ maxBytes,
61
+ bucketCount,
62
+ bucketMaxBytes,
63
+ minHostAvailableBytes,
64
+ staleAfterMs,
65
+ sharedBucketBytes,
66
+ };
67
+ }
68
+
69
+ /** @type {import('./verified-piece-gather.js').createVerifiedPieceGather} */
70
+ export async function createVerifiedPieceGather(options) {
71
+ options.startupSignal?.throwIfAborted();
72
+ // Omission preserves the original single-lane contract, not automatic tuning.
73
+ const concurrency = options.concurrency ?? 1;
74
+ const maxRanges = options.maxRanges === undefined ? 3 : options.maxRanges;
75
+ if (!Number.isSafeInteger(maxRanges) || maxRanges < 1 || maxRanges > 32) {
76
+ throw new Error('Gather maxRanges must be a positive safe integer no greater than 32.');
77
+ }
78
+ const pinned = { ...options, manifestBytes: new Uint8Array(options.manifestBytes),
79
+ maxRanges,
80
+ indexBytes: new Uint8Array(options.indexBytes), files: { ...options.files },
81
+ ...(options.fileIdentities ? { fileIdentities: structuredClone(options.fileIdentities) } : {}) };
82
+ if (pinned.fileIdentities !== undefined && (!pinned.fileIdentities || typeof pinned.fileIdentities !== 'object'
83
+ || Array.isArray(pinned.fileIdentities) || Object.keys(pinned.fileIdentities).length !== Object.keys(pinned.files).length
84
+ || Object.keys(pinned.files).some(name => {
85
+ const identity = pinned.fileIdentities?.[name];
86
+ const fields = /** @type {const} */ (['device', 'inode', 'size']);
87
+ return !identity || !fields.every(key => typeof identity[key] === 'string' && /^[0-9]+$/.test(identity[key]));
88
+ }))) {
89
+ throw new Error('Gather file identities must bind every approved file device, inode and size.');
90
+ }
91
+ const index = JSON.parse(new TextDecoder().decode(pinned.indexBytes));
92
+ const pieceBytes = index.maxPieceBytes;
93
+ const laneBytes = pinned.maxPartBytes + 2 * pieceBytes;
94
+ const memoryBytes = concurrency * laneBytes;
95
+ if (!Number.isSafeInteger(concurrency) || concurrency < 1
96
+ || !Number.isSafeInteger(pinned.maxPartBytes) || pinned.maxPartBytes < 1
97
+ || !Number.isSafeInteger(pieceBytes) || pieceBytes < 1
98
+ || !Number.isSafeInteger(memoryBytes) || !Number.isSafeInteger(pinned.memoryBudgetBytes)
99
+ || pinned.memoryBudgetBytes < memoryBytes) {
100
+ throw new Error('Gather budget must cover every concurrent output and complete-piece buffer.');
101
+ }
102
+ const protectedCache = await prepareProtectedCache(options.protectedCache, pieceBytes);
103
+ const ownedStateCache = options.sharedStateCache === undefined
104
+ ? await prepareVerifiedPieceStateCache({
105
+ rawPolicy: options.verificationCache,
106
+ manifestIdentity: index.manifestIdentity,
107
+ indexIdentity: pinned.indexIdentity,
108
+ index,
109
+ files: pinned.files,
110
+ })
111
+ : undefined;
112
+ const stateCache = options.sharedStateCache ?? ownedStateCache;
113
+ /** @type {Array<{ reader: Awaited<ReturnType<typeof createVerifiedPieceGatherLane>>, busy: boolean }>} */
114
+ const lanes = [];
115
+ try {
116
+ pinned.startupSignal?.throwIfAborted();
117
+ // Every lane authenticates the same pinned index in its own worker. Start them
118
+ // together: admitting them one after another made startup cost one index
119
+ // authentication per lane (about 0.75 s each for a 63 MB index).
120
+ const started = await Promise.allSettled(Array.from({ length: concurrency }, (_, index) =>
121
+ createVerifiedPieceGatherLane({
122
+ ...pinned,
123
+ memoryBudgetBytes: laneBytes,
124
+ indexMaxPieceBytes: pieceBytes,
125
+ protectedCache,
126
+ stateCache: stateCache?.workerPayload,
127
+ workerIndex: index,
128
+ workerCount: concurrency,
129
+ onStateDirty: stateCache ? () => stateCache.scheduleFlush() : undefined,
130
+ })));
131
+ // Register every lane that did start before reporting a failure, so cleanup owns them all.
132
+ for (const outcome of started) {
133
+ if (outcome.status === 'fulfilled') lanes.push({ reader: outcome.value, busy: false });
134
+ }
135
+ const failed = started.find(outcome => outcome.status === 'rejected');
136
+ if (failed) throw failed.reason;
137
+ pinned.startupSignal?.throwIfAborted();
138
+ } catch (error) {
139
+ const outcomes = await Promise.allSettled([
140
+ ...lanes.map(async lane => lane.reader.close()),
141
+ ...(ownedStateCache ? [ownedStateCache.close()] : []),
142
+ ]);
143
+ const failures = outcomes.flatMap(outcome => outcome.status === 'rejected' ? [outcome.reason] : []);
144
+ if (failures.length) throw new AggregateError([error, ...failures], 'Gather startup and cleanup failed.');
145
+ throw error;
146
+ }
147
+ // Ranges whose pieces are already verified for the current file state need no lane: the caller may
148
+ // read them straight into its own memory. Bound file identities and a verification cache are both
149
+ // required, because those are what the direct checks compare against.
150
+ const direct = stateCache && pinned.fileIdentities !== undefined
151
+ ? createVerifiedDirectReader({ files: pinned.files, fileIdentities: pinned.fileIdentities, index, stateCache }) : null;
152
+ let closed = false, collecting = false;
153
+ /** @type {Promise<void> | null} */
154
+ let closing = null;
155
+ // Background verification waits for a lane instead of failing. A foreground read keeps its contract
156
+ // (more concurrent reads than lanes is the caller's error) and waits only when a lane is held by a
157
+ // background job, which it is served ahead of.
158
+ /** @typedef {{ reader: Awaited<ReturnType<typeof createVerifiedPieceGatherLane>>, busy: boolean, background?: boolean }} Lane */
159
+ /** @type {Array<{ resolve: (lane: Lane) => void, reject: (error: unknown) => void, background: boolean }>} */
160
+ const waiters = [];
161
+ /** @param {Lane} lane */
162
+ const releaseLane = lane => {
163
+ let next = collecting ? -1 : waiters.findIndex(waiter => !waiter.background);
164
+ if (next < 0 && !collecting && waiters.length) next = 0;
165
+ if (next < 0) { lane.busy = false; lane.background = false; return; }
166
+ const [waiter] = waiters.splice(next, 1);
167
+ lane.background = waiter.background;
168
+ waiter.resolve(lane);
169
+ };
170
+ /** @param {AbortSignal | undefined} signal @param {boolean} background @returns {Lane | Promise<Lane>} */
171
+ const acquireLane = (signal, background) => {
172
+ /** @type {Lane | undefined} */
173
+ const lane = collecting ? undefined : lanes.find(candidate => !candidate.busy);
174
+ if (lane) { lane.busy = true; lane.background = background; return lane; }
175
+ if (!background && !lanes.some(/** @param {Lane} candidate */ candidate => candidate.background === true)) {
176
+ throw new Error('Release a current gather lease before another read.');
177
+ }
178
+ return new Promise((resolve, reject) => {
179
+ /** @param {Lane} acquired */
180
+ const settle = acquired => { signal?.removeEventListener('abort', abort); resolve(acquired); };
181
+ const waiter = { background, reject, resolve: settle };
182
+ const abort = () => {
183
+ const at = waiters.indexOf(waiter);
184
+ if (at >= 0) { waiters.splice(at, 1); reject(signal?.reason); }
185
+ };
186
+ signal?.addEventListener('abort', abort, { once: true });
187
+ waiters.push(waiter);
188
+ });
189
+ };
190
+ /** @param {(reader: Awaited<ReturnType<typeof createVerifiedPieceGatherLane>>) => Promise<import('./verified-piece-gather.js').VerifiedRangeLease>} open
191
+ * @param {AbortSignal | undefined} signal @param {boolean} [background] */
192
+ const read = async (open, signal, background = false) => {
193
+ signal?.throwIfAborted();
194
+ if (closed) throw new Error('Gather reader closed.');
195
+ // A free lane is taken without yielding, so the job is posted in the caller's own turn as before.
196
+ const acquired = acquireLane(signal, background);
197
+ const lane = acquired instanceof Promise ? await acquired : acquired;
198
+ try {
199
+ if (closed) throw new Error('Gather reader closed.');
200
+ const owned = await open(lane.reader);
201
+ if (closed) { owned.release(); throw new Error('Gather reader closed.'); }
202
+ let released = false;
203
+ return Object.freeze({ bytes: owned.bytes, ...(owned.timings === undefined ? {} : { timings: owned.timings }), release() {
204
+ if (released) return;
205
+ released = true;
206
+ try { owned.release(); } finally { releaseLane(lane); }
207
+ } });
208
+ } catch (error) { releaseLane(lane); throw error; }
209
+ };
210
+ /** @type {Pick<Awaited<ReturnType<import('./verified-piece-gather.js').createVerifiedPieceGather>>, 'readLease' | 'readManyLease' | 'getReceipt' | 'close'>} */
211
+ const result = {
212
+ readLease: (path, offset, length, signal) => read(reader => reader.readLease(path, offset, length, signal), signal),
213
+ readManyLease: (ranges, signal) => read(reader => reader.readManyLease(ranges, signal), signal),
214
+ async getReceipt() {
215
+ if (closed) throw new Error('Gather reader closed.');
216
+ if (collecting || lanes.some(lane => lane.busy)) throw new Error('Release all current gather leases before reading receipts.');
217
+ collecting = true;
218
+ try {
219
+ // Await all owners even if one failed, before allowing another read.
220
+ const outcomes = await Promise.allSettled(lanes.map(lane => lane.reader.getReceipt()));
221
+ const failed = outcomes.find(outcome => outcome.status === 'rejected');
222
+ if (failed) throw failed.reason;
223
+ if (closed) throw new Error('Gather reader closed.');
224
+ const receipts = outcomes.flatMap(outcome => outcome.status === 'fulfilled' ? [outcome.value] : []);
225
+ const merged = { ...receipts[0] };
226
+ const fields = /** @type {const} */ (['requestedBytes', 'acquisitionMs', 'verificationMs', 'copyMs', 'activeReadBytes', 'peakReadBytes', 'directPieceReads', 'directPieceBytes', 'batchReads', 'batchRanges', 'batchBytes', 'activeDigestCopyBytes', 'peakDigestCopyBytes', 'activeGenericScratchBytes', 'peakGenericScratchBytes', 'protectedCacheHits', 'protectedCacheHitBytes', 'protectedCacheMisses', 'protectedCacheAdmissions', 'protectedCacheAdmittedBytes', 'protectedCacheEvictions', 'protectedCacheEvictedBytes', 'protectedCacheSkips', 'stateCacheHits', 'stateCacheHitBytes', 'stateCacheMisses', 'stateCacheAdmissions', 'stateCacheAdmittedBytes', 'backgroundVerifiedPieces', 'backgroundVerificationMs']);
227
+ Object.assign(merged, Object.fromEntries(fields.map(field => [field, receipts.reduce((total, receipt) => total + (receipt[field] ?? 0), 0)])));
228
+ /** @type {Map<string, import('./verified-piece-reader.js').VerifiedPiece>} */
229
+ const ranges = new Map(receipts.flatMap(receipt => receipt.ranges.map(range => [`${range.path}:${range.offset}`, range])));
230
+ merged.ranges = [...ranges.values()];
231
+ const pieces = new Map(merged.ranges.map(range => [range.identity, range.size]));
232
+ merged.pieces = [...pieces.keys()];
233
+ merged.verifiedBytes = [...pieces.values()].reduce((total, bytes) => total + bytes, 0);
234
+ if (direct) {
235
+ // Bytes served from already verified pieces without a lane; not part of ranges or verifiedBytes.
236
+ const served = direct.getStats();
237
+ Object.assign(merged, { directVerifiedReads: served.reads, directVerifiedBytes: served.bytes, directDeclinedReads: served.declined,
238
+ directAheadReads: served.aheadReads, directAheadBytes: served.aheadBytes, directAheadConfirmed: served.aheadConfirmed });
239
+ }
240
+ return merged;
241
+ } finally {
242
+ collecting = false;
243
+ // Background jobs that arrived meanwhile take the lanes that are free now.
244
+ for (const lane of lanes) if (!lane.busy && waiters.length) { lane.busy = true; releaseLane(lane); }
245
+ }
246
+ },
247
+ close() {
248
+ if (!closing) {
249
+ closed = true;
250
+ for (const waiter of waiters.splice(0)) waiter.reject(new Error('Gather reader closed.'));
251
+ const operation = (async () => {
252
+ const outcomes = await Promise.allSettled([...lanes.map(async lane => lane.reader.close()),
253
+ ...(direct ? [direct.close()] : [])]);
254
+ if (ownedStateCache) await ownedStateCache.close();
255
+ const failed = outcomes.find(outcome => outcome.status === 'rejected');
256
+ if (failed) throw failed.reason;
257
+ })();
258
+ closing = operation;
259
+ operation.catch(() => { if (closing === operation) closing = null; });
260
+ }
261
+ return closing;
262
+ },
263
+ };
264
+ const manifest = JSON.parse(new TextDecoder().decode(pinned.manifestBytes));
265
+ /** @type {import('./verified-piece-gather.js').VerifiedRangeLeasePort} */
266
+ const rangeLease = { concurrency, maxRanges, maxPartBytes: pinned.maxPartBytes, memoryBytes,
267
+ fileIdentitiesBound: pinned.fileIdentities !== undefined,
268
+ ...(protectedCache ? { protectedCacheBound: true } : {}),
269
+ ...(stateCache ? { verificationCacheBound: true } : {}),
270
+ ...(pinned.fileIdentities !== undefined ? { batchFileIdentityChecks: /** @type {const} */ ('before-read-after-auth/v1') } : {}),
271
+ read(shard, offset, length, signal) {
272
+ const file = manifest.shards[shard];
273
+ if (!file) return Promise.reject(new Error('Undeclared gather shard.'));
274
+ return result.readLease(file.filename, offset, length, signal);
275
+ },
276
+ ...(direct ? { readVerifiedInto(shard, offset, destination, signal) {
277
+ const file = manifest.shards[shard];
278
+ if (!file) return Promise.reject(new Error('Undeclared gather shard.'));
279
+ if (closed) return Promise.reject(new Error('Gather reader closed.'));
280
+ return direct.readInto(file.filename, offset, destination, signal);
281
+ }, readAheadInto(shard, offset, destination, signal) {
282
+ const file = manifest.shards[shard];
283
+ if (!file) return Promise.reject(new Error('Undeclared gather shard.'));
284
+ if (closed) return Promise.reject(new Error('Gather reader closed.'));
285
+ return direct.readAheadInto(file.filename, offset, destination, signal);
286
+ }, hasVerified(shard, offset, length) {
287
+ const file = manifest.shards[shard];
288
+ return !!file && !closed && direct.isVerified(file.filename, offset, length);
289
+ } } : {}),
290
+ readMany(ranges, signal) {
291
+ if (!Array.isArray(ranges) || ranges.length < 1 || ranges.length > maxRanges) return Promise.reject(new Error('Gather batch exceeds its admitted ranges bound.'));
292
+ const selected = [];
293
+ for (const range of ranges) {
294
+ const file = Number.isSafeInteger(range?.shard) && range.shard >= 0 ? manifest.shards[range.shard] : null;
295
+ if (!file) return Promise.reject(new Error('Undeclared gather shard.'));
296
+ selected.push({ path: file.filename, offset: range.offset, length: range.length });
297
+ }
298
+ return result.readManyLease(selected, signal);
299
+ },
300
+ async verifyMany(ranges, signal) {
301
+ if (!Array.isArray(ranges) || ranges.length < 1 || ranges.length > maxRanges) throw new Error('Gather batch exceeds its admitted ranges bound.');
302
+ /** @type {Array<{ path: string, offset: number, length: number }>} */
303
+ const selected = [];
304
+ for (const range of ranges) {
305
+ const file = Number.isSafeInteger(range?.shard) && range.shard >= 0 ? manifest.shards[range.shard] : null;
306
+ if (!file) throw new Error('Undeclared gather shard.');
307
+ selected.push({ path: file.filename, offset: range.offset, length: range.length });
308
+ }
309
+ const lease = await read(reader => reader.readManyLease(selected, signal), signal, true);
310
+ const timings = lease.timings ?? null;
311
+ lease.release();
312
+ return timings;
313
+ } };
314
+ return Object.freeze({ ...result, rangeLease: Object.freeze(rangeLease) });
315
+ }
@@ -7,16 +7,30 @@ export interface VerifiedPieceReceipt {
7
7
  acquisitionMs: number; verificationMs: number; copyMs: number;
8
8
  /** Range output buffers owned by active reads, before transfer to the loader; not process RSS. */
9
9
  activeReadBytes: number; peakReadBytes: number;
10
+ stateCacheHits?: number; stateCacheHitBytes?: number; stateCacheMisses?: number;
11
+ }
12
+ export interface StateVerifiedAcquisition {
13
+ bytes: Uint8Array | ArrayBuffer;
14
+ stateVerified?: boolean;
15
+ onAuthenticated?: () => void;
10
16
  }
11
17
  export interface VerifiedPieceReaderOptions {
12
18
  manifestBytes: ArrayBuffer | Uint8Array<ArrayBuffer>; indexBytes: ArrayBuffer | Uint8Array<ArrayBuffer>; indexIdentity: string;
13
- acquire: (piece: Readonly<VerifiedPiece>, options: { signal?: AbortSignal }) => Promise<Uint8Array | ArrayBuffer>;
19
+ acquire: (piece: Readonly<VerifiedPiece>, options: { signal?: AbortSignal }) => Promise<Uint8Array | ArrayBuffer | StateVerifiedAcquisition>;
14
20
  signal?: AbortSignal;
21
+ allowStateVerifiedAcquire?: boolean;
15
22
  }
16
23
  export function createVerifiedPieceReader(options: VerifiedPieceReaderOptions): Promise<Readonly<{
17
24
  manifest: import('../formats/rdrr/index.js').RDRRManifest;
18
25
  readRange(path: string, offset: number, length: number | null): Promise<ArrayBuffer>;
26
+ /** Authenticates complete pieces before copying into caller-owned storage.
27
+ * Failure may leave a verified prefix; no writes occur after settlement. */
28
+ readInto(path: string, offset: number, destination: Uint8Array): Promise<number>;
19
29
  readBinary(path: string): Promise<ArrayBuffer>;
30
+ /** Expected metadata from the authenticated index; never a claim that source bytes were read or verified. */
31
+ resolveCompletePiece(path: string, offset: number, length: number): Readonly<VerifiedPiece> | null;
32
+ /** Frozen expected full-piece descriptors intersecting a validated range; does not acquire or authenticate source bytes. */
33
+ resolveRangePieces(path: string, offset: number, length: number): ReadonlyArray<Readonly<VerifiedPiece>>;
20
34
  getReceipt(): VerifiedPieceReceipt;
21
35
  preflight(): Promise<void>;
22
36
  close(): Promise<void>;
@@ -7,7 +7,7 @@ const digest = async bytes => 'sha256:' + [...new Uint8Array(await crypto.subtle
7
7
  * This reader authenticates bytes; it does not establish signed Capsule qualification.
8
8
  * @type {import('./verified-piece-reader.js').createVerifiedPieceReader}
9
9
  */
10
- export async function createVerifiedPieceReader({ manifestBytes, indexBytes, indexIdentity, acquire, signal }) {
10
+ export async function createVerifiedPieceReader({ manifestBytes, indexBytes, indexIdentity, acquire, signal, allowStateVerifiedAcquire = false }) {
11
11
  for (const bytes of [manifestBytes, indexBytes]) {
12
12
  if (!(bytes instanceof Uint8Array) && !(bytes instanceof ArrayBuffer)) throw new Error('Piece metadata requires bytes.');
13
13
  }
@@ -61,28 +61,86 @@ export async function createVerifiedPieceReader({ manifestBytes, indexBytes, ind
61
61
  const receipt = { indexIdentity, manifestIdentity: index.manifestIdentity, requestedBytes: 0, verifiedBytes: 0, pieces: [], ranges: [],
62
62
  acquisitionMs: 0, verificationMs: 0, copyMs: 0, activeReadBytes: 0, peakReadBytes: 0 };
63
63
  const seen = new Set(), ranges = new Set();
64
- /** @param {string} path @param {number} offset @param {number | null} length */
65
- async function readOwnedRange(path, offset, length) {
64
+ /** @param {Array<Omit<import('./verified-piece-reader.js').VerifiedPiece, 'path'>>} pieces
65
+ * @param {number} offset */
66
+ function firstPiece(pieces, offset) {
67
+ let low = 0, high = pieces.length;
68
+ while (low < high) {
69
+ const middle = Math.floor((low + high) / 2), piece = pieces[middle];
70
+ if (piece.offset + piece.size <= offset) low = middle + 1;
71
+ else high = middle;
72
+ }
73
+ return low;
74
+ }
75
+ /** Pinned expected metadata only; this lookup does not authenticate acquired bytes.
76
+ * @param {string} path @param {number} offset @param {number} length */
77
+ function resolveCompletePiece(path, offset, length) {
78
+ signal?.throwIfAborted();
79
+ if (closed) throw new Error('Piece storage closed.');
80
+ const file = files.get(path);
81
+ if (!file || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 1) return null;
82
+ const piece = file.pieces[firstPiece(file.pieces, offset)];
83
+ return piece?.offset === offset && piece.size === length ? Object.freeze({ ...piece, path }) : null;
84
+ }
85
+ /** Expected complete pieces intersecting a bounded range, without acquisition.
86
+ * @param {string} path @param {number} offset @param {number} length */
87
+ function resolveRangePieces(path, offset, length) {
88
+ signal?.throwIfAborted();
89
+ const file = files.get(path);
90
+ if (closed || !file || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length)
91
+ || length < 0 || !Number.isSafeInteger(offset + length) || offset + length > file.size) {
92
+ throw new Error('Piece range outside its declared file or storage closed.');
93
+ }
94
+ const selected = [];
95
+ if (length > 0) {
96
+ for (let index = firstPiece(file.pieces, offset); index < file.pieces.length; index++) {
97
+ const piece = file.pieces[index];
98
+ if (piece.offset >= offset + length) break;
99
+ selected.push(Object.freeze({ ...piece, path }));
100
+ }
101
+ }
102
+ return Object.freeze(selected);
103
+ }
104
+ /** @param {string} path @param {number} offset @param {number | null} length
105
+ * @param {Uint8Array | null} destination */
106
+ async function readOwnedRange(path, offset, length, destination) {
66
107
  signal?.throwIfAborted();
67
108
  const file = files.get(path);
68
109
  if (length === null) length = file ? file.size - offset : 0;
69
110
  if (closed || !file || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length)
70
111
  || length < 0 || !Number.isSafeInteger(offset + length) || offset + length > file.size) throw new Error('Piece range outside its declared file.');
71
- const output = new Uint8Array(length);
72
- receipt.activeReadBytes += length;
112
+ const output = destination ?? new Uint8Array(length);
113
+ const ownedBytes = destination === null ? length : 0;
114
+ receipt.activeReadBytes += ownedBytes;
73
115
  receipt.peakReadBytes = Math.max(receipt.peakReadBytes, receipt.activeReadBytes);
74
116
  try {
75
- for (const piece of file.pieces) {
76
- if (piece.offset >= offset + length || piece.offset + piece.size <= offset) continue;
117
+ // Coverage is validated and ordered: locate only the intersecting pieces.
118
+ const low = firstPiece(file.pieces, offset);
119
+ for (let index = low; index < file.pieces.length; index++) {
120
+ const piece = file.pieces[index];
121
+ if (piece.offset >= offset + length) break;
77
122
  signal?.throwIfAborted();
78
123
  const acquisitionStarted = performance.now();
79
- const received = await waitActive(acquire(Object.freeze({ ...piece, path }), { signal }));
124
+ const rawAcquired = await waitActive(acquire(Object.freeze({ ...piece, path }), { signal }));
80
125
  receipt.acquisitionMs += performance.now() - acquisitionStarted;
81
126
  const verificationStarted = performance.now();
127
+ const structured = allowStateVerifiedAcquire === true
128
+ && rawAcquired !== null && typeof rawAcquired === 'object'
129
+ && !(rawAcquired instanceof Uint8Array) && !(rawAcquired instanceof ArrayBuffer);
130
+ const received = structured ? rawAcquired.bytes : rawAcquired;
82
131
  if (!(received instanceof Uint8Array) && !(received instanceof ArrayBuffer)
83
132
  || received.byteLength !== piece.size) throw new Error('Acquired piece integrity mismatch.');
84
133
  const bytes = new Uint8Array(received instanceof Uint8Array ? received : new Uint8Array(received));
85
- if (await waitActive(digest(bytes)) !== piece.identity) throw new Error('Acquired piece integrity mismatch.');
134
+ if (structured && rawAcquired.stateVerified === true) {
135
+ receipt.stateCacheHits = (receipt.stateCacheHits ?? 0) + 1;
136
+ receipt.stateCacheHitBytes = (receipt.stateCacheHitBytes ?? 0) + bytes.byteLength;
137
+ } else {
138
+ if (await waitActive(digest(bytes)) !== piece.identity) throw new Error('Acquired piece integrity mismatch.');
139
+ if (structured) {
140
+ receipt.stateCacheMisses = (receipt.stateCacheMisses ?? 0) + 1;
141
+ rawAcquired.onAuthenticated?.();
142
+ }
143
+ }
86
144
  receipt.verificationMs += performance.now() - verificationStarted;
87
145
  signal?.throwIfAborted();
88
146
  if (closed) throw new Error('Piece storage closed.');
@@ -97,24 +155,36 @@ export async function createVerifiedPieceReader({ manifestBytes, indexBytes, ind
97
155
  }
98
156
  if (!seen.has(piece.identity)) { seen.add(piece.identity); receipt.verifiedBytes += bytes.byteLength; receipt.pieces.push(piece.identity); }
99
157
  }
100
- return output.buffer;
101
- } finally { receipt.activeReadBytes -= length; }
158
+ return output;
159
+ } finally { receipt.activeReadBytes -= ownedBytes; }
102
160
  }
103
- /** @param {string} path @param {number} offset @param {number | null} length */
104
- function readRange(path, offset, length) {
105
- const task = readOwnedRange(path, offset, length);
161
+ /** @template T @param {Promise<T>} task @returns {Promise<T>} */
162
+ function trackRead(task) {
106
163
  activeReads.add(task);
107
164
  const settled = () => activeReads.delete(task);
108
165
  task.then(settled, settled);
109
166
  return task;
110
167
  }
168
+ /** @param {string} path @param {number} offset @param {number | null} length */
169
+ async function readRange(path, offset, length) {
170
+ const output = await trackRead(readOwnedRange(path, offset, length, null));
171
+ // A null destination creates an owned, non-shared ArrayBuffer above.
172
+ return /** @type {ArrayBuffer} */ (output.buffer);
173
+ }
174
+ /** @param {string} path @param {number} offset @param {Uint8Array} destination */
175
+ async function readInto(path, offset, destination) {
176
+ if (!(destination instanceof Uint8Array)) throw new Error('Piece readInto requires a byte destination.');
177
+ const length = destination.byteLength;
178
+ await trackRead(readOwnedRange(path, offset, length, destination));
179
+ return length;
180
+ }
111
181
  /** @param {string} path */
112
182
  const readBinary = path => {
113
183
  const file = files.get(path);
114
184
  if (!file) throw new Error('Undeclared auxiliary artifact: ' + path);
115
185
  return readRange(path, 0, file.size);
116
186
  };
117
- return Object.freeze({ manifest, readRange, readBinary,
187
+ return Object.freeze({ manifest, readRange, readInto, readBinary, resolveCompletePiece, resolveRangePieces,
118
188
  getReceipt: () => structuredClone(receipt),
119
189
  async preflight() {
120
190
  signal?.throwIfAborted();