@oscharko-dev/keiko-model-gateway 0.2.0

package/dist/promptEnhancer/validate.js

@@ -0,0 +1,144 @@
+// Prompt Enhancer validate stage (Epic #1307, Issue #1313; ADR-0044 §4/§5/§7).
+//
+// The validate stage is the authority gate of the enhancer lifecycle. It composes two deterministic
+// signals into one wire-safe `PromptSafetyAssessment`:
+//   1. the STRUCTURAL assessment from `keiko-contracts` (required safeguards present; AC1/AC2/AC5,
+//      no-authority, no-disclosure, output validation; trusted-section defense in depth), and
+//   2. the AUTHORITATIVE text-level detection from `keiko-security` (`detectPromptInjectionSignals`)
+//      run over (a) the candidate's TRUSTED sections — any injected/override/authority/secret content
+//      there is a blocking rejection (AC3), and (b) the UNTRUSTED user input — recorded for the audit
+//      trail and escalated to human review when an attack is detected, but never blocking, because the
+//      generated prompt isolates the input as data (AC2: untrusted content cannot override).
+//
+// The model gateway is allowed to depend on {contracts, security} (ADR-0019), so this is the natural
+// home for the stage that needs both — mirroring how the QI dispatch primitives live here. The stage
+// makes NO model call and grants NO authority (ADR-0044 §4): it produces an assessment artefact only.
+//
+// Determinism: pure. No IO, clock, or randomness.
+import { assessEnhancedPromptStructuralSafety, summarizePromptSafety, PROMPT_SAFETY_VIOLATION_DETAILS, } from "@oscharko-dev/keiko-contracts";
+import { detectPromptInjectionSignals, } from "@oscharko-dev/keiko-security";
+const SIGNAL_MAPPING = {
+    "instruction-override": {
+        code: "untrusted-instruction-override",
+        ruleId: "no-manipulative-or-injected-instructions",
+    },
+    "system-prompt-disclosure": {
+        code: "system-prompt-disclosure",
+        ruleId: "no-secret-or-system-prompt-disclosure",
+    },
+    "secret-exfiltration": {
+        code: "secret-request",
+        ruleId: "no-secret-or-system-prompt-disclosure",
+    },
+    "tool-authority-request": { code: "capability-grant-claim", ruleId: "no-authority-grant" },
+    "egress-request": { code: "capability-grant-claim", ruleId: "no-authority-grant" },
+    "manipulative-framing": {
+        code: "manipulative-instruction",
+        ruleId: "no-manipulative-or-injected-instructions",
+    },
+    "embedded-secret-material": {
+        code: "secret-request",
+        ruleId: "no-secret-or-system-prompt-disclosure",
+    },
+};
+const SEVERITY_RANK = {
+    info: 0,
+    warning: 1,
+    blocking: 2,
+};
+// The trusted instruction sections of a prompt, joined for the security scan. Excludes `input`, which
+// is the untrusted channel scanned separately.
+function trustedSectionsText(prompt) {
+    return [
+        prompt.role,
+        prompt.goal,
+        ...prompt.context,
+        ...prompt.taskDecomposition,
+        ...prompt.constraints,
+        ...prompt.groundingRules,
+        ...prompt.qualityCriteria,
+        ...prompt.uncertaintyHandling,
+        ...prompt.safetyRules,
+    ].join("\n");
+}
+function findingFor(signal, severity) {
+    const mapping = SIGNAL_MAPPING[signal.code];
+    return {
+        code: mapping.code,
+        ruleId: mapping.ruleId,
+        severity,
+        detail: PROMPT_SAFETY_VIOLATION_DETAILS[mapping.code],
+    };
+}
+// Deduplicate findings by violation code, keeping the most severe instance. Keeps the assessment
+// auditable without redundant rows when both the structural and security passes flag the same concern.
+function dedupeFindings(findings) {
+    const byCode = new Map();
+    for (const finding of findings) {
+        const existing = byCode.get(finding.code);
+        if (existing === undefined ||
+            SEVERITY_RANK[finding.severity] > SEVERITY_RANK[existing.severity]) {
+            byCode.set(finding.code, finding);
+        }
+    }
+    return [...byCode.values()];
+}
+/**
+ * Assess the safety of one Enhanced Prompt against the full validate-stage rule set. Pure. Combines
+ * the contracts structural assessment with the keiko-security text detector over the trusted sections
+ * (blocking on any injected/authority/secret content — AC3) and over the untrusted input (recorded as
+ * audit evidence; escalates to human review on a critical attack but never blocks — AC2). Returns a
+ * wire-safe `PromptSafetyAssessment` that is content-free and grants no authority.
+ */
+export function assessPromptSafety(args) {
+    const { prompt, analysis, input } = args;
+    const structural = assessEnhancedPromptStructuralSafety(prompt, analysis);
+    // (a) Trusted-section scan: any unsafe signal here is a blocking rejection (a safe generated prompt
+    // never contains it; a forged/tampered candidate would).
+    const trustedFindings = detectPromptInjectionSignals(trustedSectionsText(prompt)).map((signal) => findingFor(signal, "blocking"));
+    // (b) Untrusted-input scan: recorded for the audit trail. Critical attack attempts escalate to human
+    // review; nothing here is blocking because the prompt isolates the input as data.
+    const inputSignals = detectPromptInjectionSignals(input.text);
+    const inputFindings = inputSignals.map((signal) => findingFor(signal, signal.severity === "critical" ? "warning" : "info"));
+    const inputAttackDetected = inputSignals.some((signal) => signal.severity === "critical");
+    const findings = dedupeFindings([...structural.findings, ...trustedFindings, ...inputFindings]);
+    const requiresHumanReview = structural.requiresHumanReview || inputAttackDetected;
+    const { decision, verificationStatus } = summarizePromptSafety(findings, requiresHumanReview);
+    const leastPrivilege = withHumanApproval(structural.leastPrivilege, requiresHumanReview);
+    return {
+        schemaVersion: structural.schemaVersion,
+        promptId: prompt.promptId,
+        decision,
+        requiresHumanReview,
+        verificationStatus,
+        findings,
+        leastPrivilege,
+    };
+}
+function withHumanApproval(base, requiresHumanReview) {
+    if (!requiresHumanReview || base.includes("require-human-approval")) {
+        return base;
+    }
+    return [...base, "require-human-approval"];
+}
+/**
+ * Screen a generated candidate set through the validate stage (AC3 — candidates that add hidden
+ * assumptions, unapproved tool actions, secret requests, or manipulative instructions are rejected).
+ * Pure. Each candidate is assessed independently; the result partitions them into a usable `safe` set
+ * (decision !== "rejected") and a `rejected` set, each carrying its assessment for the audit trail.
+ */
+export function screenCandidatesForSafety(candidates, analysis, input) {
+    const safe = [];
+    const rejected = [];
+    for (const candidate of candidates) {
+        const assessment = assessPromptSafety({ prompt: candidate.prompt, analysis, input });
+        const screened = { candidate, assessment };
+        if (assessment.decision === "rejected") {
+            rejected.push(screened);
+        }
+        else {
+            safe.push(screened);
+        }
+    }
+    return { safe, rejected };
+}

