doppler-gpu 0.4.15 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (221) hide show
  1. package/README.md +9 -0
  2. package/package.json +25 -2
  3. package/src/cli/doppler-cli.js +253 -94
  4. package/src/cli/runtime-profiles.js +3 -7
  5. package/src/client/doppler-api.d.ts +28 -0
  6. package/src/client/doppler-api.js +2 -0
  7. package/src/client/inspection.d.ts +122 -0
  8. package/src/client/inspection.js +343 -0
  9. package/src/client/runtime/index.d.ts +54 -0
  10. package/src/client/runtime/index.js +190 -18
  11. package/src/client/runtime/model-manager.d.ts +0 -4
  12. package/src/client/runtime/model-manager.js +0 -28
  13. package/src/client/runtime/model-session.d.ts +48 -1
  14. package/src/client/runtime/model-session.js +149 -30
  15. package/src/client/runtime/model-source.d.ts +10 -1
  16. package/src/client/runtime/scoped-session.d.ts +117 -0
  17. package/src/client/runtime/scoped-session.js +257 -0
  18. package/src/client/runtime/types.d.ts +0 -1
  19. package/src/client/runtime/types.js +0 -1
  20. package/src/config/evidence/boundary-evidence-policy.json +54 -0
  21. package/src/config/evidence/source-intake-policy.json +122 -0
  22. package/src/config/inspection/observation-policies.json +80 -0
  23. package/src/config/param-validator.js +21 -36
  24. package/src/config/runtime/compute/f16-activations.json +1 -0
  25. package/src/config/runtime/compute/f16-batched.json +1 -0
  26. package/src/config/runtime/default.json +1 -0
  27. package/src/config/runtime/diagnostics/debug-logits.json +1 -0
  28. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-alt.json +1 -0
  29. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-batched.json +1 -0
  30. package/src/config/runtime/experiments/bench/gemma3-bench-q4k.json +1 -0
  31. package/src/config/runtime/experiments/bench/gemma4-bench-q4k.json +1 -0
  32. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-alt.json +1 -0
  33. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-batched.json +1 -0
  34. package/src/config/runtime/experiments/debug/gemma3-browser-diagnose-q4k.json +1 -1
  35. package/src/config/runtime/experiments/debug/gemma3-debug-q4k.json +1 -3
  36. package/src/config/runtime/experiments/debug/gemma4-e2b-browser-diagnose-q4k.json +1 -1
  37. package/src/config/runtime/experiments/debug/qwen35-browser-diagnose-q4k.json +1 -1
  38. package/src/config/runtime/experiments/verify/gemma3-verify.json +1 -3
  39. package/src/config/runtime/experiments/verify/gemma4-e2b-verify.json +1 -3
  40. package/src/config/runtime/experiments/verify/lfm2-verify.json +1 -3
  41. package/src/config/runtime/experiments/verify/translategemma-verify.json +1 -3
  42. package/src/config/runtime/model/gemma2-debug.json +1 -0
  43. package/src/config/runtime/model/gemma2-pipeline-debug.json +1 -0
  44. package/src/config/runtime/model/gemma2-pipeline.json +1 -0
  45. package/src/config/runtime/model/gemma3-layer-probe.json +1 -0
  46. package/src/config/runtime/model/qwen3-5-layer-probe.json +1 -0
  47. package/src/config/runtime/model/qwen3-5-layer3-boundary-probe.json +1 -0
  48. package/src/config/runtime/model/qwen3-5-linear-attn-debug.json +1 -0
  49. package/src/config/runtime/optimization-candidates/registry.json +5 -0
  50. package/src/config/runtime/platform/metal-apple-q4k.json +1 -0
  51. package/src/config/runtime/profiles/default.json +1 -0
  52. package/src/config/runtime/profiles/diffusiongemma-26b-a4b-throughput.json +1 -0
  53. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-overlapped-probe.json +1 -0
  54. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-probe.json +1 -0
  55. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-b4.json +1 -3
  56. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-single.json +1 -3
  57. package/src/config/runtime/profiles/gemma4-31b-f16-activations-probe.json +1 -5
  58. package/src/config/runtime/profiles/gemma4-e2b-baseline-probe.json +1 -3
  59. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-probe.json +1 -3
  60. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-test.json +1 -0
  61. package/src/config/runtime/profiles/gemma4-e2b-int4ple-baseline-probe.json +1 -5
  62. package/src/config/runtime/profiles/gemma4-e2b-int4ple-f16a-probe.json +1 -5
  63. package/src/config/runtime/profiles/gemma4-e2b-int4ple-reference-export.json +1 -3
  64. package/src/config/runtime/profiles/gemma4-e2b-int4ple-retain-q4k-probe.json +1 -5
  65. package/src/config/runtime/profiles/gemma4-e2b-low-memory.json +1 -0
  66. package/src/config/runtime/profiles/gemma4-e2b-prefill-profile.json +1 -3
  67. package/src/config/runtime/profiles/gemma4-e2b-throughput-probe.json +1 -0
  68. package/src/config/runtime/profiles/low-memory.json +1 -0
  69. package/src/config/runtime/profiles/production.json +1 -3
  70. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-attn128-candidate.json +1 -0
  71. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-maxbatch64-candidate.json +1 -0
  72. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-normed-ffn-candidate.json +1 -0
  73. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-overlap-ringtokens1-candidate.json +1 -0
  74. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-parity.json +1 -0
  75. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-sequential-candidate.json +1 -0
  76. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-throughput.json +1 -0
  77. package/src/config/runtime/profiles/qwen-3-5-0-8b-prefill-profile.json +1 -3
  78. package/src/config/runtime/profiles/qwen-3-5-0-8b-throughput-probe.json +1 -0
  79. package/src/config/runtime/profiles/qwen-3-5-2b-f16-primary-throughput.json +1 -5
  80. package/src/config/runtime/profiles/qwen-3-5-2b-metal-parity.json +1 -0
  81. package/src/config/runtime/profiles/qwen-3-5-2b-metal-throughput.json +1 -0
  82. package/src/config/runtime/profiles/qwen-3-5-9b-metal-correctness.json +1 -0
  83. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-stability.json +1 -3
  84. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-throughput.json +1 -0
  85. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-stability.json +1 -0
  86. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-throughput.json +1 -0
  87. package/src/config/runtime/profiles/qwen3-6-27b-f16-activations-probe.json +1 -5
  88. package/src/config/runtime/profiles/rerank-stability.json +1 -3
  89. package/src/config/runtime/profiles/rerank-throughput.json +1 -3
  90. package/src/config/runtime/profiles/simulation.json +1 -3
  91. package/src/config/runtime/profiles/throughput.json +1 -3
  92. package/src/config/runtime/profiles/trace-layers.json +1 -3
  93. package/src/config/runtime/profiles/translategemma-1b-nativekd2-q4k-rdna3-throughput-probe.json +1 -0
  94. package/src/config/runtime/profiles/turboquant-contiguous-prod.json +1 -0
  95. package/src/config/runtime/profiles/turboquant-contiguous.json +1 -0
  96. package/src/config/runtime/profiles/turboquant.json +1 -0
  97. package/src/config/runtime/profiles/vector-stability.json +1 -3
  98. package/src/config/runtime/profiles/vector-throughput.json +1 -0
  99. package/src/config/runtime/profiles/verbose-trace.json +1 -3
  100. package/src/config/runtime/tiers/gemma4-128gb.json +1 -0
  101. package/src/config/runtime/tiers/gemma4-16gb.json +1 -0
  102. package/src/config/runtime/tiers/gemma4-24gb.json +1 -0
  103. package/src/config/runtime/tiers/gemma4-32gb.json +1 -0
  104. package/src/config/schema/benchmark.schema.d.ts +7 -0
  105. package/src/config/schema/benchmark.schema.js +5 -0
  106. package/src/config/schema/index.d.ts +8 -16
  107. package/src/config/schema/index.js +5 -8
  108. package/src/config/schema/kernel-thresholds.schema.d.ts +0 -12
  109. package/src/config/schema/kernel-thresholds.schema.js +0 -12
  110. package/src/config/schema/kernel-warmup.schema.d.ts +1 -3
  111. package/src/config/schema/kernel-warmup.schema.js +0 -1
  112. package/src/config/schema/runtime-profile.schema.d.ts +24 -0
  113. package/src/config/schema/runtime-profile.schema.js +92 -0
  114. package/src/config/schema/shared-runtime.schema.d.ts +1 -4
  115. package/src/config/schema/shared-runtime.schema.js +0 -2
  116. package/src/config/schema/tooling.schema.d.ts +8 -5
  117. package/src/config/schema/tooling.schema.js +3 -2
  118. package/src/debug/tensor.d.ts +2 -0
  119. package/src/debug/tensor.js +21 -2
  120. package/src/gpu/command-recorder.d.ts +5 -0
  121. package/src/gpu/command-recorder.js +17 -0
  122. package/src/gpu/kernel-runtime.js +2 -10
  123. package/src/gpu/kernels/index.d.ts +0 -2
  124. package/src/gpu/kernels/index.js +0 -2
  125. package/src/gpu/kernels/kernel-prewarm.d.ts +3 -0
  126. package/src/gpu/kernels/kernel-prewarm.js +60 -0
  127. package/src/gpu/kernels/utils.d.ts +2 -4
  128. package/src/gpu/kernels/utils.js +2 -4
  129. package/src/index.d.ts +13 -1
  130. package/src/index.js +7 -1
  131. package/src/inference/browser-harness-model-helpers.js +4 -0
  132. package/src/inference/browser-harness-runtime-helpers.js +25 -10
  133. package/src/inference/browser-harness-text-helpers.js +4 -1
  134. package/src/inference/browser-harness.d.ts +4 -0
  135. package/src/inference/browser-harness.js +91 -4
  136. package/src/inference/observation-context.d.ts +22 -0
  137. package/src/inference/observation-context.js +41 -0
  138. package/src/inference/pipelines/text/attention/attn-config.js +1 -1
  139. package/src/inference/pipelines/text/attention/executor-immediate.js +42 -0
  140. package/src/inference/pipelines/text/attention/executor-recorded.js +29 -0
  141. package/src/inference/pipelines/text/attention/index.js +7 -0
  142. package/src/inference/pipelines/text/attention/interpreter.js +1334 -0
  143. package/src/inference/pipelines/text/attention/plan.d.ts +36 -0
  144. package/src/inference/pipelines/text/attention/plan.js +328 -0
  145. package/src/inference/pipelines/text/attention/receipt.js +60 -0
  146. package/src/inference/pipelines/text/attention/record.js +8 -1278
  147. package/src/inference/pipelines/text/attention/run.js +8 -1386
  148. package/src/inference/pipelines/text/generator-decode-policy.js +4 -1
  149. package/src/inference/pipelines/text/generator-helpers.js +2 -0
  150. package/src/inference/pipelines/text/generator-steps.js +32 -15
  151. package/src/inference/pipelines/text/generator.js +10 -5
  152. package/src/inference/pipelines/text/init.d.ts +3 -0
  153. package/src/inference/pipelines/text/layer-plan-gpu.js +2 -0
  154. package/src/inference/pipelines/text/layer.js +2 -0
  155. package/src/inference/pipelines/text/model-load.d.ts +0 -1
  156. package/src/inference/pipelines/text/model-load.js +2 -11
  157. package/src/inference/pipelines/text/probes.js +10 -0
  158. package/src/inference/pipelines/text/resolved-runtime-session.d.ts +56 -0
  159. package/src/inference/pipelines/text/resolved-runtime-session.js +175 -0
  160. package/src/inference/pipelines/text/state.d.ts +6 -0
  161. package/src/inference/pipelines/text/state.js +3 -0
  162. package/src/inference/pipelines/text/types.d.ts +6 -0
  163. package/src/inference/pipelines/text.js +16 -1
  164. package/src/inference/refactor-receipt.d.ts +49 -0
  165. package/src/inference/refactor-receipt.js +188 -0
  166. package/src/inference/resource-scope.d.ts +33 -0
  167. package/src/inference/resource-scope.js +168 -0
  168. package/src/inference/test-harness.d.ts +3 -0
  169. package/src/inference/test-harness.js +1 -0
  170. package/src/storage/model-cache.d.ts +53 -0
  171. package/src/storage/model-cache.js +550 -0
  172. package/src/tooling/boundary-evidence.d.ts +51 -0
  173. package/src/tooling/boundary-evidence.js +408 -0
  174. package/src/tooling/browser-command-runner.js +4 -4
  175. package/src/tooling/command-context.d.ts +25 -0
  176. package/src/tooling/command-context.js +53 -0
  177. package/src/tooling/command-runner-shared.js +22 -5
  178. package/src/tooling/demo-receipts.d.ts +56 -0
  179. package/src/tooling/demo-receipts.js +113 -0
  180. package/src/tooling/diagnose-runner.js +2 -2
  181. package/src/tooling/execution-cost-ledger.d.ts +21 -0
  182. package/src/tooling/execution-cost-ledger.js +199 -0
  183. package/src/tooling/node-command-runner.js +2 -2
  184. package/src/tooling/opfs-cache.d.ts +11 -49
  185. package/src/tooling/opfs-cache.js +4 -510
  186. package/src/tooling/precision-replay-math.d.ts +42 -0
  187. package/src/tooling/precision-replay-math.js +174 -0
  188. package/src/tooling/program-bundle-parity.d.ts +3 -0
  189. package/src/tooling/program-bundle-parity.js +8 -0
  190. package/src/tooling/program-bundle.d.ts +1 -52
  191. package/src/tooling/program-bundle.js +0 -139
  192. package/src/tooling/registered-variant-calibration.d.ts +24 -0
  193. package/src/tooling/registered-variant-calibration.js +286 -0
  194. package/src/tooling/runtime-input-composition.js +105 -53
  195. package/src/tooling/runtime-intent.js +41 -0
  196. package/src/tooling/runtime-optimization-index.d.ts +6 -0
  197. package/src/tooling/runtime-optimization-index.js +72 -0
  198. package/src/tooling/runtime-optimization.d.ts +47 -6
  199. package/src/tooling/runtime-optimization.js +559 -40
  200. package/src/tooling/source-intake.d.ts +49 -0
  201. package/src/tooling/source-intake.js +414 -0
  202. package/src/tooling-exports/evidence.d.ts +34 -0
  203. package/src/tooling-exports/evidence.js +34 -0
  204. package/src/tooling-exports/runtime.d.ts +7 -0
  205. package/src/tooling-exports/runtime.js +7 -0
  206. package/src/tooling-exports.d.ts +11 -0
  207. package/src/tooling-exports.js +6 -3
  208. package/src/tooling-exports.shared.d.ts +32 -0
  209. package/src/tooling-exports.shared.js +31 -0
  210. package/src/version.js +1 -1
  211. package/src/config/schema/tuner.schema.d.ts +0 -39
  212. package/src/config/schema/tuner.schema.js +0 -13
  213. package/src/gpu/kernel-tuner/benchmarks.js +0 -902
  214. package/src/gpu/kernel-tuner/cache.js +0 -145
  215. package/src/gpu/kernel-tuner/index.js +0 -38
  216. package/src/gpu/kernel-tuner/tuner.js +0 -247
  217. package/src/gpu/kernel-tuner.js +0 -12
  218. package/src/gpu/kernels/kernel-tuning.d.ts +0 -42
  219. package/src/gpu/kernels/kernel-tuning.js +0 -158
  220. package/src/gpu/profiler.js +0 -382
  221. package/src/inference/pipelines/text/attention/output-gate-fusion.js +0 -37
