doppler-gpu 0.7.3 → 0.7.7

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 (768) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/package.json +5 -48
  3. package/src/capsule-runtime.d.ts +2 -2
  4. package/src/client/capsule-host.browser.js +4 -4
  5. package/src/client/capsule-host.d.ts +8 -8
  6. package/src/client/capsule-host.js +4 -4
  7. package/src/client/doppler-api.d.ts +2 -2
  8. package/src/client/inspection.d.ts +3 -0
  9. package/src/client/inspection.js +29 -0
  10. package/src/client/model-host/index.d.ts +5 -4
  11. package/src/client/model-host/index.js +28 -8
  12. package/src/client/model-host/model-evidence.js +2 -0
  13. package/src/client/model-host/model-session.d.ts +7 -5
  14. package/src/client/model-host/model-session.js +10 -3
  15. package/src/client/model-host/privacy-receipt.js +22 -0
  16. package/src/client/resident-partitions.d.ts +3 -3
  17. package/src/client/resident-partitions.js +2 -2
  18. package/src/client/runtime/capsule-acquisition.d.ts +3 -3
  19. package/src/client/runtime/capsule-acquisition.js +1 -1
  20. package/src/client/runtime/capsule-adapter-execution.d.ts +2 -2
  21. package/src/client/runtime/capsule-adapter-execution.js +3 -3
  22. package/src/client/runtime/capsule-embedding.d.ts +2 -2
  23. package/src/client/runtime/capsule-embedding.js +1 -1
  24. package/src/client/runtime/capsule-forecast.d.ts +2 -2
  25. package/src/client/runtime/capsule-forecast.js +1 -1
  26. package/src/client/runtime/capsule-operation-adapters.d.ts +1 -1
  27. package/src/client/runtime/capsule-operation-adapters.js +1 -1
  28. package/src/client/runtime/capsule-operation-deltas.js +1 -1
  29. package/src/client/runtime/capsule-operation-executor.d.ts +1 -1
  30. package/src/client/runtime/capsule-operation-executor.js +2 -2
  31. package/src/client/runtime/capsule-operation-stream.d.ts +1 -1
  32. package/src/client/runtime/capsule-operation-stream.js +2 -2
  33. package/src/client/runtime/capsule-piece-reader.js +1 -1
  34. package/src/client/runtime/capsule-program-adapter.js +1 -1
  35. package/src/client/runtime/capsule-release-authorization.js +1 -1
  36. package/src/client/runtime/capsule-rerank.d.ts +2 -2
  37. package/src/client/runtime/composition-root.d.ts +6 -6
  38. package/src/client/runtime/composition-root.js +6 -6
  39. package/src/client/runtime/fetch-capsule-artifact-store.d.ts +1 -1
  40. package/src/client/runtime/fetch-capsule-artifact-store.js +1 -1
  41. package/src/client/runtime/model-source.d.ts +4 -2
  42. package/src/client/runtime/model-source.js +5 -5
  43. package/src/client/runtime/scoped-session.d.ts +2 -2
  44. package/src/client/runtime/verified-capsule-artifact-store.d.ts +2 -2
  45. package/src/client/runtime/verified-capsule-artifact-store.js +1 -1
  46. package/src/config/backward-registry-loader.js +1 -1
  47. package/src/config/{capsule-adapter-policy.js → capsule/capsule-adapter-policy.js} +2 -2
  48. package/src/config/{capsule-adapters.d.ts → capsule/capsule-adapters.d.ts} +1 -1
  49. package/src/config/{capsule-adapters.js → capsule/capsule-adapters.js} +2 -2
  50. package/src/config/{capsule-loading.js → capsule/capsule-loading.js} +1 -1
  51. package/src/config/{capsule-operation.d.ts → capsule/capsule-operation.d.ts} +1 -1
  52. package/src/config/{capsule-operation.js → capsule/capsule-operation.js} +3 -3
  53. package/src/config/{capsule-release-contract.js → capsule/capsule-release-contract.js} +2 -2
  54. package/src/config/{capsule-release-events.d.ts → capsule/capsule-release-events.d.ts} +2 -1
  55. package/src/config/{capsule-release-events.js → capsule/capsule-release-events.js} +3 -2
  56. package/src/config/{capsule-sequence-receipt.js → capsule/capsule-sequence-receipt.js} +1 -1
  57. package/src/config/{capsule-token-selection.d.ts → capsule/capsule-token-selection.d.ts} +1 -1
  58. package/src/config/{capsule-token-selection.js → capsule/capsule-token-selection.js} +2 -2
  59. package/src/config/{capsule-v2.d.ts → capsule/capsule-v2.d.ts} +5 -4
  60. package/src/config/{capsule-v2.js → capsule/capsule-v2.js} +6 -6
  61. package/src/config/{capsule-v3.js → capsule/capsule-v3.js} +1 -1
  62. package/src/config/{capsule.js → capsule/capsule.js} +26 -7
  63. package/src/config/choice-scoring.js +1 -1
  64. package/src/config/conversion/amplify/amplify-120m-f16-af32.json +1 -1
  65. package/src/config/conversion/diffusiongemma/diffusiongemma-26b-a4b-it-q4k-ehf16-af16.json +1 -1
  66. package/src/config/conversion/embeddinggemma/google-embeddinggemma-300m-q4k-ehf16-af32.json +1 -1
  67. package/src/config/conversion/esm/esm2-t12-35m-ur50d-f32-af32.json +2 -2
  68. package/src/config/conversion/esmc/esmc-300m-f32-af32.json +1 -1
  69. package/src/config/conversion/gemma3/gemma-3-1b-it-f16-af32.json +1 -1
  70. package/src/config/conversion/gemma3/gemma-3-1b-it-q4k-ehf16-af32.json +1 -1
  71. package/src/config/conversion/gemma3/gemma-3-270m-it-f16-af32.json +1 -1
  72. package/src/config/conversion/gemma3/gemma-3-270m-it-q4k-ehf16-af16.json +1 -1
  73. package/src/config/conversion/gemma3/gemma-3-270m-it-q4k-ehf16-af32.json +1 -1
  74. package/src/config/conversion/gemma3/gemma-3-270m-it-w8a8-ehf16-af32.json +1 -1
  75. package/src/config/conversion/gemma3/translategemma-4b-1b-enes-q4k-ehf16-af32.json +1 -1
  76. package/src/config/conversion/gemma3/translategemma-4b-it-q4k-ehf16-af32.json +1 -1
  77. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-af16.json +8 -8
  78. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-af32.json +8 -8
  79. package/src/config/conversion/gemma4/gemma-4-12b-it-text-q4k-ehf16-hq4k-af16.json +8 -8
  80. package/src/config/conversion/gemma4/gemma-4-12b-it-text-w4a16-ct-ehf16-af16.json +8 -8
  81. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af16.json +8 -8
  82. package/src/config/conversion/gemma4/gemma-4-31b-it-text-q4k-ehf16-af32.json +8 -8
  83. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af16-int4ple.json +8 -8
  84. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32-int4ple.json +8 -8
  85. package/src/config/conversion/gemma4/gemma-4-e2b-it-q4k-ehf16-af32.json +8 -8
  86. package/src/config/conversion/gemma4/gemma-4-moe-q4k-ehf16-af32.json +1 -1
  87. package/src/config/conversion/glmocr/glm-ocr-f16-af32.json +1 -1
  88. package/src/config/conversion/gpt-oss-20b-f16-xmxfp4.json +1 -1
  89. package/src/config/conversion/janus/janus-pro-1b-text-q4k-ehaf16.json +1 -1
  90. package/src/config/conversion/lfm2/lfm2.5-1.2b-instruct-q4k-ehf16-af32.json +1 -1
  91. package/src/config/conversion/minicpm/minicpm4-0-5b-f16-af32.json +1 -1
  92. package/src/config/conversion/muse-glimmer/muse-glimmer-30b-text-bf16-af32.json +1 -1
  93. package/src/config/conversion/muse-glimmer/muse-glimmer-30b-text-f16-af32.json +1 -1
  94. package/src/config/conversion/nucleotide-transformer/nucleotide-transformer-v2-50m-f32-af32.json +1 -1
  95. package/src/config/conversion/qwen3/qwen-3-4b-instruct-2507-q4k-ehf16-af32.json +2 -2
  96. package/src/config/conversion/qwen3/qwen-3-5-0-8b-canonical-f32.json +1 -1
  97. package/src/config/conversion/qwen3/qwen-3-5-0-8b-q4k-ehaf16.json +1 -1
  98. package/src/config/conversion/qwen3/qwen-3-5-2b-q4k-ehaf16.json +1 -1
  99. package/src/config/conversion/qwen3/qwen-3-5-9b-f16-af32.json +1 -1
  100. package/src/config/conversion/qwen3/qwen-3-5-9b-q4k-ehaf16.json +1 -1
  101. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-eaf16.json +1 -1
  102. package/src/config/conversion/qwen3/qwen-3-6-27b-q4k-ehaf16.json +1 -1
  103. package/src/config/conversion/qwen3/qwen-3-6-35b-a3b-q4_0-passthrough.json +1 -1
  104. package/src/config/conversion/qwen3/qwen-3-6-35b-a3b-text-q4k-ehf16-af32.json +1 -1
  105. package/src/config/conversion/qwen3/qwen-3-8-flash-next-text-q4k-ehf16-af32.json +25 -22
  106. package/src/config/conversion/qwen3/qwen-3-embedding-0-6b-f16-af32.json +2 -2
  107. package/src/config/conversion/qwen3/qwen-3-embedding-0-6b-q4k-ehf16-af32.json +1 -1
  108. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-f16-af32.json +1 -1
  109. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-f16-true-logit-af32.json +2 -2
  110. package/src/config/conversion/qwen3/qwen-3-reranker-0-6b-q4k-ehf16-af32.json +2 -2
  111. package/src/config/conversion/qwen3/qwen3.8-27b-q4_0-passthrough.json +1 -1
  112. package/src/config/conversion/qwen3/qwen3.8-27b-text-f16-af32.json +1 -1
  113. package/src/config/conversion/qwen3/qwen3.8-27b-text-q4k-ehaf16.json +1 -1
  114. package/src/config/conversion/qwen3/qwen4exp-gguf-source-policy.json +53 -0
  115. package/src/config/embedding-contract.d.ts +1 -1
  116. package/src/config/embedding-contract.js +1 -1
  117. package/src/config/execution-registry-contract.d.ts +5 -5
  118. package/src/config/execution-registry-contract.js +5 -5
  119. package/src/config/generation-contract.js +2 -1
  120. package/src/config/hardware-partition-plan.d.ts +32 -0
  121. package/src/config/hardware-partition-plan.js +78 -0
  122. package/src/config/inspection/observation-policies.json +1 -1
  123. package/src/config/kernel-path-loader.d.ts +1 -1
  124. package/src/config/kernel-path-loader.js +1 -1
  125. package/src/config/kernel-registry-contract.d.ts +2 -2
  126. package/src/config/kernel-registry-contract.js +1 -1
  127. package/src/config/kernels/kernel-ref-digests.js +508 -0
  128. package/src/config/kernels/registry.js +2 -2
  129. package/src/config/kernels/registry.json +1892 -1096
  130. package/src/config/layer-partition-plan.d.ts +4 -0
  131. package/src/config/layer-partition-plan.js +10 -4
  132. package/src/config/merge.js +1 -1
  133. package/src/config/model-session-declarations.js +85 -0
  134. package/src/config/param-validator.js +3 -3
  135. package/src/config/platforms/amd-rdna3.json +2 -2
  136. package/src/config/production-release-evidence.js +1 -1
  137. package/src/config/revocation-policy.js +6 -2
  138. package/src/config/revocation-registry.json +1 -1
  139. package/src/config/runtime/model-sessions.json +23 -0
  140. package/src/config/runtime/profiles/flash-next-gguf-control-gemv.json +72 -0
  141. package/src/config/runtime/profiles/flash-next-gguf-hc-inject-gemv.json +47 -0
  142. package/src/config/schema/capsule/index.d.ts +14 -0
  143. package/src/config/schema/capsule/index.js +10 -0
  144. package/src/config/schema/{program-bundle.schema.d.ts → capsule/program-bundle.schema.d.ts} +3 -3
  145. package/src/config/schema/{program-bundle.schema.js → capsule/program-bundle.schema.js} +6 -6
  146. package/src/config/schema/{execution-v1.schema.d.ts → execution/execution-v1.schema.d.ts} +2 -0
  147. package/src/config/schema/{execution-v1.schema.js → execution/execution-v1.schema.js} +2 -2
  148. package/src/config/schema/execution/index.d.ts +203 -0
  149. package/src/config/schema/execution/index.js +94 -0
  150. package/src/config/schema/{inference.schema.d.ts → execution/inference.schema.d.ts} +1 -1
  151. package/src/config/schema/{kernel-path.schema.d.ts → execution/kernel-path.schema.d.ts} +3 -0
  152. package/src/config/schema/{kernel-registry.schema.d.ts → execution/kernel-registry.schema.d.ts} +2 -2
  153. package/src/config/schema/{kernel-thresholds.schema.d.ts → execution/kernel-thresholds.schema.d.ts} +1 -1
  154. package/src/config/schema/{kernel-thresholds.schema.js → execution/kernel-thresholds.schema.js} +1 -1
  155. package/src/config/schema/{kvcache.schema.d.ts → execution/kvcache.schema.d.ts} +8 -2
  156. package/src/config/schema/{kvcache.schema.js → execution/kvcache.schema.js} +17 -1
  157. package/src/config/schema/{ngram-embedding.schema.d.ts → execution/ngram-embedding.schema.d.ts} +3 -1
  158. package/src/config/schema/{ngram-embedding.schema.js → execution/ngram-embedding.schema.js} +16 -1
  159. package/src/config/schema/index.d.ts +8 -897
  160. package/src/config/schema/index.js +8 -506
  161. package/src/config/schema/{converter.schema.d.ts → manifest/converter.schema.d.ts} +4 -4
  162. package/src/config/schema/{converter.schema.js → manifest/converter.schema.js} +1 -1
  163. package/src/config/schema/manifest/index.d.ts +142 -0
  164. package/src/config/schema/manifest/index.js +62 -0
  165. package/src/config/schema/manifest/manifest-inference.schema.d.ts +298 -0
  166. package/src/config/schema/{manifest.schema.d.ts → manifest/manifest.schema.d.ts} +9 -291
  167. package/src/config/schema/{manifest.schema.js → manifest/manifest.schema.js} +2 -2
  168. package/src/config/schema/{emulation.schema.d.ts → platform/emulation.schema.d.ts} +1 -1
  169. package/src/config/schema/{emulation.schema.js → platform/emulation.schema.js} +6 -6
  170. package/src/config/schema/platform/index.d.ts +72 -0
  171. package/src/config/schema/platform/index.js +27 -0
  172. package/src/config/schema/{memory-limits.schema.js → platform/memory-limits.schema.js} +1 -1
  173. package/src/config/schema/policy/index.d.ts +14 -0
  174. package/src/config/schema/policy/index.js +9 -0
  175. package/src/config/schema/{doppler.schema.d.ts → runtime/doppler.schema.d.ts} +3 -3
  176. package/src/config/schema/{doppler.schema.js → runtime/doppler.schema.js} +12 -12
  177. package/src/config/schema/runtime/index.d.ts +238 -0
  178. package/src/config/schema/runtime/index.js +135 -0
  179. package/src/config/schema/{loading.schema.d.ts → runtime/loading.schema.d.ts} +26 -1
  180. package/src/config/schema/{loading.schema.js → runtime/loading.schema.js} +88 -0
  181. package/src/config/schema/{shared-runtime.schema.d.ts → runtime/shared-runtime.schema.d.ts} +5 -5
  182. package/src/config/schema/{shared-runtime.schema.js → runtime/shared-runtime.schema.js} +4 -4
  183. package/src/config/schema/{tooling.schema.d.ts → runtime/tooling.schema.d.ts} +1 -1
  184. package/src/config/schema/training/index.d.ts +63 -0
  185. package/src/config/schema/training/index.js +43 -0
  186. package/src/config/schema/{lora.schema.js → training/lora.schema.js} +1 -1
  187. package/src/config/source-packages/litert/gemma-4-e2b-it.json +1 -1
  188. package/src/config/supported-operations.json +358 -88
  189. package/src/config/target-plan.d.ts +2 -2
  190. package/src/config/target-plan.js +2 -2
  191. package/src/config/training-defaults.d.ts +2 -2
  192. package/src/config/training-defaults.js +2 -2
  193. package/src/config/transforms/execution-graph/correctness-fallback.js +86 -0
  194. package/src/config/transforms/execution-graph/prefill-attention.js +116 -0
  195. package/src/{converter → config/transforms}/execution-graph-transforms.js +5 -194
  196. package/src/converter/core.js +18 -164
  197. package/src/converter/forge-stages.js +2 -2
  198. package/src/converter/fp8-source.js +1 -1
  199. package/src/converter/gemma4/validation.js +110 -0
  200. package/src/converter/linear-norm-gate.js +1 -1
  201. package/src/converter/manifest-builder.js +2 -9
  202. package/src/converter/parsers/gguf.js +54 -4
  203. package/src/converter/quantization-info.js +2 -2
  204. package/src/converter/qwen4-exp-source-execution.js +94 -0
  205. package/src/converter/qwen4-exp-source.js +1 -201
  206. package/src/converter/tensor-transform.js +2 -9
  207. package/src/converter/tokenizer-contract.js +2 -9
  208. package/src/converter/w8a8-quantizer.js +2 -2
  209. package/src/debug/config.js +1 -1
  210. package/src/debug/perf-guards.js +1 -1
  211. package/src/errors/doppler-error.d.ts +54 -0
  212. package/src/errors/doppler-error.js +13 -5
  213. package/src/experimental/distribution/shard-delivery/receipt.js +1 -1
  214. package/src/experimental/distribution/shard-delivery/retry.js +4 -4
  215. package/src/experimental/energy/types.d.ts +1 -1
  216. package/src/experimental/logits/cpu-output.js +1 -1
  217. package/src/experimental/training/artifacts.d.ts +2 -2
  218. package/src/experimental/training/artifacts.js +2 -2
  219. package/src/experimental/training/autograd.d.ts +1 -1
  220. package/src/experimental/training/distillation/student-fixture/execution.js +1 -1
  221. package/src/experimental/training/distillation/student-fixture/model.js +1 -1
  222. package/src/experimental/training/distillation/student-fixture.js +1 -1
  223. package/src/experimental/training/loss-scaling.d.ts +1 -1
  224. package/src/experimental/training/runner/evaluation.js +1 -1
  225. package/src/experimental/training/runner.js +1 -1
  226. package/src/experimental/training/trainer.d.ts +1 -1
  227. package/src/experimental/training/workloads.js +2 -2
  228. package/src/formats/gguf/block-storage.d.ts +9 -0
  229. package/src/formats/gguf/block-storage.js +12 -3
  230. package/src/formats/gguf/qwen-source.js +5 -3
  231. package/src/formats/gguf/qwen-source.json +8 -1
  232. package/src/formats/gguf/qwen4-exp-source.js +101 -0
  233. package/src/formats/q4k-dequant.js +1 -1
  234. package/src/formats/qwen4-exp-source-contracts.js +204 -0
  235. package/src/formats/rdrr/fp8-contract.js +1 -1
  236. package/src/formats/rdrr/fp8-storage.js +1 -1
  237. package/src/formats/rdrr/q4_0-storage.js +1 -1
  238. package/src/formats/rdrr/storage-descriptor.js +1 -1
  239. package/src/formats/rdrr/tensor-config-validator.js +3 -3
  240. package/src/formats/rdrr/validation.js +1 -1
  241. package/src/formats/rdrr/w8a8-storage.js +1 -1
  242. package/src/generation/index.d.ts +1 -1
  243. package/src/generation/index.js +1 -0
  244. package/src/gpu/device.d.ts +1 -1
  245. package/src/gpu/kernels/attention/contiguous-quantized.js +252 -0
  246. package/src/gpu/kernels/attention/tiered-quantized.js +321 -0
  247. package/src/gpu/kernels/attention/tiered.js +240 -0
  248. package/src/gpu/kernels/attention.js +5 -801
  249. package/src/gpu/kernels/backward/layernorm_backward.wgsl +3 -3
  250. package/src/gpu/kernels/channel-gain.js +100 -0
  251. package/src/gpu/kernels/channel-rotation.d.ts +16 -0
  252. package/src/gpu/kernels/channel-rotation.js +47 -0
  253. package/src/gpu/kernels/channel_energy.wgsl +17 -0
  254. package/src/gpu/kernels/channel_energy_pair.wgsl +27 -0
  255. package/src/gpu/kernels/channel_gain_control.wgsl +60 -0
  256. package/src/gpu/kernels/channel_gain_derive.wgsl +40 -0
  257. package/src/gpu/kernels/channel_gain_swiglu.wgsl +64 -0
  258. package/src/gpu/kernels/channel_rotation_apply.wgsl +38 -0
  259. package/src/gpu/kernels/channel_rotation_derive.wgsl +76 -0
  260. package/src/gpu/kernels/check-finiteness-f32.js +22 -0
  261. package/src/gpu/kernels/check_finiteness.wgsl +2 -2
  262. package/src/gpu/kernels/clamp.js +2 -2
  263. package/src/gpu/kernels/dequant.js +1 -1
  264. package/src/gpu/kernels/dispatch.js +7 -0
  265. package/src/gpu/kernels/energy_quintel_grad.wgsl +7 -7
  266. package/src/gpu/kernels/energy_quintel_grad_f16.wgsl +7 -7
  267. package/src/gpu/kernels/energy_quintel_reduce.wgsl +6 -6
  268. package/src/gpu/kernels/energy_quintel_reduce_f16.wgsl +6 -6
  269. package/src/gpu/kernels/energy_quintel_update.wgsl +7 -7
  270. package/src/gpu/kernels/energy_quintel_update_f16.wgsl +7 -7
  271. package/src/gpu/kernels/fused_matmul_q4_widetile_f32.wgsl +174 -0
  272. package/src/gpu/kernels/fused_matmul_rmsnorm.wgsl +0 -49
  273. package/src/gpu/kernels/gated-delta-norm-gate.js +1 -1
  274. package/src/gpu/kernels/gated_delta_recurrent_gguf_register_prefill_sigmoid_gate.wgsl +730 -0
  275. package/src/gpu/kernels/gated_delta_recurrent_gguf_sigmoid_gate.wgsl +499 -0
  276. package/src/gpu/kernels/gather.js +16 -1
  277. package/src/gpu/kernels/gather_split4_packed_f16_vec4_f32_out.wgsl +104 -0
  278. package/src/gpu/kernels/generated/uniform-writers-0.js +7 -11
  279. package/src/gpu/kernels/generated/uniform-writers-1.js +43 -46
  280. package/src/gpu/kernels/generated/uniform-writers-2.js +80 -2
  281. package/src/gpu/kernels/generated/uniform-writers.js +33 -21
  282. package/src/gpu/kernels/hyper-connection-up.js +64 -0
  283. package/src/gpu/kernels/hyper-connection.js +15 -4
  284. package/src/gpu/kernels/hyper_connection_mix_branch.wgsl +105 -0
  285. package/src/gpu/kernels/hyper_connection_norm.wgsl +3 -3
  286. package/src/gpu/kernels/hyper_connection_up_mix_branch_q4_0.wgsl +164 -0
  287. package/src/gpu/kernels/kernel-execution.js +18 -7
  288. package/src/gpu/kernels/linear-attention-core.js +3 -4
  289. package/src/gpu/kernels/moe-route.js +14 -0
  290. package/src/gpu/kernels/moe_gather.wgsl +0 -63
  291. package/src/gpu/kernels/moe_route_q4_0_split_block_f32.wgsl +63 -0
  292. package/src/gpu/kernels/moe_route_q4_1_block_f32.wgsl +59 -0
  293. package/src/gpu/kernels/moe_route_remap.wgsl +22 -0
  294. package/src/gpu/kernels/paired-linear-attention.js +1 -1
  295. package/src/gpu/kernels/pipeline-cache.js +18 -2
  296. package/src/gpu/kernels/ple.js +11 -7
  297. package/src/gpu/kernels/ple_q4_0_to_f32.wgsl +32 -0
  298. package/src/gpu/kernels/qsa-indexer.d.ts +2 -0
  299. package/src/gpu/kernels/qsa-indexer.js +6 -4
  300. package/src/gpu/kernels/qsa_block_keys.wgsl +2 -1
  301. package/src/gpu/kernels/qsa_prepare.wgsl +2 -1
  302. package/src/gpu/kernels/relu.js +1 -1
  303. package/src/gpu/kernels/relu.wgsl +2 -2
  304. package/src/gpu/kernels/relu_f16.wgsl +2 -2
  305. package/src/gpu/kernels/residual.js +1 -1
  306. package/src/gpu/kernels/residual.wgsl +4 -4
  307. package/src/gpu/kernels/residual_f16.wgsl +2 -2
  308. package/src/gpu/kernels/residual_f16_vec4.wgsl +2 -2
  309. package/src/gpu/kernels/residual_vec4.wgsl +2 -2
  310. package/src/gpu/kernels/rope-precompute.js +1 -1
  311. package/src/gpu/kernels/scatter_add.wgsl +0 -31
  312. package/src/gpu/kernels/shader-cache.js +17 -3
  313. package/src/gpu/kernels/shader-capability-filter.js +120 -0
  314. package/src/gpu/kernels/softmax.js +10 -10
  315. package/src/gpu/kernels/topk.wgsl +0 -55
  316. package/src/gpu/kernels/transpose.js +1 -1
  317. package/src/gpu/kernels/transpose.wgsl +2 -2
  318. package/src/gpu/kernels/w8a8.js +1 -1
  319. package/src/gpu/uniform-cache.d.ts +15 -1
  320. package/src/gpu/uniform-cache.js +82 -7
  321. package/src/gpu/weight-buffer.d.ts +1 -1
  322. package/src/inference/moe-router.d.ts +1 -126
  323. package/src/inference/moe-router.js +0 -149
  324. package/src/inference/pipelines/context.js +3 -15
  325. package/src/inference/pipelines/shader-scoped-pipeline.js +10 -5
  326. package/src/inference/pipelines/text/attention/interpreter/immediate.js +4 -4
  327. package/src/inference/pipelines/text/attention/interpreter/output.js +203 -0
  328. package/src/inference/pipelines/text/attention/interpreter/recorded.js +92 -67
  329. package/src/inference/pipelines/text/attention/interpreter.js +77 -350
  330. package/src/inference/pipelines/text/attention/projection-executor.js +2 -2
  331. package/src/inference/pipelines/text/attention/projection-plan.js +1 -1
  332. package/src/inference/pipelines/text/attention/projection-precision.js +132 -0
  333. package/src/inference/pipelines/text/attention/projections.js +13 -151
  334. package/src/inference/pipelines/text/attention/recorded-health.js +83 -0
  335. package/src/inference/pipelines/text/attention/rope-observation.js +1 -1
  336. package/src/inference/pipelines/text/attention/types.js +0 -13
  337. package/src/inference/pipelines/text/config/normalization.js +2 -2
  338. package/src/inference/pipelines/text/config.d.ts +4 -4
  339. package/src/inference/pipelines/text/config.js +17 -135
  340. package/src/inference/pipelines/text/{config-components.js → configuration/config-components.js} +4 -4
  341. package/src/inference/pipelines/text/configuration/model-geometry.js +114 -0
  342. package/src/inference/pipelines/text/{resolved-runtime-session.d.ts → configuration/resolved-runtime-session.d.ts} +4 -4
  343. package/src/inference/pipelines/text/{resolved-runtime-session.js → configuration/resolved-runtime-session.js} +1 -1
  344. package/src/inference/pipelines/text/{abort-contract.js → contracts/abort-contract.js} +2 -1
  345. package/src/inference/pipelines/text/contracts/metrics.d.ts +234 -0
  346. package/src/inference/pipelines/text/{embed.js → embedding/embed.js} +15 -15
  347. package/src/inference/pipelines/text/{embedding-batch.js → embedding/embedding-batch.js} +1 -1
  348. package/src/inference/pipelines/text/{embedding-extraction.js → embedding/embedding-extraction.js} +12 -12
  349. package/src/inference/pipelines/text/{embedding-normalization.js → embedding/embedding-normalization.js} +4 -4
  350. package/src/inference/pipelines/text/{execution-plan.d.ts → execution/execution-plan.d.ts} +8 -8
  351. package/src/inference/pipelines/text/{execution-plan.js → execution/execution-plan.js} +9 -9
  352. package/src/inference/pipelines/text/{execution-runtime-builders.js → execution/execution-runtime-builders.js} +3 -3
  353. package/src/inference/pipelines/text/{execution-v1.d.ts → execution/execution-v1.d.ts} +2 -2
  354. package/src/inference/pipelines/text/{execution-v1.js → execution/execution-v1.js} +13 -183
  355. package/src/inference/pipelines/text/execution/layer-contract.js +90 -0
  356. package/src/inference/pipelines/text/{layer-execution-contract.js → execution/layer-execution-contract.js} +2 -2
  357. package/src/inference/pipelines/text/{layer-input-execution.js → execution/layer-input-execution.js} +27 -36
  358. package/src/inference/pipelines/text/{layer-partition-contract.d.ts → execution/layer-partition-contract.d.ts} +3 -3
  359. package/src/inference/pipelines/text/{layer-partition-contract.js → execution/layer-partition-contract.js} +2 -2
  360. package/src/inference/pipelines/text/{layer-plan-gpu.js → execution/layer-plan-gpu.js} +12 -12
  361. package/src/inference/pipelines/text/{layer-plan.d.ts → execution/layer-plan.d.ts} +1 -1
  362. package/src/inference/pipelines/text/{layer-plan.js → execution/layer-plan.js} +1 -1
  363. package/src/inference/pipelines/text/{layer.js → execution/layer.js} +34 -142
  364. package/src/inference/pipelines/text/{operator-identity.js → execution/operator-identity.js} +1 -1
  365. package/src/inference/pipelines/text/{ops.js → execution/ops.js} +26 -26
  366. package/src/inference/pipelines/text/{paired-execution.js → execution/paired-execution.js} +9 -9
  367. package/src/inference/pipelines/text/execution-v1/hybrid-projection-contract.js +159 -0
  368. package/src/inference/pipelines/text/expert-loading-stats.d.ts +16 -0
  369. package/src/inference/pipelines/text/expert-loading-stats.js +15 -0
  370. package/src/inference/pipelines/text/ffn/dense-executor.js +5 -4
  371. package/src/inference/pipelines/text/ffn/dense-plan.js +23 -34
  372. package/src/inference/pipelines/text/ffn/dense.js +72 -392
  373. package/src/inference/pipelines/text/ffn/fused-gate-up.js +197 -0
  374. package/src/inference/pipelines/text/ffn/moe.js +1 -1
  375. package/src/inference/pipelines/text/ffn/packed-gate-up.js +218 -0
  376. package/src/inference/pipelines/text/ffn/paired.js +3 -3
  377. package/src/inference/pipelines/text/ffn/qwen-shared-expert.js +1 -1
  378. package/src/inference/pipelines/text/ffn/sandwich.js +6 -7
  379. package/src/inference/pipelines/text/ffn/standard.js +5 -5
  380. package/src/inference/pipelines/text/ffn/types.js +6 -3
  381. package/src/inference/pipelines/text/{activity-weights.js → generator/activation/activity-weights.js} +8 -8
  382. package/src/inference/pipelines/text/generator/activation/channel-gain.d.ts +61 -0
  383. package/src/inference/pipelines/text/generator/activation/channel-gain.js +352 -0
  384. package/src/inference/pipelines/text/generator/activation/final-layer-replay.js +43 -0
  385. package/src/inference/pipelines/text/generator/{capsule-generation.js → adapters/capsule-generation.js} +5 -5
  386. package/src/inference/pipelines/text/generator/{diffusion.js → adapters/diffusion.js} +19 -19
  387. package/src/inference/pipelines/text/generator/{training.js → adapters/training.js} +21 -21
  388. package/src/inference/pipelines/text/generator/decode/advance-token.js +73 -0
  389. package/src/inference/pipelines/text/{generator-steps.js → generator/decode/batch-generation.js} +25 -288
  390. package/src/inference/pipelines/text/generator/decode/batch-readback.js +175 -0
  391. package/src/inference/pipelines/text/generator/{compiled-greedy-window.js → decode/compiled-greedy-window.js} +5 -5
  392. package/src/inference/pipelines/text/generator/{decode-components.js → decode/decode-components.js} +1 -1
  393. package/src/inference/pipelines/text/generator/{decode-runtime.js → decode/decode-loop.js} +20 -412
  394. package/src/inference/pipelines/text/generator/decode/decode-mechanics.js +288 -0
  395. package/src/inference/pipelines/text/generator/{decode-readback.js → decode/decode-readback.js} +1 -1
  396. package/src/inference/pipelines/text/generator/decode/decode-runtime.js +2 -0
  397. package/src/inference/pipelines/text/generator/{decode.js → decode/decode-step.js} +34 -313
  398. package/src/inference/pipelines/text/generator/decode/decode.js +5 -0
  399. package/src/inference/pipelines/text/generator/{greedy-head-policy.js → decode/greedy-head-policy.js} +1 -1
  400. package/src/inference/pipelines/text/generator/{recorded-step-executor.js → decode/recorded-step-executor.js} +2 -2
  401. package/src/inference/pipelines/text/generator/generator-steps.js +4 -0
  402. package/src/inference/pipelines/text/{generator.d.ts → generator/generator.d.ts} +13 -11
  403. package/src/inference/pipelines/text/{generator.js → generator/generator.js} +150 -46
  404. package/src/inference/pipelines/text/generator/{prefill-runtime.js → prefill/prefill-execution.js} +72 -278
  405. package/src/inference/pipelines/text/generator/prefill/prefill-logits.js +144 -0
  406. package/src/inference/pipelines/text/generator/{prefill-observation.js → prefill/prefill-observation.js} +2 -2
  407. package/src/inference/pipelines/text/generator/{prefill-policy.js → prefill/prefill-policy.js} +6 -1
  408. package/src/inference/pipelines/text/generator/prefill/prefill-runtime.js +2 -0
  409. package/src/inference/pipelines/text/generator/prefill/prefill-sequence.js +100 -0
  410. package/src/inference/pipelines/text/generator/{prefix-embedding.js → prefill/prefix-embedding.js} +7 -7
  411. package/src/inference/pipelines/text/{generation-request.d.ts → generator/request/generation-request.d.ts} +2 -2
  412. package/src/inference/pipelines/text/{generation-request.js → generator/request/generation-request.js} +3 -3
  413. package/src/inference/pipelines/text/generator/{prompt-input.js → request/prompt-input.js} +2 -2
  414. package/src/inference/pipelines/text/{sampling-config.d.ts → generator/sampling/sampling-config.d.ts} +1 -1
  415. package/src/inference/pipelines/text/{sampling-config.js → generator/sampling/sampling-config.js} +2 -2
  416. package/src/inference/pipelines/text/{sampling.d.ts → generator/sampling/sampling.d.ts} +15 -0
  417. package/src/inference/pipelines/text/{sampling.js → generator/sampling/sampling.js} +22 -3
  418. package/src/inference/pipelines/text/{stopping.js → generator/sampling/stopping.js} +3 -3
  419. package/src/inference/pipelines/text/generator/{token-selection.d.ts → sampling/token-selection.d.ts} +1 -1
  420. package/src/inference/pipelines/text/generator/{token-selection.js → sampling/token-selection.js} +8 -8
  421. package/src/inference/pipelines/text/generator/{activation-storage.js → session/activation-storage.js} +2 -2
  422. package/src/inference/pipelines/text/generator/{attention-lifecycle.js → session/attention-lifecycle.js} +1 -1
  423. package/src/inference/pipelines/text/generator/{diagnostic-sequence.d.ts → session/diagnostic-sequence.d.ts} +3 -3
  424. package/src/inference/pipelines/text/generator/{diagnostic-sequence.js → session/diagnostic-sequence.js} +3 -3
  425. package/src/inference/pipelines/text/generator/session/generation-runtime.js +278 -0
  426. package/src/inference/pipelines/text/{generator-runtime.d.ts → generator/session/generator-runtime.d.ts} +7 -7
  427. package/src/inference/pipelines/text/{generator-runtime.js → generator/session/generator-runtime.js} +8 -8
  428. package/src/inference/pipelines/text/generator/{recovery.js → session/recovery.js} +6 -6
  429. package/src/inference/pipelines/text/{sequence-state.d.ts → generator/session/sequence-state.d.ts} +5 -5
  430. package/src/inference/pipelines/text/{sequence-state.js → generator/session/sequence-state.js} +26 -18
  431. package/src/inference/pipelines/text/generator/{session-context.js → session/session-context.js} +12 -11
  432. package/src/inference/pipelines/text/generator/{speculative-runtime.js → session/speculative-runtime.js} +1 -1
  433. package/src/inference/pipelines/text/generator/{text.js → session/text.js} +9 -9
  434. package/src/inference/pipelines/text/{warm-generation.d.ts → generator/session/warm-generation.d.ts} +1 -1
  435. package/src/inference/pipelines/text/{warm-generation.js → generator/session/warm-generation.js} +1 -1
  436. package/src/inference/pipelines/text/generator/{whole-token-lane.js → whole-token/whole-token-lane.js} +10 -10
  437. package/src/inference/pipelines/text/generator/{whole-token-observation.d.ts → whole-token/whole-token-observation.d.ts} +2 -2
  438. package/src/inference/pipelines/text/generator/{whole-token-observation.js → whole-token/whole-token-observation.js} +5 -5
  439. package/src/inference/pipelines/text/generator/{whole-token-program.d.ts → whole-token/whole-token-program.d.ts} +3 -3
  440. package/src/inference/pipelines/text/generator/{whole-token-program.js → whole-token/whole-token-program.js} +5 -5
  441. package/src/inference/pipelines/text/hyper-connection/decoder-layer.d.ts +17 -4
  442. package/src/inference/pipelines/text/hyper-connection/decoder-layer.js +38 -14
  443. package/src/inference/pipelines/text/hyper-connection/layer-executor.js +14 -9
  444. package/src/inference/pipelines/text/hyper-connection/logits-input.js +5 -3
  445. package/src/inference/pipelines/text/hyper-connection/projection.js +52 -2
  446. package/src/inference/pipelines/text/hyper-connection/sequence-transaction.js +3 -3
  447. package/src/inference/pipelines/text/hyper-connection/session.d.ts +1 -1
  448. package/src/inference/pipelines/text/hyper-connection/session.js +9 -5
  449. package/src/inference/pipelines/text/indexed-attention/qsa-cache.d.ts +2 -1
  450. package/src/inference/pipelines/text/indexed-attention/qsa-cache.js +3 -3
  451. package/src/inference/pipelines/text/init.d.ts +4 -2
  452. package/src/inference/pipelines/text/init.js +10 -934
  453. package/src/inference/pipelines/text/initialization/init-emulation.js +76 -0
  454. package/src/inference/pipelines/text/initialization/init-kv-cache.js +547 -0
  455. package/src/inference/pipelines/text/initialization/init-moe.js +34 -0
  456. package/src/inference/pipelines/text/{init-qkv-fusion.js → initialization/init-qkv-fusion.js} +7 -7
  457. package/src/inference/pipelines/text/{init-rope.d.ts → initialization/init-rope.d.ts} +4 -4
  458. package/src/inference/pipelines/text/{init-rope.js → initialization/init-rope.js} +9 -11
  459. package/src/inference/pipelines/text/initialization/init-speculative.js +31 -0
  460. package/src/inference/pipelines/text/{init-tokenizer.js → initialization/init-tokenizer.js} +2 -2
  461. package/src/inference/pipelines/text/lifecycle.js +18 -18
  462. package/src/inference/pipelines/text/{linear-attention-ab-fusion.js → linear-attention/linear-attention-ab-fusion.js} +3 -3
  463. package/src/inference/pipelines/text/{linear-attention.d.ts → linear-attention/linear-attention.d.ts} +12 -12
  464. package/src/inference/pipelines/text/{linear-attention.js → linear-attention/linear-attention.js} +17 -17
  465. package/src/inference/pipelines/text/linear-attention/plan.js +4 -4
  466. package/src/inference/pipelines/text/linear-attention/state-checkpoint.js +1 -1
  467. package/src/inference/pipelines/text/linear-attention/state-clone.js +1 -1
  468. package/src/inference/pipelines/text/linear-attention/state-layout.js +2 -2
  469. package/src/inference/pipelines/text/loading/decode-session-config.js +295 -0
  470. package/src/inference/pipelines/text/loading/init-weights.js +254 -0
  471. package/src/inference/pipelines/text/{load-errors.js → loading/load-errors.js} +3 -3
  472. package/src/inference/pipelines/text/{model-load.js → loading/model-load.js} +14 -306
  473. package/src/inference/pipelines/text/{weight-loading-config.js → loading/weight-loading-config.js} +6 -6
  474. package/src/inference/pipelines/text/{weights.d.ts → loading/weights.d.ts} +13 -13
  475. package/src/inference/pipelines/text/{weights.js → loading/weights.js} +5 -5
  476. package/src/inference/pipelines/text/logits/gpu-executor.js +2 -2
  477. package/src/inference/pipelines/text/logits/gpu.d.ts +4 -4
  478. package/src/inference/pipelines/text/logits/gpu.js +2 -2
  479. package/src/inference/pipelines/text/{generator → logits}/hidden-projection.js +1 -1
  480. package/src/inference/pipelines/text/logits/index.d.ts +1 -1
  481. package/src/inference/pipelines/text/logits/index.js +3 -3
  482. package/src/inference/pipelines/text/{generator → logits}/logits-config.js +1 -1
  483. package/src/inference/pipelines/text/logits/output-transform.js +1 -1
  484. package/src/inference/pipelines/text/logits/precision-policy.js +1 -1
  485. package/src/inference/pipelines/text/logits/types.d.ts +2 -2
  486. package/src/inference/pipelines/text/lora-types.d.ts +1 -1
  487. package/src/inference/pipelines/text/moe/expert-loading.js +4 -1
  488. package/src/inference/pipelines/text/moe/gpu-executor.js +44 -101
  489. package/src/inference/pipelines/text/moe/grouped-prefill.js +6 -2
  490. package/src/inference/pipelines/text/moe/qwen-route-executor.d.ts +2 -2
  491. package/src/inference/pipelines/text/moe/qwen-route-executor.js +31 -2
  492. package/src/inference/pipelines/text/moe/routed-expert-chunks.js +99 -15
  493. package/src/inference/pipelines/text/moe-cache.js +11 -77
  494. package/src/inference/pipelines/text/moe-gpu.js +33 -75
  495. package/src/inference/pipelines/text/moe-impl.d.ts +3 -38
  496. package/src/inference/pipelines/text/moe-impl.js +1 -7
  497. package/src/inference/pipelines/text/ngram/ngram-addresses.d.ts +1 -1
  498. package/src/inference/pipelines/text/ngram/ngram-addresses.js +2 -2
  499. package/src/inference/pipelines/text/ngram/ngram-table.d.ts +3 -3
  500. package/src/inference/pipelines/text/ngram/ngram-table.js +5 -6
  501. package/src/inference/pipelines/text/ngram/ple-layer.d.ts +3 -3
  502. package/src/inference/pipelines/text/ngram/ple-layer.js +3 -3
  503. package/src/inference/pipelines/text/{generator-logits-observation.js → observation/generator-logits-observation.js} +4 -4
  504. package/src/inference/pipelines/text/{kernel-trace.js → observation/kernel-trace.js} +1 -1
  505. package/src/inference/pipelines/text/{operator-events.js → observation/operator-events.js} +1 -1
  506. package/src/inference/pipelines/text/{probes.js → observation/probes.js} +13 -13
  507. package/src/inference/pipelines/text/{tsir-fixture-writer.js → observation/tsir-fixture-writer.js} +3 -3
  508. package/src/inference/pipelines/text/{execution.js → operations/execution.js} +14 -14
  509. package/src/inference/pipelines/text/{image-transcription.js → operations/image-transcription.js} +8 -8
  510. package/src/inference/pipelines/text/{partition-attempt.js → partitions/partition-attempt.js} +7 -7
  511. package/src/inference/pipelines/text/{partition-execution.js → partitions/partition-execution.js} +79 -34
  512. package/src/inference/pipelines/text/partitions/partition-wire.js +50 -0
  513. package/src/inference/pipelines/text/{resident-partition-contract.d.ts → partitions/resident-partition-contract.d.ts} +10 -8
  514. package/src/inference/pipelines/text/{resident-partition-contract.js → partitions/resident-partition-contract.js} +6 -6
  515. package/src/inference/pipelines/text/{resident-partition.js → partitions/resident-partition.js} +19 -13
  516. package/src/inference/pipelines/text/{resident-pipeline-preparation.js → partitions/resident-pipeline-preparation.js} +32 -32
  517. package/src/inference/pipelines/text/per-layer/materialize.js +4 -4
  518. package/src/inference/pipelines/text/per-layer/per-layer-inputs.js +5 -0
  519. package/src/inference/pipelines/text/per-layer/plan.js +4 -4
  520. package/src/inference/pipelines/text/{per-layer-inputs.js → per-layer/prepare.js} +14 -280
  521. package/src/inference/pipelines/text/per-layer/projection-contract.js +79 -0
  522. package/src/inference/pipelines/text/per-layer/runtime-cache.js +183 -0
  523. package/src/inference/pipelines/text/pipeline.d.ts +13 -8
  524. package/src/inference/pipelines/text/pipeline.js +78 -22
  525. package/src/inference/pipelines/text/{drift-policy.js → policy/drift-policy.js} +1 -1
  526. package/src/inference/pipelines/text/{dtype-contract.js → policy/dtype-contract.js} +2 -2
  527. package/src/inference/pipelines/text/{finiteness-guard-status.js → policy/finiteness-guard-status.js} +2 -1
  528. package/src/inference/pipelines/text/{generator-decode-policy.js → policy/generator-decode-policy.js} +5 -5
  529. package/src/inference/pipelines/text/state.d.ts +9 -8
  530. package/src/inference/pipelines/text/state.js +1 -0
  531. package/src/inference/pipelines/text/types.d.ts +14 -218
  532. package/src/inference/pipelines/text.js +2 -0
  533. package/src/inference/tokenizers/bundled/merge.js +130 -0
  534. package/src/inference/tokenizers/bundled.js +2 -36
  535. package/src/loader/doppler-loader.d.ts +17 -7
  536. package/src/loader/doppler-loader.js +27 -29
  537. package/src/loader/embedding-limit-preflight.js +29 -1
  538. package/src/loader/embedding-loader.js +18 -4
  539. package/src/loader/experts/compact-expert-cache.js +488 -0
  540. package/src/loader/experts/expert-cache.d.ts +1 -1
  541. package/src/loader/experts/expert-dequant-cache.d.ts +9 -0
  542. package/src/loader/experts/expert-dequant-cache.js +75 -0
  543. package/src/loader/experts/expert-frequency-index.js +129 -0
  544. package/src/loader/experts/expert-loader.d.ts +4 -0
  545. package/src/loader/experts/expert-loader.js +13 -1
  546. package/src/loader/experts/expert-preparation.d.ts +1 -1
  547. package/src/loader/experts/expert-preparation.js +1 -1
  548. package/src/loader/experts/loader-bindings.js +117 -13
  549. package/src/loader/experts/mapped-expert-upload-cache.d.ts +61 -0
  550. package/src/loader/experts/mapped-expert-upload-cache.js +382 -0
  551. package/src/loader/experts/qwen-paging.d.ts +1 -1
  552. package/src/loader/experts/qwen-paging.js +1 -1
  553. package/src/loader/experts/routed-expert-cache.d.ts +62 -3
  554. package/src/loader/experts/routed-expert-cache.js +451 -99
  555. package/src/loader/experts/routed-expert-plan.d.ts +2 -0
  556. package/src/loader/experts/routed-expert-plan.js +14 -8
  557. package/src/loader/experts/routed-expert-prefill.js +82 -0
  558. package/src/loader/experts/routed-expert-source.js +233 -0
  559. package/src/loader/experts/routed-expert-trace.js +77 -0
  560. package/src/loader/experts/tiered-expert-cache.d.ts +12 -0
  561. package/src/loader/experts/tiered-expert-cache.js +287 -0
  562. package/src/loader/experts/tiered-expert-plan.js +74 -0
  563. package/src/loader/final-weights-loader.d.ts +1 -1
  564. package/src/loader/hyper-connection-loader.d.ts +2 -2
  565. package/src/loader/hyper-connection-loader.js +85 -13
  566. package/src/loader/layer-loader.d.ts +3 -3
  567. package/src/loader/layer-loader.js +1 -1
  568. package/src/loader/layer-tensor-aliases.js +14 -11
  569. package/src/loader/loader-types.d.ts +6 -1
  570. package/src/loader/manifest-config.js +4 -0
  571. package/src/loader/model-executor.js +18 -1
  572. package/src/loader/model-load.d.ts +1 -1
  573. package/src/loader/model-load.js +1 -1
  574. package/src/loader/ngram-table-bindings.d.ts +3 -3
  575. package/src/loader/ngram-table-bindings.js +7 -6
  576. package/src/loader/q4k-reference-weight.js +1 -1
  577. package/src/loader/shard-cache.d.ts +8 -1
  578. package/src/loader/shard-cache.js +33 -0
  579. package/src/loader/tensors/bf16-loader.js +2 -1
  580. package/src/loader/tensors/fp8-loader.js +1 -1
  581. package/src/loader/tensors/load-executor.js +10 -2
  582. package/src/loader/tensors/tensor-loader.js +1 -1
  583. package/src/loader/tensors/tensor-reader.js +18 -5
  584. package/src/loader/tensors/w8a8-loader.js +1 -1
  585. package/src/loader/weight-representation-plan.d.ts +1 -1
  586. package/src/memory/buffer-pool/readback.js +82 -0
  587. package/src/memory/buffer-pool.d.ts +11 -2
  588. package/src/memory/buffer-pool.js +12 -73
  589. package/src/partitions.d.ts +4 -3
  590. package/src/partitions.js +3 -2
  591. package/src/{converter → rules}/capability-transform-resolver.js +3 -3
  592. package/src/rules/generated/rule-bundle.json +1 -1
  593. package/src/rules/inference/capability-transforms.rules.json +95 -28
  594. package/src/rules/rule-registry.js +2 -0
  595. package/src/storage/artifact-range-loaders.js +42 -0
  596. package/src/storage/artifact-storage-context.d.ts +4 -0
  597. package/src/storage/artifact-storage-context.js +8 -18
  598. package/src/storage/backends/idb-store.js +1 -1
  599. package/src/storage/distribution-transport.js +1 -1
  600. package/src/storage/download/http-contract.js +1 -1
  601. package/src/storage/download/http-transport.js +4 -4
  602. package/src/storage/inventory.js +1 -1
  603. package/src/storage/model-cache.d.ts +2 -1
  604. package/src/storage/model-cache.js +12 -8
  605. package/src/storage/node-file-access.js +4 -0
  606. package/src/storage/quota.d.ts +2 -1
  607. package/src/storage/quota.js +2 -1
  608. package/src/storage/shard-manager.d.ts +1 -1
  609. package/src/storage/shards/integrity.js +17 -0
  610. package/src/storage/source-artifact-store.d.ts +1 -1
  611. package/src/storage/source-artifact-store.js +1 -0
  612. package/src/storage/source-storage-context.d.ts +4 -0
  613. package/src/storage/source-storage-context.js +14 -0
  614. package/src/storage/verified-piece-gather-lane.js +192 -0
  615. package/src/storage/verified-piece-gather-worker.js +520 -0
  616. package/src/storage/verified-piece-gather.d.ts +113 -0
  617. package/src/storage/verified-piece-gather.js +199 -0
  618. package/src/storage/verified-piece-reader.d.ts +7 -0
  619. package/src/storage/verified-piece-reader.js +69 -12
  620. package/src/storage/verified-piece-storage.d.ts +3 -1
  621. package/src/storage/verified-piece-storage.js +101 -11
  622. package/src/storage/verified-piece-timings.js +25 -0
  623. package/src/tooling/browser-command-runner.js +1 -1
  624. package/src/tooling/browser-harness/benchmark-execution.js +2 -2
  625. package/src/tooling/browser-harness/benchmark-rerank.js +2 -2
  626. package/src/tooling/browser-harness/inference-execution.js +1 -1
  627. package/src/tooling/browser-harness/model-resolution.js +1 -1
  628. package/src/tooling/browser-harness/runtime-config.js +1 -1
  629. package/src/tooling/browser-harness/runtime-isolation.js +2 -5
  630. package/src/tooling/browser-harness/text-evidence.js +1 -1
  631. package/src/tooling/browser-harness-contract-helpers.js +1 -1
  632. package/src/tooling/browser-harness.js +2 -2
  633. package/src/tooling/capsule-v2.js +2 -2
  634. package/src/tooling/capsule.js +2 -2
  635. package/src/tooling/command-api-constants.js +4 -2
  636. package/src/tooling/command-api.d.ts +1 -1
  637. package/src/tooling/command-api.js +15 -21
  638. package/src/tooling/command-runtime-execution.js +1 -8
  639. package/src/tooling/diagnose-runner.js +3 -41
  640. package/src/tooling/node-browser/static-server.js +2 -2
  641. package/src/tooling/node-command-execution.js +2 -34
  642. package/src/tooling/node-converter/input.js +1 -1
  643. package/src/tooling/node-converter/output.js +2 -2
  644. package/src/tooling/node-converter.js +1 -1
  645. package/src/tooling/node-runtime-bridge.js +43 -0
  646. package/src/tooling/node-source-runtime.js +34 -35
  647. package/src/tooling/production-release.js +1 -1
  648. package/src/tooling/program-bundle/materialize.js +1 -1
  649. package/src/tooling/program-bundle-parity.d.ts +1 -1
  650. package/src/tooling/program-bundle-parity.js +1 -1
  651. package/src/tooling/program-bundle.d.ts +1 -1
  652. package/src/tooling/program-bundle.js +2 -2
  653. package/src/tooling/runtime-intent.js +1 -1
  654. package/src/tooling/source-artifact-adapter.js +3 -3
  655. package/src/tooling/source-runtime/node-loader.js +32 -5
  656. package/src/tooling/source-runtime-converter-config.js +28 -6
  657. package/src/tooling-exports.shared.d.ts +3 -3
  658. package/src/tooling-exports.shared.js +2 -2
  659. package/src/version.js +1 -1
  660. package/tests/kernels/browser/kernel-suite.js +1 -1
  661. package/tests/kernels/harness/benchmark.js +1 -1
  662. package/tools/README.md +74 -0
  663. package/src/config/runtime/profiles/qwen3-6-35b-a3b-q4_0-pooled-q8-common-diagnostic.json +0 -4407
  664. package/src/inference/pipelines/text/moe-cpu.js +0 -20
  665. /package/src/config/{capsule-loading.d.ts → capsule/capsule-loading.d.ts} +0 -0
  666. /package/src/config/{capsule-release-contract.d.ts → capsule/capsule-release-contract.d.ts} +0 -0
  667. /package/src/config/{capsule-signature.d.ts → capsule/capsule-signature.d.ts} +0 -0
  668. /package/src/config/{capsule-signature.js → capsule/capsule-signature.js} +0 -0
  669. /package/src/config/{capsule-v3.d.ts → capsule/capsule-v3.d.ts} +0 -0
  670. /package/src/config/{capsule.d.ts → capsule/capsule.d.ts} +0 -0
  671. /package/src/config/schema/{diffusion.schema.d.ts → execution/diffusion.schema.d.ts} +0 -0
  672. /package/src/config/schema/{diffusion.schema.js → execution/diffusion.schema.js} +0 -0
  673. /package/src/config/schema/{energy.schema.d.ts → execution/energy.schema.d.ts} +0 -0
  674. /package/src/config/schema/{energy.schema.js → execution/energy.schema.js} +0 -0
  675. /package/src/config/schema/{hyper-connection-decoder.schema.d.ts → execution/hyper-connection-decoder.schema.d.ts} +0 -0
  676. /package/src/config/schema/{hyper-connection-decoder.schema.js → execution/hyper-connection-decoder.schema.js} +0 -0
  677. /package/src/config/schema/{inference.schema.js → execution/inference.schema.js} +0 -0
  678. /package/src/config/schema/{kernel-path.schema.js → execution/kernel-path.schema.js} +0 -0
  679. /package/src/config/schema/{kernel-registry.schema.js → execution/kernel-registry.schema.js} +0 -0
  680. /package/src/config/schema/{kernel-warmup.schema.d.ts → execution/kernel-warmup.schema.d.ts} +0 -0
  681. /package/src/config/schema/{kernel-warmup.schema.js → execution/kernel-warmup.schema.js} +0 -0
  682. /package/src/config/schema/{speculation-self.schema.d.ts → execution/speculation-self.schema.d.ts} +0 -0
  683. /package/src/config/schema/{speculation-self.schema.js → execution/speculation-self.schema.js} +0 -0
  684. /package/src/config/schema/{speculative.schema.d.ts → execution/speculative.schema.d.ts} +0 -0
  685. /package/src/config/schema/{speculative.schema.js → execution/speculative.schema.js} +0 -0
  686. /package/src/config/schema/{conversion-report.schema.d.ts → manifest/conversion-report.schema.d.ts} +0 -0
  687. /package/src/config/schema/{conversion-report.schema.js → manifest/conversion-report.schema.js} +0 -0
  688. /package/src/config/schema/{conversion.schema.d.ts → manifest/conversion.schema.d.ts} +0 -0
  689. /package/src/config/schema/{conversion.schema.js → manifest/conversion.schema.js} +0 -0
  690. /package/src/config/schema/{fp8.schema.d.ts → manifest/fp8.schema.d.ts} +0 -0
  691. /package/src/config/schema/{fp8.schema.js → manifest/fp8.schema.js} +0 -0
  692. /package/src/config/schema/{manifest-rope.schema.d.ts → manifest/manifest-rope.schema.d.ts} +0 -0
  693. /package/src/config/schema/{quantization-defaults.schema.d.ts → manifest/quantization-defaults.schema.d.ts} +0 -0
  694. /package/src/config/schema/{quantization-defaults.schema.js → manifest/quantization-defaults.schema.js} +0 -0
  695. /package/src/config/schema/{quantization.schema.d.ts → manifest/quantization.schema.d.ts} +0 -0
  696. /package/src/config/schema/{quantization.schema.js → manifest/quantization.schema.js} +0 -0
  697. /package/src/config/schema/{w8a8.schema.d.ts → manifest/w8a8.schema.d.ts} +0 -0
  698. /package/src/config/schema/{w8a8.schema.js → manifest/w8a8.schema.js} +0 -0
  699. /package/src/config/schema/{gpu-cache.schema.d.ts → platform/gpu-cache.schema.d.ts} +0 -0
  700. /package/src/config/schema/{gpu-cache.schema.js → platform/gpu-cache.schema.js} +0 -0
  701. /package/src/config/schema/{memory-limits.schema.d.ts → platform/memory-limits.schema.d.ts} +0 -0
  702. /package/src/config/schema/{platform.schema.d.ts → platform/platform.schema.d.ts} +0 -0
  703. /package/src/config/schema/{support-tiers.schema.d.ts → policy/support-tiers.schema.d.ts} +0 -0
  704. /package/src/config/schema/{support-tiers.schema.js → policy/support-tiers.schema.js} +0 -0
  705. /package/src/config/schema/{adapter.schema.d.ts → runtime/adapter.schema.d.ts} +0 -0
  706. /package/src/config/schema/{adapter.schema.js → runtime/adapter.schema.js} +0 -0
  707. /package/src/config/schema/{benchmark.schema.d.ts → runtime/benchmark.schema.d.ts} +0 -0
  708. /package/src/config/schema/{benchmark.schema.js → runtime/benchmark.schema.js} +0 -0
  709. /package/src/config/schema/{bridge.schema.d.ts → runtime/bridge.schema.d.ts} +0 -0
  710. /package/src/config/schema/{bridge.schema.js → runtime/bridge.schema.js} +0 -0
  711. /package/src/config/schema/{browser-suite-metrics.schema.d.ts → runtime/browser-suite-metrics.schema.d.ts} +0 -0
  712. /package/src/config/schema/{browser-suite-metrics.schema.js → runtime/browser-suite-metrics.schema.js} +0 -0
  713. /package/src/config/schema/{buffer-pool.schema.d.ts → runtime/buffer-pool.schema.d.ts} +0 -0
  714. /package/src/config/schema/{buffer-pool.schema.js → runtime/buffer-pool.schema.js} +0 -0
  715. /package/src/config/schema/{debug.schema.d.ts → runtime/debug.schema.d.ts} +0 -0
  716. /package/src/config/schema/{debug.schema.js → runtime/debug.schema.js} +0 -0
  717. /package/src/config/schema/{distribution.schema.d.ts → runtime/distribution.schema.d.ts} +0 -0
  718. /package/src/config/schema/{distribution.schema.js → runtime/distribution.schema.js} +0 -0
  719. /package/src/config/schema/{ecosystem.schema.d.ts → runtime/ecosystem.schema.d.ts} +0 -0
  720. /package/src/config/schema/{ecosystem.schema.js → runtime/ecosystem.schema.js} +0 -0
  721. /package/src/config/schema/{harness.schema.d.ts → runtime/harness.schema.d.ts} +0 -0
  722. /package/src/config/schema/{harness.schema.js → runtime/harness.schema.js} +0 -0
  723. /package/src/config/schema/{hotswap.schema.d.ts → runtime/hotswap.schema.d.ts} +0 -0
  724. /package/src/config/schema/{hotswap.schema.js → runtime/hotswap.schema.js} +0 -0
  725. /package/src/config/schema/{intent-bundle.schema.d.ts → runtime/intent-bundle.schema.d.ts} +0 -0
  726. /package/src/config/schema/{intent-bundle.schema.js → runtime/intent-bundle.schema.js} +0 -0
  727. /package/src/config/schema/{runtime-profile.schema.d.ts → runtime/runtime-profile.schema.d.ts} +0 -0
  728. /package/src/config/schema/{runtime-profile.schema.js → runtime/runtime-profile.schema.js} +0 -0
  729. /package/src/config/schema/{storage.schema.d.ts → runtime/storage.schema.d.ts} +0 -0
  730. /package/src/config/schema/{storage.schema.js → runtime/storage.schema.js} +0 -0
  731. /package/src/config/schema/{tooling.schema.js → runtime/tooling.schema.js} +0 -0
  732. /package/src/config/schema/{units.schema.d.ts → runtime/units.schema.d.ts} +0 -0
  733. /package/src/config/schema/{units.schema.js → runtime/units.schema.js} +0 -0
  734. /package/src/config/schema/{backward-registry.schema.d.ts → training/backward-registry.schema.d.ts} +0 -0
  735. /package/src/config/schema/{backward-registry.schema.js → training/backward-registry.schema.js} +0 -0
  736. /package/src/config/schema/{distill-training.schema.d.ts → training/distill-training.schema.d.ts} +0 -0
  737. /package/src/config/schema/{distill-training.schema.js → training/distill-training.schema.js} +0 -0
  738. /package/src/config/schema/{lora.schema.d.ts → training/lora.schema.d.ts} +0 -0
  739. /package/src/config/schema/{training-metrics.schema.d.ts → training/training-metrics.schema.d.ts} +0 -0
  740. /package/src/config/schema/{training-metrics.schema.js → training/training-metrics.schema.js} +0 -0
  741. /package/src/config/schema/{training.schema.d.ts → training/training.schema.d.ts} +0 -0
  742. /package/src/config/schema/{training.schema.js → training/training.schema.js} +0 -0
  743. /package/src/config/schema/{ul-training.schema.d.ts → training/ul-training.schema.d.ts} +0 -0
  744. /package/src/config/schema/{ul-training.schema.js → training/ul-training.schema.js} +0 -0
  745. /package/src/{converter → config/transforms}/execution-graph/dtype.js +0 -0
  746. /package/src/{converter → config/transforms}/execution-graph/fusion.js +0 -0
  747. /package/src/{converter → config/transforms}/execution-graph/kv-storage.js +0 -0
  748. /package/src/{converter → config/transforms}/execution-graph/validation.js +0 -0
  749. /package/src/{converter → formats}/qwen4-exp-source-defaults.json +0 -0
  750. /package/src/inference/pipelines/text/{buffer-types.d.ts → contracts/buffer-types.d.ts} +0 -0
  751. /package/src/inference/pipelines/text/{embedding-contract.d.ts → embedding/embedding-contract.d.ts} +0 -0
  752. /package/src/inference/pipelines/text/{embedding-contract.js → embedding/embedding-contract.js} +0 -0
  753. /package/src/inference/pipelines/text/{precomputed-input-norm.js → execution/precomputed-input-norm.js} +0 -0
  754. /package/src/inference/pipelines/text/generator/{batch-retry-policy.js → decode/batch-retry-policy.js} +0 -0
  755. /package/src/inference/pipelines/text/{chat-format.d.ts → generator/request/chat-format.d.ts} +0 -0
  756. /package/src/inference/pipelines/text/{chat-format.js → generator/request/chat-format.js} +0 -0
  757. /package/src/inference/pipelines/text/generator/{recorder-stats.js → session/recorder-stats.js} +0 -0
  758. /package/src/inference/pipelines/text/generator/{whole-token-template.js → whole-token/whole-token-template.js} +0 -0
  759. /package/src/inference/pipelines/text/{init-chat-templates.js → initialization/init-chat-templates.js} +0 -0
  760. /package/src/inference/pipelines/text/{load-policy.js → loading/load-policy.js} +0 -0
  761. /package/src/inference/pipelines/text/{pipeline-load-timing.js → loading/pipeline-load-timing.js} +0 -0
  762. /package/src/inference/pipelines/text/{generator → logits}/hidden-projection.d.ts +0 -0
  763. /package/src/inference/pipelines/text/{operator-events.d.ts → observation/operator-events.d.ts} +0 -0
  764. /package/src/inference/pipelines/text/{stage-names.d.ts → observation/stage-names.d.ts} +0 -0
  765. /package/src/inference/pipelines/text/{stage-names.js → observation/stage-names.js} +0 -0
  766. /package/src/inference/pipelines/text/{tsir-fixture-writer.d.ts → observation/tsir-fixture-writer.d.ts} +0 -0
  767. /package/src/inference/pipelines/text/{generator → per-layer}/per-layer-buffer.js +0 -0
  768. /package/src/inference/pipelines/text/{finiteness-policy.js → policy/finiteness-policy.js} +0 -0
