@try-works/tool-mode-runtime-onnx 0.0.0-stage → 0.1.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.
@@ -0,0 +1,276 @@
1
+ /**
2
+ * The declarative provider factory for ONNX (Phase 3).
3
+ *
4
+ * A code-free package names this engine in its recipe, and the host — which declares no
5
+ * engine dependency (AT-25) — calls the factory with the parsed recipe and the host-verified
6
+ * asset map. The factory owns the engine and the processor; the recipe supplies the
7
+ * artifact location, the limits and the tool schemas.
8
+ *
9
+ * ONE LIFECYCLE, TWO PIPELINES. The state machine below is shared by every processor:
10
+ * resolve the artifact, build one ManagedRuntime, force it so a broken deployment fails at
11
+ * load time, bind the graph's tensor names, then run one invoke per call under the
12
+ * recipe's timeout. Processors contribute only their descriptor, sidecar, graph binding and
13
+ * pipeline (`uhm/waveform-v1`, `clear/stft-v1`).
14
+ *
15
+ * THE SDK BOUNDARY IS PROMISE-BASED, THE ENGINE IS EFFECT-BASED. This module keeps that
16
+ * mismatch in one place.
17
+ *
18
+ * TYPED FAILURES: internally every failure is InvalidInput, RuntimeUnavailable or
19
+ * InferenceFailed. The SDK declares Promise methods, and a Schema.TaggedError carries an
20
+ * EMPTY Error.message, so the boundary throws a readable Error whose cause is the typed
21
+ * value. The typed error is still inspectable (error.cause) while a host log is not blank.
22
+ *
23
+ * @module provider-factory
24
+ */
25
+ import { readFile, stat } from 'node:fs/promises';
26
+ import path from 'node:path';
27
+ import { Effect, ManagedRuntime } from 'effect';
28
+ import { InferenceFailed, InvalidInput, RuntimeUnavailable, describeCause } from "./errors.js";
29
+ import { CLEAR_STFT_PROCESSOR, clearProcessor } from "./clear-processor.js";
30
+ import { parseAudioPath, prepareSamples, readAudioBytes, resolveAudioPath } from "./processor.js";
31
+ import { OnnxSession, onnxLayer } from "./runtime.js";
32
+ import { UHM_WAVEFORM_PROCESSOR, uhmProcessor } from "./uhm-processor.js";
33
+ const PROVIDER = 'onnx';
34
+ /** Render a typed failure, or any thrown value, as one readable sentence. */
35
+ function describeFailure(cause) {
36
+ if (cause instanceof InvalidInput)
37
+ return cause.field + ': ' + cause.message;
38
+ if (cause instanceof InferenceFailed)
39
+ return cause.phase + ': ' + cause.message;
40
+ if (cause instanceof RuntimeUnavailable)
41
+ return cause.reason;
42
+ if (cause instanceof Error)
43
+ return cause.message.length > 0 ? cause.message : cause.name;
44
+ return describeCause(cause);
45
+ }
46
+ /** Wrap a typed failure for the Promise-based SDK boundary. */
47
+ function boundaryError(message, cause) {
48
+ return new Error(message, { cause });
49
+ }
50
+ /**
51
+ * Resolve the model artifact from the prepared asset map.
52
+ *
53
+ * The host exposes TWO truthful projections: the group id resolves to the group DIRECTORY
54
+ * and each asset id resolves to its FILE. Both are accepted, and a file handle whose name
55
+ * does not match the recipe is refused rather than read as the artifact.
56
+ */
57
+ async function readArtifact(recipe, primary, fallback) {
58
+ const assetSet = recipe.model.assetSet;
59
+ const handle = primary.get(assetSet) ?? fallback.get(assetSet);
60
+ if (handle === undefined) {
61
+ throw new RuntimeUnavailable({
62
+ provider: PROVIDER,
63
+ reason: 'the "' + assetSet + '" asset set is not prepared; load() needs the host-verified asset map',
64
+ });
65
+ }
66
+ const resolved = path.resolve(handle.path);
67
+ let stats;
68
+ try {
69
+ stats = await stat(resolved);
70
+ }
71
+ catch (cause) {
72
+ throw new RuntimeUnavailable({
73
+ provider: PROVIDER,
74
+ reason: 'the "' + assetSet + '" asset handle cannot be inspected: ' + describeCause(cause),
75
+ });
76
+ }
77
+ let modelPath;
78
+ let directory;
79
+ if (stats.isDirectory()) {
80
+ modelPath = path.resolve(resolved, recipe.model.fileName);
81
+ directory = resolved;
82
+ }
83
+ else {
84
+ if (path.basename(resolved) !== recipe.model.fileName) {
85
+ throw new RuntimeUnavailable({
86
+ provider: PROVIDER,
87
+ reason: 'the "' + assetSet + '" asset handle names "' + path.basename(resolved) + '" but the recipe names "'
88
+ + recipe.model.fileName + '"',
89
+ });
90
+ }
91
+ modelPath = resolved;
92
+ directory = path.dirname(resolved);
93
+ }
94
+ if (modelPath !== directory && !modelPath.startsWith(directory + path.sep)) {
95
+ throw new RuntimeUnavailable({
96
+ provider: PROVIDER,
97
+ reason: 'the recipe file name "' + recipe.model.fileName + '" escapes the "' + assetSet + '" asset directory',
98
+ });
99
+ }
100
+ try {
101
+ return { modelBytes: new Uint8Array(await readFile(modelPath)), directory };
102
+ }
103
+ catch (cause) {
104
+ throw new RuntimeUnavailable({
105
+ provider: PROVIDER,
106
+ reason: 'the "' + assetSet + '" model artifact "' + recipe.model.fileName + '" cannot be read: ' + describeCause(cause),
107
+ });
108
+ }
109
+ }
110
+ /**
111
+ * Build the shared provider around one processor definition.
112
+ *
113
+ * @param recipe - the parsed, frozen recipe
114
+ * @param assets - the asset map captured at creation
115
+ * @param options - test seams
116
+ * @param processor - the pipeline this build implements
117
+ * @returns the SDK provider
118
+ */
119
+ function createProvider(recipe, assets, options, processor) {
120
+ const label = recipe.tool.name;
121
+ let state = { _tag: 'cold' };
122
+ const inspect = async (signal) => {
123
+ if (signal.aborted)
124
+ throw new Error('the "' + label + '" inspection was aborted before it started');
125
+ switch (state._tag) {
126
+ case 'disposed':
127
+ return { readiness: 'unavailable', features: [], missing: [], reason: 'the provider has been disposed' };
128
+ case 'failed':
129
+ return { readiness: 'failed', features: [], missing: [], reason: state.reason };
130
+ case 'cold':
131
+ return {
132
+ readiness: 'prepared-cold',
133
+ features: [processor.id],
134
+ missing: [],
135
+ reason: label + ' has not been loaded yet; load() must run before the first call',
136
+ };
137
+ case 'ready':
138
+ return { readiness: 'ready', features: [processor.id], missing: [] };
139
+ }
140
+ };
141
+ const load = async (request) => {
142
+ if (request.signal.aborted)
143
+ throw new Error('the "' + label + '" load was aborted before it started');
144
+ if (state._tag === 'disposed')
145
+ throw new Error('the provider has been disposed');
146
+ if (state._tag === 'ready')
147
+ return;
148
+ try {
149
+ const artifact = await readArtifact(recipe, request.assets, assets);
150
+ const sidecar = await processor.loadSidecar(artifact.directory);
151
+ const layerOptions = { modelBytes: artifact.modelBytes, accelerators: recipe.provider.accelerators };
152
+ const layer = options.loader === undefined
153
+ ? onnxLayer(layerOptions)
154
+ : onnxLayer({ ...layerOptions, loader: options.loader });
155
+ const candidate = ManagedRuntime.make(layer);
156
+ try {
157
+ // The runtime is lazy; force the layer to build AND read the graph names, so a
158
+ // broken deployment fails HERE and not at the first caller's expense.
159
+ const names = await candidate.runPromise(Effect.gen(function* () {
160
+ const session = yield* OnnxSession;
161
+ return { inputs: session.inputNames, outputs: session.outputNames };
162
+ }), { signal: request.signal });
163
+ const bound = processor.bindGraph(names);
164
+ if (!bound.ok)
165
+ throw new RuntimeUnavailable({ provider: PROVIDER, reason: bound.reason });
166
+ state = { _tag: 'ready', runtime: candidate, sidecar, binding: bound.value };
167
+ }
168
+ catch (cause) {
169
+ await candidate.dispose().catch(() => undefined);
170
+ throw cause;
171
+ }
172
+ }
173
+ catch (cause) {
174
+ const reason = describeFailure(cause);
175
+ state = { _tag: 'failed', reason };
176
+ throw boundaryError('the "' + label + '" model failed to load: ' + reason, cause);
177
+ }
178
+ };
179
+ const invoke = async (request) => {
180
+ if (request.context.signal.aborted)
181
+ throw new Error('the "' + label + '" invocation was aborted before it started');
182
+ if (state._tag === 'disposed')
183
+ throw new Error('the provider has been disposed');
184
+ if (state._tag === 'failed')
185
+ throw new Error('the "' + label + '" runtime is not loaded: ' + state.reason);
186
+ if (state._tag === 'cold')
187
+ throw new Error('the "' + label + '" runtime is not loaded: load() must be called before invoke()');
188
+ const runtime = state.runtime;
189
+ const sidecar = state.sidecar;
190
+ const binding = state.binding;
191
+ const controller = new AbortController();
192
+ const relayAbort = () => controller.abort(request.context.signal.reason);
193
+ request.context.signal.addEventListener('abort', relayAbort, { once: true });
194
+ const timer = setTimeout(() => {
195
+ controller.abort(new Error('the "' + label + '" invocation timed out after ' + String(recipe.limits.timeoutMs) + 'ms'));
196
+ }, recipe.limits.timeoutMs);
197
+ try {
198
+ const program = Effect.gen(function* () {
199
+ const audioPath = yield* parseAudioPath(request.input, recipe);
200
+ const resolved = yield* resolveAudioPath(request.context, audioPath);
201
+ const bytes = yield* readAudioBytes(resolved);
202
+ const audio = yield* prepareSamples(bytes, processor.sampleRate);
203
+ const session = yield* OnnxSession;
204
+ return yield* processor.invoke({
205
+ engine: session,
206
+ sidecar,
207
+ binding,
208
+ recipe,
209
+ input: request.input,
210
+ context: request.context,
211
+ audio,
212
+ });
213
+ });
214
+ return await runtime.runPromise(program, { signal: controller.signal });
215
+ }
216
+ catch (cause) {
217
+ if (request.context.signal.aborted) {
218
+ throw boundaryError('the "' + label + '" invocation was aborted', cause);
219
+ }
220
+ if (controller.signal.aborted) {
221
+ const message = 'the "' + label + '" inference timed out after ' + String(recipe.limits.timeoutMs) + 'ms';
222
+ throw boundaryError(message, new InferenceFailed({ provider: PROVIDER, phase: 'run', message }));
223
+ }
224
+ throw boundaryError('the "' + label + '" invocation failed: ' + describeFailure(cause), cause);
225
+ }
226
+ finally {
227
+ clearTimeout(timer);
228
+ request.context.signal.removeEventListener('abort', relayAbort);
229
+ }
230
+ };
231
+ const unload = async (_signal) => {
232
+ if (state._tag !== 'ready')
233
+ return;
234
+ const runtime = state.runtime;
235
+ state = { _tag: 'cold' };
236
+ await runtime.dispose();
237
+ };
238
+ const dispose = async () => {
239
+ if (state._tag === 'disposed')
240
+ return;
241
+ const runtime = state._tag === 'ready' ? state.runtime : undefined;
242
+ state = { _tag: 'disposed' };
243
+ if (runtime !== undefined)
244
+ await runtime.dispose();
245
+ };
246
+ return { inspect, load, invoke, unload, dispose };
247
+ }
248
+ /**
249
+ * Build the SDK provider for one validated, code-free model-runtime recipe.
250
+ *
251
+ * Creation is lightweight (EXT-19): it validates what can be validated statically and reads
252
+ * nothing. Assets are resolved at load() time, preferring the map the SDK hands to load()
253
+ * over the map captured at creation, because the host may build the factory before a
254
+ * preparation completes.
255
+ *
256
+ * @param recipe - the parsed, frozen model-runtime recipe.
257
+ * @param assets - the host-verified asset map captured at creation.
258
+ * @param options - test seams (a fake engine loader); production callers omit it.
259
+ * @returns the SDK's Promise-based provider.
260
+ */
261
+ export function createProviderFromRecipe(recipe, assets, options = {}) {
262
+ const label = recipe.tool.name;
263
+ if (recipe.model.format !== 'onnx') {
264
+ throw new Error('the onnx provider factory executes only onnx artifacts; the recipe "' + label + '" declares "' + recipe.model.format + '"');
265
+ }
266
+ switch (recipe.processor.id) {
267
+ case UHM_WAVEFORM_PROCESSOR:
268
+ return createProvider(recipe, assets, options, uhmProcessor());
269
+ case CLEAR_STFT_PROCESSOR:
270
+ return createProvider(recipe, assets, options, clearProcessor());
271
+ default:
272
+ throw new Error('the onnx provider factory does not implement processor "' + recipe.processor.id + '"; this build implements "'
273
+ + UHM_WAVEFORM_PROCESSOR + '" and "' + CLEAR_STFT_PROCESSOR + '"');
274
+ }
275
+ }
276
+ //# sourceMappingURL=provider-factory.js.map
@@ -0,0 +1,122 @@
1
+ /**
2
+ * `OnnxSession`: the Effect service a model provider depends on (PHASE3).
3
+ *
4
+ * Contract: the layer builds ONE onnxruntime-node session and acquires it in the layer
5
+ * scope; `run` is serialized with `Semaphore.make(1)` so a provider runs one inference at
6
+ * a time. A failed load fails the layer with `RuntimeUnavailable`; a failed run fails with
7
+ * `InferenceFailed` (`run`). The layer has no way to fail a RELEASE, because a teardown
8
+ * that throws would mask the reason the scope is closing.
9
+ *
10
+ * EXECUTION-PROVIDER NEGOTIATION. A recipe declares the lanes it may use, in preference
11
+ * order. This module asks the installed engine what it actually bundles
12
+ * (`listSupportedBackends()`; verified on Windows x64 with onnxruntime-node 1.30.0 to
13
+ * report cpu, dml and webgpu, all bundled) and takes the FIRST declared lane that is
14
+ * available. It does not silently fall back to a lane the recipe did not declare: a
15
+ * deployment that asked for a GPU lane and got CPU without being told would be a
16
+ * performance claim nobody can audit.
17
+ *
18
+ * TESTS: the unit suite injects a fake `OnnxSessionLoader`, so it proves the lifecycle,
19
+ * the negotiation rules and the error mapping — not inference.
20
+ *
21
+ * @module runtime
22
+ */
23
+ import { Context, Effect, Layer } from 'effect';
24
+ import { InferenceFailed, RuntimeUnavailable } from './errors.ts';
25
+ /** A feed tensor: float32 or int32 data and its dims. */
26
+ export interface OnnxFeed {
27
+ readonly data: Float32Array | Int32Array;
28
+ readonly dims: readonly number[];
29
+ }
30
+ /** The output data kinds a session exposes. */
31
+ export type OnnxOutputData = Float32Array | Int32Array | BigInt64Array;
32
+ /** One output tensor. */
33
+ export interface OnnxTensor {
34
+ readonly data: OnnxOutputData;
35
+ readonly dims: readonly number[];
36
+ }
37
+ /** The compute lanes a recipe may request. */
38
+ export type OnnxExecutionProvider = 'cpu' | 'dml' | 'webgpu';
39
+ /** One backend the engine reports. */
40
+ export interface OnnxBackend {
41
+ readonly name: string;
42
+ readonly bundled: boolean;
43
+ }
44
+ /** One loaded engine session. This is the unit-test seam's product. */
45
+ export interface OnnxLoadedSession {
46
+ readonly inputNames: readonly string[];
47
+ readonly outputNames: readonly string[];
48
+ readonly executionProvider: string;
49
+ readonly run: (feeds: Readonly<Record<string, OnnxFeed>>) => Promise<Readonly<Record<string, OnnxTensor>>>;
50
+ readonly release: () => Promise<void>;
51
+ }
52
+ /** What one load needs. */
53
+ export interface OnnxLoadOptions {
54
+ readonly modelBytes: Uint8Array;
55
+ /** The lanes the recipe declares, in preference order. */
56
+ readonly accelerators: readonly OnnxExecutionProvider[];
57
+ readonly intraOpNumThreads?: number;
58
+ }
59
+ /** The engine seam: onnxruntime-node in production, a fake in the unit tests. */
60
+ export interface OnnxSessionLoader {
61
+ readonly load: (options: OnnxLoadOptions) => Promise<OnnxLoadedSession>;
62
+ }
63
+ /** The session members a provider layer uses. */
64
+ export interface OnnxSessionApi {
65
+ readonly inputNames: readonly string[];
66
+ readonly outputNames: readonly string[];
67
+ /** The execution provider the session was created with. */
68
+ readonly executionProvider: string;
69
+ readonly run: (feeds: Readonly<Record<string, OnnxFeed>>) => Effect.Effect<Readonly<Record<string, OnnxTensor>>, InferenceFailed>;
70
+ }
71
+ declare const OnnxSession_base: Context.ServiceClass<OnnxSession, "tool-mode-runtime/OnnxSession", OnnxSessionApi>;
72
+ /** One engine session, safe to share across concurrent callers. */
73
+ export declare class OnnxSession extends OnnxSession_base {
74
+ }
75
+ /** The negotiation result. */
76
+ export type ProviderSelection = {
77
+ readonly ok: true;
78
+ readonly provider: OnnxExecutionProvider;
79
+ readonly supported: readonly string[];
80
+ } | {
81
+ readonly ok: false;
82
+ readonly reason: string;
83
+ };
84
+ /**
85
+ * Choose the execution provider for a session.
86
+ *
87
+ * @param requested - the recipe's lanes, most preferred first
88
+ * @param supported - what the installed engine reports
89
+ * @returns the chosen lane, or the reason no requested lane is available
90
+ */
91
+ export declare function selectExecutionProvider(requested: readonly OnnxExecutionProvider[], supported: readonly OnnxBackend[]): ProviderSelection;
92
+ /** Options for {@link onnxLayer}; `loader` is the unit-test seam. */
93
+ export interface OnnxLayerOptions {
94
+ readonly modelBytes: Uint8Array;
95
+ /** The recipe's lanes, most preferred first. Defaults to `['cpu']`. */
96
+ readonly accelerators?: readonly OnnxExecutionProvider[];
97
+ readonly intraOpNumThreads?: number;
98
+ readonly loader?: OnnxSessionLoader;
99
+ }
100
+ /**
101
+ * The real engine seam: onnxruntime-node, imported lazily.
102
+ *
103
+ * The dynamic import is deliberate. A unit test that injects a fake loader never touches
104
+ * the native binding, so the test suite runs on a machine where the binding cannot load,
105
+ * and the failure a real deployment would hit is reported by load() instead of by
106
+ * importing this module.
107
+ *
108
+ * @returns a loader backed by onnxruntime-node
109
+ */
110
+ export declare function createNodeOnnxLoader(): OnnxSessionLoader;
111
+ /**
112
+ * Build the session for one compiled model.
113
+ *
114
+ * The session is acquired when the layer builds, released when the layer's scope closes,
115
+ * and every `run` holds the single permit.
116
+ *
117
+ * @param options - the model bytes, the desired lanes and the test seam
118
+ * @returns the layer, which fails with `RuntimeUnavailable` when the engine cannot load
119
+ */
120
+ export declare const onnxLayer: (options: OnnxLayerOptions) => Layer.Layer<OnnxSession, RuntimeUnavailable>;
121
+ export {};
122
+ //# sourceMappingURL=runtime.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}
package/lib/runtime.js ADDED
@@ -0,0 +1,175 @@
1
+ /**
2
+ * `OnnxSession`: the Effect service a model provider depends on (PHASE3).
3
+ *
4
+ * Contract: the layer builds ONE onnxruntime-node session and acquires it in the layer
5
+ * scope; `run` is serialized with `Semaphore.make(1)` so a provider runs one inference at
6
+ * a time. A failed load fails the layer with `RuntimeUnavailable`; a failed run fails with
7
+ * `InferenceFailed` (`run`). The layer has no way to fail a RELEASE, because a teardown
8
+ * that throws would mask the reason the scope is closing.
9
+ *
10
+ * EXECUTION-PROVIDER NEGOTIATION. A recipe declares the lanes it may use, in preference
11
+ * order. This module asks the installed engine what it actually bundles
12
+ * (`listSupportedBackends()`; verified on Windows x64 with onnxruntime-node 1.30.0 to
13
+ * report cpu, dml and webgpu, all bundled) and takes the FIRST declared lane that is
14
+ * available. It does not silently fall back to a lane the recipe did not declare: a
15
+ * deployment that asked for a GPU lane and got CPU without being told would be a
16
+ * performance claim nobody can audit.
17
+ *
18
+ * TESTS: the unit suite injects a fake `OnnxSessionLoader`, so it proves the lifecycle,
19
+ * the negotiation rules and the error mapping — not inference.
20
+ *
21
+ * @module runtime
22
+ */
23
+ /*
24
+ * This module IS the boundary between the native engine and the runtime: the engine hands
25
+ * back values typed as `OnnxValue`/`unknown`, and turning those into `OnnxTensor` is a
26
+ * run-time proof about representations, not a typed caller. The generic anti-slop rules
27
+ * assume an already-typed value, so they are disabled for this boundary only; every value
28
+ * is validated by kind before it is exposed.
29
+ */
30
+ /* oxlint-disable anti-slop/no-unknown-parameters, anti-slop/no-runtime-typeof */
31
+ import { Context, Effect, Layer, Semaphore } from 'effect';
32
+ import { InferenceFailed, RuntimeUnavailable, describeCause } from "./errors.js";
33
+ const PROVIDER = 'onnx';
34
+ /** One engine session, safe to share across concurrent callers. */
35
+ export class OnnxSession extends Context.Service()('tool-mode-runtime/OnnxSession') {
36
+ }
37
+ /**
38
+ * Choose the execution provider for a session.
39
+ *
40
+ * @param requested - the recipe's lanes, most preferred first
41
+ * @param supported - what the installed engine reports
42
+ * @returns the chosen lane, or the reason no requested lane is available
43
+ */
44
+ export function selectExecutionProvider(requested, supported) {
45
+ const available = supported.filter((backend) => backend.bundled).map((backend) => backend.name);
46
+ if (requested.length === 0) {
47
+ return { ok: false, reason: 'no execution provider was requested; the recipe must name at least one' };
48
+ }
49
+ for (const lane of requested) {
50
+ if (available.includes(lane))
51
+ return { ok: true, provider: lane, supported: available };
52
+ }
53
+ return {
54
+ ok: false,
55
+ reason: `none of the requested execution providers (${requested.join(', ')}) is available; `
56
+ + `the engine bundles: ${available.length === 0 ? 'none' : available.join(', ')}`,
57
+ };
58
+ }
59
+ /**
60
+ * Convert one engine output to the runtime's tensor shape.
61
+ *
62
+ * The properties are read with `in`, not `Object.hasOwn`: onnxruntime-node returns a
63
+ * `Tensor` whose `data` and `dims` are PROTOTYPE getters, so an own-property check would
64
+ * reject every real output while accepting only a fake one. Values are then validated by
65
+ * kind, so nothing here trusts the engine's declared shape.
66
+ */
67
+ function toOnnxTensor(name, value) {
68
+ if (typeof value !== 'object' || value === null) {
69
+ throw new Error(`the graph returned the output ${JSON.stringify(name)} as a non-tensor value`);
70
+ }
71
+ if (!('data' in value) || !('dims' in value)) {
72
+ throw new Error(`the graph returned the output ${JSON.stringify(name)} as a non-tensor value`);
73
+ }
74
+ const data = value.data;
75
+ const dims = value.dims;
76
+ if (!(data instanceof Float32Array || data instanceof Int32Array || data instanceof BigInt64Array)) {
77
+ throw new Error(`the graph returned the output ${JSON.stringify(name)} with an unsupported data kind`);
78
+ }
79
+ if (!Array.isArray(dims) || !dims.every((dim) => typeof dim === 'number' && Number.isInteger(dim) && dim >= 0)) {
80
+ throw new Error(`the graph returned the output ${JSON.stringify(name)} with invalid dimensions`);
81
+ }
82
+ return { data, dims: [...dims] };
83
+ }
84
+ /**
85
+ * The real engine seam: onnxruntime-node, imported lazily.
86
+ *
87
+ * The dynamic import is deliberate. A unit test that injects a fake loader never touches
88
+ * the native binding, so the test suite runs on a machine where the binding cannot load,
89
+ * and the failure a real deployment would hit is reported by load() instead of by
90
+ * importing this module.
91
+ *
92
+ * @returns a loader backed by onnxruntime-node
93
+ */
94
+ export function createNodeOnnxLoader() {
95
+ return {
96
+ async load(options) {
97
+ const ort = await import('onnxruntime-node');
98
+ const supported = ort.listSupportedBackends().map((backend) => ({
99
+ name: backend.name,
100
+ bundled: backend.bundled,
101
+ }));
102
+ const selection = selectExecutionProvider(options.accelerators, supported);
103
+ if (!selection.ok)
104
+ throw new RuntimeUnavailable({ provider: PROVIDER, reason: selection.reason });
105
+ const sessionOptions = {
106
+ executionProviders: [selection.provider],
107
+ };
108
+ if (options.intraOpNumThreads !== undefined)
109
+ sessionOptions.intraOpNumThreads = options.intraOpNumThreads;
110
+ const session = await ort.InferenceSession.create(options.modelBytes, sessionOptions);
111
+ return {
112
+ inputNames: session.inputNames,
113
+ outputNames: session.outputNames,
114
+ executionProvider: selection.provider,
115
+ run: async (feeds) => {
116
+ const tensors = {};
117
+ for (const [name, feed] of Object.entries(feeds)) {
118
+ tensors[name] = feed.data instanceof Float32Array
119
+ ? new ort.Tensor('float32', feed.data, [...feed.dims])
120
+ : new ort.Tensor('int32', feed.data, [...feed.dims]);
121
+ }
122
+ const outputs = await session.run(tensors);
123
+ const converted = {};
124
+ for (const [name, value] of Object.entries(outputs)) {
125
+ converted[name] = toOnnxTensor(name, value);
126
+ }
127
+ return converted;
128
+ },
129
+ release: () => session.release(),
130
+ };
131
+ },
132
+ };
133
+ }
134
+ /**
135
+ * Build the session for one compiled model.
136
+ *
137
+ * The session is acquired when the layer builds, released when the layer's scope closes,
138
+ * and every `run` holds the single permit.
139
+ *
140
+ * @param options - the model bytes, the desired lanes and the test seam
141
+ * @returns the layer, which fails with `RuntimeUnavailable` when the engine cannot load
142
+ */
143
+ export const onnxLayer = (options) => Layer.effect(OnnxSession, Effect.gen(function* () {
144
+ const loader = options.loader ?? createNodeOnnxLoader();
145
+ const accelerators = options.accelerators ?? ['cpu'];
146
+ const baseOptions = { modelBytes: options.modelBytes, accelerators };
147
+ const loadOptions = options.intraOpNumThreads === undefined
148
+ ? baseOptions
149
+ : { ...baseOptions, intraOpNumThreads: options.intraOpNumThreads };
150
+ const loaded = yield* Effect.acquireRelease(Effect.tryPromise({
151
+ try: () => loader.load(loadOptions),
152
+ catch: (cause) => cause instanceof RuntimeUnavailable
153
+ ? cause
154
+ : new RuntimeUnavailable({ provider: PROVIDER, reason: describeCause(cause) }),
155
+ }), (session) => Effect.promise(async () => {
156
+ try {
157
+ await session.release();
158
+ }
159
+ catch {
160
+ // Teardown must not fail; the native session may already be unusable.
161
+ }
162
+ }));
163
+ const permits = yield* Semaphore.make(1);
164
+ const run = (feeds) => permits.withPermit(Effect.tryPromise({
165
+ try: () => loaded.run(feeds),
166
+ catch: (cause) => new InferenceFailed({ provider: PROVIDER, phase: 'run', message: describeCause(cause) }),
167
+ }));
168
+ return OnnxSession.of({
169
+ inputNames: loaded.inputNames,
170
+ outputNames: loaded.outputNames,
171
+ executionProvider: loaded.executionProvider,
172
+ run,
173
+ });
174
+ }));
175
+ //# sourceMappingURL=runtime.js.map
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Processor `uhm/waveform-v1`: filler-word detection (Phase 3, the first model).
3
+ *
4
+ * The pipeline is `frames.ts` + `wav.ts`; this module is only the processor seam: the
5
+ * labels sidecar, the one-input/one-output graph binding, and the window loop.
6
+ *
7
+ * @module uhm-processor
8
+ */
9
+ import type { ProcessorDefinition } from './processor.ts';
10
+ /** The recipe processor id this module implements. */
11
+ export declare const UHM_WAVEFORM_PROCESSOR = "uhm/waveform-v1";
12
+ /** The graph binding the provider proves at load time. */
13
+ export interface UhmBinding {
14
+ readonly inputName: string;
15
+ readonly outputName: string;
16
+ }
17
+ /**
18
+ * The uhm processor definition.
19
+ *
20
+ * @returns the definition the provider factory dispatches to
21
+ */
22
+ export declare function uhmProcessor(): ProcessorDefinition<readonly string[], UhmBinding>;
23
+ //# sourceMappingURL=uhm-processor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"uhm-processor.d.ts","sourceRoot":"","sources":["../src/uhm-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAGzD,sDAAsD;AACtD,eAAO,MAAM,sBAAsB,oBAAoB,CAAA;AAIvD,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAoDD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,mBAAmB,CAAC,SAAS,MAAM,EAAE,EAAE,UAAU,CAAC,CAsDjF"}