@independo/inderun-web 0.2.0-dev.1 → 0.2.0-dev.3

package/dist/onnx-transformers-runtime.d.ts

@@ -0,0 +1,72 @@
+import type { ModelPackage } from "@independo/inderun-contracts";
+import { type OnnxTextGenerationRuntime } from "./onnx-runtime.js";
+/**
+ * Structural view of the `@huggingface/transformers` entry points this runtime uses.
+ *
+ * The dependency is optional, so the module is typed structurally instead of imported for types.
+ */
+export interface TransformersModule {
+    /** Builds a task pipeline, downloading or loading model assets as needed. */
+    pipeline: (task: string, model?: string, options?: Record<string, unknown>) => Promise<TransformersTextGenerator>;
+    /** Global Transformers.js environment used to point the loader at local model assets. */
+    env?: Record<string, unknown>;
+}
+/**
+ * Structural view of a Transformers.js `text-generation` pipeline.
+ */
+export type TransformersTextGenerator = (input: unknown, options?: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Configuration for the Transformers.js-backed ONNX runtime.
+ */
+export interface TransformersJsRuntimeOptions {
+    /**
+     * Overrides how the `@huggingface/transformers` module is loaded. Tests inject a fake module;
+     * production uses a lazy dynamic import so the dependency stays optional.
+     */
+    load?: () => Promise<TransformersModule>;
+    /**
+     * Execution backend passed to Transformers.js. Defaults to `webgpu` when `navigator.gpu`
+     * exists and `wasm` otherwise. This is an ONNX Runtime execution backend, not an IndeRun
+     * routing concept.
+     */
+    device?: string;
+    /**
+     * Weight quantization passed to Transformers.js (for example `q4`, `q4f16`, `q8`, `fp16`,
+     * `fp32`).
+     *
+     * Defaults to a quantized variant (`q4f16` on WebGPU, `q4` otherwise) because Transformers.js
+     * would otherwise load full `fp32` weights, which exhausts browser memory for all but the
+     * smallest models. Set explicitly when the model does not publish the default variant.
+     */
+    dtype?: string;
+    /** Base path or URL for locally served model assets (`bundled` / `app_managed` sources). */
+    localModelPath?: string;
+    /** Extra options merged into the Transformers.js `pipeline()` call. */
+    pipelineOptions?: Record<string, unknown>;
+    /**
+     * Supplies a pre-built generator instead of letting this runtime construct one. Required for
+     * `programmatic` model sources, where the application owns model resolution.
+     */
+    createGenerator?: (context: {
+        modelPackage: ModelPackage;
+        module: TransformersModule;
+        device: string;
+    }) => Promise<TransformersTextGenerator>;
+}
+/**
+ * Creates the default Web ONNX runtime, backed by Transformers.js (which runs ONNX models through
+ * `onnxruntime-web`).
+ *
+ * ONNX Runtime GenAI has no browser build, so Transformers.js fills the generative-loop role
+ * (tokenization, sampling, KV cache) behind the `OnnxTextGenerationRuntime` seam. Applications that
+ * need a different runtime implement the seam themselves and pass it to the provider.
+ *
+ * `@huggingface/transformers` is an optional dependency the application installs: when it is absent
+ * the runtime
+ * reports itself unavailable instead of throwing, so routing degrades to an explainable
+ * `capability_unavailable` rejection.
+ *
+ * @param options - Loader, backend, and model-resolution overrides.
+ */
+export declare function createTransformersJsRuntime(options?: TransformersJsRuntimeOptions): OnnxTextGenerationRuntime;
+//# sourceMappingURL=onnx-transformers-runtime.d.ts.map

package/dist/onnx-transformers-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnx-transformers-runtime.d.ts","sourceRoot":"","sources":["../src/onnx-transformers-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,EAAE,CACR,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACxC,yFAAyF;IACzF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACzC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE;QAC1B,YAAY,EAAE,YAAY,CAAC;QAC3B,MAAM,EAAE,kBAAkB,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC1C;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,4BAAiC,GACzC,yBAAyB,CAyI3B"}

package/dist/onnx-transformers-runtime.js

@@ -0,0 +1,210 @@
+import { OnnxRuntimeError } from "./onnx-runtime.js";
+const TEXT_GENERATION_TASK = "text-generation";
+/**
+ * Creates the default Web ONNX runtime, backed by Transformers.js (which runs ONNX models through
+ * `onnxruntime-web`).
+ *
+ * ONNX Runtime GenAI has no browser build, so Transformers.js fills the generative-loop role
+ * (tokenization, sampling, KV cache) behind the `OnnxTextGenerationRuntime` seam. Applications that
+ * need a different runtime implement the seam themselves and pass it to the provider.
+ *
+ * `@huggingface/transformers` is an optional dependency the application installs: when it is absent
+ * the runtime
+ * reports itself unavailable instead of throwing, so routing degrades to an explainable
+ * `capability_unavailable` rejection.
+ *
+ * @param options - Loader, backend, and model-resolution overrides.
+ */
+export function createTransformersJsRuntime(options = {}) {
+    let modulePromise;
+    let generatorPromise;
+    async function loadModule() {
+        modulePromise ??= (options.load ?? loadTransformersModule)();
+        return modulePromise;
+    }
+    async function loadGenerator(modelPackage) {
+        generatorPromise ??= (async () => {
+            const module = await loadModule();
+            const device = resolveDevice(options.device);
+            if (options.createGenerator) {
+                return options.createGenerator({ modelPackage, module, device });
+            }
+            const modelRef = getModelRef(modelPackage);
+            if (!modelRef) {
+                throw new OnnxRuntimeError("capability", "model source unavailable: the model package does not declare source.ref.");
+            }
+            applyEnvironment(module, modelPackage, options.localModelPath);
+            const pipelineOptions = {
+                device,
+                dtype: options.dtype ?? defaultDtype(device),
+                ...(options.pipelineOptions ?? {})
+            };
+            return module.pipeline(TEXT_GENERATION_TASK, modelRef, pipelineOptions);
+        })();
+        return generatorPromise;
+    }
+    return {
+        async prepare(modelPackage) {
+            let module;
+            try {
+                module = await loadModule();
+            }
+            catch (err) {
+                modulePromise = undefined;
+                return {
+                    available: false,
+                    reason: `runtime package unavailable: install the optional dependency @huggingface/transformers (${getErrorMessage(err)}).`
+                };
+            }
+            if (typeof module.pipeline !== "function") {
+                return {
+                    available: false,
+                    reason: "runtime initialization failed: @huggingface/transformers did not expose pipeline()."
+                };
+            }
+            if (modelPackage.format !== "onnx") {
+                return {
+                    available: false,
+                    reason: `unsupported model format: the Transformers.js runtime consumes ONNX weights, received '${modelPackage.format}'.`
+                };
+            }
+            const sourceType = modelPackage.source?.sourceType;
+            if (sourceType === "programmatic" && !options.createGenerator) {
+                return {
+                    available: false,
+                    reason: "model source unavailable: programmatic model packages require a createGenerator option."
+                };
+            }
+            if (!options.createGenerator && !getModelRef(modelPackage)) {
+                return {
+                    available: false,
+                    reason: "model source unavailable: the model package does not declare source.ref."
+                };
+            }
+            return { available: true };
+        },
+        async generate(input, signal) {
+            let generator;
+            try {
+                generator = await loadGenerator(input.modelPackage);
+            }
+            catch (err) {
+                generatorPromise = undefined;
+                if (err instanceof OnnxRuntimeError)
+                    throw err;
+                if (isResourceExhaustion(err)) {
+                    throw new OnnxRuntimeError("unavailable", `insufficient memory to load the model: ${getErrorMessage(err)}. Try a smaller model or a more aggressive dtype (for example 'q4').`, err);
+                }
+                throw new OnnxRuntimeError("capability", `model files missing or unreadable: ${getErrorMessage(err)}`, err);
+            }
+            if (signal?.aborted) {
+                throw new OnnxRuntimeError("timeout", "ONNX generation was aborted before it started.");
+            }
+            let raw;
+            try {
+                raw = await generator(input.messages, createGenerationOptions(input, signal));
+            }
+            catch (err) {
+                throw new OnnxRuntimeError("internal", `ONNX generation failed: ${getErrorMessage(err)}`, err);
+            }
+            const text = extractGeneratedText(raw);
+            if (text === undefined) {
+                throw new OnnxRuntimeError("internal", "model output malformed: the Transformers.js pipeline returned no text.");
+            }
+            return { text };
+        }
+    };
+}
+async function loadTransformersModule() {
+    // The specifier stays a literal so bundlers and dev servers resolve the bare package name; the
+    // `as string` cast keeps TypeScript from requiring the optional dependency's types here. Apps that
+    // do not install Transformers.js should pass their own `load` (or a different runtime) rather than
+    // relying on this default, which their bundler will fail to resolve.
+    return (await import("@huggingface/transformers"));
+}
+/**
+ * Browser-viable weight variant. Transformers.js defaults to `fp32`, which makes ONNX Runtime
+ * allocate the full-precision model and fail session creation with an allocation error for
+ * anything but tiny models.
+ */
+function defaultDtype(device) {
+    return device === "webgpu" ? "q4f16" : "q4";
+}
+function resolveDevice(configured) {
+    if (configured !== undefined)
+        return configured;
+    const gpu = globalThis.navigator?.gpu;
+    return gpu ? "webgpu" : "wasm";
+}
+function getModelRef(modelPackage) {
+    const ref = modelPackage.source?.ref;
+    return typeof ref === "string" && ref.length > 0 ? ref : undefined;
+}
+function applyEnvironment(module, modelPackage, localModelPath) {
+    const env = module.env;
+    if (!env)
+        return;
+    const sourceType = modelPackage.source?.sourceType;
+    if (sourceType === "bundled" || sourceType === "app_managed") {
+        env.allowLocalModels = true;
+        env.allowRemoteModels = false;
+        if (localModelPath !== undefined) {
+            env.localModelPath = localModelPath;
+        }
+    }
+}
+function createGenerationOptions(input, signal) {
+    const generation = input.generation;
+    const generationOptions = {};
+    if (generation?.maxOutputTokens !== undefined) {
+        generationOptions.max_new_tokens = generation.maxOutputTokens;
+    }
+    if (generation?.temperature !== undefined) {
+        generationOptions.temperature = generation.temperature;
+        generationOptions.do_sample = generation.temperature > 0;
+    }
+    if (generation?.topP !== undefined) {
+        generationOptions.top_p = generation.topP;
+    }
+    if (generation?.stop !== undefined && generation.stop.length > 0) {
+        generationOptions.stop_strings = generation.stop;
+    }
+    if (signal !== undefined) {
+        generationOptions.signal = signal;
+    }
+    return generationOptions;
+}
+function extractGeneratedText(raw) {
+    const first = Array.isArray(raw) ? raw[0] : raw;
+    if (!isRecord(first)) {
+        return typeof first === "string" ? first : undefined;
+    }
+    const generated = first.generated_text;
+    if (typeof generated === "string") {
+        return generated;
+    }
+    if (Array.isArray(generated)) {
+        const last = generated[generated.length - 1];
+        if (isRecord(last) && typeof last.content === "string") {
+            return last.content;
+        }
+    }
+    return undefined;
+}
+/**
+ * Detects out-of-memory failures surfaced by ONNX Runtime session creation, which arrive as
+ * allocation errors from the WASM/native layer rather than as typed errors.
+ */
+function isResourceExhaustion(error) {
+    const message = getErrorMessage(error).toLowerCase();
+    return (message.includes("bad_alloc") ||
+        message.includes("out of memory") ||
+        message.includes("failed to allocate") ||
+        message.includes("allocation failed"));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/onnx.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Provider-specific entry point for the Web member of the ONNX Runtime provider family.
+ *
+ * Kept out of the unified SDK index (`@independo/inderun-web`) so the top-level
+ * surface stays provider-agnostic. Import from `@independo/inderun-web/onnx`
+ * when registering the adapter manually or when implementing a custom
+ * `OnnxTextGenerationRuntime`; most browser apps should pass `onnx` to
+ * `createIndeRunWeb` from the main entry point instead.
+ */
+export { OnnxRuntimeWebProvider, DEFAULT_ONNX_WEB_PROVIDER_ID, SUPPORTED_WEB_MODEL_SOURCE_TYPES, type OnnxProviderOptions } from "./onnx-provider.js";
+export { OnnxRuntimeError, createFixtureOnnxRuntime, type FixtureOnnxRuntimeOptions, type OnnxGenerationInput, type OnnxGenerationMessage, type OnnxGenerationOutput, type OnnxRuntimeAvailability, type OnnxRuntimeErrorKind, type OnnxTextGenerationRuntime } from "./onnx-runtime.js";
+export { createTransformersJsRuntime, type TransformersJsRuntimeOptions, type TransformersModule, type TransformersTextGenerator } from "./onnx-transformers-runtime.js";
+//# sourceMappingURL=onnx.d.ts.map

package/dist/onnx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnx.d.ts","sourceRoot":"","sources":["../src/onnx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,gCAAgC,EAChC,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,2BAA2B,EAC3B,KAAK,4BAA4B,EACjC,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC/B,MAAM,gCAAgC,CAAC"}

package/dist/onnx.js

@@ -0,0 +1,12 @@
+/**
+ * Provider-specific entry point for the Web member of the ONNX Runtime provider family.
+ *
+ * Kept out of the unified SDK index (`@independo/inderun-web`) so the top-level
+ * surface stays provider-agnostic. Import from `@independo/inderun-web/onnx`
+ * when registering the adapter manually or when implementing a custom
+ * `OnnxTextGenerationRuntime`; most browser apps should pass `onnx` to
+ * `createIndeRunWeb` from the main entry point instead.
+ */
+export { OnnxRuntimeWebProvider, DEFAULT_ONNX_WEB_PROVIDER_ID, SUPPORTED_WEB_MODEL_SOURCE_TYPES } from "./onnx-provider.js";
+export { OnnxRuntimeError, createFixtureOnnxRuntime } from "./onnx-runtime.js";
+export { createTransformersJsRuntime } from "./onnx-transformers-runtime.js";

package/dist/route-planner.d.ts

@@ -12,11 +12,28 @@ export interface SharedPlannerModule {
     planRouteJson: (inputJson: string) => string | Promise<string>;
 }
 /**
- * Strategy that turns planner input into a deterministic route plan, or `null`
- * when the planner is unavailable (callers then fall back to local selection).
+ * Coarse, privacy-safe reason the WASM planner produced no route plan. Used
+ * only for observability (telemetry/logging) — callers still fall back to
+ * local selection regardless of which reason fired.
+ */
+export type WasmUnavailableReason = "import_failed" | "invalid_module_shape" | "init_failed" | "plan_failed";
+/**
+ * Result of a {@link RoutePlanner} attempt. `routePlan` is `null` when the
+ * planner could not produce a plan, in which case `source` is `"unavailable"`
+ * and `unavailableReason` narrows down why, so callers can log/emit telemetry
+ * instead of silently swapping planners.
+ */
+export interface PlannerOutcome {
+    routePlan: SharedPlannerRoutePlan | null;
+    source: "wasm" | "unavailable";
+    unavailableReason?: WasmUnavailableReason;
+}
+/**
+ * Strategy that turns planner input into a deterministic route plan, or an
+ * "unavailable" outcome (callers then fall back to local selection).
  */
 export interface RoutePlanner {
-    planRoute(input: SharedPlannerInput): Promise<SharedPlannerRoutePlan | null>;
+    planRoute(input: SharedPlannerInput): Promise<PlannerOutcome>;
 }
 /**
  * A provider paired with the descriptor/capability projection the shared route
@@ -29,16 +46,22 @@ export interface ProviderRuntimeSnapshot {
 }
 /**
  * {@link RoutePlanner} backed by the Rust route core compiled to WASM. The
- * module is imported lazily and memoized; if it cannot be loaded, `planRoute`
- * resolves to `null` so the engine can fall back to local selection.
+ * module specifier is a static literal (not configurable) so bundlers such as
+ * Vite/webpack/Rollup can statically resolve and chunk it — a variable
+ * specifier defeats bundler analysis and silently never loads in the browser
+ * (see issue #109). The module is imported lazily and memoized; if it cannot
+ * be loaded, `planRoute` resolves an "unavailable" outcome so the engine can
+ * fall back to local selection, and logs once via `console.warn` so the
+ * degradation is never fully silent.
  */
 export declare class WasmRoutePlanner implements RoutePlanner {
-    private readonly moduleSpecifier;
     private modulePromise?;
-    constructor(moduleSpecifier?: string);
-    planRoute(input: SharedPlannerInput): Promise<SharedPlannerRoutePlan | null>;
+    private loadFailureReason?;
+    private hasWarned;
+    planRoute(input: SharedPlannerInput): Promise<PlannerOutcome>;
     private loadModule;
     private importModule;
+    private warnOnce;
 }
 /**
  * Describes each provider and evaluates its dynamic capabilities against the

package/dist/route-planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-planner.d.ts","sourceRoot":"","sources":["../src/route-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,sBAAsB,EACnC,iBAAiB,IAAI,kBAAkB,EACvC,WAAW,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChE;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;CAC9E;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAClE,YAAY,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;CACvE;AAID;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IAGvC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAF5C,OAAO,CAAC,aAAa,CAAC,CAAsC;gBAE/B,eAAe,GAAE,MAA+B;IAEvE,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;YAWpE,UAAU;YAOV,YAAY;CAiB3B;AAED;;;GAGG;AACH,wBAAsB,+BAA+B,CACnD,iBAAiB,EAAE,eAAe,EAAE,EACpC,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAepC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,uBAAuB,EAAE,EACpC,aAAa,EAAE,OAAO,GACrB,kBAAkB,CAsBpB"}
+{"version":3,"file":"route-planner.d.ts","sourceRoot":"","sources":["../src/route-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,sBAAsB,EACnC,iBAAiB,IAAI,kBAAkB,EACvC,WAAW,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC/B,eAAe,GAAG,sBAAsB,GAAG,aAAa,GAAG,aAAa,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACzC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC;IAC/B,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAClE,YAAY,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;CACvE;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,aAAa,CAAC,CAAsC;IAC5D,OAAO,CAAC,iBAAiB,CAAC,CAAwB;IAClD,OAAO,CAAC,SAAS,CAAS;IAEpB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;YAkBrD,UAAU;YAOV,YAAY;IA6B1B,OAAO,CAAC,QAAQ;CAUjB;AAED;;;GAGG;AACH,wBAAsB,+BAA+B,CACnD,iBAAiB,EAAE,eAAe,EAAE,EACpC,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAepC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,uBAAuB,EAAE,EACpC,aAAa,EAAE,OAAO,GACrB,kBAAkB,CAsBpB"}

package/dist/route-planner.js

@@ -1,23 +1,33 @@
-const DEFAULT_WASM_SPECIFIER = "@independo/inderun-route-core-wasm";
 /**
  * {@link RoutePlanner} backed by the Rust route core compiled to WASM. The
- * module is imported lazily and memoized; if it cannot be loaded, `planRoute`
- * resolves to `null` so the engine can fall back to local selection.
+ * module specifier is a static literal (not configurable) so bundlers such as
+ * Vite/webpack/Rollup can statically resolve and chunk it — a variable
+ * specifier defeats bundler analysis and silently never loads in the browser
+ * (see issue #109). The module is imported lazily and memoized; if it cannot
+ * be loaded, `planRoute` resolves an "unavailable" outcome so the engine can
+ * fall back to local selection, and logs once via `console.warn` so the
+ * degradation is never fully silent.
  */
 export class WasmRoutePlanner {
-    moduleSpecifier;
     modulePromise;
-    constructor(moduleSpecifier = DEFAULT_WASM_SPECIFIER) {
-        this.moduleSpecifier = moduleSpecifier;
-    }
+    loadFailureReason;
+    hasWarned = false;
     async planRoute(input) {
         const module = await this.loadModule();
         if (!module) {
-            return null;
+            const unavailableReason = this.loadFailureReason ?? "import_failed";
+            this.warnOnce(unavailableReason);
+            return { routePlan: null, source: "unavailable", unavailableReason };
+        }
+        try {
+            const json = JSON.stringify(input);
+            const result = await module.planRouteJson(json);
+            return { routePlan: JSON.parse(result), source: "wasm" };
+        }
+        catch (error) {
+            this.warnOnce("plan_failed", error);
+            return { routePlan: null, source: "unavailable", unavailableReason: "plan_failed" };
         }
-        const json = JSON.stringify(input);
-        const result = await module.planRouteJson(json);
-        return JSON.parse(result);
     }
     async loadModule() {
         if (!this.modulePromise) {
@@ -26,19 +36,38 @@ export class WasmRoutePlanner {
         return this.modulePromise;
     }
     async importModule() {
+        let mod;
         try {
-            const mod = (await import(/* @vite-ignore */ this.moduleSpecifier));
-            if (mod.initSharedCore) {
+            mod = (await import("@independo/inderun-route-core-wasm"));
+        }
+        catch (error) {
+            this.loadFailureReason = "import_failed";
+            this.warnOnce("import_failed", error);
+            return null;
+        }
+        if (typeof mod.planRouteJson !== "function") {
+            this.loadFailureReason = "invalid_module_shape";
+            this.warnOnce("invalid_module_shape");
+            return null;
+        }
+        if (mod.initSharedCore) {
+            try {
                 await mod.initSharedCore();
             }
-            if (typeof mod.planRouteJson !== "function") {
+            catch (error) {
+                this.loadFailureReason = "init_failed";
+                this.warnOnce("init_failed", error);
                 return null;
             }
-            return mod;
         }
-        catch {
-            return null;
+        return mod;
+    }
+    warnOnce(reason, error) {
+        if (this.hasWarned) {
+            return;
         }
+        this.hasWarned = true;
+        console.warn(`[IndeRun] WASM route planner unavailable (${reason}); falling back to local route selection.`, error);
     }
 }
 /**

package/dist/router.d.ts

@@ -2,7 +2,7 @@ import type { TaskRequest } from "@independo/inderun-contracts";
 import type { HostServices } from "./host.js";
 import type { ProviderAdapter } from "./provider.js";
 import type { ProviderRegistry } from "./registry.js";
-import { type RoutePlanner, type SharedPlannerRoutePlan } from "./route-planner.js";
+import { type RoutePlanner, type SharedPlannerRoutePlan, type WasmUnavailableReason } from "./route-planner.js";
 /**
  * Output structure from the Router containing the chosen provider and a route selection description.
  */
@@ -23,6 +23,16 @@ export interface RouteSelection {
      * Explanation detailing the selection decision. Useful for debugging and telemetry.
      */
     explanation: string;
+    /**
+     * Which planner produced `routePlan`: the shared Rust/WASM core, or the
+     * local TypeScript fallback used when the WASM planner is unavailable.
+     */
+    plannerSource: "wasm" | "fallback";
+    /**
+     * Set when `plannerSource` is `"fallback"` because the WASM planner failed;
+     * `undefined` when the fallback was not caused by a planner failure.
+     */
+    plannerUnavailableReason?: WasmUnavailableReason;
 }
 /**
  * Routing engine module. Filters registered providers against task types, request constraints,

package/dist/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD,OAAO,EAIL,KAAK,YAAY,EAEjB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;gBADP,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,YAAqC;IAGxD;;;;;;;;;OASG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAc5F,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,2BAA2B;IAuBnC,OAAO,CAAC,kBAAkB;IAuF1B,OAAO,CAAC,2BAA2B;IAiCnC,OAAO,CAAC,gBAAgB;CAYzB"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD,OAAO,EAIL,KAAK,YAAY,EAEjB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,EAAE,MAAM,GAAG,UAAU,CAAC;IACnC;;;OAGG;IACH,wBAAwB,CAAC,EAAE,qBAAqB,CAAC;CAClD;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;gBADP,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,YAAqC;IAGxD;;;;;;;;;OASG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAc5F,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,2BAA2B;IA2BnC,OAAO,CAAC,kBAAkB;IA0F1B,OAAO,CAAC,2BAA2B;IAiCnC,OAAO,CAAC,gBAAgB;CAYzB"}

package/dist/router.js

@@ -26,26 +26,26 @@ export class Router {
         const online = await hostServices.connectivity.isOnline();
         const snapshots = await collectProviderRuntimeSnapshots(this.registry.list(), hostServices);
         const planInput = buildSharedPlannerInput(request, snapshots, online);
-        const routePlan = await this.planner.planRoute(planInput);
-        if (routePlan) {
-            return this.selectFromSharedPlan(snapshots, routePlan);
+        const outcome = await this.planner.planRoute(planInput);
+        if (outcome.routePlan) {
+            return this.selectFromSharedPlan(snapshots, outcome.routePlan);
         }
-        return this.selectFallbackRoute(request, snapshots, online);
+        return this.selectFallbackRoute(request, snapshots, online, outcome.unavailableReason);
     }
     selectFromSharedPlan(snapshots, routePlan) {
         if (!routePlan.selectedProviderId) {
             throw this.routePlanFailure(routePlan);
         }
-        return this.buildSelectionFromRoutePlan(snapshots, routePlan);
+        return this.buildSelectionFromRoutePlan(snapshots, routePlan, "wasm");
     }
-    selectFallbackRoute(request, snapshots, online) {
+    selectFallbackRoute(request, snapshots, online, plannerUnavailableReason) {
         const plan = this.createFallbackPlan(request, snapshots, online);
         if (!plan.selectedProviderId) {
             throw this.routePlanFailure(plan);
         }
-        return this.buildSelectionFromRoutePlan(snapshots, plan);
+        return this.buildSelectionFromRoutePlan(snapshots, plan, "fallback", plannerUnavailableReason);
     }
-    buildSelectionFromRoutePlan(snapshots, routePlan) {
+    buildSelectionFromRoutePlan(snapshots, routePlan, plannerSource, plannerUnavailableReason) {
         const orderedProviders = routePlan.candidates
             .map((candidate) => snapshots.find((snapshot) => snapshot.descriptor.id === candidate.providerId))
             .filter((snapshot) => snapshot !== undefined);
@@ -57,7 +57,9 @@ export class Router {
             provider: selected.provider,
             fallbackProviders: orderedProviders.slice(1).map((snapshot) => snapshot.provider),
             routePlan,
-            explanation: routePlan.explanation.summary
+            explanation: routePlan.explanation.summary,
+            plannerSource,
+            ...(plannerUnavailableReason ? { plannerUnavailableReason } : {})
         };
     }
     createFallbackPlan(request, snapshots, online) {
@@ -67,17 +69,24 @@ export class Router {
             .filter((candidate) => candidate.descriptor.supports.run);
         const localCandidates = eligible.filter((candidate) => candidate.descriptor.type !== "cloud");
         const cloudCandidates = eligible.filter((candidate) => candidate.descriptor.type === "cloud");
-        const selected = eligible.find((candidate) => {
+        // Constraint filtering must apply to the whole candidate list, not just the selected provider:
+        // the remainder becomes the engine's fallback chain, and a fallback that violates the request
+        // constraints would let a `local_required` run be retried against a cloud provider.
+        const admissible = eligible.filter((candidate) => {
             const descriptor = candidate.descriptor;
             const constraints = planInput.constraints;
-            const privacy = descriptor.privacy?.dataLeavesDevice ?? descriptor.type !== "cloud";
+            // Mirrors `is_data_private` in the shared Rust planner: a provider is private when it
+            // declares that data does not leave the device, defaulting to non-cloud providers.
+            const isDataPrivate = descriptor.privacy
+                ? !descriptor.privacy.dataLeavesDevice
+                : descriptor.type !== "cloud";
             if (constraints.cloud === "forbidden" && descriptor.type === "cloud") {
                 return false;
             }
             if (constraints.cloud === "required" && descriptor.type !== "cloud") {
                 return false;
             }
-            if (constraints.privacy === "local_required" && !privacy) {
+            if (constraints.privacy === "local_required" && !isDataPrivate) {
                 return false;
             }
             if (constraints.privacy === "cloud_required" && descriptor.type !== "cloud") {
@@ -88,10 +97,7 @@ export class Router {
             }
             return candidate.capabilities.available;
         });
-        const ordered = selected
-            ? [selected, ...eligible.filter((candidate) => candidate !== selected)]
-            : [];
-        if (ordered.length === 0) {
+        if (admissible.length === 0) {
             const failureSummary = this.buildFallbackFailureSummary({
                 online,
                 constraints: planInput.constraints,
@@ -114,17 +120,17 @@ export class Router {
                 }
             };
         }
-        const selectedProviderId = ordered[0]?.descriptor.id;
+        const selectedProviderId = admissible[0]?.descriptor.id;
         return {
             selectedProviderId,
-            fallbackProviderIds: ordered.slice(1).map((candidate) => candidate.descriptor.id),
-            candidates: ordered.map((candidate, index) => ({
+            fallbackProviderIds: admissible.slice(1).map((candidate) => candidate.descriptor.id),
+            candidates: admissible.map((candidate, index) => ({
                 providerId: candidate.descriptor.id,
                 order: index
             })),
             rejectedProviders: [],
             explanation: {
-                summary: `Selected provider '${selectedProviderId}' deterministically from ${ordered.length} eligible candidate(s).`,
+                summary: `Selected provider '${selectedProviderId}' deterministically from ${admissible.length} eligible candidate(s).`,
                 selectedProviderId
             }
         };