@dcdr/contracts 1.9.6

package/dist/execution.contract.d.ts

@@ -0,0 +1,240 @@
+import { ExecutionError } from "./errors.contract";
+import { Message } from "./messages.contract";
+import { Intent } from "./intent.contract";
+import { IntentProvider } from "./provider.contract";
+/**
+ * A single execution request coming into the gateway.
+ * The backend typically calls this and later writes AICallLog itself.
+ */
+export interface ExecuteIntentRequest {
+    context?: ExecutionContext;
+    /**
+     * Optional template variables for prompt rendering.
+     * If omitted, gateway derives variables from `input`.
+     */
+    vars?: Record<string, unknown>;
+    /**
+     * Optional routing hints from backend.
+     * Useful for debugging or forcing a provider/implementation temporarily.
+     */
+    routing?: {
+        preferProviders?: IntentProvider[];
+        denyProviders?: IntentProvider[];
+        forceImplementationId?: string | null;
+        allowFallback?: boolean;
+        maxAttempts?: number;
+    };
+}
+/**
+ * One attempt in an execution (for retries/fallback reporting).
+ * This is gold for debugging and later AICallLog correlation.
+ */
+export interface ExecutionAttemptReport {
+    attempt: number;
+    provider: IntentProvider;
+    implementationId: string;
+    status: ExecutionStatus;
+    latencyMs: number;
+    error: ExecutionError | null;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    runHash?: string | null;
+    cached: boolean;
+}
+/**
+ * Final execution report returned by the gateway.
+ * The backend should persist the relevant fields into AICallLog.
+ */
+export interface ExecutionReport {
+    sessionId: string;
+    appId: string;
+    context?: ExecutionContext;
+    gatewayRequestId: string;
+    intent: Intent;
+    /**
+     * Prompt identity used for reproducibility.
+     * Backend should persist at least id+version+sha256.
+     */
+    prompt: {
+        id: string;
+        version: string;
+        sha256: string;
+    };
+    /** Final chosen provider/implementation. */
+    finalImplementation: {
+        provider: IntentProvider;
+        model: string;
+        implementationId: string;
+        latencyMs: number;
+    };
+    /** All attempts (including failures). */
+    attempts: ExecutionAttemptReport[];
+    /** Aggregate usage if available. */
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    /**
+     * Timing breakdown for this execution.
+     *
+     * Notes:
+     * - All `*Ms` fields are durations in milliseconds.
+     * - `startedAt`/`endedAt` are wall-clock ISO strings (for correlation/logs).
+     * - Duration fields are best-effort and computed by the gateway; they can differ slightly
+     *   from sums of attempt latencies due to rounding and internal scheduling.
+     */
+    timing: {
+        /** Wall-clock start time (ISO). */
+        startedAt: string;
+        /** Wall-clock end time (ISO). */
+        endedAt: string;
+        /** Total end-to-end latency as measured by the gateway. */
+        latencyMs: number;
+        /**
+         * Gateway-only overhead excluding provider execution time (best-effort).
+         *
+          * Relationship (approx):
+          * - gatewayOverheadMs ≈ latencyMs - providerTotalMs
+          *
+         * This includes (among other things):
+         * - request validation
+         * - configuration/registry lookup
+         * - prompt rendering / template preparation
+         * - routing & candidate selection
+         * - retry backoff/jitter waits between attempts
+         * - response shaping (parsing/validation) and report building
+         */
+        gatewayOverheadMs?: number;
+        /**
+         * Time spent in the gateway BEFORE the first provider call (best-effort).
+         * Intended to capture validation + prompt render + routing.
+         */
+        gatewayPreProviderMs?: number;
+        /**
+         * Time spent in the gateway AFTER provider calls until the response/report is ready (best-effort).
+         * This typically includes output parsing/validation and response construction.
+         */
+        gatewayPostProviderMs?: number;
+        /**
+         * Sum of provider execution time across all attempts (best-effort).
+         *
+         * This is the time spent waiting for the provider(s)/LLM(s) to return, including retries/fallback.
+         */
+        providerTotalMs?: number;
+    };
+    /** Output validation summary. */
+    validation?: {
+        parsed?: boolean;
+        schemaOk?: boolean;
+        errors?: string[];
+    };
+    /** The bundle version used during this execution (helps debugging). */
+    configVersion?: string;
+    problemHash?: string | null;
+    runHash?: string | null;
+    outputHash?: string | null;
+    cached: boolean;
+}
+export declare enum ExecutionStatus {
+    OK = "OK",
+    ERROR = "ERROR"
+}
+/**
+ * Response object returned by the gateway.
+ * Keep this stable; it's your public internal contract.
+ */
+export interface ExecuteIntentResponse {
+    status: ExecutionStatus;
+    /** The input */
+    input: Message[];
+    /** Parsed result (if ok). */
+    output?: any;
+    /** Error (if error). */
+    error?: ExecutionError;
+    /** Execution report for backend logging. */
+    report: ExecutionReport;
+}
+/**
+ * Context info for logging and analytics.
+ */
+export interface ExecutionContext {
+    [key: string]: any;
+}
+/**
+ * Streaming execution event type names.
+ *
+ * Notes
+ * - These strings are used as SSE `event:` names.
+ * - Keep values stable (wire-level behavior).
+ */
+export declare enum ExecutionStreamEventType {
+    META = "meta",
+    DELTA = "delta",
+    FINAL = "final",
+    ERROR = "error"
+}
+/**
+ * Metadata emitted at the start of a streaming execution.
+ */
+export interface ExecutionStreamMetaEventData {
+    /** Gateway-generated correlation ID for this execution. */
+    gatewayRequestId: string;
+    /** Intent name being executed. */
+    intent: Intent;
+    /** ISO timestamp for when the stream started (gateway wall-clock). */
+    startedAt: string;
+}
+/**
+ * A text delta emitted during streaming generation.
+ *
+ * Notes
+ * - v1 focuses on text deltas only.
+ * - Providers that do not support native streaming may emit zero delta events.
+ */
+export interface ExecutionStreamDeltaEventData {
+    text: string;
+}
+/**
+ * Final execution payload emitted at the end of the stream.
+ *
+ * Notes
+ * - This is the same response shape as non-streaming `executeIntent`.
+ * - Even error executions should be delivered as a final response where possible.
+ */
+export interface ExecutionStreamFinalEventData {
+    response: ExecuteIntentResponse;
+}
+/**
+ * Fatal streaming error emitted when the stream cannot produce a final response.
+ *
+ * Notes
+ * - Prefer emitting `final` with `status=ERROR` when possible.
+ */
+export interface ExecutionStreamErrorEventData {
+    error: ExecutionError;
+}
+/** Streaming `meta` event envelope. */
+export interface ExecutionStreamMetaEvent {
+    type: ExecutionStreamEventType.META;
+    data: ExecutionStreamMetaEventData;
+}
+/** Streaming `delta` event envelope. */
+export interface ExecutionStreamDeltaEvent {
+    type: ExecutionStreamEventType.DELTA;
+    data: ExecutionStreamDeltaEventData;
+}
+/** Streaming `final` event envelope. */
+export interface ExecutionStreamFinalEvent {
+    type: ExecutionStreamEventType.FINAL;
+    data: ExecutionStreamFinalEventData;
+}
+/** Streaming `error` event envelope. */
+export interface ExecutionStreamErrorEvent {
+    type: ExecutionStreamEventType.ERROR;
+    data: ExecutionStreamErrorEventData;
+}
+//# sourceMappingURL=execution.contract.d.ts.map

