@independo/inderun-contracts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Independo GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @independo/inderun-contracts
+
+Canonical JSON Schema-backed contracts for IndeRun.
+
+The JSON Schema files in `contracts/schemas/` are the source of truth. TypeScript types and validators in this package,
+and the generated Swift contract models, are produced from those schemas.
+
+Use this package when you need the generated request, result, error, HTTP, route-planning, or telemetry contract types.
+
+## Commands
+
+```sh
+pnpm generate
+pnpm --filter @independo/inderun-contracts build
+pnpm --filter @independo/inderun-contracts test
+```

package/dist/generated/http-request.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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";
+//# sourceMappingURL=http-request.d.ts.map

package/dist/generated/http-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-request.d.ts","sourceRoot":"","sources":["../../src/generated/http-request.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACtB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC"}

package/dist/generated/http-request.js

@@ -0,0 +1,2 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+export {};

package/dist/generated/http-response.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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;
+};
+//# sourceMappingURL=http-response.d.ts.map

package/dist/generated/http-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-response.d.ts","sourceRoot":"","sources":["../../src/generated/http-response.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,OAAO,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA"}

package/dist/generated/http-response.js

@@ -0,0 +1,2 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+export {};

package/dist/generated/inderun-error.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Normalized Milestone-1 error contract.
+ */
+export type IndeRunError = {
+    /**
+     * Optional structured diagnostic details. It must not contain raw secrets.
+     */
+    details?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Normalized error taxonomy class.
+     */
+    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 class.
+ */
+export type ErrorClass = "CapabilityMismatch" | "Offline" | "AuthError" | "RateLimited" | "Timeout" | "Unavailable" | "Internal";
+//# sourceMappingURL=inderun-error.d.ts.map

package/dist/generated/inderun-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inderun-error.d.ts","sourceRoot":"","sources":["../../src/generated/inderun-error.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACvB;;OAEG;IACH,OAAO,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACrC;;OAEG;IACH,UAAU,EAAE,UAAU,CAAC;IACvB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;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,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,aAAa,EAAE,KAAK,CAAC;IACrB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,oBAAoB,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC"}

package/dist/generated/inderun-error.js

@@ -0,0 +1,2 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+export {};

package/dist/generated/index.d.ts

@@ -0,0 +1,10 @@
+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 * from "./schemas.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/generated/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generated/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,cAAc,cAAc,CAAC"}

package/dist/generated/index.js

@@ -0,0 +1,2 @@
+/* This file was generated from JSON Schema. Do not edit by hand. */
+export * from "./schemas.js";

package/dist/generated/route-plan.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 = {
+    code: Code;
+    message: string;
+    [property: string]: unknown;
+};
+export type Code = "task_not_supported" | "run_not_supported" | "privacy_constraint" | "cloud_constraint" | "offline" | "capability_unavailable";
+//# sourceMappingURL=route-plan.d.ts.map

package/dist/generated/route-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-plan.d.ts","sourceRoot":"","sources":["../../src/generated/route-plan.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB;;OAEG;IACH,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;OAEG;IACH,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B;;OAEG;IACH,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACpB,KAAK,EAAO,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAc,MAAM,CAAC;IAC5B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,qBAAqB,GAAG,SAAS,GAAG,aAAa,CAAC;AAE5E,MAAM,MAAM,gBAAgB,GAAG;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAK,MAAM,EAAE,CAAC;IACrB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACjB,IAAI,EAAK,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED,MAAM,MAAM,IAAI,GAAG,oBAAoB,GAAG,mBAAmB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,SAAS,GAAG,wBAAwB,CAAC"}

package/dist/generated/route-plan.js

@@ -0,0 +1,2 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+export {};

package/dist/generated/route-planner-input.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure data input contract for deterministic shared-core Mode-1 route planning.
+ */
+export type RoutePlannerInput = {
+    /**
+     * Hard routing constraints evaluated before provider selection.
+     */
+    constraints: Constraints;
+    /**
+     * 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";
+/**
+ * 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;
+    reason?: string;
+    [property: string]: unknown;
+};
+export type Descriptor = {
+    id: string;
+    /**
+     * Descriptor privacy metadata used to enforce local/cloud routing rules.
+     */
+    privacy?: PrivacyObject;
+    supports: Supports;
+    tasks: string[];
+    type: Type;
+    [property: string]: unknown;
+};
+/**
+ * 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;
+    [property: string]: unknown;
+};
+export type Type = "local" | "edge" | "cloud";
+/**
+ * Minimal task descriptor for provider task matching.
+ */
+export type Task = {
+    kind: string;
+    [property: string]: unknown;
+};
+//# sourceMappingURL=route-planner-input.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route-planner-input.d.ts","sourceRoot":"","sources":["../../src/generated/route-planner-input.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;OAEG;IACH,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;IACX,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAEpG;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACtB;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtE,MAAM,MAAM,QAAQ,GAAG;IACnB,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,EAAI,UAAU,CAAC;IACzB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAI,MAAM,CAAC;IAClB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX;;OAEG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAK,MAAM,EAAE,CAAC;IACnB,IAAI,EAAM,IAAI,CAAC;IACf,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAU,MAAM,EAAE,CAAC;IAC3B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACnB,GAAG,EAAE,OAAO,CAAC;IACb,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA;AAED,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG;IACf,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B,CAAA"}

package/dist/generated/route-planner-input.js

@@ -0,0 +1,2 @@
+/* This file was generated from JSON Schema using quicktype. Do not edit by hand. */
+export {};