package/dist/qualityIntelligence/budget.d.ts

@@ -0,0 +1,10 @@
+export interface QualityIntelligenceBudgetState {
+    readonly totalBudget: number;
+    readonly consumed: number;
+}
+export declare function createBudget(totalBudget: number): QualityIntelligenceBudgetState;
+export declare function reserveBudget(state: QualityIntelligenceBudgetState, cost: number): QualityIntelligenceBudgetState;
+export declare function releaseBudget(state: QualityIntelligenceBudgetState, refund: number): QualityIntelligenceBudgetState;
+export declare function isExhausted(state: QualityIntelligenceBudgetState): boolean;
+export declare function remainingBudget(state: QualityIntelligenceBudgetState): number;
+//# sourceMappingURL=budget.d.ts.map

package/dist/qualityIntelligence/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/budget.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,8BAA8B,CAGhF;AASD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,8BAA8B,EACrC,IAAI,EAAE,MAAM,GACX,8BAA8B,CAOhC;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,8BAA8B,EACrC,MAAM,EAAE,MAAM,GACb,8BAA8B,CAOhC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,8BAA8B,GAAG,OAAO,CAE1E;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,8BAA8B,GAAG,MAAM,CAE7E"}

package/dist/qualityIntelligence/budget.js

@@ -0,0 +1,38 @@
+// Quality Intelligence token-budget accounting (Epic #270, Issue #279).
+//
+// Pure-function budget state machine: reserve, release, exhaustion check. State is an
+// immutable shape — every mutating call returns a NEW state value. Negative reservations
+// and refunds are clamped to zero so callers cannot accidentally inflate or underflow the
+// budget.
+export function createBudget(totalBudget) {
+    const clamped = Number.isFinite(totalBudget) && totalBudget > 0 ? totalBudget : 0;
+    return Object.freeze({ totalBudget: clamped, consumed: 0 });
+}
+function clampCost(cost) {
+    if (!Number.isFinite(cost) || cost <= 0) {
+        return 0;
+    }
+    return cost;
+}
+export function reserveBudget(state, cost) {
+    const delta = clampCost(cost);
+    const nextConsumed = Math.min(state.totalBudget, state.consumed + delta);
+    return Object.freeze({
+        totalBudget: state.totalBudget,
+        consumed: nextConsumed,
+    });
+}
+export function releaseBudget(state, refund) {
+    const delta = clampCost(refund);
+    const nextConsumed = Math.max(0, state.consumed - delta);
+    return Object.freeze({
+        totalBudget: state.totalBudget,
+        consumed: nextConsumed,
+    });
+}
+export function isExhausted(state) {
+    return state.consumed >= state.totalBudget;
+}
+export function remainingBudget(state) {
+    return Math.max(0, state.totalBudget - state.consumed);
+}