package/dist/execution.contract.d.ts.map

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

package/dist/execution.contract.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionStreamEventType = exports.ExecutionStatus = void 0;
+var ExecutionStatus;
+(function (ExecutionStatus) {
+    ExecutionStatus["OK"] = "OK";
+    ExecutionStatus["ERROR"] = "ERROR";
+})(ExecutionStatus || (exports.ExecutionStatus = ExecutionStatus = {}));
+/**
+ * Streaming execution event type names.
+ *
+ * Notes
+ * - These strings are used as SSE `event:` names.
+ * - Keep values stable (wire-level behavior).
+ */
+var ExecutionStreamEventType;
+(function (ExecutionStreamEventType) {
+    ExecutionStreamEventType["META"] = "meta";
+    ExecutionStreamEventType["DELTA"] = "delta";
+    ExecutionStreamEventType["FINAL"] = "final";
+    ExecutionStreamEventType["ERROR"] = "error";
+})(ExecutionStreamEventType || (exports.ExecutionStreamEventType = ExecutionStreamEventType = {}));

package/dist/http.contract.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Canonical HTTP params shape used by runtime for request customization.
+ *
+ * IMPORTANT:
+ * - No multi-value headers yet. Duplicates should be resolved by the runtime merge rules.
+ */
+export interface NameValuePair {
+    name: string;
+    value: string;
+}
+export interface HttpRequestParams {
+    headers?: NameValuePair[];
+    query?: NameValuePair[];
+    /**
+     * Convenience field to build the outgoing request Cookie header.
+     * Runtime will serialize these pairs into a single `Cookie` header.
+     */
+    cookies?: NameValuePair[];
+}
+//# sourceMappingURL=http.contract.d.ts.map

