doppler-gpu 0.4.14 → 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 (222) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +83 -52
  3. package/package.json +25 -2
  4. package/src/cli/doppler-cli.js +253 -94
  5. package/src/cli/runtime-profiles.js +3 -7
  6. package/src/client/doppler-api.d.ts +28 -0
  7. package/src/client/doppler-api.js +2 -0
  8. package/src/client/inspection.d.ts +122 -0
  9. package/src/client/inspection.js +343 -0
  10. package/src/client/runtime/index.d.ts +54 -0
  11. package/src/client/runtime/index.js +190 -18
  12. package/src/client/runtime/model-manager.d.ts +0 -4
  13. package/src/client/runtime/model-manager.js +0 -28
  14. package/src/client/runtime/model-session.d.ts +116 -1
  15. package/src/client/runtime/model-session.js +351 -1
  16. package/src/client/runtime/model-source.d.ts +10 -1
  17. package/src/client/runtime/scoped-session.d.ts +117 -0
  18. package/src/client/runtime/scoped-session.js +257 -0
  19. package/src/client/runtime/types.d.ts +0 -1
  20. package/src/client/runtime/types.js +0 -1
  21. package/src/config/evidence/boundary-evidence-policy.json +54 -0
  22. package/src/config/evidence/source-intake-policy.json +122 -0
  23. package/src/config/inspection/observation-policies.json +80 -0
  24. package/src/config/param-validator.js +21 -36
  25. package/src/config/runtime/compute/f16-activations.json +1 -0
  26. package/src/config/runtime/compute/f16-batched.json +1 -0
  27. package/src/config/runtime/default.json +1 -0
  28. package/src/config/runtime/diagnostics/debug-logits.json +1 -0
  29. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-alt.json +1 -0
  30. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-batched.json +1 -0
  31. package/src/config/runtime/experiments/bench/gemma3-bench-q4k.json +1 -0
  32. package/src/config/runtime/experiments/bench/gemma4-bench-q4k.json +1 -0
  33. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-alt.json +1 -0
  34. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-batched.json +1 -0
  35. package/src/config/runtime/experiments/debug/gemma3-browser-diagnose-q4k.json +1 -1
  36. package/src/config/runtime/experiments/debug/gemma3-debug-q4k.json +1 -3
  37. package/src/config/runtime/experiments/debug/gemma4-e2b-browser-diagnose-q4k.json +1 -1
  38. package/src/config/runtime/experiments/debug/qwen35-browser-diagnose-q4k.json +1 -1
  39. package/src/config/runtime/experiments/verify/gemma3-verify.json +1 -3
  40. package/src/config/runtime/experiments/verify/gemma4-e2b-verify.json +1 -3
  41. package/src/config/runtime/experiments/verify/lfm2-verify.json +1 -3
  42. package/src/config/runtime/experiments/verify/translategemma-verify.json +1 -3
  43. package/src/config/runtime/model/gemma2-debug.json +1 -0
  44. package/src/config/runtime/model/gemma2-pipeline-debug.json +1 -0
  45. package/src/config/runtime/model/gemma2-pipeline.json +1 -0
  46. package/src/config/runtime/model/gemma3-layer-probe.json +1 -0
  47. package/src/config/runtime/model/qwen3-5-layer-probe.json +1 -0
  48. package/src/config/runtime/model/qwen3-5-layer3-boundary-probe.json +1 -0
  49. package/src/config/runtime/model/qwen3-5-linear-attn-debug.json +1 -0
  50. package/src/config/runtime/optimization-candidates/registry.json +5 -0
  51. package/src/config/runtime/platform/metal-apple-q4k.json +1 -0
  52. package/src/config/runtime/profiles/default.json +1 -0
  53. package/src/config/runtime/profiles/diffusiongemma-26b-a4b-throughput.json +1 -0
  54. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-overlapped-probe.json +1 -0
  55. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-probe.json +1 -0
  56. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-b4.json +1 -3
  57. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-single.json +1 -3
  58. package/src/config/runtime/profiles/gemma4-31b-f16-activations-probe.json +1 -5
  59. package/src/config/runtime/profiles/gemma4-e2b-baseline-probe.json +1 -3
  60. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-probe.json +1 -3
  61. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-test.json +1 -0
  62. package/src/config/runtime/profiles/gemma4-e2b-int4ple-baseline-probe.json +1 -5
  63. package/src/config/runtime/profiles/gemma4-e2b-int4ple-f16a-probe.json +1 -5
  64. package/src/config/runtime/profiles/gemma4-e2b-int4ple-reference-export.json +1 -3
  65. package/src/config/runtime/profiles/gemma4-e2b-int4ple-retain-q4k-probe.json +1 -5
  66. package/src/config/runtime/profiles/gemma4-e2b-low-memory.json +1 -0
  67. package/src/config/runtime/profiles/gemma4-e2b-prefill-profile.json +1 -3
  68. package/src/config/runtime/profiles/gemma4-e2b-throughput-probe.json +1 -0
  69. package/src/config/runtime/profiles/low-memory.json +1 -0
  70. package/src/config/runtime/profiles/production.json +1 -3
  71. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-attn128-candidate.json +1 -0
  72. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-maxbatch64-candidate.json +1 -0
  73. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-normed-ffn-candidate.json +1 -0
  74. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-overlap-ringtokens1-candidate.json +1 -0
  75. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-parity.json +1 -0
  76. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-sequential-candidate.json +1 -0
  77. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-throughput.json +1 -0
  78. package/src/config/runtime/profiles/qwen-3-5-0-8b-prefill-profile.json +1 -3
  79. package/src/config/runtime/profiles/qwen-3-5-0-8b-throughput-probe.json +1 -0
  80. package/src/config/runtime/profiles/qwen-3-5-2b-f16-primary-throughput.json +1 -5
  81. package/src/config/runtime/profiles/qwen-3-5-2b-metal-parity.json +1 -0
  82. package/src/config/runtime/profiles/qwen-3-5-2b-metal-throughput.json +1 -0
  83. package/src/config/runtime/profiles/qwen-3-5-9b-metal-correctness.json +1 -0
  84. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-stability.json +1 -3
  85. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-throughput.json +1 -0
  86. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-stability.json +1 -0
  87. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-throughput.json +1 -0
  88. package/src/config/runtime/profiles/qwen3-6-27b-f16-activations-probe.json +1 -5
  89. package/src/config/runtime/profiles/rerank-stability.json +1 -3
  90. package/src/config/runtime/profiles/rerank-throughput.json +1 -3
  91. package/src/config/runtime/profiles/simulation.json +1 -3
  92. package/src/config/runtime/profiles/throughput.json +1 -3
  93. package/src/config/runtime/profiles/trace-layers.json +1 -3
  94. package/src/config/runtime/profiles/translategemma-1b-nativekd2-q4k-rdna3-throughput-probe.json +1 -0
  95. package/src/config/runtime/profiles/turboquant-contiguous-prod.json +1 -0
  96. package/src/config/runtime/profiles/turboquant-contiguous.json +1 -0
  97. package/src/config/runtime/profiles/turboquant.json +1 -0
  98. package/src/config/runtime/profiles/vector-stability.json +1 -3
  99. package/src/config/runtime/profiles/vector-throughput.json +1 -0
  100. package/src/config/runtime/profiles/verbose-trace.json +1 -3
  101. package/src/config/runtime/tiers/gemma4-128gb.json +1 -0
  102. package/src/config/runtime/tiers/gemma4-16gb.json +1 -0
  103. package/src/config/runtime/tiers/gemma4-24gb.json +1 -0
  104. package/src/config/runtime/tiers/gemma4-32gb.json +1 -0
  105. package/src/config/schema/benchmark.schema.d.ts +7 -0
  106. package/src/config/schema/benchmark.schema.js +5 -0
  107. package/src/config/schema/index.d.ts +8 -16
  108. package/src/config/schema/index.js +5 -8
  109. package/src/config/schema/kernel-thresholds.schema.d.ts +0 -12
  110. package/src/config/schema/kernel-thresholds.schema.js +0 -12
  111. package/src/config/schema/kernel-warmup.schema.d.ts +1 -3
  112. package/src/config/schema/kernel-warmup.schema.js +0 -1
  113. package/src/config/schema/runtime-profile.schema.d.ts +24 -0
  114. package/src/config/schema/runtime-profile.schema.js +92 -0
  115. package/src/config/schema/shared-runtime.schema.d.ts +1 -4
  116. package/src/config/schema/shared-runtime.schema.js +0 -2
  117. package/src/config/schema/tooling.schema.d.ts +8 -5
  118. package/src/config/schema/tooling.schema.js +3 -2
  119. package/src/debug/tensor.d.ts +2 -0
  120. package/src/debug/tensor.js +21 -2
  121. package/src/gpu/command-recorder.d.ts +5 -0
  122. package/src/gpu/command-recorder.js +17 -0
  123. package/src/gpu/kernel-runtime.js +2 -10
  124. package/src/gpu/kernels/index.d.ts +0 -2
  125. package/src/gpu/kernels/index.js +0 -2
  126. package/src/gpu/kernels/kernel-prewarm.d.ts +3 -0
  127. package/src/gpu/kernels/kernel-prewarm.js +60 -0
  128. package/src/gpu/kernels/utils.d.ts +2 -4
  129. package/src/gpu/kernels/utils.js +2 -4
  130. package/src/index.d.ts +13 -1
  131. package/src/index.js +7 -1
  132. package/src/inference/browser-harness-model-helpers.js +4 -0
  133. package/src/inference/browser-harness-runtime-helpers.js +25 -10
  134. package/src/inference/browser-harness-text-helpers.js +4 -1
  135. package/src/inference/browser-harness.d.ts +4 -0
  136. package/src/inference/browser-harness.js +91 -4
  137. package/src/inference/observation-context.d.ts +22 -0
  138. package/src/inference/observation-context.js +41 -0
  139. package/src/inference/pipelines/text/attention/attn-config.js +1 -1
  140. package/src/inference/pipelines/text/attention/executor-immediate.js +42 -0
  141. package/src/inference/pipelines/text/attention/executor-recorded.js +29 -0
  142. package/src/inference/pipelines/text/attention/index.js +7 -0
  143. package/src/inference/pipelines/text/attention/interpreter.js +1334 -0
  144. package/src/inference/pipelines/text/attention/plan.d.ts +36 -0
  145. package/src/inference/pipelines/text/attention/plan.js +328 -0
  146. package/src/inference/pipelines/text/attention/receipt.js +60 -0
  147. package/src/inference/pipelines/text/attention/record.js +8 -1278
  148. package/src/inference/pipelines/text/attention/run.js +8 -1386
  149. package/src/inference/pipelines/text/generator-decode-policy.js +4 -1
  150. package/src/inference/pipelines/text/generator-helpers.js +2 -0
  151. package/src/inference/pipelines/text/generator-steps.js +32 -15
  152. package/src/inference/pipelines/text/generator.js +10 -5
  153. package/src/inference/pipelines/text/init.d.ts +3 -0
  154. package/src/inference/pipelines/text/layer-plan-gpu.js +2 -0
  155. package/src/inference/pipelines/text/layer.js +2 -0
  156. package/src/inference/pipelines/text/model-load.d.ts +0 -1
  157. package/src/inference/pipelines/text/model-load.js +2 -11
  158. package/src/inference/pipelines/text/probes.js +10 -0
  159. package/src/inference/pipelines/text/resolved-runtime-session.d.ts +56 -0
  160. package/src/inference/pipelines/text/resolved-runtime-session.js +175 -0
  161. package/src/inference/pipelines/text/state.d.ts +6 -0
  162. package/src/inference/pipelines/text/state.js +3 -0
  163. package/src/inference/pipelines/text/types.d.ts +6 -0
  164. package/src/inference/pipelines/text.js +16 -1
  165. package/src/inference/refactor-receipt.d.ts +49 -0
  166. package/src/inference/refactor-receipt.js +188 -0
  167. package/src/inference/resource-scope.d.ts +33 -0
  168. package/src/inference/resource-scope.js +168 -0
  169. package/src/inference/test-harness.d.ts +3 -0
  170. package/src/inference/test-harness.js +1 -0
  171. package/src/storage/model-cache.d.ts +53 -0
  172. package/src/storage/model-cache.js +550 -0
  173. package/src/tooling/boundary-evidence.d.ts +51 -0
  174. package/src/tooling/boundary-evidence.js +408 -0
  175. package/src/tooling/browser-command-runner.js +4 -4
  176. package/src/tooling/command-context.d.ts +25 -0
  177. package/src/tooling/command-context.js +53 -0
  178. package/src/tooling/command-runner-shared.js +22 -5
  179. package/src/tooling/demo-receipts.d.ts +56 -0
  180. package/src/tooling/demo-receipts.js +113 -0
  181. package/src/tooling/diagnose-runner.js +2 -2
  182. package/src/tooling/execution-cost-ledger.d.ts +21 -0
  183. package/src/tooling/execution-cost-ledger.js +199 -0
  184. package/src/tooling/node-command-runner.js +2 -2
  185. package/src/tooling/opfs-cache.d.ts +11 -49
  186. package/src/tooling/opfs-cache.js +4 -510
  187. package/src/tooling/precision-replay-math.d.ts +42 -0
  188. package/src/tooling/precision-replay-math.js +174 -0
  189. package/src/tooling/program-bundle-parity.d.ts +3 -0
  190. package/src/tooling/program-bundle-parity.js +8 -0
  191. package/src/tooling/program-bundle.d.ts +1 -52
  192. package/src/tooling/program-bundle.js +0 -139
  193. package/src/tooling/registered-variant-calibration.d.ts +24 -0
  194. package/src/tooling/registered-variant-calibration.js +286 -0
  195. package/src/tooling/runtime-input-composition.js +105 -53
  196. package/src/tooling/runtime-intent.js +41 -0
  197. package/src/tooling/runtime-optimization-index.d.ts +6 -0
  198. package/src/tooling/runtime-optimization-index.js +72 -0
  199. package/src/tooling/runtime-optimization.d.ts +47 -6
  200. package/src/tooling/runtime-optimization.js +559 -40
  201. package/src/tooling/source-intake.d.ts +49 -0
  202. package/src/tooling/source-intake.js +414 -0
  203. package/src/tooling-exports/evidence.d.ts +34 -0
  204. package/src/tooling-exports/evidence.js +34 -0
  205. package/src/tooling-exports/runtime.d.ts +7 -0
  206. package/src/tooling-exports/runtime.js +7 -0
  207. package/src/tooling-exports.d.ts +11 -0
  208. package/src/tooling-exports.js +6 -3
  209. package/src/tooling-exports.shared.d.ts +32 -0
  210. package/src/tooling-exports.shared.js +31 -0
  211. package/src/version.js +1 -1
  212. package/src/config/schema/tuner.schema.d.ts +0 -39
  213. package/src/config/schema/tuner.schema.js +0 -13
  214. package/src/gpu/kernel-tuner/benchmarks.js +0 -902
  215. package/src/gpu/kernel-tuner/cache.js +0 -145
  216. package/src/gpu/kernel-tuner/index.js +0 -38
  217. package/src/gpu/kernel-tuner/tuner.js +0 -247
  218. package/src/gpu/kernel-tuner.js +0 -12
  219. package/src/gpu/kernels/kernel-tuning.d.ts +0 -42
  220. package/src/gpu/kernels/kernel-tuning.js +0 -158
  221. package/src/gpu/profiler.js +0 -382
  222. package/src/inference/pipelines/text/attention/output-gate-fusion.js +0 -37