package/dist/qualityIntelligence/cancellation.d.ts

@@ -0,0 +1,7 @@
+export interface QualityIntelligenceCancellationHandle {
+    readonly signal: AbortSignal;
+    readonly reasonKind: () => "timeout" | "external" | "none";
+    readonly dispose: () => void;
+}
+export declare function composeCancellationSignal(timeoutMs: number, external: AbortSignal | undefined): QualityIntelligenceCancellationHandle;
+//# sourceMappingURL=cancellation.d.ts.map

package/dist/qualityIntelligence/cancellation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/cancellation.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAsDD,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,WAAW,GAAG,SAAS,GAChC,qCAAqC,CAcvC"}

package/dist/qualityIntelligence/cancellation.js

@@ -0,0 +1,58 @@
+// Quality Intelligence cancellation composition (Epic #270, Issue #279).
+//
+// Composes an external AbortSignal with an internal profile-timeout into a single effective
+// signal. The dispatcher hands the resulting signal to the underlying ModelPort so it can
+// abort the in-flight call on EITHER the timeout firing OR the external signal aborting.
+// No timers leak: the caller MUST invoke `dispose()` once the call settles.
+function attachExternal(external, controller, reason) {
+    if (external === undefined) {
+        return () => {
+            /* nothing to detach */
+        };
+    }
+    if (external.aborted) {
+        reason.kind = "external";
+        controller.abort();
+        return () => {
+            /* already aborted */
+        };
+    }
+    const onAbort = () => {
+        reason.kind = "external";
+        controller.abort();
+    };
+    external.addEventListener("abort", onAbort, { once: true });
+    return () => {
+        external.removeEventListener("abort", onAbort);
+    };
+}
+function attachTimeout(timeoutMs, controller, reason) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return () => {
+            /* no timeout requested */
+        };
+    }
+    const timer = setTimeout(() => {
+        if (reason.kind === "none") {
+            reason.kind = "timeout";
+        }
+        controller.abort();
+    }, timeoutMs);
+    return () => {
+        clearTimeout(timer);
+    };
+}
+export function composeCancellationSignal(timeoutMs, external) {
+    const controller = new AbortController();
+    const reason = { kind: "none" };
+    const detachExternal = attachExternal(external, controller, reason);
+    const detachTimeout = attachTimeout(timeoutMs, controller, reason);
+    return Object.freeze({
+        signal: controller.signal,
+        reasonKind: () => reason.kind,
+        dispose: () => {
+            detachTimeout();
+            detachExternal();
+        },
+    });
+}