package/dist/http.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.contract.d.ts","sourceRoot":"","sources":["../src/http.contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IAExB;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;CAC3B"}

package/dist/http.contract.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Canonical HTTP params shape used by runtime for request customization.
+ *
+ * IMPORTANT:
+ * - No multi-value headers yet. Duplicates should be resolved by the runtime merge rules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/implementations.contract.d.ts

@@ -0,0 +1,120 @@
+import { IntentProvider } from "./provider.contract";
+import { HttpRequestParams } from "./http.contract";
+/**
+ * Time window constraints for an implementation.
+ * If present, the implementation is eligible ONLY within these windows.
+ */
+export interface ExecutionWindow {
+    /**
+     * UTC window: Bit 0..6 represent days of week (recommended: 0=Mon ... 6=Sun).
+     */
+    daysMask?: number;
+    /**
+     * UTC window: Bit 0..23 represent hour slots (bit0 = 00:00-01:00, bit23 = 23:00-00:00).
+     */
+    hoursMask?: number;
+    /**
+     * Whether the execution window must be enforced (if false, the gateway may ignore it and use the implementation anyway).
+     */
+    active?: boolean;
+}
+/**
+ * Time window constraints for an implementation.
+ * If present, the implementation is eligible ONLY within these windows.
+ */
+export interface ExecutionWindow {
+    /**
+     * UTC window: Bit 0..6 represent days of week (recommended: 0=Mon ... 6=Sun).
+     */
+    daysMask?: number;
+    /**
+     * UTC window: Bit 0..23 represent hour slots (bit0 = 00:00-01:00, bit23 = 23:00-00:00).
+     */
+    hoursMask?: number;
+    /**
+     * Whether the execution window must be enforced (if false, the gateway may ignore it and use the implementation anyway).
+     */
+    active?: boolean;
+}
+/**
+ * Implementation contract: describes how a given provider/model endpoint can be used.
+ * This is pure configuration; provider adapters interpret it.
+ */
+export interface ImplementationContract {
+    /** Unique implementation ID (stable, e.g., UUID). */
+    id: string;
+    /** Provider type (OFFICE, OPEN_AI, GROK...). */
+    provider: IntentProvider;
+    /** Human-readable name for this implementation (e.g., "openai-format-parser"). */
+    name: string;
+    /** Version of this implementation (e.g., "2026-02-18.2"). */
+    version: string;
+    /**
+     * SHA256 hash of the canonical implementation payload (stable JSON serialization).
+     * Useful as an immutable fingerprint / audit trail.
+     */
+    sha256: string;
+    /**
+     * Precomputed semantic hash (stable across irrelevant formatting changes).
+     * This MUST be exported from backend and used for:
+     * - runHash (execution dedupe)
+     */
+    semanticHash: string;
+    /**
+     * Technical model identifier for the provider.
+     * Examples:
+     * - "gpt-4.1-mini"
+     * - "Qwen3-4B-Instruct-2507"
+     * - "grok-2"
+     */
+    model: string;
+    /** Human readable description for diagnostics. */
+    description?: string;
+    /** Execution endpoint (HTTP, OpenAI-compatible, Dcdr, etc). */
+    endpoint: string;
+    /**
+     * Auth configuration (token, headers, mTLS, etc).
+     * NOTE: This must NOT affect semantic hashing in runtime.
+     */
+    authConfig?: HttpRequestParams;
+    /** Optional reference to a credential contract (by id) for provider-specific auth config */
+    credentialRef?: string;
+    /**
+     * Provider-specific runtime defaults (modelName, temperature, top_p, max_tokens, response_format, etc).
+     * NOTE: AISemantics will filter keys when building runtimeParamsKey.
+     */
+    runtimeConfig?: any;
+    /** Is this implementation usable. */
+    active: boolean;
+    /** Weight for load balancing or selection purposes. */
+    weight?: number;
+    order?: number;
+    /**
+     * Whether this implementation should be considered local / on-prem / office-side.
+     * Useful for LOCAL_FIRST execution policies.
+     */
+    local?: boolean;
+    /**
+     * Relative cost score for policy-based selection.
+     * Lower values mean cheaper implementations.
+     * Used by CHEAPEST_FIRST policies.
+     */
+    costScore?: number;
+    /**
+     * Relative latency score for policy-based selection.
+     * Lower values mean faster implementations.
+     * Used by FASTEST_FIRST policies.
+     */
+    latencyScore?: number;
+    /**
+     * Relative quality score for policy-based selection.
+     * Higher values mean better expected output quality.
+     * Used by QUALITY_FIRST policies.
+     */
+    qualityScore?: number;
+    trackingIOProbability?: number;
+    cacheTTLSeconds?: number;
+    /** Execution window constraints. */
+    executionWindow?: ExecutionWindow;
+}
+//# sourceMappingURL=implementations.contract.d.ts.map

