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,188 @@
1
+ import { sha256Hex } from '../utils/sha256.js';
2
+ import { stableSortObject } from '../utils/stable-sort-object.js';
3
+
4
+ export const REFACTOR_RECEIPT_SCHEMA = 'doppler.refactor-receipt/v1';
5
+
6
+ function assertJsonSafe(value, path = 'receipt') {
7
+ if (value === null) {
8
+ return;
9
+ }
10
+ const valueType = typeof value;
11
+ if (valueType === 'string' || valueType === 'boolean') {
12
+ return;
13
+ }
14
+ if (valueType === 'number') {
15
+ if (!Number.isFinite(value)) {
16
+ throw new Error(`[RefactorReceipt] ${path} must contain only finite numbers.`);
17
+ }
18
+ return;
19
+ }
20
+ if (valueType === 'undefined' || valueType === 'function' || valueType === 'symbol' || valueType === 'bigint') {
21
+ throw new Error(`[RefactorReceipt] ${path} is not JSON-safe.`);
22
+ }
23
+ if (Array.isArray(value)) {
24
+ for (let index = 0; index < value.length; index += 1) {
25
+ assertJsonSafe(value[index], `${path}[${index}]`);
26
+ }
27
+ return;
28
+ }
29
+ if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
30
+ throw new Error(`[RefactorReceipt] ${path} must describe tensor data instead of embedding binary data.`);
31
+ }
32
+ const prototype = Object.getPrototypeOf(value);
33
+ if (prototype !== Object.prototype && prototype !== null) {
34
+ throw new Error(`[RefactorReceipt] ${path} must contain plain objects only.`);
35
+ }
36
+ for (const [key, entry] of Object.entries(value)) {
37
+ assertJsonSafe(entry, `${path}.${key}`);
38
+ }
39
+ }
40
+
41
+ function deepFreeze(value) {
42
+ if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
43
+ return value;
44
+ }
45
+ Object.freeze(value);
46
+ for (const entry of Object.values(value)) {
47
+ deepFreeze(entry);
48
+ }
49
+ return value;
50
+ }
51
+
52
+ export function canonicalizeRefactorReceiptValue(value) {
53
+ assertJsonSafe(value);
54
+ return stableSortObject(value);
55
+ }
56
+
57
+ export function hashRefactorReceiptValue(value) {
58
+ const canonical = canonicalizeRefactorReceiptValue(value);
59
+ return `sha256:${sha256Hex(JSON.stringify(canonical))}`;
60
+ }
61
+
62
+ function normalizeOptionalRecord(value, label) {
63
+ if (value === undefined || value === null) {
64
+ return null;
65
+ }
66
+ assertJsonSafe(value, label);
67
+ return stableSortObject(value);
68
+ }
69
+
70
+ function normalizeEventList(value, label) {
71
+ if (value === undefined || value === null) {
72
+ return [];
73
+ }
74
+ if (!Array.isArray(value)) {
75
+ throw new Error(`[RefactorReceipt] ${label} must be an array.`);
76
+ }
77
+ assertJsonSafe(value, label);
78
+ return value.map((entry) => stableSortObject(entry));
79
+ }
80
+
81
+ export function createRefactorReceipt(input = {}) {
82
+ const commandContext = normalizeOptionalRecord(input.commandContext, 'commandContext');
83
+ const resolvedSession = normalizeOptionalRecord(input.resolvedSession, 'resolvedSession');
84
+ const observationContext = normalizeOptionalRecord(input.observationContext, 'observationContext');
85
+ const operationPlan = normalizeOptionalRecord(input.operationPlan, 'operationPlan');
86
+ const operations = normalizeEventList(input.operations, 'operations');
87
+ const dtypeTransitions = normalizeEventList(input.dtypeTransitions, 'dtypeTransitions');
88
+ const resourceEvents = normalizeEventList(input.resourceEvents, 'resourceEvents');
89
+ const failure = normalizeOptionalRecord(input.failure, 'failure');
90
+
91
+ const semanticCore = {
92
+ resolvedSession,
93
+ operationPlan,
94
+ };
95
+ const executionCore = {
96
+ operations,
97
+ dtypeTransitions,
98
+ resourceEvents,
99
+ failure,
100
+ };
101
+ const core = {
102
+ schema: REFACTOR_RECEIPT_SCHEMA,
103
+ commandContext,
104
+ resolvedSession,
105
+ observationContext,
106
+ operationPlan,
107
+ operations,
108
+ dtypeTransitions,
109
+ resourceEvents,
110
+ failure,
111
+ semanticHash: hashRefactorReceiptValue(semanticCore),
112
+ executionHash: hashRefactorReceiptValue(executionCore),
113
+ };
114
+ const receipt = {
115
+ ...core,
116
+ receiptHash: hashRefactorReceiptValue(core),
117
+ };
118
+ return deepFreeze(receipt);
119
+ }
120
+
121
+ export function verifyRefactorReceipt(receipt) {
122
+ if (!receipt || receipt.schema !== REFACTOR_RECEIPT_SCHEMA) {
123
+ throw new Error(`[RefactorReceipt] schema must be "${REFACTOR_RECEIPT_SCHEMA}".`);
124
+ }
125
+ const {
126
+ semanticHash,
127
+ executionHash,
128
+ receiptHash,
129
+ ...core
130
+ } = receipt;
131
+ const expectedSemanticHash = hashRefactorReceiptValue({
132
+ resolvedSession: receipt.resolvedSession,
133
+ operationPlan: receipt.operationPlan,
134
+ });
135
+ const expectedExecutionHash = hashRefactorReceiptValue({
136
+ operations: receipt.operations,
137
+ dtypeTransitions: receipt.dtypeTransitions,
138
+ resourceEvents: receipt.resourceEvents,
139
+ failure: receipt.failure,
140
+ });
141
+ const expectedReceiptHash = hashRefactorReceiptValue({
142
+ ...core,
143
+ semanticHash,
144
+ executionHash,
145
+ });
146
+ if (semanticHash !== expectedSemanticHash) {
147
+ throw new Error('[RefactorReceipt] semanticHash mismatch.');
148
+ }
149
+ if (executionHash !== expectedExecutionHash) {
150
+ throw new Error('[RefactorReceipt] executionHash mismatch.');
151
+ }
152
+ if (receiptHash !== expectedReceiptHash) {
153
+ throw new Error('[RefactorReceipt] receiptHash mismatch.');
154
+ }
155
+ return true;
156
+ }
157
+
158
+ export function compareRefactorReceipts(expected, actual) {
159
+ verifyRefactorReceipt(expected);
160
+ verifyRefactorReceipt(actual);
161
+ const fields = [
162
+ 'semanticHash',
163
+ 'executionHash',
164
+ 'commandContext',
165
+ 'resolvedSession',
166
+ 'observationContext',
167
+ 'operationPlan',
168
+ 'operations',
169
+ 'dtypeTransitions',
170
+ 'resourceEvents',
171
+ 'failure',
172
+ ];
173
+ const differences = [];
174
+ for (const field of fields) {
175
+ if (
176
+ JSON.stringify(canonicalizeRefactorReceiptValue(expected[field]))
177
+ !== JSON.stringify(canonicalizeRefactorReceiptValue(actual[field]))
178
+ ) {
179
+ differences.push(field);
180
+ }
181
+ }
182
+ return deepFreeze({
183
+ matches: differences.length === 0,
184
+ semanticMatches: expected.semanticHash === actual.semanticHash,
185
+ executionMatches: expected.executionHash === actual.executionHash,
186
+ differences,
187
+ });
188
+ }
@@ -0,0 +1,33 @@
1
+ export type ResourceOwnership =
2
+ | 'borrowed'
3
+ | 'scopeOwned'
4
+ | 'submitOwned'
5
+ | 'transferred'
6
+ | 'retained';
7
+
8
+ export const RESOURCE_OWNERSHIP: readonly ResourceOwnership[];
9
+
10
+ export interface ResourceEvent {
11
+ readonly sequence: number;
12
+ readonly action: string;
13
+ readonly label: string;
14
+ readonly ownership: ResourceOwnership | null;
15
+ readonly detail: string | null;
16
+ }
17
+
18
+ export interface ResourceScope<T = object> {
19
+ readonly mode: 'immediate' | 'recorded';
20
+ register(resource: T | null, label: string, ownership?: ResourceOwnership): T | null;
21
+ transfer(resource: T, ownership: ResourceOwnership, detail?: string | null): T;
22
+ release(resource: T | null, label?: string | null): boolean;
23
+ retain(resource: T | null, label?: string | null, detail?: string | null): T | null;
24
+ close(outcome?: 'success' | 'failure'): ReadonlyArray<ResourceEvent>;
25
+ getEvents(): ReadonlyArray<ResourceEvent>;
26
+ }
27
+
28
+ export function createImmediateResourceScope<T = object>(options: {
29
+ release(resource: T): void;
30
+ }): ResourceScope<T>;
31
+ export function createRecordedResourceScope<T = object>(recorder: {
32
+ trackTemporaryBuffer(resource: T): void;
33
+ }): ResourceScope<T>;
@@ -0,0 +1,168 @@
1
+ export const RESOURCE_OWNERSHIP = Object.freeze([
2
+ 'borrowed',
3
+ 'scopeOwned',
4
+ 'submitOwned',
5
+ 'transferred',
6
+ 'retained',
7
+ ]);
8
+
9
+ function assertOwnership(value) {
10
+ if (!RESOURCE_OWNERSHIP.includes(value)) {
11
+ throw new Error(`[ResourceScope] unsupported ownership "${String(value)}".`);
12
+ }
13
+ return value;
14
+ }
15
+
16
+ function normalizeLabel(label) {
17
+ const value = String(label ?? '').trim();
18
+ return value || 'resource';
19
+ }
20
+
21
+ class ResourceScope {
22
+ constructor(mode, dispose) {
23
+ this.mode = mode;
24
+ this.dispose = dispose;
25
+ this.entries = new Map();
26
+ this.events = [];
27
+ this.closed = false;
28
+ }
29
+
30
+ emit(action, entry, detail = null) {
31
+ this.events.push(Object.freeze({
32
+ sequence: this.events.length,
33
+ action,
34
+ label: entry.label,
35
+ ownership: entry.ownership,
36
+ detail,
37
+ }));
38
+ }
39
+
40
+ assertOpen() {
41
+ if (this.closed) {
42
+ throw new Error('[ResourceScope] scope is already closed.');
43
+ }
44
+ }
45
+
46
+ register(resource, label, ownership = 'scopeOwned') {
47
+ this.assertOpen();
48
+ if (!resource) {
49
+ return resource;
50
+ }
51
+ const normalizedOwnership = assertOwnership(ownership);
52
+ const existing = this.entries.get(resource);
53
+ if (existing) {
54
+ if (existing.disposed) {
55
+ const entry = {
56
+ resource,
57
+ label: normalizeLabel(label),
58
+ ownership: normalizedOwnership,
59
+ disposed: false,
60
+ };
61
+ this.entries.set(resource, entry);
62
+ this.emit('reacquire', entry, existing.label);
63
+ return resource;
64
+ }
65
+ if (existing.ownership !== normalizedOwnership && existing.ownership !== 'transferred') {
66
+ throw new Error(
67
+ `[ResourceScope] "${existing.label}" is already registered as ${existing.ownership}; ` +
68
+ `cannot register it as ${normalizedOwnership}.`
69
+ );
70
+ }
71
+ this.emit('alias', existing, normalizeLabel(label));
72
+ return resource;
73
+ }
74
+ const entry = {
75
+ resource,
76
+ label: normalizeLabel(label),
77
+ ownership: normalizedOwnership,
78
+ disposed: false,
79
+ };
80
+ this.entries.set(resource, entry);
81
+ this.emit('acquire', entry);
82
+ return resource;
83
+ }
84
+
85
+ transfer(resource, ownership, detail = null) {
86
+ this.assertOpen();
87
+ const entry = this.entries.get(resource);
88
+ if (!entry) {
89
+ throw new Error('[ResourceScope] cannot transfer an unregistered resource.');
90
+ }
91
+ if (entry.disposed) {
92
+ throw new Error(`[ResourceScope] cannot transfer disposed resource "${entry.label}".`);
93
+ }
94
+ entry.ownership = assertOwnership(ownership);
95
+ this.emit('transfer', entry, detail);
96
+ return resource;
97
+ }
98
+
99
+ release(resource, label = null) {
100
+ this.assertOpen();
101
+ if (!resource) {
102
+ return false;
103
+ }
104
+ let entry = this.entries.get(resource);
105
+ if (!entry) {
106
+ this.register(resource, label, this.mode === 'recorded' ? 'submitOwned' : 'scopeOwned');
107
+ entry = this.entries.get(resource);
108
+ }
109
+ if (entry.disposed || entry.ownership === 'borrowed' || entry.ownership === 'transferred' || entry.ownership === 'retained') {
110
+ this.emit('release-skip', entry);
111
+ return false;
112
+ }
113
+ this.dispose(resource);
114
+ entry.disposed = true;
115
+ this.emit(this.mode === 'recorded' ? 'submit-retain' : 'release', entry);
116
+ return true;
117
+ }
118
+
119
+ retain(resource, label = null, detail = null) {
120
+ this.assertOpen();
121
+ if (!resource) {
122
+ return resource;
123
+ }
124
+ if (!this.entries.has(resource)) {
125
+ this.register(resource, label, 'scopeOwned');
126
+ }
127
+ return this.transfer(resource, 'retained', detail);
128
+ }
129
+
130
+ close(outcome = 'success') {
131
+ this.assertOpen();
132
+ for (const entry of this.entries.values()) {
133
+ if (
134
+ !entry.disposed
135
+ && (entry.ownership === 'scopeOwned' || entry.ownership === 'submitOwned')
136
+ ) {
137
+ this.release(entry.resource);
138
+ }
139
+ }
140
+ this.closed = true;
141
+ this.events.push(Object.freeze({
142
+ sequence: this.events.length,
143
+ action: 'close',
144
+ label: this.mode,
145
+ ownership: null,
146
+ detail: outcome,
147
+ }));
148
+ return this.getEvents();
149
+ }
150
+
151
+ getEvents() {
152
+ return Object.freeze([...this.events]);
153
+ }
154
+ }
155
+
156
+ export function createImmediateResourceScope(options = {}) {
157
+ if (typeof options.release !== 'function') {
158
+ throw new Error('[ResourceScope] immediate scope requires a release(resource) function.');
159
+ }
160
+ return new ResourceScope('immediate', options.release);
161
+ }
162
+
163
+ export function createRecordedResourceScope(recorder) {
164
+ if (!recorder || typeof recorder.trackTemporaryBuffer !== 'function') {
165
+ throw new Error('[ResourceScope] recorded scope requires recorder.trackTemporaryBuffer().');
166
+ }
167
+ return new ResourceScope('recorded', (resource) => recorder.trackTemporaryBuffer(resource));
168
+ }
@@ -17,6 +17,7 @@ import { type RDRRManifest } from '../formats/rdrr/index.js';
17
17
  import { type Pipeline } from './pipelines/text.js';