@@ -0,0 +1,286 @@
1
+ import { computeCanonicalSha256 } from '../utils/canonical-hash.js';
2
+
3
+ export const REGISTERED_VARIANT_CALIBRATION_PLAN_SCHEMA =
4
+ 'doppler.registered-variant-calibration-plan/v1';
5
+ export const REGISTERED_VARIANT_CALIBRATION_RECEIPT_SCHEMA =
6
+ 'doppler.registered-variant-calibration-receipt/v1';
7
+
8
+ const PHASES = new Set(['prefill', 'decode']);
9
+ const TAIL_CLASSES = new Set(['full-block', 'tail']);
10
+
11
+ function isObject(value) {
12
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
13
+ }
14
+
15
+ function assertDigest(value, label) {
16
+ if (!/^sha256:[0-9a-f]{64}$/.test(value ?? '')) {
17
+ throw new Error(`registered calibration: ${label} must be sha256:<64 hex chars>`);
18
+ }
19
+ }
20
+
21
+ function validateShape(shape, index) {
22
+ const label = `shapeSuite[${index}]`;
23
+ if (!isObject(shape) || typeof shape.shapeId !== 'string' || !shape.shapeId) {
24
+ throw new Error(`registered calibration: ${label}.shapeId is required`);
25
+ }
26
+ if (!PHASES.has(shape.phase)) {
27
+ throw new Error(`registered calibration: ${label}.phase must be prefill or decode`);
28
+ }
29
+ for (const field of ['sequenceLength', 'batch']) {
30
+ if (!Number.isInteger(shape[field]) || shape[field] <= 0) {
31
+ throw new Error(`registered calibration: ${label}.${field} must be a positive integer`);
32
+ }
33
+ }
34
+ for (const field of ['query', 'kv', 'dim']) {
35
+ if (!Number.isInteger(shape.heads?.[field]) || shape.heads[field] <= 0) {
36
+ throw new Error(`registered calibration: ${label}.heads.${field} is required`);
37
+ }
38
+ }
39
+ if (!TAIL_CLASSES.has(shape.tailClass)) {
40
+ throw new Error(`registered calibration: ${label}.tailClass is invalid`);
41
+ }
42
+ for (const field of ['input', 'weight', 'output', 'kv']) {
43
+ if (typeof shape.layouts?.[field] !== 'string' || !shape.layouts[field]) {
44
+ throw new Error(`registered calibration: ${label}.layouts.${field} is required`);
45
+ }
46
+ }
47
+ for (const field of ['storage', 'materialization', 'accumulation']) {
48
+ if (typeof shape.dtypes?.[field] !== 'string' || !shape.dtypes[field]) {
49
+ throw new Error(`registered calibration: ${label}.dtypes.${field} is required`);
50
+ }
51
+ }
52
+ for (const field of ['fusionRole', 'quantizationFormat']) {
53
+ if (typeof shape[field] !== 'string' || !shape[field]) {
54
+ throw new Error(`registered calibration: ${label}.${field} is required`);
55
+ }
56
+ }
57
+ }
58
+
59
+ export function digestRegisteredVariantDescriptor(operation, variantId, descriptor) {
60
+ return computeCanonicalSha256({ operation, variantId, descriptor });
61
+ }
62
+
63
+ function resolveVariant(registry, reference, capabilities) {
64
+ const descriptor = registry?.operations?.[reference.operation]?.variants?.[reference.variantId];
65
+ if (!descriptor) {
66
+ throw new Error(
67
+ `registered calibration: unregistered variant ${reference.operation}/${reference.variantId}`
68
+ );
69
+ }
70
+ const descriptorDigest = digestRegisteredVariantDescriptor(
71
+ reference.operation,
72
+ reference.variantId,
73
+ descriptor
74
+ );
75
+ assertDigest(reference.descriptorDigest, `${reference.operation}/${reference.variantId} descriptorDigest`);
76
+ assertDigest(reference.kernelDigest, `${reference.operation}/${reference.variantId} kernelDigest`);
77
+ if (reference.descriptorDigest !== descriptorDigest) {
78
+ throw new Error(
79
+ `registered calibration: descriptor digest mismatch for ` +
80
+ `${reference.operation}/${reference.variantId}`
81
+ );
82
+ }
83
+ const available = new Set(capabilities);
84
+ const missingCapabilities = (descriptor.requires ?? []).filter(
85
+ (capability) => !available.has(capability)
86
+ );
87
+ return {
88
+ reference: { ...reference },
89
+ descriptor,
90
+ descriptorDigest,
91
+ compatible: missingCapabilities.length === 0,
92
+ missingCapabilities,
93
+ };
94
+ }
95
+
96
+ export function validateRegisteredVariantCalibrationPlan(plan, registry) {
97
+ if (plan?.schema !== REGISTERED_VARIANT_CALIBRATION_PLAN_SCHEMA) {
98
+ throw new Error(
99
+ `registered calibration: expected ${REGISTERED_VARIANT_CALIBRATION_PLAN_SCHEMA}`
100
+ );
101
+ }
102
+ for (const field of [
103
+ 'artifactDigest',
104
+ 'manifestDigest',
105
+ 'executionGraphDigest',
106
+ 'browserDigest',
107
+ 'adapterDigest',
108
+ 'wrapperDigest',
109
+ ]) {
110
+ assertDigest(plan.identity?.[field], `identity.${field}`);
111
+ }
112
+ if (!Array.isArray(plan.identity?.capabilities)) {
113
+ throw new Error('registered calibration: identity.capabilities is required');
114
+ }
115
+ if (!Array.isArray(plan.shapeSuite) || plan.shapeSuite.length === 0) {
116
+ throw new Error('registered calibration: shapeSuite is required');
117
+ }
118
+ plan.shapeSuite.forEach(validateShape);
119
+ if (!Array.isArray(plan.candidates) || plan.candidates.length === 0) {
120
+ throw new Error('registered calibration: candidates are required');
121
+ }
122
+ const resolvedCandidates = plan.candidates.map((candidate) => (
123
+ resolveVariant(registry, candidate, plan.identity.capabilities)
124
+ ));
125
+ const baseline = resolveVariant(registry, plan.baseline, plan.identity.capabilities);
126
+ if (!baseline.compatible) {
127
+ throw new Error('registered calibration: baseline is incompatible with capability fingerprint');
128
+ }
129
+ return {
130
+ ...plan,
131
+ identity: {
132
+ ...plan.identity,
133
+ capabilities: [...plan.identity.capabilities].sort(),
134
+ },
135
+ baseline,
136
+ resolvedCandidates,
137
+ };
138
+ }
139
+
140
+ function gatePassed(result, mode, candidate = null) {
141
+ if (mode === 'operator-reference') {
142
+ return result?.passed === true
143
+ && result?.kernelDigest === candidate?.reference?.kernelDigest;
144
+ }
145
+ if (mode === 'boundary-pack') {
146
+ return result?.schema === 'doppler.boundary-comparison-receipt/v1'
147
+ && result?.promotionGate?.boundaryCompatible === true
148
+ && result?.promotionGate?.sourcePrecisionControlPassed === true;
149
+ }
150
+ return result?.exact === true && result?.tokenCount >= 128;
151
+ }
152
+
153
+ async function evaluateCorrectnessGates(plan, candidate, runCorrectness) {
154
+ const operatorReference = [];
155
+ for (const shape of plan.shapeSuite) {
156
+ const result = await runCorrectness({
157
+ mode: 'operator-reference',
158
+ identity: plan.identity,
159
+ baseline: plan.baseline,
160
+ candidate,
161
+ shape,
162
+ });
163
+ operatorReference.push({ shapeId: shape.shapeId, result });
164
+ if (!gatePassed(result, 'operator-reference', candidate)) {
165
+ return {
166
+ passed: false,
167
+ failedGate: 'operator-reference',
168
+ operatorReference,
169
+ };
170
+ }
171
+ }
172
+ const boundaryPack = await runCorrectness({
173
+ mode: 'boundary-pack',
174
+ identity: plan.identity,
175
+ baseline: plan.baseline,
176
+ candidate,
177
+ shapeSuite: plan.shapeSuite,
178
+ });
179
+ if (!gatePassed(boundaryPack, 'boundary-pack')) {
180
+ return { passed: false, failedGate: 'boundary-pack', operatorReference, boundaryPack };
181
+ }
182
+ const tokenParity = await runCorrectness({
183
+ mode: 'token-parity',
184
+ identity: plan.identity,
185
+ baseline: plan.baseline,
186
+ candidate,
187
+ minimumTokenCount: 128,
188
+ });
189
+ return {
190
+ passed: gatePassed(tokenParity, 'token-parity'),
191
+ failedGate: gatePassed(tokenParity, 'token-parity') ? null : 'token-parity',
192
+ operatorReference,
193
+ boundaryPack,
194
+ tokenParity,
195
+ };
196
+ }
197
+
198
+ export async function calibrateRegisteredVariants(planInput, options) {
199
+ if (typeof options?.runCorrectness !== 'function') {
200
+ throw new Error('registered calibration: runCorrectness callback is required');
201
+ }
202
+ if (typeof options?.evaluatePerformance !== 'function') {
203
+ throw new Error('registered calibration: evaluatePerformance callback is required');
204
+ }
205
+ const plan = validateRegisteredVariantCalibrationPlan(planInput, options.registry);
206
+ const results = [];
207
+ for (const candidate of plan.resolvedCandidates) {
208
+ if (!candidate.compatible) {
209
+ results.push({
210
+ candidate: candidate.reference,
211
+ decision: 'incompatible',
212
+ missingCapabilities: candidate.missingCapabilities,
213
+ });
214
+ continue;
215
+ }
216
+ const correctness = await evaluateCorrectnessGates(
217
+ plan,
218
+ candidate,
219
+ options.runCorrectness
220
+ );
221
+ if (!correctness.passed) {
222
+ results.push({
223
+ candidate: candidate.reference,
224
+ correctness,
225
+ decision: 'rejected',
226
+ reason: `${correctness.failedGate}_failed`,
227
+ });
228
+ continue;
229
+ }
230
+ const typedCandidate = {
231
+ kind: 'registered-kernel-variant',
232
+ reference: {
233
+ operation: candidate.reference.operation,
234
+ variantId: candidate.reference.variantId,
235
+ descriptorDigest: candidate.descriptorDigest,
236
+ kernelDigest: candidate.reference.kernelDigest,
237
+ },
238
+ scope: {
239
+ artifactDigest: plan.identity.artifactDigest,
240
+ executionGraphDigest: plan.identity.executionGraphDigest,
241
+ browserDigest: plan.identity.browserDigest,
242
+ adapterDigest: plan.identity.adapterDigest,
243
+ shapeSignatures: plan.shapeSuite,
244
+ },
245
+ };
246
+ const performance = await options.evaluatePerformance({
247
+ typedCandidate,
248
+ baseline: plan.baseline,
249
+ candidate,
250
+ shapeSuite: plan.shapeSuite,
251
+ identity: plan.identity,
252
+ });
253
+ if (performance?.schema !== 'doppler.runtime-optimization-receipt/v1') {
254
+ throw new Error(
255
+ 'registered calibration: evaluatePerformance must return ' +
256
+ 'doppler.runtime-optimization-receipt/v1'
257
+ );
258
+ }
259
+ const accepted = performance?.decision?.accepted === true;
260
+ results.push({
261
+ candidate: candidate.reference,
262
+ correctness,
263
+ performance,
264
+ decision: accepted ? 'proposed' : 'rejected',
265
+ proposal: accepted
266
+ ? {
267
+ kind: plan.outputKind ?? 'registered-execution-graph-patch',
268
+ activation: 'manual-promotion-required',
269
+ candidate: typedCandidate,
270
+ }
271
+ : null,
272
+ reason: accepted ? null : 'performance_evidence_failed',
273
+ });
274
+ }
275
+ const core = {
276
+ schema: REGISTERED_VARIANT_CALIBRATION_RECEIPT_SCHEMA,
277
+ planDigest: computeCanonicalSha256(planInput),
278
+ identity: plan.identity,
279
+ results,
280
+ proposedSelections: results
281
+ .filter((result) => result.decision === 'proposed')
282
+ .map((result) => result.proposal),
283
+ runtimeMutationApplied: false,
284
+ };
285
+ return { ...core, digest: computeCanonicalSha256(core) };
286
+ }
@@ -7,79 +7,131 @@ export function resolveRuntimeFromConfig(config) {
7
7
  return null;
8
8
  }