package/dist/implementations.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implementations.contract.d.ts","sourceRoot":"","sources":["../src/implementations.contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAE9B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAGD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAE9B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAGD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IAErC,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IAEX,gDAAgD;IAChD,QAAQ,EAAE,cAAc,CAAC;IAEzB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IAEb,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAG/B,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB;;;OAGG;IACH,aAAa,CAAC,EAAE,GAAG,CAAC;IAEpB,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;IAEhB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,oCAAoC;IACpC,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC"}

package/dist/implementations.contract.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export * from "./control.contract";
+export * from "./errors.contract";
+export * from "./execution.contract";
+export * from "./implementations.contract";
+export * from "./messages.contract";
+export * from "./intent.contract";
+export * from "./policies.contract";
+export * from "./prompts.contract";
+export * from "./session.contract";
+export * from "./logs.contract";
+export * from "./provider.contract";
+export * from "./credentials.contract";
+export * from "./http.contract";
+export * from "./entitlements.contract";
+export * from "./service-tokens.contract";
+export * from "./capabilities.contract";
+export * from "./subscription.contract";
+export * from "./runtime.client";
+export * from "./utils.contract";
+export * from "./prompt-variable-schema.contract";
+export * from "./registry.stats.contract";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mCAAmC,CAAC;AAClD,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./control.contract"), exports);
+__exportStar(require("./errors.contract"), exports);
+__exportStar(require("./execution.contract"), exports);
+__exportStar(require("./implementations.contract"), exports);
+__exportStar(require("./messages.contract"), exports);
+__exportStar(require("./intent.contract"), exports);
+__exportStar(require("./policies.contract"), exports);
+__exportStar(require("./prompts.contract"), exports);
+__exportStar(require("./session.contract"), exports);
+__exportStar(require("./logs.contract"), exports);
+__exportStar(require("./provider.contract"), exports);
+__exportStar(require("./credentials.contract"), exports);
+__exportStar(require("./http.contract"), exports);
+__exportStar(require("./entitlements.contract"), exports);
+__exportStar(require("./service-tokens.contract"), exports);
+__exportStar(require("./capabilities.contract"), exports);
+__exportStar(require("./subscription.contract"), exports);
+__exportStar(require("./runtime.client"), exports);
+__exportStar(require("./utils.contract"), exports);
+__exportStar(require("./prompt-variable-schema.contract"), exports);
+__exportStar(require("./registry.stats.contract"), exports);

package/dist/intent.contract.d.ts

