@independo/inderun-web 0.3.3 → 0.4.0-rc.2

package/README.md

@@ -10,31 +10,58 @@ TypeScript/Web SDK for IndeRun.
 
 This package provides the Web SDK entrypoint, the engine core, routing, telemetry, error normalization, the OpenAI-compatible cloud provider, the Web ONNX Runtime provider for developer-supplied local models, and the Web system-model provider for browser-managed on-device models.
 
-The contract types this SDK's own signatures take and return — `TaskRequest`, `TaskResult`, `StreamEvent`, `StreamRunHandle`, `StreamTerminalOutcome`, `IndeRunError`, the host-service and telemetry interfaces, and (from the `/onnx` subpath) `ModelPackage` — are re-exported here, so a fully typed app does not need to depend on `@independo/inderun-contracts` separately. Import that package directly only if you want the JSON Schemas or the `get*ValidationIssues` validators.
+The contract types this SDK's own signatures take and return — `TaskRequest`, `TaskResult`, `StreamEvent`, `StreamRunHandle`, `StreamTerminalOutcome`, `IndeRunError`, `ExecutionProvenance`, the telemetry interfaces, the host-service interfaces (from `/provider`), and (from the `/onnx` subpath) `ModelPackage` — are re-exported here, so a fully typed app does not need to depend on `@independo/inderun-contracts` separately. Import that package directly only if you want the JSON Schemas or the `get*ValidationIssues` validators.
+
+## Entry points
+
+| Import | For | Contains |
+| --- | --- | --- |
+| `@independo/inderun-web` | Applications | `generateText` / `streamText`, `createIndeRunWeb`, the advanced task API (`IndeRun`, `run()` / `stream()` / `checkCapabilities()`), model profiles, contract types, `IndeRunException`, telemetry |
+| `@independo/inderun-web/provider` | Provider authors and host integrators | `ProviderAdapter` and the descriptor/capability types, `ProviderRegistry`, `HostServices` and the browser host services, the `create*` error constructors |
+| `@independo/inderun-web/openai`, `/onnx`, `/system-model` | Registering a provider by hand | One provider adapter each |
+
+The router, the route planner bindings and the Event Gate are engine internals and are not exported. Moving from 0.3?
+See the [migration guide](https://github.com/independo-gmbh/inderun/blob/main/docs/migration.md).
 
 ## Basic Usage
 
 ```ts
-import { createIndeRunWeb } from "@independo/inderun-web";
+import { createIndeRunWeb, generateText, streamText } from "@independo/inderun-web";
 
 const inderun = createIndeRunWeb({
   openAI: {
-    model: "gpt-5.2",
+    models: ["gpt-5.2"],
     endpointUrl: "/api/inderun/openai-responses",
     auth: "none"
   }
 });
 
-const result = await inderun.run({
-  schemaVersion: "1.0",
-  task: { kind: "text_to_text" },
-  prompt: "Write a one-sentence summary of IndeRun."
+const { text, provenance } = await generateText(inderun, {
+  prompt: "Write a one-sentence summary of IndeRun.",
+  execution: { privacy: "local_preferred" }
 });
+
+const stream = await streamText(inderun, { system: "Use plain language.", prompt: "Explain routing." });
+for await (const delta of stream.textStream) process.stdout.write(delta);
+const { finishReason } = await stream.result;
 ```
 
+`generateText` and `streamText` take `prompt` or `messages`, an optional `system`, `model` (a
+[model profile](https://github.com/independo-gmbh/inderun/blob/main/docs/architecture/api-layering.md#model-profiles),
+default `"auto"`), the usual sampling options, and an `execution` policy that reuses the canonical
+constraint values. Each call compiles to one `TaskRequest` — `toTaskRequest(options)` shows which —
+and runs through the engine below, so errors, fallback, and cancellation match the advanced API.
+
+## Advanced: the task API
+
+Use `TaskRequest` with `run()` / `stream()` when you need the raw event sequence, build requests in code (for example
+with your own `requestId`), or check capabilities before offering an option —
+`await inderun.checkCapabilities()` reports every registered target's live availability. Both layers run through the
+same engine.
+
 ## Streaming
 
-`stream()` returns the run handle, its canonical `StreamEvent` sequence, and a `cancel()` hook:
+For the full event sequence, use the advanced API. `stream()` returns the run handle, its canonical `StreamEvent` sequence, and a `cancel()` hook:
 
 ```ts
 const { handle, events, cancel } = await inderun.stream({
@@ -66,6 +93,9 @@ accept `"stream": true` and emit `text/event-stream` with the Responses event ty
 response object. Unknown event types are ignored, so an endpoint that emits extra events is
 fine; one that emits a different vocabulary entirely is not.
 
+[OpenRouter](https://github.com/independo-gmbh/inderun/blob/main/docs/openrouter.md) is reached this way: point
+`endpointUrl` at its Responses endpoint (through a proxy in browser apps) and list `vendor/model` ids as `models`.
+
 ## Security Model
 
 Browser apps should use a proxy endpoint and keep provider credentials server-side. `createIndeRunWeb` rejects direct calls to the public OpenAI Responses endpoint unless `allowDirectOpenAIEndpoint: true` is set for a controlled environment.
@@ -78,10 +108,17 @@ distributed client code — put it behind a trusted backend proxy and point `end
 ## Advanced: registering the OpenAI provider directly
 
 `createIndeRunWeb` wires the OpenAI Responses provider for you. To register it
-manually (e.g. alongside other providers), import it from the provider subpath:
+manually (e.g. alongside other providers), import it from the provider subpath and build the engine from
+the `/provider` entry point:
 
 ```ts
+import { IndeRun } from "@independo/inderun-web";
 import { OpenAIResponsesProvider } from "@independo/inderun-web/openai";
+import { ProviderRegistry, createBrowserHostServices } from "@independo/inderun-web/provider";
+
+const registry = new ProviderRegistry();
+registry.register(new OpenAIResponsesProvider({ model: "gpt-5.2", endpointUrl: "/api/inderun/openai-responses", auth: "none" }));
+const inderun = new IndeRun(registry, createBrowserHostServices());
 ```
 
 The provider normalizes OpenAI transport and API failures into the IndeRun error

package/dist/core/engine.d.ts

@@ -4,12 +4,28 @@ import type { ProviderCapabilitySnapshot, StreamRun } from "./provider.js";
 import type { IndeRunApi } from "./generated/inderun-api.js";
 import { ProviderRegistry } from "./registry.js";
 import { type TelemetryService } from "./telemetry.js";
+import { type ModelProfiles } from "./model-profiles.js";
 /**
  * @deprecated Renamed to `StreamRun`, which is the name the generated
  * `IndeRunApi` surface and the Swift/Kotlin SDKs use. Kept as an alias so the
  * rename is not a breaking change.
  */
 export type StreamHandleResult = StreamRun;
+/**
+ * Optional engine configuration.
+ */
+export interface IndeRunOptions {
+    /**
+     * Telemetry listener. Defaults to the host's telemetry service, then to a no-op.
+     */
+    telemetryService?: TelemetryService;
+    /**
+     * Named model profiles requests can route within (`TaskRequest.modelProfile`).
+     * Each maps a profile name to an ordered list of target (provider instance) ids.
+     * `"auto"` is built in and cannot be redefined. See `docs/architecture/api-layering.md`.
+     */
+    modelProfiles?: ModelProfiles;
+}
 /**
  * Main orchestrator SDK entrypoint class.
  * Validates tasks, executes routing rules based on request constraints and connectivity,
@@ -20,13 +36,21 @@ export declare class IndeRun implements IndeRunApi {
     private hostServices;
     private router;
     private telemetryService;
+    private modelProfiles;
     /**
      * Initializes the IndeRun instance.
      * @param registry - Registry filled with active providers.
      * @param hostServices - Services wrapping OS interfaces and indicators.
-     * @param telemetryService - Optional custom telemetry service listener.
+     * @param options - Optional telemetry listener and model profiles.
+     * @throws {Error} If a model profile is malformed (see {@link validateModelProfiles}).
+     */
+    constructor(registry: ProviderRegistry, hostServices: HostServices, options?: IndeRunOptions);
+    /**
+     * Validates the request against the schema and resolves its model profile.
+     * Both failures are request validation errors: they are reported before any
+     * provider is probed, with the offending fields in `details.validationIssues`.
      */
-    constructor(registry: ProviderRegistry, hostServices: HostServices, telemetryService?: TelemetryService);
+    private validateRequest;
     /**
      * Current time from the host clock, falling back to wall-clock time when the
      * host does not supply one.

package/dist/core/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAmB,0BAA0B,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAQjD,OAAO,EAAuB,KAAK,gBAAgB,EAAwB,MAAM,gBAAgB,CAAC;AAGlG;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,OAAQ,YAAW,UAAU;IAWtC,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,YAAY;IAXtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAmB;IAE3C;;;;;OAKG;gBAEO,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,YAAY,EAClC,gBAAgB,CAAC,EAAE,gBAAgB;IAOrC;;;OAGG;IACH,OAAO,CAAC,GAAG;IAIX;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAShB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;OAOG;IACG,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAsHpD;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IA+PtD;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC;CASjE"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAmB,0BAA0B,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAQjD,OAAO,EAAuB,KAAK,gBAAgB,EAAwB,MAAM,gBAAgB,CAAC;AAElG,OAAO,EAEL,KAAK,aAAa,EAInB,MAAM,qBAAqB,CAAC;AAG7B;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;GAIG;AACH,qBAAa,OAAQ,YAAW,UAAU;IAatC,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,YAAY;IAbtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,aAAa,CAAgB;IAErC;;;;;;OAMG;gBAEO,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,YAAY,EAClC,OAAO,GAAE,cAAmB;IAS9B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;OAGG;IACH,OAAO,CAAC,GAAG;IAIX;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAwBxB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAShB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;OAOG;IACG,GAAG,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IA4HpD;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IAoRtD;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC;CASjE"}

package/dist/core/engine.js

@@ -4,6 +4,8 @@ import { Router } from "./router.js";
 import { createCapabilityMismatch, createInternal, createUnavailable, toIndeRunException } from "./errors.js";
 import { NoOpTelemetryService } from "./telemetry.js";
 import { EventGate } from "./event-gate.js";
+import { AUTO_MODEL_PROFILE, resolveModelProfile, validateModelProfiles } from "./model-profiles.js";
+import { ProvenanceRecorder } from "./provenance.js";
 /**
  * Main orchestrator SDK entrypoint class.
  * Validates tasks, executes routing rules based on request constraints and connectivity,
@@ -14,18 +16,44 @@ export class IndeRun {
     hostServices;
     router;
     telemetryService;
+    modelProfiles;
     /**
      * Initializes the IndeRun instance.
      * @param registry - Registry filled with active providers.
      * @param hostServices - Services wrapping OS interfaces and indicators.
-     * @param telemetryService - Optional custom telemetry service listener.
+     * @param options - Optional telemetry listener and model profiles.
+     * @throws {Error} If a model profile is malformed (see {@link validateModelProfiles}).
      */
-    constructor(registry, hostServices, telemetryService) {
+    constructor(registry, hostServices, options = {}) {
         this.registry = registry;
         this.hostServices = hostServices;
         this.router = new Router(this.registry);
         this.telemetryService =
-            telemetryService || this.hostServices.telemetry || new NoOpTelemetryService();
+            options.telemetryService || this.hostServices.telemetry || new NoOpTelemetryService();
+        this.modelProfiles = options.modelProfiles ?? {};
+        validateModelProfiles(this.modelProfiles);
+    }
+    /**
+     * Validates the request against the schema and resolves its model profile.
+     * Both failures are request validation errors: they are reported before any
+     * provider is probed, with the offending fields in `details.validationIssues`.
+     */
+    validateRequest(request, runId) {
+        const validationIssues = getTaskRequestValidationIssues(request);
+        if (validationIssues.length === 0) {
+            const resolved = resolveModelProfile(this.modelProfiles, request.modelProfile);
+            if (resolved.known) {
+                return resolved.profile;
+            }
+            validationIssues.push({
+                path: "/modelProfile",
+                message: `unknown model profile "${request.modelProfile}"; configure it in the engine's modelProfiles`
+            });
+        }
+        const message = `Validation failed for TaskRequest: ${validationIssues
+            .map((i) => `${i.path} - ${i.message}`)
+            .join("; ")}`;
+        throw createInternal(message, { runId, details: { validationIssues } });
     }
     /**
      * Current time from the host clock, falling back to wall-clock time when the
@@ -50,6 +78,7 @@ export class IndeRun {
                 rejectedProviders: routeSelection.routePlan.rejectedProviders,
                 fallbackAvailable: providerCount > 1,
                 taskKind: request.task.kind,
+                modelProfile: request.modelProfile ?? "auto",
                 constraints: request.constraints ?? null,
                 preferences: request.preferences ?? null,
                 explanation: routeSelection.explanation
@@ -103,21 +132,14 @@ export class IndeRun {
     async run(request) {
         const startTime = this.now();
         const runId = request.requestId || `run_${Math.random().toString(36).substring(2, 11)}`;
+        const provenance = new ProvenanceRecorder(request.modelProfile ?? AUTO_MODEL_PROFILE);
         try {
-            // 1. Validate request payload using schema contracts
-            const validationIssues = getTaskRequestValidationIssues(request);
-            if (validationIssues.length > 0) {
-                const message = `Validation failed for TaskRequest: ${validationIssues
-                    .map((i) => `${i.path} - ${i.message}`)
-                    .join("; ")}`;
-                throw createInternal(message, {
-                    runId,
-                    details: { validationIssues }
-                });
-            }
-            // 2. Select the route based on constraints and host capabilities
-            const routeSelection = await this.router.selectRoute(request, this.hostServices, "run");
+            // 1. Validate request payload using schema contracts and resolve its model profile
+            const modelProfile = this.validateRequest(request, runId);
+            // 2. Select the route based on constraints, model profile, and host capabilities
+            const routeSelection = await this.router.selectRoute(request, this.hostServices, "run", modelProfile);
             const providers = [routeSelection.provider, ...routeSelection.fallbackProviders];
+            provenance.routed(routeSelection.routePlan);
             this.emitRouteDecided(runId, request, routeSelection, providers.length);
             // 3. Execute the run task using the planned provider chain
             const attemptedProviderIds = [];
@@ -138,6 +160,8 @@ export class IndeRun {
                         providerUsed: providerId,
                         totalMs
                     };
+                    provenance.attempted(providerId, "succeeded");
+                    result.provenance = provenance.build(provider.describe(), result.telemetry.reportedModel);
                     this.safeEmit({
                         type: "attempt_succeeded",
                         runId,
@@ -152,7 +176,7 @@ export class IndeRun {
                     return result;
                 }
                 catch (err) {
-                    lastError = toIndeRunException(err, {
+                    const attemptError = toIndeRunException(err, {
                         providerId,
                         runId,
                         details: {
@@ -161,6 +185,8 @@ export class IndeRun {
                             routePlan: routeSelection.routePlan
                         }
                     });
+                    provenance.attempted(providerId, "failed", attemptError.errorClass);
+                    lastError = attemptError;
                 }
             }
             const endTime = this.now();
@@ -170,14 +196,14 @@ export class IndeRun {
                 details: {
                     totalMs,
                     attemptedProviderIds,
-                    fallbackOccurred: providers.length > 1,
+                    fallbackOccurred: attemptedProviderIds.length > 1,
                     routePlan: routeSelection.routePlan
                 }
             });
             throw exception;
         }
         catch (error) {
-            const exception = toIndeRunException(error, {
+            const normalized = toIndeRunException(error, {
                 runId,
                 details: {
                     totalMs: typeof error.details?.totalMs === "number"
@@ -185,6 +211,10 @@ export class IndeRun {
                         : this.now() - startTime
                 }
             });
+            // A routing refusal throws before any attempt; its rejections travel on the details.
+            provenance.routingFailed(normalized.details);
+            // No attempt produced the result, so the outcome is attributed to no provider.
+            const exception = normalized.withProvenance(provenance.build());
             const endTime = this.now();
             const totalMs = typeof exception.details?.totalMs === "number"
                 ? exception.details?.totalMs
@@ -225,24 +255,28 @@ export class IndeRun {
         const startTime = this.now();
         const now = () => this.now();
         const runId = request.requestId || `run_${Math.random().toString(36).substring(2, 11)}`;
-        const validationIssues = getTaskRequestValidationIssues(request);
-        if (validationIssues.length > 0) {
-            const message = `Validation failed for TaskRequest: ${validationIssues
-                .map((i) => `${i.path} - ${i.message}`)
-                .join("; ")}`;
-            throw createInternal(message, { runId, details: { validationIssues } });
+        const provenance = new ProvenanceRecorder(request.modelProfile ?? AUTO_MODEL_PROFILE);
+        let modelProfile;
+        try {
+            modelProfile = this.validateRequest(request, runId);
+        }
+        catch (error) {
+            throw toIndeRunException(error, { runId }).withProvenance(provenance.build());
         }
         // Route selection failures are the one class of stream error that surfaces as a
         // rejected promise instead of a terminal event, so they must still carry the
         // runId — there is no handle for the caller to correlate them with otherwise.
         let routeSelection;
         try {
-            routeSelection = await this.router.selectRoute(request, this.hostServices, "stream");
+            routeSelection = await this.router.selectRoute(request, this.hostServices, "stream", modelProfile);
         }
         catch (error) {
-            throw toIndeRunException(error, { runId });
+            const exception = toIndeRunException(error, { runId });
+            provenance.routingFailed(exception.details);
+            throw exception.withProvenance(provenance.build());
         }
         const providers = [routeSelection.provider, ...routeSelection.fallbackProviders];
+        provenance.routed(routeSelection.routePlan);
         this.emitRouteDecided(runId, request, routeSelection, providers.length);
         // Defensive only: streaming eligibility is decided by the route planner, which
         // throws with its own rejection reasons when nothing can stream. Reaching here
@@ -267,14 +301,18 @@ export class IndeRun {
         async function* run() {
             const attemptedProviderIds = [];
             let committed = false;
-            const cancelledOutcome = (partialText) => {
+            const cancelledOutcome = (partialText, cancelledProvider) => {
                 const reason = typeof controller.signal.reason === "string" ? controller.signal.reason : undefined;
+                if (cancelledProvider !== undefined) {
+                    provenance.attempted(cancelledProvider.describe().id, "cancelled");
+                }
                 return {
                     outcome: "cancelled",
                     runId,
                     schemaVersion: "1.0",
                     partialText,
-                    ...(reason !== undefined ? { reason } : {})
+                    ...(reason !== undefined ? { reason } : {}),
+                    provenance: provenance.build(cancelledProvider?.describe())
                 };
             };
             for (const [index, provider] of providers.entries()) {
@@ -325,6 +363,7 @@ export class IndeRun {
                             continue;
                         }
                         // ev.kind === "done"
+                        provenance.attempted(providerId, "succeeded");
                         const outcome = {
                             outcome: "completed",
                             runId,
@@ -332,7 +371,8 @@ export class IndeRun {
                             finalText: ev.finalText,
                             telemetry: { providerUsed: providerId, totalMs: now() - startTime },
                             ...(ev.finishReason !== undefined ? { finishReason: ev.finishReason } : {}),
-                            ...(ev.usage !== undefined ? { usage: ev.usage } : {})
+                            ...(ev.usage !== undefined ? { usage: ev.usage } : {}),
+                            provenance: provenance.build(provider.describe(), ev.reportedModel)
                         };
                         const terminal = gate.terminate(outcome, now());
                         safeEmit({
@@ -350,7 +390,7 @@ export class IndeRun {
                         return;
                     }
                     if (controller.signal.aborted) {
-                        const terminal = gate.terminate(cancelledOutcome(partialText), now());
+                        const terminal = gate.terminate(cancelledOutcome(partialText, provider), now());
                         safeEmit({
                             type: "stream_cancelled",
                             runId,
@@ -366,7 +406,7 @@ export class IndeRun {
                 }
                 catch (err) {
                     if (controller.signal.aborted) {
-                        const terminal = gate.terminate(cancelledOutcome(partialText), now());
+                        const terminal = gate.terminate(cancelledOutcome(partialText, provider), now());
                         safeEmit({
                             type: "stream_cancelled",
                             runId,
@@ -382,6 +422,7 @@ export class IndeRun {
                         runId,
                         details: { attemptedProviderIds }
                     });
+                    provenance.attempted(providerId, "failed", exception.errorClass);
                     if (!committed) {
                         safeEmit({
                             type: "stream_attempt_failed",
@@ -395,12 +436,14 @@ export class IndeRun {
                         });
                         continue;
                     }
+                    // Committed: the failure belongs to this provider, not to the chain.
                     const outcome = {
                         outcome: "error",
                         runId,
                         schemaVersion: "1.0",
                         error: exception.toContractError(),
-                        partialText
+                        partialText,
+                        provenance: provenance.build(provider.describe())
                     };
                     const terminal = gate.terminate(outcome, now());
                     safeEmit({
@@ -441,7 +484,8 @@ export class IndeRun {
                 runId,
                 schemaVersion: "1.0",
                 error: exception.toContractError(),
-                partialText: ""
+                partialText: "",
+                provenance: provenance.build()
             };
             const terminal = gate.terminate(outcome, now());
             safeEmit({

package/dist/core/errors.d.ts

@@ -1,4 +1,4 @@
-import type { IndeRunError, IndeRunErrorClass } from "@independo/inderun-contracts";
+import type { ExecutionProvenance, IndeRunError, IndeRunErrorClass } from "@independo/inderun-contracts";
 /**
  * Parameter structure required to initialize an IndeRunException.
  */
@@ -31,6 +31,10 @@ export interface IndeRunExceptionParams {
      * Rich contextual metadata regarding the error.
      */
     details?: Record<string, unknown>;
+    /**
+     * How the failed execution played out, attached by the engine.
+     */
+    provenance?: ExecutionProvenance;
 }
 /**
  * Standardized framework exception thrown when route selection or provider execution fails.
@@ -51,11 +55,19 @@ export declare class IndeRunException extends Error {
     readonly retryAfterMs?: number;
     /** Custom details and metadata context. */
     readonly details?: Record<string, unknown>;
+    /** How the failed execution played out: attempts, rejections, the provider committed to. */
+    readonly provenance?: ExecutionProvenance;
     constructor(params: IndeRunExceptionParams);
     /**
      * Converts the exception into a JSON-compatible contract-compliant IndeRunError.
      */
     toContractError(): IndeRunError;
+    /**
+     * A copy of this exception carrying `provenance`. The engine attaches provenance once it
+     * knows how the whole execution ended, replacing anything set earlier.
+     */
+    withProvenance(provenance: ExecutionProvenance): IndeRunException;
+    private params;
 }
 /**
  * Factory helper for CapabilityMismatch error class.

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,UAAU,EAAE,iBAAiB,CAAC;IAC9B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,qDAAqD;IACrD,QAAQ,CAAC,aAAa,SAAS;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,mCAAmC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE/B,MAAM,EAAE,sBAAsB;IAa1C;;OAEG;IACH,eAAe,IAAI,YAAY;CAahC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,YAAY,GAAG,SAAS,CAAC,GAC7D,gBAAgB,CAElB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,YAAY,GAAG,SAAS,CAAC,GAC7D,gBAAgB,CAElB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,YAAY,GAAG,SAAS,CAAC,GAC7D,gBAAgB,CAElB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,YAAY,GAAG,SAAS,CAAC,GAC7D,gBAAgB,CAElB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,YAAY,GAAG,SAAS,CAAC,GAC7D,gBAAgB,CAElB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,YAAY,GAAG,SAAS,CAAC,GAC7D,gBAAgB,CAElB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,YAAY,GAAG,SAAS,CAAC,GAC7D,gBAAgB,CAElB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,cAAc,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,CAAC,GAChE,gBAAgB,CAuDlB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.js

@@ -17,6 +17,8 @@ export class IndeRunException extends Error {
     retryAfterMs;
     /** Custom details and metadata context. */
     details;
+    /** How the failed execution played out: attempts, rejections, the provider committed to. */
+    provenance;
     constructor(params) {
         super(params.message);
         this.name = "IndeRunException";
@@ -31,6 +33,8 @@ export class IndeRunException extends Error {
             this.retryAfterMs = params.retryAfterMs;
         if (params.details !== undefined)
             this.details = params.details;
+        if (params.provenance !== undefined)
+            this.provenance = params.provenance;
         Object.setPrototypeOf(this, IndeRunException.prototype);
     }
     /**
@@ -52,8 +56,33 @@ export class IndeRunException extends Error {
             err.retryAfterMs = this.retryAfterMs;
         if (this.details !== undefined)
             err.details = this.details;
+        if (this.provenance !== undefined)
+            err.provenance = this.provenance;
         return err;
     }
+    /**
+     * A copy of this exception carrying `provenance`. The engine attaches provenance once it
+     * knows how the whole execution ended, replacing anything set earlier.
+     */
+    withProvenance(provenance) {
+        return new IndeRunException({ ...this.params(), provenance });
+    }
+    params() {
+        const params = { errorClass: this.errorClass, message: this.message };
+        if (this.runId !== undefined)
+            params.runId = this.runId;
+        if (this.providerId !== undefined)
+            params.providerId = this.providerId;
+        if (this.retryable !== undefined)
+            params.retryable = this.retryable;
+        if (this.retryAfterMs !== undefined)
+            params.retryAfterMs = this.retryAfterMs;
+        if (this.details !== undefined)
+            params.details = this.details;
+        if (this.provenance !== undefined)
+            params.provenance = this.provenance;
+        return params;
+    }
 }
 /**
  * Factory helper for CapabilityMismatch error class.
@@ -126,6 +155,9 @@ export function toIndeRunException(error, fallbackParams) {
                     ...(fallbackParams.details || {})
                 };
             }
+            const provenance = error.provenance ?? fallbackParams.provenance;
+            if (provenance !== undefined)
+                mergedParams.provenance = provenance;
             return new IndeRunException(mergedParams);
         }
         return error;

package/dist/core/model-profiles.d.ts

@@ -0,0 +1,34 @@
+import type { SharedPlannerInput } from "./route-planner.js";
+/**
+ * The built-in profile: every registered target, ranked by constraints and
+ * preferences alone. Requests that name no profile route within it.
+ */
+export declare const AUTO_MODEL_PROFILE = "auto";
+/**
+ * Application-defined model profiles: a profile name mapped to an ordered list of
+ * target ids (provider instance ids, each bound to one model). Requests name a
+ * profile through `TaskRequest.modelProfile`; the route planner treats the list as
+ * an allow-list and ranks its entries after placement and before preferences.
+ * Ids that name no registered provider are ignored by the planner.
+ */
+export type ModelProfiles = Readonly<Record<string, readonly string[]>>;
+/** A resolved profile as the shared planner consumes it; absent means `auto`. */
+export type ResolvedModelProfile = SharedPlannerInput["modelProfile"];
+/**
+ * Checks profile configuration once, when the engine is constructed, so a
+ * malformed profile is a setup error rather than a per-request surprise.
+ * @throws {Error} When a profile is named `auto`, is empty, or lists a target twice.
+ */
+export declare function validateModelProfiles(profiles: ModelProfiles): void;
+/**
+ * Resolves a request's profile name against the configured profiles.
+ * @returns `{ known: true }` with the planner input (undefined for `auto`), or
+ *   `{ known: false }` when the name matches no configured profile.
+ */
+export declare function resolveModelProfile(profiles: ModelProfiles, name: string | undefined): {
+    known: true;
+    profile: ResolvedModelProfile;
+} | {
+    known: false;
+};
+//# sourceMappingURL=model-profiles.d.ts.map

package/dist/core/model-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-profiles.d.ts","sourceRoot":"","sources":["../../src/core/model-profiles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAExE,iFAAiF;AACjF,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAwBnE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAUnE"}

package/dist/core/model-profiles.js

@@ -0,0 +1,49 @@
+/**
+ * The built-in profile: every registered target, ranked by constraints and
+ * preferences alone. Requests that name no profile route within it.
+ */
+export const AUTO_MODEL_PROFILE = "auto";
+/**
+ * Checks profile configuration once, when the engine is constructed, so a
+ * malformed profile is a setup error rather than a per-request surprise.
+ * @throws {Error} When a profile is named `auto`, is empty, or lists a target twice.
+ */
+export function validateModelProfiles(profiles) {
+    for (const [name, targetIds] of Object.entries(profiles)) {
+        if (name.length === 0) {
+            throw new Error("Model profile names must be non-empty.");
+        }
+        if (name === AUTO_MODEL_PROFILE) {
+            throw new Error(`"${AUTO_MODEL_PROFILE}" is the built-in model profile and cannot be redefined.`);
+        }
+        if (targetIds.length === 0) {
+            throw new Error(`Model profile "${name}" must list at least one target id.`);
+        }
+        const seen = new Set();
+        for (const id of targetIds) {
+            if (id.length === 0) {
+                throw new Error(`Model profile "${name}" lists an empty target id.`);
+            }
+            if (seen.has(id)) {
+                throw new Error(`Model profile "${name}" lists target "${id}" more than once.`);
+            }
+            seen.add(id);
+        }
+    }
+}
+/**
+ * Resolves a request's profile name against the configured profiles.
+ * @returns `{ known: true }` with the planner input (undefined for `auto`), or
+ *   `{ known: false }` when the name matches no configured profile.
+ */
+export function resolveModelProfile(profiles, name) {
+    if (name === undefined || name === AUTO_MODEL_PROFILE) {
+        return { known: true, profile: undefined };
+    }
+    if (!Object.hasOwn(profiles, name)) {
+        return { known: false };
+    }
+    // validateModelProfiles guarantees every configured profile is non-empty.
+    const [first, ...rest] = profiles[name];
+    return { known: true, profile: { name, targetIds: [first, ...rest] } };
+}