@independo/inderun-contracts 0.3.0-dev.12 → 0.3.0-dev.13

package/dist/index.d.ts

@@ -1,6 +1,35 @@
+/**
+ * Canonical IndeRun contracts for TypeScript (`@independo/inderun-contracts`).
+ *
+ * Everything here derives from the JSON Schemas in `contracts/schemas/`, which are
+ * the single source of truth across all four languages — the TypeScript types
+ * below, the Kotlin and Swift contract models, and the Rust route-core model are
+ * all generated from them by `pnpm generate`. Do not hand-edit anything under
+ * `src/generated/`; change the schema and regenerate.
+ *
+ * Apps normally do not depend on this package directly: the SDKs re-export the
+ * contract types their own signatures use. Reach for it when you need the schemas
+ * themselves or the runtime validators.
+ */
+/** 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";
+/**
+ * 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";
+/**
+ * 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.
+ */
 export type { FinishReason, IndeRunErrorClass, ModelPackageFormat, ModelSourceType, SchemaVersion, SharedRoutePlan, SharedRoutePlannerInput, TaskKind, RoutingConstraints, RoutingPreferences } from "./types.js";
+/**
+ * The host-services contract: the platform capabilities an SDK reads and calls
+ * through. Defined here rather than per-SDK so the three platforms expose the
+ * same seams.
+ */
 export type { AbortSignalLike, ConnectivityService, ThermalState, DeviceConstraintsService, SecureStorageService, ClockService, HttpClientService, HttpStreamResponse, HttpStreamingClientService, TelemetryEventType, TelemetryService, HostServices } from "./host.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,sBAAsB,CAAC;AAC1C,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,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,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,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,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"}

package/dist/index.js

@@ -1,2 +1,21 @@
+/**
+ * Canonical IndeRun contracts for TypeScript (`@independo/inderun-contracts`).
+ *
+ * Everything here derives from the JSON Schemas in `contracts/schemas/`, which are
+ * the single source of truth across all four languages — the TypeScript types
+ * below, the Kotlin and Swift contract models, and the Rust route-core model are
+ * all generated from them by `pnpm generate`. Do not hand-edit anything under
+ * `src/generated/`; change the schema and regenerate.
+ *
+ * Apps normally do not depend on this package directly: the SDKs re-export the
+ * contract types their own signatures use. Reach for it when you need the schemas
+ * 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";
+/**
+ * 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@independo/inderun-contracts",
-  "version": "0.3.0-dev.12",
+  "version": "0.3.0-dev.13",
   "description": "Canonical JSON Schemas, generated TypeScript types, and validators for IndeRun contracts.",
   "license": "MIT",
   "author": {
@@ -11,7 +11,7 @@
   "bugs": "https://github.com/independo-gmbh/inderun/issues",
   "repository": {
     "type": "git",
-    "url": "https://github.com/independo-gmbh/inderun.git",
+    "url": "git+https://github.com/independo-gmbh/inderun.git",
     "directory": "packages/contracts"
   },
   "publishConfig": {
@@ -39,17 +39,20 @@
   },
   "files": [
     "dist",
+    "src",
+    "!src/**/*.test.ts",
     "README.md"
   ],
   "dependencies": {
     "ajv": "^8.20.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.4.1",
     "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run"
+    "test": "vitest run",
+    "verify:packaging": "publint && attw --pack . --profile esm-only"
   }
 }

package/src/generated/http-request.ts

@@ -0,0 +1,34 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * Normalized HTTP request payload for host-provided cloud transport.
+ */
+export type HttpRequest = {
+    /**
+     * Optional serialized request body. For JSON APIs this should be a JSON string.
+     */
+    body?: string;
+    /**
+     * HTTP headers to send after the provider adapter has applied any required transport-level
+     * credentials.
+     */
+    headers?: { [key: string]: string };
+    /**
+     * HTTP method to use for the request.
+     */
+    method: Method;
+    /**
+     * Optional maximum duration for the host transport attempt in milliseconds.
+     */
+    timeoutMs?: number;
+    /**
+     * Absolute target URL for the provider transport request.
+     */
+    url: string;
+    [property: string]: unknown;
+}
+
+/**
+ * HTTP method to use for the request.
+ */
+export type Method = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";

