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

package/dist/generated/task-result.d.ts

@@ -19,6 +19,12 @@ export type TaskResult = {
      * The normalized content returned from the selected provider.
      */
     output: Output;
+    /**
+     * Normalized execution provenance: which target ran, its declared locality, the configured
+     * and reported model, and how fallback and routing played out. See
+     * execution-provenance.schema.json.
+     */
+    provenance?: ExecutionProvenance;
     /**
      * A unique, opaque identifier assigned by the engine for this specific execution attempt.
      */
@@ -59,6 +65,108 @@ export type Output = {
     type: "text";
     [property: string]: unknown;
 };
+/**
+ * Normalized execution provenance: which target ran, its declared locality, the configured
+ * and reported model, and how fallback and routing played out. See
+ * execution-provenance.schema.json.
+ *
+ * Provider-neutral record of how an execution was carried out: the target the outcome is
+ * attributed to, its declared locality, the configured and provider-reported model, every
+ * attempt, and why other candidates were rejected. Carried on TaskResult, on every
+ * StreamTerminalOutcome branch, and on IndeRunError. It reports what the engine observed
+ * and what providers declared or reported; it never infers a model or locality a provider
+ * did not state, and it never contains request content, credentials, or provider payloads.
+ */
+export type ExecutionProvenance = {
+    /**
+     * How many providers were attempted. 0 when the request failed validation or routing, or
+     * was cancelled before any attempt started.
+     */
+    attemptCount: number;
+    /**
+     * Every attempted provider, in attempt order, with how its attempt ended.
+     */
+    attempts: ExecutionProvenanceAttempt[];
+    /**
+     * The model providerId is bound to, as its descriptor declares it. Absent when the provider
+     * cannot name its model or no provider is attributed.
+     */
+    configuredModel?: string;
+    /**
+     * Whether more than one provider was attempted (attemptCount > 1).
+     */
+    fallbackOccurred: boolean;
+    /**
+     * Where providerId declares it executes: 'on_device' for a local provider, 'edge', or
+     * 'cloud'. A declaration by the provider's descriptor, not a measurement. 'unknown' when
+     * providerId is absent.
+     */
+    locality: Locality;
+    /**
+     * The model profile the request routed within; 'auto' when the request named none.
+     */
+    modelProfile: string;
+    /**
+     * The target the outcome is attributed to: the provider that produced the result, the
+     * provider a stream had committed to when it ended, or the provider that was running when
+     * it was cancelled. Absent when no provider was reached or when every attempted provider
+     * failed before one was committed to.
+     */
+    providerId?: string;
+    /**
+     * The model identifier the provider reported in its own response. Absent means the provider
+     * did not report one; it is never inferred from configuration.
+     */
+    reportedModel?: string;
+    /**
+     * Providers the route planner rejected before any attempt, with the normalized RoutePlan
+     * reason codes. Codes only: no provider-supplied messages.
+     */
+    routeRejections: ExecutionProvenanceRouteRejection[];
+    /**
+     * Contract schema version used to interpret this provenance record.
+     */
+    schemaVersion: "1.0";
+    [property: string]: unknown;
+};
+export type ExecutionProvenanceAttempt = {
+    /**
+     * Normalized error class of a failed attempt.
+     */
+    errorClass?: ErrorClass;
+    /**
+     * 'succeeded' (produced the result or was committed to and completed), 'failed', or
+     * 'cancelled'.
+     */
+    outcome: AttemptOutcome;
+    providerId: string;
+    [property: string]: unknown;
+};
+/**
+ * Normalized error class of a failed attempt.
+ *
+ * Present only if a provider reports a degraded outcome on an otherwise-successful result;
+ * no provider in this codebase currently sets this. Distinct from run() throwing — a thrown
+ * IndeRunError never produces a TaskResult at all.
+ */
+export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";
+/**
+ * 'succeeded' (produced the result or was committed to and completed), 'failed', or
+ * 'cancelled'.
+ */
+export type AttemptOutcome = "succeeded" | "failed" | "cancelled";
+/**
+ * Where providerId declares it executes: 'on_device' for a local provider, 'edge', or
+ * 'cloud'. A declaration by the provider's descriptor, not a measurement. 'unknown' when
+ * providerId is absent.
+ */
+export type Locality = "on_device" | "edge" | "cloud" | "unknown";
+export type ExecutionProvenanceRouteRejection = {
+    codes: Code[];
+    providerId: string;
+    [property: string]: unknown;
+};
+export type Code = "task_not_supported" | "run_not_supported" | "streaming_not_supported" | "streaming_unavailable" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable" | "not_in_model_profile";
 /**
  * Required metadata providing an overview of the execution result and performance metrics.
  */
@@ -74,6 +182,12 @@ export type Telemetry = {
      * 'openai_compatible_cloud').
      */
     providerUsed: string;
+    /**
+     * The model identifier the provider reported in its own response, set by the provider when
+     * its backend reports one. The engine carries it into provenance.reportedModel; it is never
+     * inferred from configuration.
+     */
+    reportedModel?: string;
     /**
      * Measured execution duration in milliseconds, including route selection and result
      * processing.
@@ -81,12 +195,6 @@ export type Telemetry = {
     totalMs: number;
     [property: string]: unknown;
 };
-/**
- * Present only if a provider reports a degraded outcome on an otherwise-successful result;
- * no provider in this codebase currently sets this. Distinct from run() throwing — a thrown
- * IndeRunError never produces a TaskResult at all.
- */
-export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";
 /**
  * Optional metadata regarding the quantity of tokens processed by the provider.
  */

package/dist/generated/task-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-result.d.ts","sourceRoot":"","sources":["../../src/generated/task-result.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG;IACrB;;;;;;OAMG;IACH,YAAY,EAAE,YAAY,CAAC;IAC3B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,aAAa,EAAE,KAAK,CAAC;IACrB;;OAEG;IACH,SAAS,EAAE,SAAS,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,oBAAoB,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEjI;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG;IAChB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA"}
+{"version":3,"file":"task-result.d.ts","sourceRoot":"","sources":["../../src/generated/task-result.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -14,13 +14,13 @@
 /** The generated request/response, streaming, routing, and telemetry models. */
 export type * from "./generated/index.js";
 /** The JSON Schemas those models were generated from, for runtime use. */
-export { httpRequestSchema, httpResponseSchema, inderunErrorSchema, modelPackageSchema, routePlanSchema, routePlannerInputSchema, streamEventSchema, streamRunSchema, streamTerminalOutcomeSchema, taskRequestSchema, taskResultSchema, telemetryEventSchema } from "./generated/index.js";
+export { executionProvenanceSchema, httpRequestSchema, httpResponseSchema, inderunErrorSchema, modelPackageSchema, routePlanSchema, routePlannerInputSchema, streamEventSchema, streamRunSchema, streamTerminalOutcomeSchema, taskRequestSchema, taskResultSchema, telemetryEventSchema } from "./generated/index.js";
 /**
  * Ajv-backed validators for each contract. The `get*ValidationIssues` form returns
  * a list of human-readable issues (empty when valid); the `validate*` form is the
  * boolean type guard.
  */
-export { getHttpRequestValidationIssues, getHttpResponseValidationIssues, getIndeRunErrorValidationIssues, getModelPackageValidationIssues, getRoutePlanValidationIssues, getRoutePlannerInputValidationIssues, getStreamEventValidationIssues, getStreamRunHandleValidationIssues, getStreamTerminalOutcomeValidationIssues, getTaskRequestValidationIssues, getTaskResultValidationIssues, getTelemetryEventValidationIssues, validateHttpRequest, validateHttpResponse, validateIndeRunError, validateModelPackage, validateRoutePlan, validateRoutePlannerInput, validateStreamEvent, validateStreamRunHandle, validateStreamTerminalOutcome, validateTaskRequest, validateTaskResult, validateTelemetryEvent, type ValidationIssue } from "./validators.js";
+export { getExecutionProvenanceValidationIssues, getHttpRequestValidationIssues, getHttpResponseValidationIssues, getIndeRunErrorValidationIssues, getModelPackageValidationIssues, getRoutePlanValidationIssues, getRoutePlannerInputValidationIssues, getStreamEventValidationIssues, getStreamRunHandleValidationIssues, getStreamTerminalOutcomeValidationIssues, getTaskRequestValidationIssues, getTaskResultValidationIssues, getTelemetryEventValidationIssues, validateExecutionProvenance, validateHttpRequest, validateHttpResponse, validateIndeRunError, validateModelPackage, validateRoutePlan, validateRoutePlannerInput, validateStreamEvent, validateStreamRunHandle, validateStreamTerminalOutcome, validateTaskRequest, validateTaskResult, validateTelemetryEvent, type ValidationIssue } from "./validators.js";
 /**
  * Narrowed aliases over the generated models: the closed enums the SDKs switch on,
  * and the routing input/output shapes under the names the engines use.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,gFAAgF;AAChF,mBAAmB,sBAAsB,CAAC;AAE1C,0EAA0E;AAC1E,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAC9B;;;;GAIG;AACH,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,EAC/B,+BAA+B,EAC/B,4BAA4B,EAC5B,oCAAoC,EACpC,8BAA8B,EAC9B,kCAAkC,EAClC,wCAAwC,EACxC,8BAA8B,EAC9B,6BAA6B,EAC7B,iCAAiC,EACjC,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EACvB,6BAA6B,EAC7B,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AACzB;;;GAGG;AACH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,eAAe,EACf,uBAAuB,EACvB,QAAQ,EACR,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,wBAAwB,EACxB,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACb,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,gFAAgF;AAChF,mBAAmB,sBAAsB,CAAC;AAE1C,0EAA0E;AAC1E,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAC9B;;;;GAIG;AACH,OAAO,EACL,sCAAsC,EACtC,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,EAC/B,+BAA+B,EAC/B,4BAA4B,EAC5B,oCAAoC,EACpC,8BAA8B,EAC9B,kCAAkC,EAClC,wCAAwC,EACxC,8BAA8B,EAC9B,6BAA6B,EAC7B,iCAAiC,EACjC,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EACvB,6BAA6B,EAC7B,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AACzB;;;GAGG;AACH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,eAAe,EACf,uBAAuB,EACvB,QAAQ,EACR,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,wBAAwB,EACxB,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACb,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -12,10 +12,10 @@
  * themselves or the runtime validators.
  */
 /** The JSON Schemas those models were generated from, for runtime use. */
-export { httpRequestSchema, httpResponseSchema, inderunErrorSchema, modelPackageSchema, routePlanSchema, routePlannerInputSchema, streamEventSchema, streamRunSchema, streamTerminalOutcomeSchema, taskRequestSchema, taskResultSchema, telemetryEventSchema } from "./generated/index.js";
+export { executionProvenanceSchema, httpRequestSchema, httpResponseSchema, inderunErrorSchema, modelPackageSchema, routePlanSchema, routePlannerInputSchema, streamEventSchema, streamRunSchema, streamTerminalOutcomeSchema, taskRequestSchema, taskResultSchema, telemetryEventSchema } from "./generated/index.js";
 /**
  * Ajv-backed validators for each contract. The `get*ValidationIssues` form returns
  * a list of human-readable issues (empty when valid); the `validate*` form is the
  * boolean type guard.
  */
-export { getHttpRequestValidationIssues, getHttpResponseValidationIssues, getIndeRunErrorValidationIssues, getModelPackageValidationIssues, getRoutePlanValidationIssues, getRoutePlannerInputValidationIssues, getStreamEventValidationIssues, getStreamRunHandleValidationIssues, getStreamTerminalOutcomeValidationIssues, getTaskRequestValidationIssues, getTaskResultValidationIssues, getTelemetryEventValidationIssues, validateHttpRequest, validateHttpResponse, validateIndeRunError, validateModelPackage, validateRoutePlan, validateRoutePlannerInput, validateStreamEvent, validateStreamRunHandle, validateStreamTerminalOutcome, validateTaskRequest, validateTaskResult, validateTelemetryEvent } from "./validators.js";
+export { getExecutionProvenanceValidationIssues, getHttpRequestValidationIssues, getHttpResponseValidationIssues, getIndeRunErrorValidationIssues, getModelPackageValidationIssues, getRoutePlanValidationIssues, getRoutePlannerInputValidationIssues, getStreamEventValidationIssues, getStreamRunHandleValidationIssues, getStreamTerminalOutcomeValidationIssues, getTaskRequestValidationIssues, getTaskResultValidationIssues, getTelemetryEventValidationIssues, validateExecutionProvenance, validateHttpRequest, validateHttpResponse, validateIndeRunError, validateModelPackage, validateRoutePlan, validateRoutePlannerInput, validateStreamEvent, validateStreamRunHandle, validateStreamTerminalOutcome, validateTaskRequest, validateTaskResult, validateTelemetryEvent } from "./validators.js";

package/dist/validators.d.ts

@@ -1,3 +1,4 @@
+import type { ExecutionProvenance } from "./generated/execution-provenance.js";
 import type { IndeRunError } from "./generated/inderun-error.js";
 import type { HttpRequest } from "./generated/http-request.js";
 import type { HttpResponse } from "./generated/http-response.js";
@@ -30,6 +31,8 @@ export declare function validateStreamTerminalOutcome(value: unknown): value is
 export declare function getTaskRequestValidationIssues(value: unknown): ValidationIssue[];
 export declare function getTaskResultValidationIssues(value: unknown): ValidationIssue[];
 export declare function getIndeRunErrorValidationIssues(value: unknown): ValidationIssue[];
+export declare function validateExecutionProvenance(value: unknown): value is ExecutionProvenance;
+export declare function getExecutionProvenanceValidationIssues(value: unknown): ValidationIssue[];
 export declare function getHttpRequestValidationIssues(value: unknown): ValidationIssue[];
 export declare function getHttpResponseValidationIssues(value: unknown): ValidationIssue[];
 export declare function getTelemetryEventValidationIssues(value: unknown): ValidationIssue[];

package/dist/validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"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"}

package/dist/validators.js

@@ -1,5 +1,5 @@
 import Ajv2020 from "ajv/dist/2020.js";
-import { httpRequestSchema, httpResponseSchema, inderunErrorSchema, modelPackageSchema, routePlanSchema, routePlannerInputSchema, streamEventSchema, streamRunSchema, streamTerminalOutcomeSchema, taskRequestSchema, taskResultSchema, telemetryEventSchema } from "./generated/index.js";
+import { executionProvenanceSchema, httpRequestSchema, httpResponseSchema, inderunErrorSchema, modelPackageSchema, routePlanSchema, routePlannerInputSchema, streamEventSchema, streamRunSchema, streamTerminalOutcomeSchema, taskRequestSchema, taskResultSchema, telemetryEventSchema } from "./generated/index.js";
 const Ajv2020Constructor = Ajv2020;
 const ajv = new Ajv2020Constructor({
     allErrors: true,
@@ -7,6 +7,9 @@ const ajv = new Ajv2020Constructor({
     strictRequired: false,
     validateSchema: true
 });
+// Referenced by `$ref` from every schema that carries provenance, so it has to be known
+// to Ajv before any of them compiles. Compiling it registers it under its `$id`.
+const validateExecutionProvenanceSchema = ajv.compile(executionProvenanceSchema);
 const validateTaskRequestSchema = ajv.compile(taskRequestSchema);
 const validateTaskResultSchema = ajv.compile(taskResultSchema);
 const validateIndeRunErrorSchema = ajv.compile(inderunErrorSchema);
@@ -72,6 +75,14 @@ export function getIndeRunErrorValidationIssues(value) {
         forbidInlineSecrets: true
     });
 }
+export function validateExecutionProvenance(value) {
+    return getExecutionProvenanceValidationIssues(value).length === 0;
+}
+export function getExecutionProvenanceValidationIssues(value) {
+    return getValidationIssues(validateExecutionProvenanceSchema, value, {
+        forbidInlineSecrets: true
+    });
+}
 export function getHttpRequestValidationIssues(value) {
     return getValidationIssues(validateHttpRequestSchema, value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@independo/inderun-contracts",
-  "version": "0.3.3",
+  "version": "0.4.0-rc.2",
   "description": "Canonical JSON Schemas, generated TypeScript types, and validators for the IndeRun task, streaming, error, and routing contracts.",
   "license": "MIT",
   "author": {

package/src/generated/execution-provenance.ts

@@ -0,0 +1,102 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * Provider-neutral record of how an execution was carried out: the target the outcome is
+ * attributed to, its declared locality, the configured and provider-reported model, every
+ * attempt, and why other candidates were rejected. Carried on TaskResult, on every
+ * StreamTerminalOutcome branch, and on IndeRunError. It reports what the engine observed
+ * and what providers declared or reported; it never infers a model or locality a provider
+ * did not state, and it never contains request content, credentials, or provider payloads.
+ */
+export type ExecutionProvenance = {
+    /**
+     * How many providers were attempted. 0 when the request failed validation or routing, or
+     * was cancelled before any attempt started.
+     */
+    attemptCount: number;
+    /**
+     * Every attempted provider, in attempt order, with how its attempt ended.
+     */
+    attempts: ExecutionProvenanceAttempt[];
+    /**
+     * The model providerId is bound to, as its descriptor declares it. Absent when the provider
+     * cannot name its model or no provider is attributed.
+     */
+    configuredModel?: string;
+    /**
+     * Whether more than one provider was attempted (attemptCount > 1).
+     */
+    fallbackOccurred: boolean;
+    /**
+     * Where providerId declares it executes: 'on_device' for a local provider, 'edge', or
+     * 'cloud'. A declaration by the provider's descriptor, not a measurement. 'unknown' when
+     * providerId is absent.
+     */
+    locality: Locality;
+    /**
+     * The model profile the request routed within; 'auto' when the request named none.
+     */
+    modelProfile: string;
+    /**
+     * The target the outcome is attributed to: the provider that produced the result, the
+     * provider a stream had committed to when it ended, or the provider that was running when
+     * it was cancelled. Absent when no provider was reached or when every attempted provider
+     * failed before one was committed to.
+     */
+    providerId?: string;
+    /**
+     * The model identifier the provider reported in its own response. Absent means the provider
+     * did not report one; it is never inferred from configuration.
+     */
+    reportedModel?: string;
+    /**
+     * Providers the route planner rejected before any attempt, with the normalized RoutePlan
+     * reason codes. Codes only: no provider-supplied messages.
+     */
+    routeRejections: ExecutionProvenanceRouteRejection[];
+    /**
+     * Contract schema version used to interpret this provenance record.
+     */
+    schemaVersion: "1.0";
+    [property: string]: unknown;
+}
+
+export type ExecutionProvenanceAttempt = {
+    /**
+     * Normalized error class of a failed attempt.
+     */
+    errorClass?: ErrorClass;
+    /**
+     * 'succeeded' (produced the result or was committed to and completed), 'failed', or
+     * 'cancelled'.
+     */
+    outcome:    AttemptOutcome;
+    providerId: string;
+    [property: string]: unknown;
+}
+
+/**
+ * Normalized error class of a failed attempt.
+ */
+export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";
+
+/**
+ * 'succeeded' (produced the result or was committed to and completed), 'failed', or
+ * 'cancelled'.
+ */
+export type AttemptOutcome = "succeeded" | "failed" | "cancelled";
+
+/**
+ * Where providerId declares it executes: 'on_device' for a local provider, 'edge', or
+ * 'cloud'. A declaration by the provider's descriptor, not a measurement. 'unknown' when
+ * providerId is absent.
+ */
+export type Locality = "on_device" | "edge" | "cloud" | "unknown";
+
+export type ExecutionProvenanceRouteRejection = {
+    codes:      Code[];
+    providerId: string;
+    [property: string]: unknown;
+}
+
+export type Code = "task_not_supported" | "run_not_supported" | "streaming_not_supported" | "streaming_unavailable" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable" | "not_in_model_profile";

package/src/generated/inderun-error.ts

@@ -22,6 +22,12 @@ export type IndeRunError = {
      * Human-readable error message suitable for logs and developer diagnostics.
      */
     message: string;
+    /**
+     * Normalized execution provenance: which target ran, its declared locality, the configured
+     * and reported model, and how fallback and routing played out. See
+     * execution-provenance.schema.json.
+     */
+    provenance?: ExecutionProvenance;
     /**
      * Identifier of the provider associated with the failure, if execution reached a provider.
      */
@@ -51,5 +57,107 @@ export type IndeRunError = {
  * Offline/Unavailable (provider unreachable or not ready), AuthError (credential/auth
  * failure), RateLimited (provider throttled the request), Timeout (provider exceeded its
  * execution budget), Internal (unexpected engine-side failure).
+ *
+ * Normalized error class of a failed attempt.
  */
 export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";
+
+/**
+ * Normalized execution provenance: which target ran, its declared locality, the configured
+ * and reported model, and how fallback and routing played out. See
+ * execution-provenance.schema.json.
+ *
+ * Provider-neutral record of how an execution was carried out: the target the outcome is
+ * attributed to, its declared locality, the configured and provider-reported model, every
+ * attempt, and why other candidates were rejected. Carried on TaskResult, on every
+ * StreamTerminalOutcome branch, and on IndeRunError. It reports what the engine observed
+ * and what providers declared or reported; it never infers a model or locality a provider
+ * did not state, and it never contains request content, credentials, or provider payloads.
+ */
+export type ExecutionProvenance = {
+    /**
+     * How many providers were attempted. 0 when the request failed validation or routing, or
+     * was cancelled before any attempt started.
+     */
+    attemptCount: number;
+    /**
+     * Every attempted provider, in attempt order, with how its attempt ended.
+     */
+    attempts: ExecutionProvenanceAttempt[];
+    /**
+     * The model providerId is bound to, as its descriptor declares it. Absent when the provider
+     * cannot name its model or no provider is attributed.
+     */
+    configuredModel?: string;
+    /**
+     * Whether more than one provider was attempted (attemptCount > 1).
+     */
+    fallbackOccurred: boolean;
+    /**
+     * Where providerId declares it executes: 'on_device' for a local provider, 'edge', or
+     * 'cloud'. A declaration by the provider's descriptor, not a measurement. 'unknown' when
+     * providerId is absent.
+     */
+    locality: Locality;
+    /**
+     * The model profile the request routed within; 'auto' when the request named none.
+     */
+    modelProfile: string;
+    /**
+     * The target the outcome is attributed to: the provider that produced the result, the
+     * provider a stream had committed to when it ended, or the provider that was running when
+     * it was cancelled. Absent when no provider was reached or when every attempted provider
+     * failed before one was committed to.
+     */
+    providerId?: string;
+    /**
+     * The model identifier the provider reported in its own response. Absent means the provider
+     * did not report one; it is never inferred from configuration.
+     */
+    reportedModel?: string;
+    /**
+     * Providers the route planner rejected before any attempt, with the normalized RoutePlan
+     * reason codes. Codes only: no provider-supplied messages.
+     */
+    routeRejections: ExecutionProvenanceRouteRejection[];
+    /**
+     * Contract schema version used to interpret this provenance record.
+     */
+    schemaVersion: "1.0";
+    [property: string]: unknown;
+}
+
+export type ExecutionProvenanceAttempt = {
+    /**
+     * Normalized error class of a failed attempt.
+     */
+    errorClass?: ErrorClass;
+    /**
+     * 'succeeded' (produced the result or was committed to and completed), 'failed', or
+     * 'cancelled'.
+     */
+    outcome:    AttemptOutcome;
+    providerId: string;
+    [property: string]: unknown;
+}
+
+/**
+ * 'succeeded' (produced the result or was committed to and completed), 'failed', or
+ * 'cancelled'.
+ */
+export type AttemptOutcome = "succeeded" | "failed" | "cancelled";
+
+/**
+ * Where providerId declares it executes: 'on_device' for a local provider, 'edge', or
+ * 'cloud'. A declaration by the provider's descriptor, not a measurement. 'unknown' when
+ * providerId is absent.
+ */
+export type Locality = "on_device" | "edge" | "cloud" | "unknown";
+
+export type ExecutionProvenanceRouteRejection = {
+    codes:      Code[];
+    providerId: string;
+    [property: string]: unknown;
+}
+
+export type Code = "task_not_supported" | "run_not_supported" | "streaming_not_supported" | "streaming_unavailable" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable" | "not_in_model_profile";

package/src/generated/index.ts

@@ -12,4 +12,5 @@ export type { ModelPackage } from "./model-package.js";
 export type { StreamRunHandle } from "./stream-run.js";
 export type { StreamEvent } from "./stream-event.js";
 export type { StreamTerminalOutcome } from "./stream-terminal-outcome.js";
+export type { ExecutionProvenance } from "./execution-provenance.js";
 export * from "./schemas.js";

package/src/generated/route-plan.ts

@@ -62,7 +62,8 @@ export type Reason = {
      * Normalized rejection reason. 'streaming_not_supported' means the descriptor does not
      * statically declare Mode-2 streaming; 'streaming_unavailable' means it declares streaming
      * but the dynamic capability snapshot reports it cannot stream in the current host
-     * environment.
+     * environment. 'not_in_model_profile' means the request named a model profile that does not
+     * list this provider.
      */
     code:    Code;
     message: string;
@@ -73,6 +74,7 @@ export type Reason = {
  * Normalized rejection reason. 'streaming_not_supported' means the descriptor does not
  * statically declare Mode-2 streaming; 'streaming_unavailable' means it declares streaming
  * but the dynamic capability snapshot reports it cannot stream in the current host
- * environment.
+ * environment. 'not_in_model_profile' means the request named a model profile that does not
+ * list this provider.
  */
-export type Code = "task_not_supported" | "run_not_supported" | "streaming_not_supported" | "streaming_unavailable" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable";
+export type Code = "task_not_supported" | "run_not_supported" | "streaming_not_supported" | "streaming_unavailable" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable" | "not_in_model_profile";

package/src/generated/route-planner-input.ts

@@ -14,6 +14,14 @@ export type RoutePlannerInput = {
      * eligible providers; it never changes candidate ordering.
      */
     interactionMode?: InteractionMode;
+    /**
+     * The resolved model profile the request routes within. Absent means the built-in 'auto'
+     * profile: no allow-list, and ordering by placement and preference alone. When present,
+     * providers whose id is not in targetIds are rejected with 'not_in_model_profile', and the
+     * position in targetIds ranks the survivors after placement and before preferences. Ids
+     * that name no registered provider are ignored.
+     */
+    modelProfile?: ModelProfile;
     /**
      * Soft route ordering preferences applied after hard filtering.
      */
@@ -65,6 +73,25 @@ export type PrivacyEnum = "local_required" | "local_preferred" | "cloud_allowed"
  */
 export type InteractionMode = "run" | "stream";
 
+/**
+ * The resolved model profile the request routes within. Absent means the built-in 'auto'
+ * profile: no allow-list, and ordering by placement and preference alone. When present,
+ * providers whose id is not in targetIds are rejected with 'not_in_model_profile', and the
+ * position in targetIds ranks the survivors after placement and before preferences. Ids
+ * that name no registered provider are ignored.
+ */
+export type ModelProfile = {
+    /**
+     * Profile name, carried for explanations.
+     */
+    name: string;
+    /**
+     * Provider ids in profile order.
+     */
+    targetIds: [string, ...string[]];
+    [property: string]: unknown;
+}
+
 /**
  * Soft route ordering preferences applied after hard filtering.
  */