@@ -0,0 +1,137 @@
+import { ImplementationContract } from "./implementations.contract";
+import { RetryPolicy, ExecutionPolicy } from "./policies.contract";
+import { PromptTemplate, PromptVariable } from "./prompts.contract";
+export type Intent = string;
+/**
+ * Supported intent execution types.
+ *
+ * This defines the type of task the intent performs and which
+ * provider capabilities are required.
+ */
+export declare enum IntentType {
+    /**
+     * Standard conversational or prompt-response interaction.
+     *
+     * Examples:
+     * - Q&A
+     * - summarization
+     * - reasoning
+     * - structured output generation
+     */
+    CHAT = "CHAT",
+    /**
+     * Text embedding generation.
+     *
+     * Examples:
+     * - semantic search
+     * - vector indexing
+     * - similarity comparison
+     */
+    EMBEDDING = "EMBEDDING",
+    /**
+     * Image generation.
+     *
+     * Examples:
+     * - DALL·E
+     * - diffusion models
+     */
+    IMAGE_GENERATION = "IMAGE_GENERATION",
+    /**
+     * Image understanding / multimodal analysis.
+     *
+     * Examples:
+     * - vision LLMs
+     * - OCR-assisted models
+     */
+    IMAGE_ANALYSIS = "IMAGE_ANALYSIS",
+    /**
+     * Audio transcription.
+     *
+     * Examples:
+     * - Whisper
+     * - speech-to-text models
+     */
+    SPEECH_TO_TEXT = "SPEECH_TO_TEXT",
+    /**
+     * Audio generation / text-to-speech.
+     */
+    TEXT_TO_SPEECH = "TEXT_TO_SPEECH",
+    /**
+     * Multimodal tasks combining text + images + audio.
+     */
+    MULTIMODAL = "MULTIMODAL",
+    /**
+     * Deterministic tool execution.
+     *
+     * Examples:
+     * - HTTP calls
+     * - scripts
+     * - external API connectors
+     */
+    TOOL = "TOOL",
+    /**
+     * Internal deterministic rule engine.
+     */
+    RULE_ENGINE = "RULE_ENGINE"
+}
+/**
+ * A single intent contract.
+ * This is what the gateway uses to execute requests in a provider-agnostic way.
+ */
+export interface IntentContract {
+    id: string;
+    /** Semantic intent (e.g., "name_processor", "format_parser"). */
+    intent: Intent;
+    /** Intent execution type */
+    type: IntentType;
+    /** Optional human-friendly name for diagnostics/UI (can equal intent). */
+    name?: string;
+    /** Global enable/disable for this intent. */
+    active: boolean;
+    /** Human readable description for diagnostics. */
+    description?: string;
+    /**
+     * Input schema (JSON Schema or custom prompt schema).
+     * The gateway may validate input before running providers.
+     */
+    inputSchema?: Record<string, PromptVariable>;
+    /**
+     * Output schema (JSON Schema or custom prompt schema).
+     * The gateway may validate output and trigger repair/fallback when it fails.
+     */
+    outputSchema?: Record<string, PromptVariable>;
+    /**
+     * Active prompt template for this intent.
+     * Versioned + hashed for reproducibility.
+     */
+    defaultPrompt: PromptTemplate;
+    /**
+     * Optional alternate prompt template for canary/A/B testing.
+     */
+    canaryPrompt?: PromptTemplate;
+    /**
+     * Weight for selecting the canary prompt (e.g., 0.1 for 10% traffic).
+     * The gateway should use this to randomly route requests to the canary prompt.
+     */
+    canaryPromptWeight?: number;
+    /**
+     * Execution policy for selecting and prioritizing implementations.
+     */
+    executionPolicy?: ExecutionPolicy;
+    /**
+     * Retry/fallback policy for this intent.
+     * This should be centrally configured from your backend UI.
+     */
+    retryPolicy: RetryPolicy;
+    /**
+     * Implementations available for this intent.
+     * The gateway selects candidates based on the execution policy first,
+     * then applies retry/fallback logic if needed.
+     */
+    implementations: ImplementationContract[];
+    /**
+     * Optional tags for future filtering (e.g., sector, "strict_json", etc.).
+     */
+    tags?: string[];
+}
+//# sourceMappingURL=intent.contract.d.ts.map

package/dist/intent.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.contract.d.ts","sourceRoot":"","sources":["../src/intent.contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAoB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIpE,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAG5B;;;;;GAKG;AACH,oBAAY,UAAU;IAEpB;;;;;;;;OAQG;IACH,IAAI,SAAS;IAEb;;;;;;;OAOG;IACH,SAAS,cAAc;IAEvB;;;;;;OAMG;IACH,gBAAgB,qBAAqB;IAErC;;;;;;OAMG;IACH,cAAc,mBAAmB;IAEjC;;;;;;OAMG;IACH,cAAc,mBAAmB;IAEjC;;OAEG;IACH,cAAc,mBAAmB;IAEjC;;OAEG;IACH,UAAU,eAAe;IAEzB;;;;;;;OAOG;IACH,IAAI,SAAS;IAEb;;OAEG;IACH,WAAW,gBAAgB;CAC5B;AAID;;;GAGG;AACH,MAAM,WAAW,cAAc;IAE7B,EAAE,EAAE,MAAM,CAAC;IAEX,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IAEf,4BAA4B;IAC5B,IAAI,EAAE,UAAU,CAAC;IAEjB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAC;IAEhB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE7C;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE9C;;;OAGG;IACH,aAAa,EAAE,cAAc,CAAC;IAE9B;;OAEG;IACH,YAAY,CAAC,EAAE,cAAc,CAAC;IAE9B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC;IAEzB;;;;OAIG;IACH,eAAe,EAAE,sBAAsB,EAAE,CAAC;IAE1C;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB"}