package/src/generated/http-response.ts

@@ -0,0 +1,24 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * Normalized HTTP response payload returned by host-provided cloud transport.
+ */
+export type HttpResponse = {
+    /**
+     * Serialized response body returned by the provider transport.
+     */
+    body: string;
+    /**
+     * HTTP response headers normalized to string key-value pairs.
+     */
+    headers: { [key: string]: string };
+    /**
+     * HTTP status code returned by the provider transport.
+     */
+    status: number;
+    /**
+     * HTTP status text returned by the provider transport.
+     */
+    statusText: string;
+    [property: string]: unknown;
+}

package/src/generated/inderun-error.ts

@@ -0,0 +1,55 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * The error shape thrown by run() (wrapped in an IndeRunException) when execution fails —
+ * via validation, routing (no eligible provider), or every attempted provider failing.
+ * Never returned as part of a successful TaskResult.
+ */
+export type IndeRunError = {
+    /**
+     * Optional structured diagnostic details. It must not contain raw secrets.
+     */
+    details?: { [key: string]: unknown };
+    /**
+     * Normalized error taxonomy, shared with TaskResult.telemetry.errorClass:
+     * CapabilityMismatch (request needs something no eligible provider supports),
+     * 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).
+     */
+    errorClass: ErrorClass;
+    /**
+     * Human-readable error message suitable for logs and developer diagnostics.
+     */
+    message: string;
+    /**
+     * Identifier of the provider associated with the failure, if execution reached a provider.
+     */
+    providerId?: string;
+    /**
+     * Whether retrying the same request may succeed.
+     */
+    retryable?: boolean;
+    /**
+     * Optional suggested delay before retrying, in milliseconds.
+     */
+    retryAfterMs?: number;
+    /**
+     * Opaque run identifier associated with the failed execution, if available.
+     */
+    runId?: string;
+    /**
+     * Contract schema version used to interpret the error payload.
+     */
+    schemaVersion: "1.0";
+    [property: string]: unknown;
+}
+
+/**
+ * Normalized error taxonomy, shared with TaskResult.telemetry.errorClass:
+ * CapabilityMismatch (request needs something no eligible provider supports),
+ * 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).
+ */
+export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";

package/src/generated/index.ts

@@ -0,0 +1,15 @@
+/* This file was generated from JSON Schema. Do not edit by hand. */
+
+export type { TaskRequest } from "./task-request.js";
+export type { TaskResult } from "./task-result.js";
+export type { IndeRunError } from "./inderun-error.js";
+export type { HttpRequest } from "./http-request.js";
+export type { HttpResponse } from "./http-response.js";
+export type { TelemetryEvent } from "./telemetry-event.js";
+export type { RoutePlannerInput } from "./route-planner-input.js";
+export type { RoutePlan } from "./route-plan.js";
+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 * from "./schemas.js";

package/src/generated/model-package.ts

