Distillation

Date: Sep 16, 2026

• 🔴 (12:11) User stated native ONNX Runtime resolution is fail-closed and must never interrupt WASM fallback.
• 🔴 (12:11) User stated resolveNativeOrtBindingPath() never throws: an unresolvable native package is the expected dist-only case and must degrade to the WASM fallback rather than crash embedding.
• 🔴 (12:11) User stated workspace native resolution may use only the worker package’s own declared onnxruntime-node dependency and must never select an arbitrary ancestor workspace package.
• 🔴 (12:11) User stated nativeIntraOpThreads() must never touch ORT’s default on an unconstrained host; an override is appropriate only when availableParallelism() < os.cpus().length, indicating a genuine CPU restriction.
• 🔴 (12:11) packages/core/test/ort-native.test.ts includes a regression named "returns null and never throws when native packages are absent", enforcing graceful WASM fallback when native packages are unavailable.
• 🔴 (12:11) Native package selection supports exact published platform packages named with the literal @loreai/onnxruntime-<os>-<arch> shape; these packages are pinned and require no postinstall download.
• 🔴 (12:11) Native resolver tests cover: exact direct workspace dependency resolution; preference for an exact published platform package; rejection of malformed published-package metadata through publishedMutations; and rejection of native packages outside ORT_NATIVE_TARGETS.
• 🔴 (12:12) packages/core/test/ort-native.test.ts requires a nested @loreai/gateway with declared devDependencies: { "onnxruntime-node": ORT_VERSION } to resolve a hoisted workspace binding, but the same nested gateway without that declaration must return null rather than resolve an undeclared ancestor package.
• 🔴 (12:12) Native resolver security regressions require rejecting a package whose bin directory is a symlink escaping the declared package and rejecting onnxruntime_binding.node content that lacks the expected platform-native file format.
• 🔴 (12:12) nativeIntraOpThreads() tests require unconstrained inputs (4, 4), (8, 8), (1, 1), and (8, 4) to return undefined; constrained inputs (2, 8) and (1, 16) return 2 and 1, respectively.
• 🔴 (12:12) nativeIntraOpThreads() floors fractional constrained parallelism and never returns a cap below 1: (2.9, 8) → 2, (0, 8) → 1, (Number.NaN, 8) → 1, and (-4, 8) → 1; calling it with defaults must never throw and must return either undefined or an integer >= 1.
• 🔴 (12:12) In packages/core/src/embedding-worker-types.ts, isMissingLocalStackError() classifies the optional local-embedding stack as absent only when a module/package-not-found signal is paired with a reference to @huggingface/transformers, onnxruntime, or sharp; unrelated resolution failures must not be misclassified.
• 🔴 (12:12) @huggingface/transformers and native transitive dependencies onnxruntime-node, onnxruntime-web, and sharp are an optionalDependency stack for @loreai/core; consumers using remote embeddings, or the SEA binary with its own runtime, may install with --omit=optional and omit approximately 480 MB of ML runtime. Absence is treated as an expected warn-to-FTS-only degraded state rather than a genuine initialization error.
• 🔴 (12:13) isNativeOrtLoadError() requires both a native-runtime identifier—onnxruntime_binding.node, an ONNX Runtime .so/.dylib/.dll, or OrtGetApiBase—and a native-load failure signal such as ERR_DLOPEN_FAILED, invalid ELF/Mach-O/Win32 format, file too short, missing shared library/image/module, undefined/missing symbol, or dlopen.
• 🔴 (12:13) shouldRequestWasmRespawn(usedNative, isVendored, errorMessage, fileLooksIntact) returns true only when native was used, the model is not vendored, the file looks structurally intact, and isCorruptModelError(errorMessage) is true. The canonical case is Bun’s npm bundle loading onnxruntime-node but failing InferenceSession.create() with "protobuf parsing failed" on an intact approximately 137 MB model.
• 🔴 (12:13) Native parse failure handling distinguishes an intact non-vendored model from actual truncation: an intact model under native ONNX requests a forced-WASM respawn, whereas a truncated download follows purge-and-redownload recovery; a vendored SEA model has no WASM sibling and therefore cannot use this fallback.
• 🔴 (12:13) Backend choice is committed on the first ONNX module import. After a native worker requests fallback, the main thread respawns it with WorkerInitData.forceWasm=true, creating a new module graph that skips native resolution and uses bundled, Bun-hardened WASM; this choice remains sticky across respawns rather than bouncing back to native.
• 🔴 (12:13) shouldPostPerRequestError(initFailed, wasmRespawnRequested) returns !initFailed && !wasmRespawnRequested. It must suppress per-request errors after init-error to prevent duplicate reporting and after init-needs-wasm so the main thread does not reject and drop the pending request before respawnForWasm() resubmits it to the fresh WASM worker.