package/dist/qualityIntelligence/capabilityGate.d.ts

@@ -0,0 +1,13 @@
+import type { ModelCapability } from "@oscharko-dev/keiko-contracts";
+import type { ModelSelectionQuery } from "../model-selection.js";
+import type { QualityIntelligenceCapability, QualityIntelligenceTaskProfile } from "./taskProfiles.js";
+/**
+ * Project a profile's required QI capabilities onto the gateway `ModelSelectionQuery` constraints
+ * the selector understands. This is the WRITE side of the SAME capability mapping that `modelSupports`
+ * READS, kept in one file so auto-selection and the gate can never drift (Issue #762: a single shared
+ * capability mapping, never a per-stage duplicate). text → chat kind (every QI task profile is a chat
+ * task); structured-output → structuredOutput; function-calling → toolCalling; vision → supportsImageInput.
+ */
+export declare function buildSelectionQueryForCapabilities(required: readonly QualityIntelligenceCapability[]): ModelSelectionQuery;
+export declare function assertProfileCompatibleWithModel(profile: QualityIntelligenceTaskProfile, modelCapability: ModelCapability): void;
+//# sourceMappingURL=capabilityGate.d.ts.map

package/dist/qualityIntelligence/capabilityGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityGate.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/capabilityGate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EACV,6BAA6B,EAC7B,8BAA8B,EAC/B,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,SAAS,6BAA6B,EAAE,GACjD,mBAAmB,CAyBrB;AAED,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,8BAA8B,EACvC,eAAe,EAAE,eAAe,GAC/B,IAAI,CAWN"}

package/dist/qualityIntelligence/capabilityGate.js

@@ -0,0 +1,51 @@
+// Quality Intelligence capability gate (Epic #270, Issue #279).
+//
+// Asserts that a model's capability record satisfies the structural requirements of a QI
+// task profile. Throws a safe-error exception (no inputs, no secrets) on mismatch.
+import { QualityIntelligenceSafeErrorException, makeCapabilityMismatchError } from "./safeError.js";
+import { modelSupportsCapability } from "./capabilityMapping.js";
+/**
+ * Project a profile's required QI capabilities onto the gateway `ModelSelectionQuery` constraints
+ * the selector understands. This is the WRITE side of the SAME capability mapping that `modelSupports`
+ * READS, kept in one file so auto-selection and the gate can never drift (Issue #762: a single shared
+ * capability mapping, never a per-stage duplicate). text → chat kind (every QI task profile is a chat
+ * task); structured-output → structuredOutput; function-calling → toolCalling; vision → supportsImageInput.
+ */
+export function buildSelectionQueryForCapabilities(required) {
+    let structuredOutput;
+    let toolCalling;
+    let supportsImageInput;
+    for (const capability of required) {
+        switch (capability) {
+            case "text":
+                break;
+            case "structured-output":
+                structuredOutput = true;
+                break;
+            case "function-calling":
+                toolCalling = true;
+                break;
+            case "vision":
+                supportsImageInput = true;
+                break;
+        }
+    }
+    return {
+        kind: "chat",
+        ...(structuredOutput !== undefined ? { structuredOutput } : {}),
+        ...(toolCalling !== undefined ? { toolCalling } : {}),
+        ...(supportsImageInput !== undefined ? { supportsImageInput } : {}),
+    };
+}
+export function assertProfileCompatibleWithModel(profile, modelCapability) {
+    const missing = [];
+    for (const required of profile.requiredCapabilities) {
+        if (!modelSupportsCapability(required, modelCapability)) {
+            missing.push(required);
+        }
+    }
+    if (missing.length === 0) {
+        return;
+    }
+    throw new QualityIntelligenceSafeErrorException(makeCapabilityMismatchError(profile.id, missing));
+}