@@ -0,0 +1,191 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * Provider-neutral descriptor for a developer-supplied/custom local model made available to
+ * an IndeRun local-model provider family (for example, the ONNX Runtime family). It
+ * describes model identity, format, task support, source, files, integrity, licensing, and
+ * resource expectations. It is bootstrap/configuration metadata resolved before execution;
+ * it is not part of the public TaskRequest/TaskResult surface, and it must not carry raw
+ * secrets.
+ */
+export type ModelPackage = {
+    /**
+     * Files that make up the model package, expressed as source-relative names/paths. The
+     * provider adapter and model source resolve these to concrete bytes per platform.
+     */
+    files?: Files;
+    /**
+     * Model packaging format the target runtime family must understand. 'onnx' is a plain ONNX
+     * graph, 'ort' is an ONNX Runtime optimized/mobile format, 'genai' is an ONNX Runtime GenAI
+     * model package.
+     */
+    format: Format;
+    /**
+     * Stable application-scoped identifier for the model package.
+     */
+    id: string;
+    /**
+     * Optional integrity metadata used to validate resolved files before load.
+     */
+    integrity?: Integrity;
+    /**
+     * Optional license/source metadata for the model, for developer transparency. Free-form.
+     */
+    license?: License;
+    /**
+     * Optional known resource expectations, used by capability checks to reject on constrained
+     * devices before load.
+     */
+    limits?: Limits;
+    /**
+     * Optional runtime compatibility expectations. Fields are advisory hints for capability
+     * checks; the provider adapter owns exact enforcement.
+     */
+    runtime?: Runtime;
+    /**
+     * Where the model files are obtained from. Availability of each source type is
+     * platform-dependent; see the ONNX Runtime provider-family specification for the
+     * per-platform support matrix.
+     */
+    source?: Source;
+    /**
+     * IndeRun task kinds this model package can serve (for example 'text_to_text'). Used by
+     * dynamic capability checks and route matching.
+     */
+    tasks?: string[];
+    /**
+     * Optional application-defined version for the model package, used for cache invalidation
+     * and compatibility checks.
+     */
+    version?: string;
+    [property: string]: unknown;
+}
+
+/**
+ * Files that make up the model package, expressed as source-relative names/paths. The
+ * provider adapter and model source resolve these to concrete bytes per platform.
+ */
+export type Files = {
+    /**
+     * Optional model/generation config file, where the model requires one.
+     */
+    config?: string;
+    /**
+     * Optional external data files referenced by the model graph (for example ONNX external
+     * weights).
+     */
+    external?: string[];
+    /**
+     * Files that must be present for the package to load (for example the model graph).
+     */
+    required?: string[];
+    /**
+     * Optional tokenizer file, where the model requires one.
+     */
+    tokenizer?: string;
+    [property: string]: unknown;
+}
+
+/**
+ * Model packaging format the target runtime family must understand. 'onnx' is a plain ONNX
+ * graph, 'ort' is an ONNX Runtime optimized/mobile format, 'genai' is an ONNX Runtime GenAI
+ * model package.
+ */
+export type Format = "onnx" | "ort" | "genai";
+
+/**
+ * Optional integrity metadata used to validate resolved files before load.
+ */
+export type Integrity = {
+    /**
+     * Map of file name to expected checksum (for example 'sha256:...'). Absence means integrity
+     * is not verified by IndeRun.
+     */
+    checksums?: { [key: string]: string };
+    [property: string]: unknown;
+}
+
+/**
+ * Optional license/source metadata for the model, for developer transparency. Free-form.
+ */
+export type License = {
+    /**
+     * SPDX license identifier where known (for example 'Apache-2.0').
+     */
+    spdx?: string;
+    /**
+     * License or model card URL where available.
+     */
+    url?: string;
+    [property: string]: unknown;
+}
+
+/**
+ * Optional known resource expectations, used by capability checks to reject on constrained
+ * devices before load.
+ */
+export type Limits = {
+    /**
+     * Approximate on-disk size of the resolved package, where known.
+     */
+    diskBytes?: number;
+    /**
+     * Approximate peak memory required to run the model, where known.
+     */
+    memBytes?: number;
+    [property: string]: unknown;
+}
+
+/**
+ * Optional runtime compatibility expectations. Fields are advisory hints for capability
+ * checks; the provider adapter owns exact enforcement.
+ */
+export type Runtime = {
+    /**
+     * Minimum ONNX opset version the model requires, where known.
+     */
+    minOpset?: number;
+    /**
+     * Minimum runtime package version required to load the model, where known.
+     */
+    minRuntimeVersion?: string;
+    /**
+     * Platforms the package is expected to run on (for example 'web', 'android', 'apple').
+     * Absence means unconstrained.
+     */
+    platforms?: string[];
+    [property: string]: unknown;
+}
+
+/**
+ * Where the model files are obtained from. Availability of each source type is
+ * platform-dependent; see the ONNX Runtime provider-family specification for the
+ * per-platform support matrix.
+ */
+export type Source = {
+    /**
+     * Optional source-specific reference (for example a registry repo id or a bundled asset
+     * base path). Interpretation depends on 'sourceType'. Must not contain credentials: URL
+     * userinfo (for example 'https://user:pass@host/...') is rejected, and credentials must be
+     * supplied via authContextRef instead.
+     */
+    ref?: string;
+    /**
+     * Discriminator for how the host makes model files available. 'registry' is a web
+     * repository/registry reference (for example a Hugging Face-style repo), 'bundled' is an
+     * app asset/resource, 'programmatic' is supplied directly by application code, 'filesystem'
+     * is a local path where the platform allows it, 'app_managed' is an app-managed
+     * cache/storage location, 'remote' is a host-managed download.
+     */
+    sourceType: SourceType;
+    [property: string]: unknown;
+}
+
+/**
+ * Discriminator for how the host makes model files available. 'registry' is a web
+ * repository/registry reference (for example a Hugging Face-style repo), 'bundled' is an
+ * app asset/resource, 'programmatic' is supplied directly by application code, 'filesystem'
+ * is a local path where the platform allows it, 'app_managed' is an app-managed
+ * cache/storage location, 'remote' is a host-managed download.
+ */
+export type SourceType = "registry" | "bundled" | "programmatic" | "filesystem" | "app_managed" | "remote";

