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

package/src/generated/task-result.ts

@@ -21,6 +21,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.
      */
@@ -64,6 +70,115 @@ export type Output = {
     [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.
  */
@@ -79,6 +194,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.
@@ -87,13 +208,6 @@ export type Telemetry = {
     [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/src/index.ts

@@ -17,6 +17,7 @@ export type * from "./generated/index.js";
 
 /** The JSON Schemas those models were generated from, for runtime use. */
 export {
+  executionProvenanceSchema,
   httpRequestSchema,
   httpResponseSchema,
   inderunErrorSchema,
@@ -36,6 +37,7 @@ export {
  * boolean type guard.
  */
 export {
+  getExecutionProvenanceValidationIssues,
   getHttpRequestValidationIssues,
   getHttpResponseValidationIssues,
   getIndeRunErrorValidationIssues,
@@ -48,6 +50,7 @@ export {
   getTaskRequestValidationIssues,
   getTaskResultValidationIssues,
   getTelemetryEventValidationIssues,
+  validateExecutionProvenance,
   validateHttpRequest,
   validateHttpResponse,
   validateIndeRunError,

package/src/validators.ts

@@ -1,6 +1,7 @@
 import Ajv2020 from "ajv/dist/2020.js";
 import type { ErrorObject, ValidateFunction } from "ajv";
 
+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";
@@ -8,6 +9,7 @@ import type { ModelPackage } from "./generated/model-package.js";
 import type { RoutePlan } from "./generated/route-plan.js";
 import type { RoutePlannerInput } from "./generated/route-planner-input.js";
 import {
+  executionProvenanceSchema,
   httpRequestSchema,
   httpResponseSchema,
   inderunErrorSchema,
@@ -45,6 +47,9 @@ const ajv = new Ajv2020Constructor({
   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);
@@ -127,6 +132,16 @@ export function getIndeRunErrorValidationIssues(value: unknown): ValidationIssue
   });
 }
 
+export function validateExecutionProvenance(value: unknown): value is ExecutionProvenance {
+  return getExecutionProvenanceValidationIssues(value).length === 0;
+}
+
+export function getExecutionProvenanceValidationIssues(value: unknown): ValidationIssue[] {
+  return getValidationIssues(validateExecutionProvenanceSchema, value, {
+    forbidInlineSecrets: true
+  });
+}
+
 export function getHttpRequestValidationIssues(value: unknown): ValidationIssue[] {
   return getValidationIssues(validateHttpRequestSchema, value);
 }