package/dist/qualityIntelligence/capabilityMapping.d.ts

@@ -0,0 +1,4 @@
+import type { ModelCapability } from "@oscharko-dev/keiko-contracts";
+import type { QualityIntelligenceCapability } from "./taskProfiles.js";
+export declare function modelSupportsCapability(capability: QualityIntelligenceCapability, model: ModelCapability): boolean;
+//# sourceMappingURL=capabilityMapping.d.ts.map

package/dist/qualityIntelligence/capabilityMapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityMapping.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/capabilityMapping.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AAEvE,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,6BAA6B,EACzC,KAAK,EAAE,eAAe,GACrB,OAAO,CAWT"}

package/dist/qualityIntelligence/capabilityMapping.js

@@ -0,0 +1,21 @@
+// Quality Intelligence capability mapping (Epic #270, Issue #279; consolidated under Epic #761).
+//
+// The single source of truth for the READ side of the QI-capability ⇄ model-capability mapping:
+// "does a model satisfy a required QI capability?". Both the capability gate
+// (assertProfileCompatibleWithModel) and the deterministic profile router (selectModelForProfile)
+// consume this one predicate, so they can never disagree on what a capability means. The WRITE-side
+// counterpart that projects required capabilities onto a gateway ModelSelectionQuery is
+// buildSelectionQueryForCapabilities (capabilityGate.ts), kept consistent with this READ side by the
+// capabilityGate tests.
+export function modelSupportsCapability(capability, model) {
+    switch (capability) {
+        case "text":
+            return model.kind === "chat";
+        case "vision":
+            return model.supportsImageInput;
+        case "structured-output":
+            return model.structuredOutput;
+        case "function-calling":
+            return model.toolCalling;
+    }
+}

package/dist/qualityIntelligence/circuitBreaker.d.ts

@@ -0,0 +1,26 @@
+export type QualityIntelligenceCircuitState = "closed" | "open" | "half-open";
+export interface QualityIntelligenceCircuitBreakerState {
+    readonly state: QualityIntelligenceCircuitState;
+    readonly consecutiveFailures: number;
+    readonly openedAtMs: number | null;
+}
+export interface QualityIntelligenceCircuitBreakerConfig {
+    readonly failureThreshold: number;
+    readonly cooldownMs: number;
+    readonly halfOpenProbes: number;
+}
+export declare const DEFAULT_QUALITY_INTELLIGENCE_CIRCUIT_BREAKER_CONFIG: QualityIntelligenceCircuitBreakerConfig;
+export declare function createCircuitBreakerState(): QualityIntelligenceCircuitBreakerState;
+export type QualityIntelligenceCircuitEvent = {
+    readonly kind: "success";
+} | {
+    readonly kind: "failure";
+} | {
+    readonly kind: "probe";
+} | {
+    readonly kind: "tick";
+    readonly nowMs: number;
+};
+export declare function transitionOn(state: QualityIntelligenceCircuitBreakerState, event: QualityIntelligenceCircuitEvent, config?: QualityIntelligenceCircuitBreakerConfig, nowMs?: number): QualityIntelligenceCircuitBreakerState;
+export declare function shouldAttempt(state: QualityIntelligenceCircuitBreakerState): boolean;
+//# sourceMappingURL=circuitBreaker.d.ts.map

package/dist/qualityIntelligence/circuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/circuitBreaker.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,+BAA+B,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE9E,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,KAAK,EAAE,+BAA+B,CAAC;IAChD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,uCAAuC;IACtD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,eAAO,MAAM,mDAAmD,EAAE,uCAK9D,CAAC;AAEL,wBAAgB,yBAAyB,IAAI,sCAAsC,CAMlF;AAED,MAAM,MAAM,+BAA+B,GACvC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA6DtD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,sCAAsC,EAC7C,KAAK,EAAE,+BAA+B,EACtC,MAAM,GAAE,uCAA6F,EACrG,KAAK,SAAI,GACR,sCAAsC,CAWxC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,sCAAsC,GAAG,OAAO,CAEpF"}