package/src/generated/route-plan.ts

@@ -0,0 +1,78 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * Deterministic shared-core Mode-1 route planning result.
+ */
+export type RoutePlan = {
+    /**
+     * Eligible candidates in deterministic order.
+     */
+    candidates: Candidate[];
+    /**
+     * Human-readable selection or failure explanation suitable for telemetry/debugging.
+     */
+    explanation: Explanation;
+    /**
+     * Normalized routing failure class when no provider is selected.
+     */
+    failureCode?: FailureCode;
+    /**
+     * Fallback provider IDs ordered after the primary selection.
+     */
+    fallbackProviderIds: string[];
+    /**
+     * Providers filtered out during planning together with machine-readable reasons.
+     */
+    rejectedProviders: RejectedProvider[];
+    /**
+     * Chosen primary provider ID, if any.
+     */
+    selectedProviderId?: string;
+    [property: string]: unknown;
+}
+
+export type Candidate = {
+    order:      number;
+    providerId: string;
+    [property: string]: unknown;
+}
+
+/**
+ * Human-readable selection or failure explanation suitable for telemetry/debugging.
+ */
+export type Explanation = {
+    selectedProviderId?: string;
+    summary:             string;
+    [property: string]: unknown;
+}
+
+/**
+ * Normalized routing failure class when no provider is selected.
+ */
+export type FailureCode = "capability_mismatch" | "offline" | "unavailable";
+
+export type RejectedProvider = {
+    providerId: string;
+    reasons:    Reason[];
+    [property: string]: unknown;
+}
+
+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.
+     */
+    code:    Code;
+    message: string;
+    [property: string]: unknown;
+}
+
+/**
+ * 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.
+ */
+export type Code = "task_not_supported" | "run_not_supported" | "streaming_not_supported" | "streaming_unavailable" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable";

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