@@ -0,0 +1,520 @@
1
+ import { parentPort, threadId, workerData } from 'node:worker_threads';
2
+ import {
3
+ openSync, readSync, read as readAsync, writeSync, closeSync, fstatSync, lstatSync,
4
+ futimesSync, readdirSync, readFileSync, renameSync, unlinkSync, constants,
5
+ } from 'node:fs';
6
+ import { createHash } from 'node:crypto';
7
+ import { join } from 'node:path';
8
+ import { createVerifiedPieceReader } from './verified-piece-reader.js';
9
+ import { snapshotVerifiedPieceJobTimings } from './verified-piece-timings.js';
10
+
11
+ // This worker owns acquisition, complete-piece authentication and range gathering.
12
+ // Only the finished range crosses the thread boundary. No caller scratch is detached.
13
+ /** @type {Map<string, number>} */
14
+ const handles = new Map();
15
+ if (!parentPort) throw new Error('Gather requires a worker port.');
16
+ const port = parentPort;
17
+ const maxRanges = workerData.maxRanges === undefined ? 3 : workerData.maxRanges;
18
+ if (!Number.isSafeInteger(maxRanges) || maxRanges < 1 || maxRanges > 32) {
19
+ throw new Error('Gather maxRanges must be a positive safe integer no greater than 32.');
20
+ }
21
+ let closing = false;
22
+ /** @param {string} path @param {number} handle */
23
+ function assertIdentity(path, handle) {
24
+ const expected = workerData.fileIdentities?.[path];
25
+ if (!expected) return;
26
+ /** @param {import('node:fs').BigIntStats} stat */
27
+ const matches = stat => stat.isFile() && stat.dev.toString() === expected.device
28
+ && stat.ino.toString() === expected.inode && stat.size.toString() === expected.size;
29
+ if (!matches(fstatSync(handle, { bigint: true }))
30
+ || !matches(lstatSync(workerData.files[path], { bigint: true }))) {
31
+ throw new Error('Gather source identity changed after local approval.');
32
+ }
33
+ }
34
+ /** @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece
35
+ * @param {Uint8Array} bytes */
36
+ function admitFile(piece, bytes) {
37
+ if (closing) throw new Error('Gather worker closed.');
38
+ if (bytes.byteLength !== piece.size) throw new Error('Direct source read must cover its complete piece.');
39
+ const filename = workerData.files[piece.path];
40
+ if (typeof filename !== 'string') throw new Error('Missing approved piece file.');
41
+ let handle = handles.get(piece.path);
42
+ if (handle === undefined) {
43
+ if (!Number.isInteger(constants.O_NOFOLLOW) || !Number.isInteger(constants.O_NONBLOCK)) {
44
+ throw new Error('Gather regular-file admission is unsupported on this platform.');
45
+ }
46
+ // A replaced leaf must not follow a symlink or block admission on a FIFO.
47
+ // Once admitted, the retained FD owns this regular file; every read still
48
+ // authenticates complete piece bytes against the pinned index.
49
+ handle = openSync(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
50
+ try {
51
+ if (!fstatSync(handle).isFile()) throw new Error('Gather source must be a regular file.');
52
+ assertIdentity(piece.path, handle);
53
+ } catch (error) {
54
+ try { closeSync(handle); }
55
+ catch (cleanup) { throw new AggregateError([error, cleanup], 'Gather file admission and cleanup failed.'); }
56
+ throw error;
57
+ }
58
+ handles.set(piece.path, handle);
59
+ } else assertIdentity(piece.path, handle);
60
+ return handle;
61
+ }
62
+ /** @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece
63
+ * @param {Uint8Array} bytes @param {number | null} [admittedHandle] */
64
+ function readFile(piece, bytes, admittedHandle = null) {
65
+ const handle = admittedHandle ?? admitFile(piece, bytes);
66
+ let read = 0;
67
+ while (read < bytes.length) {
68
+ const count = readSync(handle, bytes, read, bytes.length - read, piece.offset + read);
69
+ if (!count) throw new Error('Incomplete authenticated piece.');
70
+ read += count;
71
+ }
72
+ if (admittedHandle === null) assertIdentity(piece.path, handle);
73
+ }
74
+ /** Whole-piece batch outputs are disjoint owned views, so parallel reads need no
75
+ * extra complete-piece scratch. Partial/generic acquisitions remain serialized.
76
+ * @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece
77
+ * @param {Uint8Array} bytes @param {number | null} admittedHandle */
78
+ async function readFileParallel(piece, bytes, admittedHandle = null) {
79
+ const handle = admittedHandle ?? admitFile(piece, bytes);
80
+ let read = 0;
81
+ while (read < bytes.length) {
82
+ if (closing) throw new Error('Gather worker closed.');
83
+ const count = await new Promise((resolve, reject) => {
84
+ readAsync(handle, bytes, read, bytes.length - read, piece.offset + read,
85
+ (error, bytesRead) => error ? reject(error) : resolve(bytesRead));
86
+ });
87
+ if (!count) throw new Error('Incomplete authenticated piece.');
88
+ read += count;
89
+ }
90
+ if (admittedHandle === null) assertIdentity(piece.path, handle);
91
+ }
92
+ const reader = await createVerifiedPieceReader({ ...workerData.metadata,
93
+ acquire: async () => { throw new Error('Gather worker uses owned piece verification.'); },
94
+ });
95
+ // Only the common verifier's authenticated index may select the direct path.
96
+ // This worker owns the FD and transferred output; no external acquisition callback
97
+ // can mutate the bytes between full-piece SHA and publication.
98
+ let directPieceReads = 0, directPieceBytes = 0, acquisitionMs = 0, verificationMs = 0;
99
+ let batchReads = 0, batchRanges = 0, batchBytes = 0;
100
+ let activeGenericScratchBytes = 0, peakGenericScratchBytes = 0, genericRequestedBytes = 0, genericCopyMs = 0;
101
+ let protectedCacheHits = 0, protectedCacheHitBytes = 0, protectedCacheMisses = 0;
102
+ let protectedCacheAdmissions = 0, protectedCacheAdmittedBytes = 0;
103
+ let protectedCacheEvictions = 0, protectedCacheEvictedBytes = 0, protectedCacheSkips = 0;
104
+ const protectedCache = workerData.protectedCache ?? null;
105
+ const bucketBytesView = protectedCache ? new BigInt64Array(protectedCache.sharedBucketBytes) : null;
106
+ const expectedUid = typeof process.geteuid === 'function' ? process.geteuid() : null;
107
+ let tmpSeq = 0, lastMemCheckAt = 0, lastMemAvailableBytes = Infinity;
108
+
109
+ /** @param {number} extraBytes */
110
+ function hasHostMemoryReserve(extraBytes) {
111
+ if (!protectedCache || protectedCache.minHostAvailableBytes <= 0 || process.platform !== 'linux') return true;
112
+ const now = performance.now();
113
+ if (now - lastMemCheckAt >= 50) {
114
+ lastMemCheckAt = now;
115
+ try {
116
+ const text = readFileSync('/proc/meminfo', 'utf8');
117
+ const match = /^MemAvailable:\s+(\d+)/mu.exec(text);
118
+ lastMemAvailableBytes = match ? Number(match[1]) * 1024 : 0;
119
+ } catch {
120
+ lastMemAvailableBytes = 0;
121
+ }
122
+ }
123
+ return lastMemAvailableBytes - extraBytes >= protectedCache.minHostAvailableBytes;
124
+ }
125
+
126
+ /** @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece */
127
+ function protectedLocation(piece) {
128
+ if (!protectedCache || typeof piece.identity !== 'string' || !piece.identity.startsWith('sha256:')) return null;
129
+ const hex = piece.identity.slice(7);
130
+ if (!/^[a-f0-9]{64}$/u.test(hex)) return null;
131
+ const bucketIndex = parseInt(hex.slice(0, 2), 16) & (protectedCache.bucketCount - 1);
132
+ const bucketDir = join(protectedCache.directory, bucketIndex.toString(16).padStart(2, '0'));
133
+ return { hex, bucketIndex, bucketDir, cachePath: join(bucketDir, `${hex}.piece`) };
134
+ }
135
+
136
+ /**
137
+ * Attempt to read a complete piece from the protected cache, authenticating its
138
+ * full SHA-256 digest before accepting. Corrupted cache entries are unlinked and
139
+ * fall back transparently to the admitted underlying source file.
140
+ * @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece
141
+ * @param {Uint8Array} output
142
+ * @param {boolean} isDirect
143
+ */
144
+ function tryReadProtectedPiece(piece, output, isDirect) {
145
+ const loc = protectedLocation(piece);
146
+ if (!loc || output.byteLength !== piece.size) return false;
147
+ let fd = -1;
148
+ const readStart = performance.now();
149
+ try {
150
+ fd = openSync(loc.cachePath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
151
+ const st = fstatSync(fd);
152
+ if (!st.isFile() || st.size !== piece.size || (expectedUid !== null && st.uid !== expectedUid)) {
153
+ try { unlinkSync(loc.cachePath); } catch {}
154
+ return false;
155
+ }
156
+ let read = 0;
157
+ while (read < output.length) {
158
+ const count = readSync(fd, output, read, output.length - read, read);
159
+ if (!count) {
160
+ try { unlinkSync(loc.cachePath); } catch {}
161
+ return false;
162
+ }
163
+ read += count;
164
+ }
165
+ if (Date.now() - st.mtimeMs >= 5000) {
166
+ const nowSec = Date.now() / 1000;
167
+ try { futimesSync(fd, nowSec, nowSec); } catch {}
168
+ }
169
+ } catch {
170
+ return false;
171
+ } finally {
172
+ if (fd !== -1) {
173
+ try { closeSync(fd); } catch {}
174
+ }
175
+ acquisitionMs += performance.now() - readStart;
176
+ }
177
+ const hashStart = performance.now();
178
+ const digest = 'sha256:' + createHash('sha256').update(output).digest('hex');
179
+ verificationMs += performance.now() - hashStart;
180
+ if (digest !== piece.identity) {
181
+ output.fill(0);
182
+ try {
183
+ unlinkSync(loc.cachePath);
184
+ if (bucketBytesView) Atomics.sub(bucketBytesView, loc.bucketIndex, BigInt(piece.size));
185
+ } catch {}
186
+ return false;
187
+ }
188
+ if (isDirect) recordDirect(piece, digest);
189
+ else recordPiece(piece, digest);
190
+ protectedCacheHits++;
191
+ protectedCacheHitBytes += piece.size;
192
+ return true;
193
+ }
194
+
195
+ /**
196
+ * Admit an already SHA-256-authenticated piece into the bounded protected cache.
197
+ * Uses scan-resistant hash-priority retention among fresh entries and evicts
198
+ * stale entries across workload transitions without exceeding bucketMaxBytes.
199
+ * @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece
200
+ * @param {Uint8Array} output
201
+ */
202
+ function admitProtectedPiece(piece, output) {
203
+ const loc = protectedLocation(piece);
204
+ if (!loc || !protectedCache || !bucketBytesView || closing
205
+ || output.byteLength !== piece.size || piece.size > protectedCache.bucketMaxBytes) {
206
+ return;
207
+ }
208
+ if (!hasHostMemoryReserve(piece.size)) {
209
+ protectedCacheSkips++;
210
+ return;
211
+ }
212
+ const sizeBig = BigInt(piece.size);
213
+ const maxBig = BigInt(protectedCache.bucketMaxBytes);
214
+ if (Atomics.load(bucketBytesView, loc.bucketIndex) + sizeBig > maxBig) {
215
+ const nowMs = Date.now();
216
+ let actualBytes = 0;
217
+ /** @type {Array<{ hex: string, path: string, size: number, mtimeMs: number }>} */
218
+ const stale = [];
219
+ /** @type {Array<{ hex: string, path: string, size: number, mtimeMs: number }>} */
220
+ const lowerPriorityFresh = [];
221
+ try {
222
+ for (const name of readdirSync(loc.bucketDir)) {
223
+ const entryPath = join(loc.bucketDir, name);
224
+ if (name.includes('.tmp.')) {
225
+ try {
226
+ const st = lstatSync(entryPath);
227
+ if (nowMs - st.mtimeMs > 30_000) unlinkSync(entryPath);
228
+ } catch {}
229
+ continue;
230
+ }
231
+ if (!name.endsWith('.piece')) continue;
232
+ try {
233
+ const st = lstatSync(entryPath);
234
+ if (!st.isFile()) continue;
235
+ const entryHex = name.slice(0, -6);
236
+ if (entryHex === loc.hex && st.size === piece.size) return;
237
+ actualBytes += st.size;
238
+ if (nowMs - st.mtimeMs > protectedCache.staleAfterMs) {
239
+ stale.push({ hex: entryHex, path: entryPath, size: st.size, mtimeMs: st.mtimeMs });
240
+ } else if (entryHex > loc.hex) {
241
+ lowerPriorityFresh.push({ hex: entryHex, path: entryPath, size: st.size, mtimeMs: st.mtimeMs });
242
+ }
243
+ } catch {}
244
+ }
245
+ } catch {
246
+ protectedCacheSkips++;
247
+ return;
248
+ }
249
+ Atomics.store(bucketBytesView, loc.bucketIndex, BigInt(actualBytes));
250
+ if (actualBytes + piece.size > protectedCache.bucketMaxBytes) {
251
+ stale.sort((a, b) => a.mtimeMs - b.mtimeMs);
252
+ lowerPriorityFresh.sort((a, b) => (a.hex < b.hex ? 1 : a.hex > b.hex ? -1 : 0));
253
+ const candidates = [...stale, ...lowerPriorityFresh];
254
+ const reclaimable = candidates.reduce((sum, item) => sum + item.size, 0);
255
+ if (actualBytes - reclaimable + piece.size > protectedCache.bucketMaxBytes) {
256
+ protectedCacheSkips++;
257
+ return;
258
+ }
259
+ for (const victim of candidates) {
260
+ if (actualBytes + piece.size <= protectedCache.bucketMaxBytes) break;
261
+ try {
262
+ unlinkSync(victim.path);
263
+ actualBytes -= victim.size;
264
+ Atomics.sub(bucketBytesView, loc.bucketIndex, BigInt(victim.size));
265
+ protectedCacheEvictions++;
266
+ protectedCacheEvictedBytes += victim.size;
267
+ } catch {}
268
+ }
269
+ if (actualBytes + piece.size > protectedCache.bucketMaxBytes) {
270
+ protectedCacheSkips++;
271
+ return;
272
+ }
273
+ }
274
+ }
275
+ const reservedAfter = Atomics.add(bucketBytesView, loc.bucketIndex, sizeBig) + sizeBig;
276
+ if (reservedAfter > maxBig) {
277
+ Atomics.sub(bucketBytesView, loc.bucketIndex, sizeBig);
278
+ protectedCacheSkips++;
279
+ return;
280
+ }
281
+ const tmpPath = join(loc.bucketDir, `${loc.hex}.tmp.${process.pid}.${threadId}.${++tmpSeq}`);
282
+ let fd = -1;
283
+ try {
284
+ try {
285
+ const existing = lstatSync(loc.cachePath);
286
+ if (existing.isFile() && existing.size === piece.size) {
287
+ Atomics.sub(bucketBytesView, loc.bucketIndex, sizeBig);
288
+ return;
289
+ }
290
+ } catch {}
291
+ fd = openSync(tmpPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
292
+ let written = 0;
293
+ while (written < output.length) {
294
+ written += writeSync(fd, output, written, output.length - written, written);
295
+ }
296
+ closeSync(fd);
297
+ fd = -1;
298
+ renameSync(tmpPath, loc.cachePath);
299
+ protectedCacheAdmissions++;
300
+ protectedCacheAdmittedBytes += piece.size;
301
+ } catch {
302
+ if (fd !== -1) {
303
+ try { closeSync(fd); } catch {}
304
+ }
305
+ try { unlinkSync(tmpPath); } catch {}
306
+ Atomics.sub(bucketBytesView, loc.bucketIndex, sizeBig);
307
+ protectedCacheSkips++;
308
+ }
309
+ }
310
+ /** @type {Map<string, Readonly<import('./verified-piece-reader.js').VerifiedPiece>>} */
311
+ const verifiedRanges = new Map();
312
+ const maxPieceBytes = JSON.parse(new TextDecoder().decode(workerData.metadata.indexBytes)).maxPieceBytes;
313
+ /** @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece
314
+ * @param {string} identity */
315
+ function recordPiece(piece, identity) {
316
+ if (identity !== piece.identity) throw new Error('Acquired piece integrity mismatch.');
317
+ verifiedRanges.set(`${piece.path}:${piece.offset}`, piece);
318
+ }
319
+ /** @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece
320
+ * @param {string} identity */
321
+ function recordDirect(piece, identity) {
322
+ recordPiece(piece, identity);
323
+ directPieceReads++; directPieceBytes += piece.size;
324
+ }
325
+ /** @param {Readonly<import('./verified-piece-reader.js').VerifiedPiece>} piece
326
+ * @param {Uint8Array} output */
327
+ function authenticateDirect(piece, output) {
328
+ const started = performance.now();
329
+ const identity = 'sha256:' + createHash('sha256').update(output).digest('hex');
330
+ verificationMs += performance.now() - started;
331
+ recordDirect(piece, identity);
332
+ }
333
+ /** @returns {import('./verified-piece-gather.js').VerifiedPieceGatherReceipt} */
334
+ function getReceipt() {
335
+ const generic = reader.getReceipt();
336
+ const ranges = new Map([
337
+ ...generic.ranges.map(range => /** @type {const} */ ([`${range.path}:${range.offset}`, range])),
338
+ ...verifiedRanges,
339
+ ]);
340
+ const pieces = new Map([...ranges.values()].map(range => [range.identity, range.size]));
341
+ return { ...generic, ranges: [...ranges.values()], pieces: [...pieces.keys()],
342
+ verifiedBytes: [...pieces.values()].reduce((sum, size) => sum + size, 0),
343
+ requestedBytes: generic.requestedBytes + directPieceBytes + genericRequestedBytes,
344
+ copyMs: generic.copyMs + genericCopyMs,
345
+ acquisitionMs: generic.acquisitionMs + acquisitionMs, verificationMs: generic.verificationMs + verificationMs,
346
+ directPieceReads, directPieceBytes, batchReads, batchRanges, batchBytes,
347
+ activeDigestCopyBytes: 0, peakDigestCopyBytes: 0,
348
+ activeGenericScratchBytes, peakGenericScratchBytes,
349
+ protectedCacheHits, protectedCacheHitBytes, protectedCacheMisses,
350
+ protectedCacheAdmissions, protectedCacheAdmittedBytes,
351
+ protectedCacheEvictions, protectedCacheEvictedBytes, protectedCacheSkips };
352
+ }
353
+ port.postMessage({ ready: true });
354
+ /** @type {Set<Promise<void>>} */
355
+ const operations = new Set();
356
+ /** @type {Promise<void> | null} */
357
+ let retirement = null;
358
+ function closeWorker() {
359
+ closing = true;
360
+ if (!retirement) {
361
+ const operation = (async () => {
362
+ await Promise.allSettled([...operations]);
363
+ await reader.close();
364
+ const errors = [];
365
+ for (const [path, handle] of handles) {
366
+ try { closeSync(handle); handles.delete(path); }
367
+ catch (error) { errors.push(error); }
368
+ }
369
+ if (errors.length) throw new AggregateError(errors, 'Gather descriptor retirement failed.');
370
+ })();
371
+ retirement = operation;
372
+ operation.catch(() => { if (retirement === operation) retirement = null; });
373
+ }
374
+ return retirement;
375
+ }
376
+ /** @param {{ ranges: ReadonlyArray<{path: string, offset: number, length: number}>, length: number,
377
+ * buffer: ArrayBuffer, batch?: boolean }} request */
378
+ async function gather({ ranges, length, buffer, batch }) {
379
+ const started = performance.now();
380
+ const before = { acquisitionMs, verificationMs, genericCopyMs };
381
+ try {
382
+ if (closing) throw new Error('Gather worker closed.');
383
+ if (operations.size) throw new Error('Gather worker already owns a request.');
384
+ if (!(buffer instanceof ArrayBuffer) || buffer.byteLength !== workerData.maxPartBytes
385
+ || !Array.isArray(ranges) || ranges.length < 1 || ranges.length > maxRanges
386
+ || !Number.isSafeInteger(length) || length < 0 || length > buffer.byteLength
387
+ || ranges.some(range => typeof range.path !== 'string' || !Number.isSafeInteger(range.offset) || range.offset < 0
388
+ || !Number.isSafeInteger(range.length) || range.length < (batch ? 1 : 0)
389
+ || !Number.isSafeInteger(range.offset + range.length))
390
+ || ranges.reduce((sum, range) => sum + range.length, 0) !== length) {
391
+ throw new Error('Invalid bounded gather request.');
392
+ }
393
+ const pieces = ranges.map(({ path, offset, length: rangeLength }) => reader.resolveCompletePiece(path, offset, rangeLength));
394
+ if (batch && pieces.every(piece => piece !== null)) {
395
+ let destination = 0;
396
+ const outputs = pieces.map(piece => {
397
+ const output = new Uint8Array(buffer, destination, piece.size);
398
+ destination += piece.size;
399
+ return output;
400
+ });
401
+ // One job owns these exact descriptor bindings. Admission checks each
402
+ // distinct path before any read; publication checks them again only after
403
+ // every native read and digest settles. Never reuse guards across jobs.
404
+ /** @type {Map<string, number>} */
405
+ const admitted = new Map();
406
+ for (const [index, piece] of pieces.entries()) {
407
+ if (!admitted.has(piece.path)) admitted.set(piece.path, admitFile(piece, outputs[index]));
408
+ }
409
+ const reads = pieces.map((piece, index) => {
410
+ const output = outputs[index];
411
+ return (async () => {
412
+ if (tryReadProtectedPiece(piece, output, true)) {
413
+ if (closing) throw new Error('Gather worker closed.');
414
+ return;
415
+ }
416
+ if (protectedCache) protectedCacheMisses++;
417
+ const readStart = performance.now();
418
+ try {
419
+ if (pieces.length === 1) readFile(piece, output, admitted.get(piece.path));
420
+ else await readFileParallel(piece, output, admitted.get(piece.path));
421
+ } finally { acquisitionMs += performance.now() - readStart; }
422
+ if (closing) throw new Error('Gather worker closed.');
423
+ // This worker exclusively owns the output until transfer. Hash that
424
+ // storage directly, without WebCrypto's input snapshot and another
425
+ // shared thread-pool handoff. Other worker lanes still run in parallel.
426
+ authenticateDirect(piece, output);
427
+ admitProtectedPiece(piece, output);
428
+ })();
429
+ });
430
+ // A rejected read must not zero or transfer a buffer while a sibling native
431
+ // read can still write it. Settle every admitted read before either outcome.
432
+ const outcomes = await Promise.allSettled(reads);
433
+ const failed = outcomes.find(outcome => outcome.status === 'rejected');
434
+ const identityFailures = [];
435
+ for (const [path, handle] of admitted) {
436
+ try { assertIdentity(path, handle); } catch (error) { identityFailures.push(error); }
437
+ }
438
+ if (failed) throw failed.reason;
439
+ if (identityFailures.length) throw identityFailures[0];
440
+ } else {
441
+ let destination = 0;
442
+ /** @type {Uint8Array<ArrayBuffer> | null} */
443
+ let scratch = null;
444
+ try {
445
+ for (const [index, { path, offset, length: rangeLength }] of ranges.entries()) {
446
+ const output = new Uint8Array(buffer, destination, rangeLength);
447
+ const piece = pieces[index];
448
+ if (piece) {
449
+ const admittedHandle = admitFile(piece, output);
450
+ if (!tryReadProtectedPiece(piece, output, true)) {
451
+ if (protectedCache) protectedCacheMisses++;
452
+ const readStart = performance.now();
453
+ try { readFile(piece, output, admittedHandle); }
454
+ finally { acquisitionMs += performance.now() - readStart; }
455
+ authenticateDirect(piece, output);
456
+ admitProtectedPiece(piece, output);
457
+ }
458
+ } else {
459
+ const selected = reader.resolveRangePieces(path, offset, rangeLength);
460
+ if (!selected.length) { destination += rangeLength; continue; }
461
+ if (!scratch) {
462
+ scratch = new Uint8Array(maxPieceBytes);
463
+ activeGenericScratchBytes = scratch.byteLength;
464
+ peakGenericScratchBytes = Math.max(peakGenericScratchBytes, activeGenericScratchBytes);
465
+ }
466
+ for (const current of selected) {
467
+ const bytes = scratch.subarray(0, current.size);
468
+ const admittedHandle = admitFile(current, bytes);
469
+ if (!tryReadProtectedPiece(current, bytes, false)) {
470
+ if (protectedCache) protectedCacheMisses++;
471
+ const readStart = performance.now();
472
+ try { readFile(current, bytes, admittedHandle); }
473
+ finally { acquisitionMs += performance.now() - readStart; }
474
+ const hashStart = performance.now();
475
+ const identity = 'sha256:' + createHash('sha256').update(bytes).digest('hex');
476
+ verificationMs += performance.now() - hashStart; recordPiece(current, identity);
477
+ admitProtectedPiece(current, bytes);
478
+ }
479
+ const start = Math.max(offset, current.offset), end = Math.min(offset + rangeLength, current.offset + current.size);
480
+ const copyStart = performance.now();
481
+ output.set(bytes.subarray(start - current.offset, end - current.offset), start - offset);
482
+ genericCopyMs += performance.now() - copyStart; genericRequestedBytes += end - start;
483
+ }
484
+ }
485
+ destination += rangeLength;
486
+ }
487
+ } finally { scratch = null; activeGenericScratchBytes = 0; }
488
+ // Full and partial single leases also retain their admitted binding until
489
+ // publication. A matching-content path replacement during hashing must not
490
+ // relabel the old descriptor as the approved source. Empty reads own no FD.
491
+ for (const path of new Set(ranges.filter(range => range.length > 0).map(range => range.path))) {
492
+ const handle = handles.get(path);
493
+ if (handle === undefined) throw new Error('Gather source descriptor missing.');
494
+ assertIdentity(path, handle);
495
+ }
496
+ }
497
+ if (closing) throw new Error('Gather worker closed.');
498
+ if (batch) { batchReads++; batchRanges += ranges.length; batchBytes += length; }
499
+ const timings = snapshotVerifiedPieceJobTimings({ workerWallMs: performance.now() - started,
500
+ readWaitMs: acquisitionMs - before.acquisitionMs, verificationMs: verificationMs - before.verificationMs,
501
+ copyMs: genericCopyMs - before.genericCopyMs });
502
+ port.postMessage({ buffer, length, timings }, [buffer]);
503
+ } catch (error) {
504
+ // Never publish a verified prefix after a later piece fails verification.
505
+ new Uint8Array(buffer).fill(0);
506
+ port.postMessage({ buffer, error: String(error.message ?? error) }, [buffer]);
507
+ }
508
+ }
509
+ port.on('message', message => {
510
+ if (message.close === true) {
511
+ closeWorker().then(() => port.postMessage({ closed: true, receipt: getReceipt() }),
512
+ error => port.postMessage({ closed: true, error: String(error.message ?? error) }));
513
+ return;
514
+ }
515
+ if (message.receipt === true) { port.postMessage({ receipt: getReceipt() }); return; }
516
+ const operation = gather(message);
517
+ operations.add(operation);
518
+ operation.finally(() => operations.delete(operation)).catch(() => {});
519
+ });
520
+ process.on('exit', () => { for (const handle of handles.values()) closeSync(handle); });
@@ -0,0 +1,113 @@
1
+ import type { VerifiedPieceReceipt } from './verified-piece-reader.js';
2
+ export interface VerifiedPieceProtectedCacheOptions {
3
+ /** Explicit absolute directory (for example on tmpfs /dev/shm) owned by the current user; symlinks are rejected. */
4
+ directory: string;
5
+ /** Maximum bytes retained across all content-addressed piece buckets. */
6
+ maxBytes: number;
7
+ /** Optional host MemAvailable floor in bytes; admissions pause when freeable reserve would dip below this floor. */
8
+ minHostAvailableBytes?: number;
9
+ /** Optional staleness horizon in milliseconds before unhit entries yield to new workloads (default 90000). */
10
+ staleAfterMs?: number;
11
+ }
12
+ export interface VerifiedPieceGatherOptions {
13
+ manifestBytes: Uint8Array<ArrayBuffer>;
14
+ indexBytes: Uint8Array<ArrayBuffer>;
15
+ indexIdentity: string;
16
+ /** Explicit approved regular files, indexed by authenticated piece-index filename.
17
+ * Resolve authorized links before passing their canonical paths; leaf symlinks are rejected. */
18
+ files: Record<string, string>;
19
+ /** Optional explicit host snapshot. Canonical path and opened descriptor must
20
+ * retain this device/inode/size through post-authentication publication checks
21
+ * for nonempty single and batched leases; complete-piece SHA still applies. */
22
+ fileIdentities?: Record<string, { device: string; inode: string; size: string }>;
23
+ maxPartBytes: number;
24
+ /** Explicit range-count bound per output, 1..32; omission preserves three. */
25
+ maxRanges?: number;
26
+ /** Explicit worker count; omission preserves one lane. */
27
+ concurrency?: number;
28
+ /** Cancels asynchronous worker admission; does not replace read signals or close ownership. */
29
+ startupSignal?: AbortSignal;
30
+ /** All outputs plus a conservative two-piece allowance per worker for generic
31
+ * piece buffers. Excludes fixed native digest state, metadata and VM overhead. */
32
+ memoryBudgetBytes: number;
33
+ /** Optional bounded host-protected cache of authenticated pieces; every cache hit is still SHA-256 verified. */
34
+ protectedCache?: VerifiedPieceProtectedCacheOptions;
35
+ }
36
+ /** Per-job worker observations. Async read waits and different worker jobs can overlap. */
37
+ export interface VerifiedPieceJobTimings {
38
+ workerWallMs: number;
39
+ /** Includes native I/O and callback/scheduling wait; not isolated disk time. */
40
+ readWaitMs: number;
41
+ verificationMs: number;
42
+ copyMs: number;
43
+ }
44
+ export interface VerifiedRangeLeaseTimings extends VerifiedPieceJobTimings {
45
+ /** Lane-local elapsed time from posting the owned job until its reply, not a cross-clock subtraction. */
46
+ roundTripMs: number;
47
+ }
48
+ export interface VerifiedRangeLease {
49
+ bytes: Uint8Array<ArrayBuffer>;
50
+ /** Frozen bounded scalar observations, piggybacked on the existing successful reply.
51
+ * Omission means unsupported; zero-valued fields alone do not establish coverage. */
52
+ timings?: Readonly<VerifiedRangeLeaseTimings>;
53
+ /** Idempotent. Detaches bytes; call only after the consumer has copied them. */
54
+ release(): void;
55
+ }
56
+ export interface VerifiedPieceGatherReceipt extends VerifiedPieceReceipt {
57
+ /** Successful full-piece reads directly into the worker-owned output, authenticated before transfer. */
58
+ directPieceReads: number;
59
+ directPieceBytes: number;
60
+ /** Successfully published multi-range requests, ranges and payload bytes. */
61
+ batchReads: number;
62
+ batchRanges: number;
63
+ batchBytes: number;
64
+ /** Retained receipt field; direct worker-owned SHA creates no input snapshots. */
65
+ activeDigestCopyBytes: number;
66
+ /** Retained receipt field; zero for direct worker-owned SHA. */
67
+ peakDigestCopyBytes: number;
68
+ /** Reusable owned generic piece scratch. Whole-piece reads need none. */
69
+ activeGenericScratchBytes: number;
70
+ /** Per-worker peaks are summed as a conservative aggregate upper bound. */
71
+ peakGenericScratchBytes: number;
72
+ /** Protected cache counters; zero when protectedCache is omitted. */
73
+ protectedCacheHits: number;
74
+ protectedCacheHitBytes: number;
75
+ protectedCacheMisses: number;
76
+ protectedCacheAdmissions: number;
77
+ protectedCacheAdmittedBytes: number;
78
+ protectedCacheEvictions: number;
79
+ protectedCacheEvictedBytes: number;
80
+ protectedCacheSkips: number;
81
+ }
82
+ export function createVerifiedPieceGather(options: VerifiedPieceGatherOptions): Promise<Readonly<{
83
+ /** At most concurrency in-flight reads or outstanding leases. Cancellation is checked before
84
+ * publishing; close rejects pending reads immediately and waits for settled worker ownership. */
85
+ readLease(path: string, offset: number, length: number, signal?: AbortSignal): Promise<VerifiedRangeLease>;
86
+ /** One concatenated owned output; positive ranges share maxPartBytes and the explicit maxRanges bound. */
87
+ readManyLease(ranges: ReadonlyArray<{ path: string; offset: number; length: number }>, signal?: AbortSignal): Promise<VerifiedRangeLease>;
88
+ /** Snapshot of worker verification evidence; requires no outstanding lease. */
89
+ getReceipt(): Promise<VerifiedPieceGatherReceipt>;
90
+ /** Stops admission permanently and awaits all I/O/hash jobs and closed descriptors
91
+ * before terminating workers. Failed retirement remains retryable.
92
+ * Published leases remain caller-owned until release, even after close. */
93
+ close(): Promise<void>;
94
+ rangeLease: VerifiedRangeLeasePort;
95
+ }>>;
96
+
97
+ export interface VerifiedRangeLeasePort {
98
+ /** True only when the worker enforces the supplied file identity snapshot. */
99
+ fileIdentitiesBound?: boolean;
100
+ /** True when workers read/admit through an explicit bounded protected piece cache. */
101
+ protectedCacheBound?: boolean;
102
+ /** readMany validates every requested path and open descriptor before reads and after authentication, before publication. */
103
+ batchFileIdentityChecks?: 'before-read-after-auth/v1';
104
+ /** Omission denotes a legacy single-lane port. */
105
+ concurrency?: number;
106
+ maxPartBytes: number;
107
+ /** Omission denotes the legacy three-range batch bound. */
108
+ maxRanges?: number;
109
+ memoryBytes: number;
110
+ read(shard: number, offset: number, length: number, signal: AbortSignal): Promise<VerifiedRangeLease>;
111
+ /** Optional batch capability. One output contains ranges in caller order, without padding. */
112
+ readMany?(ranges: ReadonlyArray<{ shard: number; offset: number; length: number }>, signal: AbortSignal): Promise<VerifiedRangeLease>;
113
+ }