package/dist/qualityIntelligence/circuitBreaker.js

@@ -0,0 +1,78 @@
+// Quality Intelligence circuit breaker (Epic #270, Issue #279).
+//
+// Pure half-open state machine. The dispatcher records each model call outcome via
+// `transitionOn` and consults `state` to decide whether to attempt or skip a call. State is
+// immutable; every transition returns a new value. Thresholds are configurable but default
+// to a frozen constant tuned for QI workloads.
+export const DEFAULT_QUALITY_INTELLIGENCE_CIRCUIT_BREAKER_CONFIG = Object.freeze({
+    failureThreshold: 4,
+    cooldownMs: 30_000,
+    halfOpenProbes: 1,
+});
+export function createCircuitBreakerState() {
+    return Object.freeze({
+        state: "closed",
+        consecutiveFailures: 0,
+        openedAtMs: null,
+    });
+}
+function onSuccess() {
+    return Object.freeze({
+        state: "closed",
+        consecutiveFailures: 0,
+        openedAtMs: null,
+    });
+}
+function onFailure(state, config, nowMs) {
+    const nextFailures = state.consecutiveFailures + 1;
+    if (nextFailures >= config.failureThreshold) {
+        return Object.freeze({
+            state: "open",
+            consecutiveFailures: nextFailures,
+            openedAtMs: nowMs,
+        });
+    }
+    return Object.freeze({
+        state: state.state === "half-open" ? "open" : state.state,
+        consecutiveFailures: nextFailures,
+        openedAtMs: state.state === "half-open" ? nowMs : state.openedAtMs,
+    });
+}
+function onProbe(state) {
+    if (state.state === "open") {
+        return Object.freeze({
+            state: "half-open",
+            consecutiveFailures: state.consecutiveFailures,
+            openedAtMs: state.openedAtMs,
+        });
+    }
+    return state;
+}
+function onTick(state, config, nowMs) {
+    if (state.state !== "open" || state.openedAtMs === null) {
+        return state;
+    }
+    if (nowMs - state.openedAtMs >= config.cooldownMs) {
+        return Object.freeze({
+            state: "half-open",
+            consecutiveFailures: state.consecutiveFailures,
+            openedAtMs: state.openedAtMs,
+        });
+    }
+    return state;
+}
+export function transitionOn(state, event, config = DEFAULT_QUALITY_INTELLIGENCE_CIRCUIT_BREAKER_CONFIG, nowMs = 0) {
+    switch (event.kind) {
+        case "success":
+            return onSuccess();
+        case "failure":
+            return onFailure(state, config, nowMs);
+        case "probe":
+            return onProbe(state);
+        case "tick":
+            return onTick(state, config, event.nowMs);
+    }
+}
+export function shouldAttempt(state) {
+    return state.state !== "open";
+}

package/dist/qualityIntelligence/dispatcher.d.ts