@@ -0,0 +1,161 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+
+/**
+ * Pure data input contract for deterministic shared-core route planning.
+ */
+export type RoutePlannerInput = {
+    /**
+     * Hard routing constraints evaluated before provider selection.
+     */
+    constraints: Constraints;
+    /**
+     * Interaction mode the caller is requesting. Absent means 'run' (Mode 1), so planner inputs
+     * produced before this field existed keep their exact Mode-1 semantics. The mode filters
+     * eligible providers; it never changes candidate ordering.
+     */
+    interactionMode?: InteractionMode;
+    /**
+     * Soft route ordering preferences applied after hard filtering.
+     */
+    preferences: Preferences;
+    /**
+     * Static descriptors plus dynamic capability snapshots for planning.
+     */
+    providers: Provider[];
+    /**
+     * Minimal task descriptor for provider task matching.
+     */
+    task: Task;
+    [property: string]: unknown;
+}
+
+/**
+ * Hard routing constraints evaluated before provider selection.
+ */
+export type Constraints = {
+    /**
+     * Cloud execution constraint.
+     */
+    cloud?: Cloud;
+    /**
+     * Current connectivity snapshot used for cloud route planning.
+     */
+    networkOnline?: boolean;
+    /**
+     * Privacy requirement or preference for execution placement.
+     */
+    privacy?: PrivacyEnum;
+    [property: string]: unknown;
+}
+
+/**
+ * Cloud execution constraint.
+ */
+export type Cloud = "forbidden" | "allowed" | "required";
+
+/**
+ * Privacy requirement or preference for execution placement.
+ */
+export type PrivacyEnum = "local_required" | "local_preferred" | "cloud_allowed" | "cloud_required";
+
+/**
+ * Interaction mode the caller is requesting. Absent means 'run' (Mode 1), so planner inputs
+ * produced before this field existed keep their exact Mode-1 semantics. The mode filters
+ * eligible providers; it never changes candidate ordering.
+ */
+export type InteractionMode = "run" | "stream";
+
+/**
+ * Soft route ordering preferences applied after hard filtering.
+ */
+export type Preferences = {
+    /**
+     * Primary optimization goal when multiple providers remain eligible.
+     */
+    optimizeFor?: OptimizeFor;
+    [property: string]: unknown;
+}
+
+/**
+ * Primary optimization goal when multiple providers remain eligible.
+ */
+export type OptimizeFor = "privacy" | "latency" | "cost" | "balanced";
+
+export type Provider = {
+    capabilities: Capabilities;
+    descriptor:   Descriptor;
+    [property: string]: unknown;
+}
+
+export type Capabilities = {
+    available: boolean;
+    /**
+     * Whether cancellation is honored right now in this host environment. Absent inherits the
+     * static descriptor.cancel value (any value other than 'none' means available).
+     */
+    cancellationAvailable?: boolean;
+    reason?:                string;
+    /**
+     * Whether the provider can stream right now in this host environment. Absent inherits the
+     * static descriptor.supports.streaming value.
+     */
+    streamingAvailable?: boolean;
+    /**
+     * Human-readable explanation used when streamingAvailable is false. Absent lets the planner
+     * synthesize a default message.
+     */
+    streamingUnavailableReason?: string;
+    [property: string]: unknown;
+}
+
+export type Descriptor = {
+    /**
+     * Cancellation guarantee the provider offers. Carried for route explanations and telemetry;
+     * the planner does not filter on it.
+     */
+    cancel?: Cancel;
+    id:      string;
+    /**
+     * Descriptor privacy metadata used to enforce local/cloud routing rules.
+     */
+    privacy?: PrivacyObject;
+    supports: Supports;
+    tasks:    string[];
+    type:     Type;
+    [property: string]: unknown;
+}
+
+/**
+ * Cancellation guarantee the provider offers. Carried for route explanations and telemetry;
+ * the planner does not filter on it.
+ */
+export type Cancel = "hard" | "soft" | "none";
+
+/**
+ * Descriptor privacy metadata used to enforce local/cloud routing rules.
+ */
+export type PrivacyObject = {
+    dataLeavesDevice: boolean;
+    regions?:         string[];
+    [property: string]: unknown;
+}
+
+export type Supports = {
+    run: boolean;
+    /**
+     * Whether the provider statically declares Mode-2 streaming. Absent is treated as false: a
+     * descriptor that predates this field cannot be assumed to stream.
+     */
+    streaming?: boolean;
+    [property: string]: unknown;
+}
+
+export type Type = "local" | "edge" | "cloud";
+
+/**
+ * Minimal task descriptor for provider task matching.
+ */
+export type Task = {
+    kind: string;
+    [property: string]: unknown;
+}