9
9
 
10
- function mergeRuntimePatch(runtimeBridge, patch) {
11
- if (!patch) return;
12
- const mergedRuntime = mergeRuntimeValues(runtimeBridge.getRuntimeConfig(), patch);
13
- runtimeBridge.setRuntimeConfig(mergedRuntime);
10
+ function requireLoader(loader, label) {
11
+ if (typeof loader !== 'function') {
12
+ throw new Error(`runtime input composition does not support ${label} on this surface.`);
13
+ }
14
+ return loader;
14
15
  }
15
16
 
16
- function requireRuntimeBridge(runtimeBridge) {
17
- if (!runtimeBridge?.setRuntimeConfig) {
18
- throw new Error('runtime bridge must provide setRuntimeConfig().');
17
+ function normalizeLoadedDocument(loaded, label) {
18
+ if (!loaded || typeof loaded !== 'object') {
19
+ throw new Error(`${label} did not resolve to a config object.`);
19
20
  }
20
- if (typeof runtimeBridge.getRuntimeConfig !== 'function') {
21
- throw new Error('runtime bridge must provide getRuntimeConfig().');
21
+ const config = (
22
+ loaded.config
23
+ && typeof loaded.config === 'object'
24
+ && !Array.isArray(loaded.config)
25
+ )
26
+ ? loaded.config
27
+ : loaded;
28
+ const runtime = (
29
+ loaded.runtime
30
+ && typeof loaded.runtime === 'object'
31
+ && !Array.isArray(loaded.runtime)
32
+ )
33
+ ? loaded.runtime
34
+ : resolveRuntimeFromConfig(config);
35
+ if (!runtime) {
36
+ throw new Error(`${label} is missing runtime fields.`);
22
37
  }
38
+ return { config, runtime };
23
39
  }
24
40
 
25
- async function applyConfigChain(configChain, runtimeBridge, loadRuntimeConfigFromRef, options) {
26
- if (!Array.isArray(configChain) || configChain.length === 0) {
27
- return;
28
- }
29
- if (typeof loadRuntimeConfigFromRef !== 'function') {
30
- throw new Error('runtime input composition does not support configChain on this surface.');
31
- }
32
- for (const ref of configChain) {
33
- const loaded = await loadRuntimeConfigFromRef(ref, options);
34
- const runtime = resolveRuntimeFromConfig(loaded);
35
- if (!runtime) {
36
- throw new Error(`Loaded runtime config "${ref}" is missing runtime fields.`);
41
+ function appendDocument(state, kind, ref, loaded, label) {
42
+ const document = normalizeLoadedDocument(loaded, label);
43
+ return {
44
+ runtime: mergeRuntimeValues(state.runtime, document.runtime),
45
+ documents: [
46
+ ...state.documents,
47
+ {
48
+ kind,
49
+ ref,
50
+ config: document.config,
51
+ runtime: document.runtime,
52
+ },
53
+ ],
54
+ };
55
+ }
56
+
57
+ export async function resolveOrderedRuntimeInputs(
58
+ initialRuntime,
59
+ inputs = {},
60
+ handlers = {},
61
+ options = {}
62
+ ) {
63
+ let state = {
64
+ runtime: initialRuntime,
65
+ documents: [],
66
+ };
67
+
68
+ if (Array.isArray(inputs.configChain) && inputs.configChain.length > 0) {
69
+ const loadConfig = requireLoader(handlers.loadRuntimeConfigFromRef, 'configChain');
70
+ for (const ref of inputs.configChain) {
71
+ const loaded = await loadConfig(ref, options);
72
+ state = appendDocument(state, 'configChain', ref, loaded, `Loaded runtime config "${ref}"`);
37
73
  }
38
- mergeRuntimePatch(runtimeBridge, runtime);
39
74
  }
40
- }
41
75
 
42
- async function applyRuntimeProfile(runtimeProfile, applyProfile, options) {
43
- if (!runtimeProfile) {
44
- return;
76
+ if (inputs.runtimeProfile) {
77
+ const loadProfile = requireLoader(handlers.loadRuntimeProfile, 'runtimeProfile');
78
+ const loaded = await loadProfile(inputs.runtimeProfile, options);
79
+ state = appendDocument(
80
+ state,
81
+ 'runtimeProfile',
82
+ inputs.runtimeProfile,
83
+ loaded,
84
+ `Runtime profile "${inputs.runtimeProfile}"`
85
+ );
86
+ }
87
+
88
+ if (inputs.runtimeConfigUrl) {
89
+ const loadConfigUrl = requireLoader(handlers.loadRuntimeConfigFromUrl, 'runtimeConfigUrl');
90
+ const loaded = await loadConfigUrl(inputs.runtimeConfigUrl, options);
91
+ state = appendDocument(
92
+ state,
93
+ 'runtimeConfigUrl',
94
+ inputs.runtimeConfigUrl,
95
+ loaded,
96
+ `Runtime config URL "${inputs.runtimeConfigUrl}"`
97
+ );
45
98
  }
46
- if (typeof applyProfile !== 'function') {
47
- throw new Error('runtime input composition does not support runtimeProfile on this surface.');
99
+
100
+ if (inputs.runtimeConfig) {
101
+ state = appendDocument(
102
+ state,
103
+ 'runtimeConfig',
104
+ 'inline',
105
+ inputs.runtimeConfig,
106
+ 'runtimeConfig'
107
+ );
48
108
  }
49
- await applyProfile(runtimeProfile, options);
109
+
110
+ return {
111
+ runtime: state.runtime,
112
+ documents: Object.freeze(state.documents.map((document) => Object.freeze(document))),
113
+ };
50
114
  }
51
115
 
52
- async function applyRuntimeConfigUrl(runtimeConfigUrl, applyConfigFromUrl, options) {
53
- if (!runtimeConfigUrl) {
54
- return;
116
+ function requireRuntimeBridge(runtimeBridge) {
117
+ if (!runtimeBridge?.setRuntimeConfig) {
118
+ throw new Error('runtime bridge must provide setRuntimeConfig().');
55
119
  }
56
- if (typeof applyConfigFromUrl !== 'function') {
57
- throw new Error('runtime input composition does not support runtimeConfigUrl on this surface.');
120
+ if (typeof runtimeBridge.getRuntimeConfig !== 'function') {
121
+ throw new Error('runtime bridge must provide getRuntimeConfig().');
58
122
  }
59
- await applyConfigFromUrl(runtimeConfigUrl, options);
60
123
  }
61
124
 
62
125
  export async function applyOrderedRuntimeInputs(runtimeBridge, inputs = {}, handlers = {}, options = {}) {
63
126
  requireRuntimeBridge(runtimeBridge);
64
-
65
- await applyConfigChain(
66
- inputs.configChain,
67
- runtimeBridge,
68
- handlers.loadRuntimeConfigFromRef,
69
- options
70
- );
71
- await applyRuntimeProfile(
72
- inputs.runtimeProfile,
73
- handlers.applyRuntimeProfile,
127
+ const resolved = await resolveOrderedRuntimeInputs(
128
+ runtimeBridge.getRuntimeConfig(),
129
+ inputs,
130
+ handlers,
74
131
  options
75
132
  );
76
- await applyRuntimeConfigUrl(inputs.runtimeConfigUrl, handlers.applyRuntimeConfigFromUrl, options);
77
-
78
- if (inputs.runtimeConfig) {
79
- const runtime = resolveRuntimeFromConfig(inputs.runtimeConfig);
80
- if (!runtime) {
81
- throw new Error('runtimeConfig is missing runtime fields');
82
- }
83
- mergeRuntimePatch(runtimeBridge, runtime);
133
+ if (resolved.documents.length > 0) {
134
+ runtimeBridge.setRuntimeConfig(resolved.runtime);
84
135
  }
136
+ return resolved;
85
137
  }
@@ -0,0 +1,41 @@
1
+ import { assertRuntimeProfileIntentCompatibility } from '../config/schema/runtime-profile.schema.js';
2
+
3
+ export function getLegacyRuntimeIntent(runtimeConfig) {
4
+ return runtimeConfig?.shared?.tooling?.intent ?? null;
5
+ }
6
+
7
+ export function stripLegacyRuntimeIntent(runtimeConfig) {
8
+ if (!runtimeConfig?.shared?.tooling || runtimeConfig.shared.tooling.intent === undefined) {
9
+ return runtimeConfig;
10
+ }
11
+ const tooling = { ...runtimeConfig.shared.tooling };
12
+ delete tooling.intent;
13
+ return {
14
+ ...runtimeConfig,
15
+ shared: {
16
+ ...runtimeConfig.shared,
17
+ tooling,
18
+ },
19
+ };
20
+ }
21
+
22
+ export function assertRuntimeInputIntentCompatibility(requestIntent, documents) {
23
+ for (const document of documents) {
24
+ const legacyIntent = getLegacyRuntimeIntent(document.runtime);
25
+ if (legacyIntent !== null && legacyIntent !== requestIntent) {
26
+ throw new Error(
27
+ `tooling command: ${document.kind} "${document.ref}" declares legacy ` +
28
+ `runtime.shared.tooling.intent="${legacyIntent}", which conflicts with normalized ` +
29
+ `request.intent="${requestIntent}".`
30
+ );
31
+ }
32
+ if (document.kind === 'runtimeProfile') {
33
+ assertRuntimeProfileIntentCompatibility(
34
+ document.config,
35
+ requestIntent,
36
+ `runtime profile "${document.ref}"`
37
+ );
38
+ }
39
+ }
40
+ return true;
41
+ }
@@ -0,0 +1,6 @@
1
+ export declare const RUNTIME_OPTIMIZATION_RESULTS_INDEX_SCHEMA:
2
+ 'doppler.runtime-optimization-results-index/v1';
3
+
4
+ export declare function buildRuntimeOptimizationResultsIndex(
5
+ receipts: Array<Record<string, unknown>>
6
+ ): Record<string, unknown>;
@@ -0,0 +1,72 @@
1
+ import { computeCanonicalSha256 } from '../utils/canonical-hash.js';
2
+
3
+ export const RUNTIME_OPTIMIZATION_RESULTS_INDEX_SCHEMA =
4
+ 'doppler.runtime-optimization-results-index/v1';
5
+
6
+ function receiptIdentity(receipt) {
7
+ const device = receipt.measurement?.pairs
8
+ ?.find((pair) => pair.valid)
9
+ ?.candidate?.deviceInfo ?? null;
10
+ return {
11
+ candidateKind: receipt.candidateKind ?? 'runtime-profile',
12
+ candidateReferenceDigest: receipt.registeredReference?.digest ?? receipt.candidateHash,
13
+ modelId: receipt.model?.modelId ?? null,
14
+ metricPath: receipt.measurement?.metricPath ?? null,
15
+ deviceDigest: device ? computeCanonicalSha256(device) : null,
16
+ workloadDigest: computeCanonicalSha256({
17
+ runtimeInputs: receipt.runtimeInputs,
18
+ metricPath: receipt.measurement?.metricPath ?? null,
19
+ }),
20
+ };
21
+ }
22
+
23
+ export function buildRuntimeOptimizationResultsIndex(receipts) {
24
+ if (!Array.isArray(receipts)) {
25
+ throw new Error('runtime optimization index: receipts must be an array');
26
+ }
27
+ const groups = new Map();
28
+ for (const receipt of receipts) {
29
+ if (receipt?.schema !== 'doppler.runtime-optimization-receipt/v1') {
30
+ throw new Error('runtime optimization index: unsupported receipt schema');
31
+ }
32
+ const identity = receiptIdentity(receipt);
33
+ const key = computeCanonicalSha256(identity);
34
+ const group = groups.get(key) ?? {
35
+ key,
36
+ identity,
37
+ accepted: 0,
38
+ rejected: 0,
39
+ invalid: 0,
40
+ reasons: {},
41
+ receiptHashes: [],
42
+ };
43
+ const status = receipt.decision?.status;
44
+ if (status === 'accepted') group.accepted += 1;
45
+ else if (status === 'invalid') group.invalid += 1;
46
+ else group.rejected += 1;
47
+ for (const reason of receipt.decision?.reasons ?? []) {
48
+ group.reasons[reason] = (group.reasons[reason] ?? 0) + 1;
49
+ }
50
+ group.receiptHashes.push(receipt.receiptHash ?? computeCanonicalSha256(receipt));
51
+ groups.set(key, group);
52
+ }
53
+ const entries = Array.from(groups.values())
54
+ .map((entry) => ({
55
+ ...entry,
56
+ reasons: Object.fromEntries(
57
+ Object.entries(entry.reasons).sort(([left], [right]) => left.localeCompare(right))
58
+ ),
59
+ receiptHashes: [...entry.receiptHashes].sort(),
60
+ }))
61
+ .sort((left, right) => left.key.localeCompare(right.key));
62
+ const core = {
63
+ schema: RUNTIME_OPTIMIZATION_RESULTS_INDEX_SCHEMA,
64
+ receiptCount: receipts.length,
65
+ negativeResultCount: entries.reduce(
66
+ (count, entry) => count + entry.rejected + entry.invalid,
67
+ 0
68
+ ),
69
+ entries,
70
+ };
71
+ return { ...core, digest: computeCanonicalSha256(core) };
72
+ }