@@ -0,0 +1,36 @@
1
+ export const ATTENTION_PLAN_SCHEMA: 'doppler.attention-plan/v1';
2
+
3
+ export interface SemanticAttentionPlan {
4
+ readonly schema: typeof ATTENTION_PLAN_SCHEMA;
5
+ readonly id: string;
6
+ readonly phase: 'prefill' | 'decode';
7
+ readonly geometry: Readonly<Record<string, number>>;
8
+ readonly dtypes: Readonly<Record<string, string>>;
9
+ readonly transitions: Readonly<Record<string, string | null>>;
10
+ readonly fusion: Readonly<Record<string, boolean>>;
11
+ readonly kv: Readonly<Record<string, unknown>>;
12
+ readonly attention: Readonly<Record<string, unknown>>;
13
+ readonly outputGate: Readonly<Record<string, unknown>>;
14
+ readonly outputProjection: Readonly<Record<string, unknown>>;
15
+ readonly observation: Readonly<Record<string, unknown>>;
16
+ readonly lifetimes: Readonly<Record<string, boolean>>;
17
+ readonly stages: readonly string[];
18
+ }
19
+
20
+ export function resolveAttentionPlan(input: Record<string, unknown>): SemanticAttentionPlan;
21
+ export function resolveAttentionPlanForDispatch(options: Record<string, unknown>): SemanticAttentionPlan;
22
+ export function kernelPathSupportsOutputGateFusion(kernelPath: Record<string, unknown> | null): boolean;
23
+ export function bindAttentionPlan<T extends Record<string, unknown>>(
24
+ plan: SemanticAttentionPlan,
25
+ resources: T
26
+ ): Readonly<{ plan: SemanticAttentionPlan; resources: T }>;
27
+ export function executeBoundAttentionPlan<T>(
28
+ boundPlan: Readonly<{ plan: SemanticAttentionPlan; resources: Record<string, unknown> }>,
29
+ executor: {
30
+ executeStage(stage: string, boundPlan: unknown, previous: unknown): Promise<unknown>;
31
+ }
32
+ ): Promise<T>;
33
+ export function createAttentionExecutor(
34
+ mode: 'immediate' | 'recorded',
35
+ stageRunners?: Record<string, (boundPlan: unknown, previous: unknown) => unknown>
36
+ ): Readonly<Record<string, unknown>>;
@@ -0,0 +1,328 @@
1
+ import { selectRuleValue } from '../../../../rules/rule-registry.js';
2
+ import { hashRefactorReceiptValue } from '../../../refactor-receipt.js';
3
+
4
+ export const ATTENTION_PLAN_SCHEMA = 'doppler.attention-plan/v1';
5
+
6
+ function deepFreeze(value) {
7
+ if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
8
+ return value;
9
+ }
10
+ Object.freeze(value);
11
+ for (const entry of Object.values(value)) {
12
+ deepFreeze(entry);
13
+ }
14
+ return value;
15
+ }
16
+
17
+ function requirePositiveInteger(value, label) {
18
+ if (!Number.isInteger(value) || value < 1) {
19
+ throw new Error(`[AttentionPlan] ${label} must be a positive integer.`);
20
+ }
21
+ return value;
22
+ }
23
+
24
+ function requireDtype(value, label) {
25
+ if (value !== 'f16' && value !== 'f32') {
26
+ throw new Error(`[AttentionPlan] ${label} must be "f16" or "f32".`);
27
+ }
28
+ return value;
29
+ }
30
+
31
+ function resolveAttentionImplementation(input) {
32
+ return selectRuleValue('inference', 'attention', 'attentionKernelVariant', {
33
+ kvLayout: input.kv.layout,
34
+ numTokens: input.geometry.numTokens,
35
+ coldQuantMode: input.kv.coldQuantMode,
36
+ });
37
+ }
38
+
39
+ function resolveOutputResidualMode(input) {
40
+ const hasResidual = input.outputProjection.hasResidual === true;
41
+ const residualMatches = input.outputProjection.residualDtype === input.dtypes.outputProjectionInput;
42
+ const standardFused = selectRuleValue('inference', 'attention', 'useFusedOProjResidual', {
43
+ allowFusedResidual: input.geometry.numTokens === 1,
44
+ hasResidual,
45
+ residualMatches,
46
+ attnIsF32: input.dtypes.outputProjectionInput === 'f32',
47
+ attnIsF16: input.dtypes.outputProjectionInput === 'f16',
48
+ hasLoRA: input.outputProjection.hasLoRA === true,
49
+ oProjIsF16: input.outputProjection.weightDtype === 'f16',
50
+ });
51
+ if (standardFused) {
52
+ return 'matmul-residual';
53
+ }
54
+ const wideTileFused = hasResidual
55
+ && residualMatches
56
+ && input.outputProjection.weightDtype === 'q4k'
57
+ && input.dtypes.outputProjectionInput === 'f32'
58
+ && input.dtypes.output === 'f32'
59
+ && input.outputProjection.hasLoRA !== true
60
+ && input.capabilities.hasF16 === true
61
+ && input.capabilities.hasSubgroups === true
62
+ && input.session.useWideTileResidualFusion === true
63
+ && input.session.retainQ4KMaterialization === true
64
+ && (
65
+ input.phase === 'decode'
66
+ ? input.session.useWideTileQ4KDecode === true
67
+ : input.session.useWideTileQ4KPrefill === true
68
+ );
69
+ return wideTileFused ? 'wide-tile-epilogue' : 'separate';
70
+ }
71
+
72
+ function resolveOutputGateMode(input) {
73
+ if (input.outputGate.enabled !== true) {
74
+ return 'none';
75
+ }
76
+ const kernelPathSupportsFusion = input.outputGate.kernelPathSupportsFusion === true;
77
+ const fused = input.phase === 'decode'
78
+ && input.geometry.numTokens === 1
79
+ && input.geometry.headDim === 256
80
+ && input.dtypes.cachedK === 'f16'
81
+ && input.dtypes.cachedV === 'f16'
82
+ && input.outputGate.tensorDtype === 'f32'
83
+ && input.outputGate.tensorElementCount >= (
84
+ input.geometry.numTokens * input.geometry.numHeads * input.geometry.headDim
85
+ )
86
+ && input.session.attentionDecodeOnline?.useOutputGateFusion === true
87
+ && kernelPathSupportsFusion
88
+ && input.diffusionGemmaDecoder !== true;
89
+ return fused ? 'attention-epilogue' : 'sigmoid-post-attention';
90
+ }
91
+
92
+ export function kernelPathSupportsOutputGateFusion(kernelPath) {
93
+ const steps = kernelPath?.decode?.steps;
94
+ if (!Array.isArray(steps)) {
95
+ return false;
96
+ }
97
+ return steps.some((step) => (
98
+ step?.op === 'attention'
99
+ && step?.kernel === 'attention_decode_online_head256_f16kv_output_gate.wgsl'
100
+ && (step?.entry === undefined || step.entry === 'main')
101
+ ));
102
+ }
103
+
104
+ export function resolveAttentionPlan(input = {}) {
105
+ if (input.phase !== 'prefill' && input.phase !== 'decode') {
106
+ throw new Error('[AttentionPlan] phase must be "prefill" or "decode".');
107
+ }
108
+ const geometry = {
109
+ layerIdx: Number.isInteger(input.geometry?.layerIdx) ? input.geometry.layerIdx : 0,
110
+ numTokens: requirePositiveInteger(input.geometry?.numTokens, 'geometry.numTokens'),
111
+ numHeads: requirePositiveInteger(input.geometry?.numHeads, 'geometry.numHeads'),
112
+ numKVHeads: requirePositiveInteger(input.geometry?.numKVHeads, 'geometry.numKVHeads'),
113
+ headDim: requirePositiveInteger(input.geometry?.headDim, 'geometry.headDim'),
114
+ hiddenSize: requirePositiveInteger(input.geometry?.hiddenSize, 'geometry.hiddenSize'),
115
+ currentSeqLen: Number.isInteger(input.geometry?.currentSeqLen) && input.geometry.currentSeqLen >= 0
116
+ ? input.geometry.currentSeqLen
117
+ : 0,
118
+ };
119
+ const normalized = {
120
+ phase: input.phase,
121
+ geometry,
122
+ dtypes: {
123
+ input: requireDtype(input.dtypes?.input, 'dtypes.input'),
124
+ activation: requireDtype(input.dtypes?.activation, 'dtypes.activation'),
125
+ projection: requireDtype(input.dtypes?.projection, 'dtypes.projection'),
126
+ kv: requireDtype(input.dtypes?.kv, 'dtypes.kv'),
127
+ cachedK: requireDtype(input.dtypes?.cachedK, 'dtypes.cachedK'),
128
+ cachedV: requireDtype(input.dtypes?.cachedV, 'dtypes.cachedV'),
129
+ outputProjectionInput: requireDtype(
130
+ input.dtypes?.outputProjectionInput,
131
+ 'dtypes.outputProjectionInput'
132
+ ),
133
+ output: requireDtype(input.dtypes?.output, 'dtypes.output'),
134
+ },
135
+ kv: {
136
+ layout: String(input.kv?.layout ?? 'contiguous'),
137
+ coldQuantMode: String(input.kv?.coldQuantMode ?? 'none'),
138
+ length: requirePositiveInteger(input.kv?.length, 'kv.length'),
139
+ pageSize: Number.isInteger(input.kv?.pageSize) ? input.kv.pageSize : 0,
140
+ },
141
+ session: input.session ?? {},
142
+ capabilities: {
143
+ hasF16: input.capabilities?.hasF16 === true,
144
+ hasSubgroups: input.capabilities?.hasSubgroups === true,
145
+ },
146
+ fusion: {
147
+ inputNormProjection: input.fusion?.inputNormProjection === true,
148
+ qkvProjection: input.fusion?.qkvProjection === true,
149
+ qkNorm: input.fusion?.qkNorm === true,
150
+ qkNormRoPE: input.fusion?.qkNormRoPE === true,
151
+ },
152
+ outputGate: {
153
+ enabled: input.outputGate?.enabled === true,
154
+ tensorDtype: input.outputGate?.tensorDtype ?? null,
155
+ tensorElementCount: Number.isInteger(input.outputGate?.tensorElementCount)
156
+ ? input.outputGate.tensorElementCount
157
+ : 0,
158
+ kernelPathSupportsFusion: input.outputGate?.kernelPathSupportsFusion === true,
159
+ },
160
+ outputProjection: {
161
+ weightDtype: input.outputProjection?.weightDtype ?? null,
162
+ hasResidual: input.outputProjection?.hasResidual === true,
163
+ residualDtype: input.outputProjection?.residualDtype ?? null,
164
+ hasLoRA: input.outputProjection?.hasLoRA === true,
165
+ },
166
+ diagnosticsEligible: input.diagnosticsEligible === true,
167
+ sharedKV: {
168
+ reuses: input.sharedKV?.reuses === true,
169
+ stores: input.sharedKV?.stores === true,
170
+ },
171
+ diffusionGemmaDecoder: input.diffusionGemmaDecoder === true,
172
+ };
173
+ const implementation = resolveAttentionImplementation(normalized);
174
+ const planCore = {
175
+ phase: normalized.phase,
176
+ geometry: normalized.geometry,
177
+ dtypes: normalized.dtypes,
178
+ transitions: {
179
+ inputCast: normalized.dtypes.input === normalized.dtypes.activation
180
+ ? null
181
+ : `${normalized.dtypes.input}->${normalized.dtypes.activation}`,
182
+ projectionCast: normalized.dtypes.projection === normalized.dtypes.outputProjectionInput
183
+ ? null
184
+ : `${normalized.dtypes.projection}->${normalized.dtypes.outputProjectionInput}`,
185
+ },
186
+ fusion: normalized.fusion,
187
+ kv: {
188
+ ...normalized.kv,
189
+ implementation,
190
+ },
191
+ attention: {
192
+ implementation,
193
+ flashPrefill: normalized.phase === 'prefill'
194
+ && normalized.diffusionGemmaDecoder !== true
195
+ && normalized.session.useFlashPrefillAttention === true,
196
+ ortFlashPrefill: normalized.phase === 'prefill'
197
+ && normalized.diffusionGemmaDecoder !== true
198
+ && normalized.session.useOrtFlashPrefillAttention === true,
199
+ },
200
+ outputGate: {
201
+ enabled: normalized.outputGate.enabled,
202
+ semantics: normalized.outputGate.enabled ? 'sigmoid' : 'none',
203
+ mode: resolveOutputGateMode(normalized),
204
+ },
205
+ outputProjection: {
206
+ inputDtype: normalized.dtypes.outputProjectionInput,
207
+ outputDtype: normalized.dtypes.output,
208
+ residualMode: resolveOutputResidualMode(normalized),
209
+ hasLoRA: normalized.outputProjection.hasLoRA,
210
+ },
211
+ observation: {
212
+ diagnosticsEligible: normalized.diagnosticsEligible,
213
+ },
214
+ lifetimes: {
215
+ retainSharedKV: normalized.sharedKV.reuses || normalized.sharedKV.stores,
216
+ valueMayAliasKey: true,
217
+ submitRetentionRequired: true,
218
+ },
219
+ stages: [
220
+ 'input-normalization',
221
+ 'qkv-projection',
222
+ 'kv-update',
223
+ 'attention',
224
+ 'output-gate',
225
+ 'output-projection',
226
+ ],
227
+ };
228
+ return deepFreeze({
229
+ schema: ATTENTION_PLAN_SCHEMA,
230
+ id: hashRefactorReceiptValue(planCore),
231
+ ...planCore,
232
+ });
233
+ }
234
+
235
+ function tensorElementCount(tensor) {
236
+ if (!Array.isArray(tensor?.shape)) {
237
+ return 0;
238
+ }
239
+ return tensor.shape.reduce((total, value) => total * value, 1);
240
+ }
241
+
242
+ export function resolveAttentionPlanForDispatch(options = {}) {
243
+ const config = options.config ?? {};
244
+ const dispatchParams = options.dispatchParams ?? {};
245
+ const kvState = options.kvState ?? {};
246
+ return resolveAttentionPlan({
247
+ phase: config.isPrefill ? 'prefill' : 'decode',
248
+ geometry: {
249
+ layerIdx: config.layerIdx,
250
+ numTokens: config.numTokens,
251
+ numHeads: config.numHeads,
252
+ numKVHeads: config.numKVHeads,
253
+ headDim: config.headDim,
254
+ hiddenSize: config.hiddenSize,
255
+ currentSeqLen: config.currentSeqLen,
256
+ },
257
+ dtypes: {
258
+ input: options.inputDtype,
259
+ activation: options.activationDtype,
260
+ projection: options.projectionDtype,
261
+ kv: options.kvDtype,
262
+ cachedK: dispatchParams.cachedKDtype,
263
+ cachedV: dispatchParams.cachedVDtype,
264
+ outputProjectionInput: options.outputProjectionInputDtype,
265
+ output: options.outputDtype,
266
+ },
267
+ kv: {
268
+ layout: kvState.kvLayout,
269
+ coldQuantMode: kvState.coldQuantMode,
270
+ length: kvState.kvLenForAttention,
271
+ pageSize: kvState.kvPageSize ?? kvState.coldPageSize ?? 0,
272
+ },
273
+ session: options.session,
274
+ capabilities: options.capabilities,
275
+ fusion: options.fusion,
276
+ outputGate: {
277
+ enabled: config.attentionOutputGate === true,
278
+ tensorDtype: options.qGateTensor?.dtype ?? null,
279
+ tensorElementCount: tensorElementCount(options.qGateTensor),
280
+ kernelPathSupportsFusion: kernelPathSupportsOutputGateFusion(config.kernelPath),
281
+ },
282
+ outputProjection: {
283
+ weightDtype: options.outputProjectionWeightDtype ?? null,
284
+ hasResidual: config.residualTensor != null,
285
+ residualDtype: config.residualTensor?.dtype ?? null,
286
+ hasLoRA: options.outputProjectionHasLoRA === true,
287
+ },
288
+ diagnosticsEligible: options.diagnosticsEligible === true,
289
+ sharedKV: options.sharedKV,
290
+ diffusionGemmaDecoder: config.diffusionGemmaDecoder === true,
291
+ });
292
+ }
293
+
294
+ export function bindAttentionPlan(plan, resources = {}) {
295
+ if (!plan || plan.schema !== ATTENTION_PLAN_SCHEMA) {
296
+ throw new Error('[AttentionPlan] bindAttentionPlan requires a resolved semantic plan.');
297
+ }
298
+ return Object.freeze({
299
+ plan,
300
+ resources,
301
+ });
302
+ }
303
+
304
+ export async function executeBoundAttentionPlan(boundPlan, executor) {
305
+ if (!boundPlan?.plan || !executor || typeof executor.executeStage !== 'function') {
306
+ throw new Error('[AttentionPlan] executeBoundAttentionPlan requires a bound plan and executor.');
307
+ }
308
+ let result;
309
+ for (const stage of boundPlan.plan.stages) {
310
+ result = await executor.executeStage(stage, boundPlan, result);
311
+ }
312
+ return result;
313
+ }
314
+
315
+ export function createAttentionExecutor(mode, stageRunners = {}) {
316
+ if (mode !== 'immediate' && mode !== 'recorded') {
317
+ throw new Error('[AttentionPlan] executor mode must be "immediate" or "recorded".');
318
+ }
319
+ return Object.freeze({
320
+ mode,
321
+ async executeStage(stage, boundPlan, previous) {
322
+ const runner = stageRunners[stage];
323
+ return typeof runner === 'function'
324
+ ? runner(boundPlan, previous)
325
+ : previous;
326
+ },
327
+ });
328
+ }
@@ -0,0 +1,60 @@
1
+ import { createRefactorReceipt } from '../../../refactor-receipt.js';
2
+
3
+ function normalizeError(error, boundary) {
4
+ if (!error) {
5
+ return null;
6
+ }
7
+ return {
8
+ boundary,
9
+ name: typeof error.name === 'string' ? error.name : 'Error',
10
+ message: typeof error.message === 'string' ? error.message : String(error),
11
+ cleanup: 'completed',
12
+ };
13
+ }
14
+
15
+ export function captureAttentionRefactorReceipt(options = {}) {
16
+ const state = options.state ?? {};
17
+ const policy = state.observationContext?.receiptPolicy ?? 'off';
18
+ const failure = options.error
19
+ ? normalizeError(options.error, options.failureBoundary ?? 'attention')
20
+ : null;
21
+ if (policy === 'off' || (policy === 'on_failure' && !failure)) {
22
+ return null;
23
+ }
24
+ const plan = options.plan ?? null;
25
+ const receipt = createRefactorReceipt({
26
+ commandContext: state.observationContext?.commandContext ?? null,
27
+ resolvedSession: state.resolvedRuntimeSession ?? null,
28
+ observationContext: state.observationContext ?? null,
29
+ operationPlan: plan,
30
+ operations: (plan?.stages ?? []).map((stage, sequence) => ({
31
+ sequence,
32
+ stage,
33
+ })),
34
+ dtypeTransitions: Object.entries(plan?.transitions ?? {})
35
+ .filter(([, transition]) => transition != null)
36
+ .map(([boundary, transition]) => ({
37
+ boundary,
38
+ transition,
39
+ })),
40
+ resourceEvents: options.resourceEvents ?? [],
41
+ failure,
42
+ });
43
+ state.stats ??= {};
44
+ state.stats.refactorReceipts ??= [];
45
+ state.stats.refactorReceipts.push(receipt);
46
+ if (
47
+ failure
48
+ && options.error
49
+ && typeof options.error === 'object'
50
+ && Object.isExtensible(options.error)
51
+ ) {
52
+ options.error.details = {
53
+ ...(options.error.details && typeof options.error.details === 'object'
54
+ ? options.error.details
55
+ : {}),
56
+ refactorReceipt: receipt,
57
+ };
58
+ }
59
+ return receipt;
60
+ }