18
18
  import type { RuntimeConfigSchema } from '../config/schema/index.js';
19
19
  import type { PipelineStorageContext } from './pipelines/text/init.js';
20
+ import type { CommandContext } from '../tooling/command-context.js';
20
21
 
21
22
  // ============================================================================
22
23
  // Types
@@ -49,6 +50,8 @@ export interface RuntimeOverrides {
49
50
  * Options for pipeline initialization
50
51
  */
51
52
  export interface InferenceHarnessOptions {
53
+ /** Immutable normalized command identity */
54
+ commandContext?: CommandContext | null;
52
55
  /** Base URL for model files (default: inferred from model URL) */
53
56
  baseUrl?: string;
54
57
  /** Runtime overrides for kernel selection */
@@ -425,6 +425,7 @@ export async function initializeInference(modelUrl, options = {}) {
425
425
  'createPipeline',
426
426
  { modelUrl, modelId: manifest.modelId ?? null },
427
427
  () => createPipeline( ( (manifest)), {
428
+ commandContext: options.commandContext ?? null,
428
429
  storage: storageContext,
429
430
  gpu: { device },
430
431
  runtime,
@@ -0,0 +1,53 @@
1
+ export interface EnsureModelCachedResult {
2
+ cached: boolean;
3
+ fromCache: boolean;
4
+ cacheState: 'hit' | 'verified-hit' | 'manifest-refresh' | 'imported' | 'error';
5
+ modelId: string;
6
+ error: string | null;
7
+ }
8
+
9
+ export interface CacheProgressEvent {
10
+ stage: 'cache-hit' | 'cache-refresh' | 'cache-invalidate' | 'download-start' | 'downloading' | 'download-complete';
11
+ modelId?: string;
12
+ message?: string;
13
+ percent?: number;
14
+ totalBytes?: number;
15
+ downloadedBytes?: number;
16
+ totalShards?: number;
17
+ completedShards?: number;
18
+ speed?: number;
19
+ speedFormatted?: string;
20
+ totalFormatted?: string;
21
+ downloadedFormatted?: string;
22
+ eta?: string;
23
+ }
24
+
25
+ export interface CachedModelSourceResult extends EnsureModelCachedResult {
26
+ manifest: Record<string, unknown>;
27
+ manifestText: string;
28
+ manifestHash: string;
29
+ storageContext: Record<string, unknown>;
30
+ storageBackend: 'opfs';
31
+ totalBytes: number;
32
+ }
33
+
34
+ export interface EnsureModelCachedSourceOptions {
35
+ expectedManifestHash?: string | { hex?: string; hash?: string; digest?: string };
36
+ }
37
+
38
+ export declare function ensureModelCached(
39
+ modelId: string,
40
+ modelBaseUrl: string,
41
+ onProgress?: ((progress: CacheProgressEvent) => void) | null
42
+ ): Promise<EnsureModelCachedResult>;
43
+
44
+ export declare function ensureModelCachedSource(
45
+ modelId: string,
46
+ modelBaseUrl: string,
47
+ onProgress?: ((progress: CacheProgressEvent) => void) | null,
48
+ options?: EnsureModelCachedSourceOptions
49
+ ): Promise<CachedModelSourceResult>;
50
+
51
+ export declare function loadPersistentModelSource(
52
+ modelId: string
53
+ ): Promise<CachedModelSourceResult | null>;