@@ -0,0 +1,38 @@
+import type { ModelCapability, NormalizedResponse } from "@oscharko-dev/keiko-contracts";
+import type { QualityIntelligenceBudgetState } from "./budget.js";
+import { type QualityIntelligenceUntrustedEvidenceInput } from "./promptSegmentation.js";
+import { type QualityIntelligenceReplayCachePort } from "./replayCache.js";
+import type { QualityIntelligenceTaskProfile } from "./taskProfiles.js";
+import type { ModelProviderConfig, ProviderAdapter } from "../types.js";
+export interface QualityIntelligenceDispatcherArgs {
+    readonly profile: QualityIntelligenceTaskProfile;
+    readonly instruction: string;
+    readonly evidence: readonly QualityIntelligenceUntrustedEvidenceInput[];
+    readonly model: ModelCapability;
+    readonly providerConfig: ModelProviderConfig;
+    readonly port: ProviderAdapter;
+    readonly cache: QualityIntelligenceReplayCachePort<NormalizedResponse>;
+    readonly budget: QualityIntelligenceBudgetState;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface QualityIntelligenceDispatcherResult {
+    readonly response: NormalizedResponse;
+    readonly budget: QualityIntelligenceBudgetState;
+    readonly cacheHit: boolean;
+}
+/**
+ * Compose a single Quality Intelligence model call with capability gate, budget reservation,
+ * prompt segmentation, replay cache, composed timeout/cancellation, and qi/* safe-error shaping.
+ *
+ * REUSABLE PRIMITIVE — NOT the current live path. The live generation/judge runtime
+ * (`keiko-server` generationPort.ts / judgePort.ts) deliberately calls the gateway `ModelPort`
+ * directly and applies its own capability gate + prompt segmentation, inheriting timeout / retry /
+ * circuit-breaking from the gateway resilience layer (`resilience.ts`) — the same machinery Chat
+ * and grounded-QA use. This dispatcher (and its budget / replayCache / circuitBreaker / cancellation
+ * helpers) is the ported-from-Test-Intelligence composition kept available for a future multi-call
+ * QI flow that wants combined budget + cache + circuit semantics at one call site. It must NOT be
+ * force-wired into the live ports (that would change the resilience contract) and must NOT be
+ * deleted as "dead code" (#279: ported TI ideas live here as generic gateway capabilities).
+ */
+export declare function dispatchQualityIntelligenceRequest(args: QualityIntelligenceDispatcherArgs): Promise<QualityIntelligenceDispatcherResult>;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/qualityIntelligence/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/dispatcher.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAGV,eAAe,EACf,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAElE,OAAO,EAGL,KAAK,yCAAyC,EAC/C,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,kCAAkC,EACxC,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAExE,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,OAAO,EAAE,8BAA8B,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,yCAAyC,EAAE,CAAC;IACxE,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,kCAAkC,CAAC,kBAAkB,CAAC,CAAC;IACvE,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAuED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kCAAkC,CACtD,IAAI,EAAE,iCAAiC,GACtC,OAAO,CAAC,mCAAmC,CAAC,CAuC9C"}

package/dist/qualityIntelligence/dispatcher.js

@@ -0,0 +1,116 @@
+// Quality Intelligence dispatcher (Epic #270, Issue #279).
+//
+// Routes a Quality Intelligence model call through the existing gateway ModelPort. The
+// dispatcher COMPOSES — it never instantiates a provider SDK. It performs (in order):
+//   1. capability check                       (M1: capabilityGate)
+//   2. budget reservation                     (M2: budget)
+//   3. prompt segmentation                    (M1: promptSegmentation)
+//   4. cache lookup                           (M2: replayCache)
+//   5. wire-prompt assembly                   (this file, pure)
+//   6. ModelPort.call(...) with composed signal and profile timeout (this file)
+//   7. cache store (if cacheable)             (M2: replayCache)
+//   8. error -> qi/* safe-error shape         (M1: safeError)
+// The ModelPort itself is the gateway's existing ProviderAdapter — proven at the type
+// level by the parameter signature.
+import { composeCancellationSignal } from "./cancellation.js";
+import { isExhausted, reserveBudget } from "./budget.js";
+import { assertProfileCompatibleWithModel } from "./capabilityGate.js";
+import { buildPromptSegments, } from "./promptSegmentation.js";
+import { deriveReplayCacheKey, isCacheable, } from "./replayCache.js";
+import { QualityIntelligenceSafeErrorException, makeBudgetExhaustedError, makeCancelledError, makeProviderError, makeTimeoutError, } from "./safeError.js";
+function assembleMessages(segments) {
+    const evidenceBlock = segments.evidenceUntrusted.length === 0
+        ? ""
+        : segments.evidenceUntrusted
+            .map((e) => `<qi-evidence kind="${e.kind}">${e.value}</qi-evidence>`)
+            .join("\n");
+    const userContent = evidenceBlock === ""
+        ? segments.instructionTrusted
+        : `${segments.instructionTrusted}\n${evidenceBlock}`;
+    return Object.freeze([
+        Object.freeze({ role: "system", content: segments.systemTrusted }),
+        Object.freeze({ role: "user", content: userContent }),
+    ]);
+}
+function buildGatewayRequest(modelId, segments, signal) {
+    return Object.freeze({
+        modelId,
+        messages: assembleMessages(segments),
+        stream: false,
+        cancellationSignal: signal,
+    });
+}
+function classifyAndThrow(profileId, timeoutMs, reasonKind, caught) {
+    if (caught instanceof QualityIntelligenceSafeErrorException) {
+        throw caught;
+    }
+    if (reasonKind === "timeout") {
+        throw new QualityIntelligenceSafeErrorException(makeTimeoutError(profileId, timeoutMs));
+    }
+    if (reasonKind === "external") {
+        throw new QualityIntelligenceSafeErrorException(makeCancelledError(profileId));
+    }
+    throw new QualityIntelligenceSafeErrorException(makeProviderError(profileId));
+}
+async function invokePort(ctx) {
+    const handle = composeCancellationSignal(ctx.profile.timeoutMsHint, ctx.externalSignal);
+    try {
+        const request = buildGatewayRequest(ctx.modelId, ctx.segments, handle.signal);
+        return await ctx.port.call(request, ctx.providerConfig);
+    }
+    catch (caught) {
+        classifyAndThrow(ctx.profile.id, ctx.profile.timeoutMsHint, handle.reasonKind(), caught);
+    }
+    finally {
+        handle.dispose();
+    }
+}
+/**
+ * Compose a single Quality Intelligence model call with capability gate, budget reservation,
+ * prompt segmentation, replay cache, composed timeout/cancellation, and qi/* safe-error shaping.
+ *
+ * REUSABLE PRIMITIVE — NOT the current live path. The live generation/judge runtime
+ * (`keiko-server` generationPort.ts / judgePort.ts) deliberately calls the gateway `ModelPort`
+ * directly and applies its own capability gate + prompt segmentation, inheriting timeout / retry /
+ * circuit-breaking from the gateway resilience layer (`resilience.ts`) — the same machinery Chat
+ * and grounded-QA use. This dispatcher (and its budget / replayCache / circuitBreaker / cancellation
+ * helpers) is the ported-from-Test-Intelligence composition kept available for a future multi-call
+ * QI flow that wants combined budget + cache + circuit semantics at one call site. It must NOT be
+ * force-wired into the live ports (that would change the resilience contract) and must NOT be
+ * deleted as "dead code" (#279: ported TI ideas live here as generic gateway capabilities).
+ */
+export async function dispatchQualityIntelligenceRequest(args) {
+    assertProfileCompatibleWithModel(args.profile, args.model);
+    if (isExhausted(args.budget)) {
+        throw new QualityIntelligenceSafeErrorException(makeBudgetExhaustedError(args.profile.id));
+    }
+    const nextBudget = reserveBudget(args.budget, args.profile.tokenBudgetHint);
+    const segments = buildPromptSegments(args.profile, args.instruction, args.evidence);
+    const cacheKey = await deriveReplayCacheKey(args.profile, segments, args.model.id);
+    if (isCacheable(args.profile)) {
+        const cached = args.cache.get(cacheKey);
+        if (cached !== undefined) {
+            return Object.freeze({
+                response: cached,
+                budget: nextBudget,
+                cacheHit: true,
+            });
+        }
+    }
+    const response = await invokePort({
+        profile: args.profile,
+        port: args.port,
+        providerConfig: args.providerConfig,
+        modelId: args.model.id,
+        segments,
+        externalSignal: args.signal,
+    });
+    if (isCacheable(args.profile)) {
+        args.cache.set(cacheKey, response);
+    }
+    return Object.freeze({
+        response,
+        budget: nextBudget,
+        cacheHit: false,
+    });
+}