ai-runtime-engine 1.1.0

package/dist/core/router/normalize.js

@@ -0,0 +1,119 @@
+/**
+ * Phase 1 — task normalization. Turns a public `RunRequest` + the task registry into a
+ * `NormalizedTask` (required/preferred capabilities, strategy, sensitivity) plus a provider-agnostic
+ * request template that the executor completes with a chosen model. An UNKNOWN task never fails: its
+ * requirements are inferred from the request's own hints and its confidence is stamped low.
+ */
+function toInput(input) {
+    if (typeof input === 'string')
+        return { text: input };
+    return input;
+}
+function requirementsFrom(reqs, minEvidence) {
+    if (!reqs)
+        return [];
+    const out = [];
+    const groups = ['input', 'output', 'intelligence', 'agent'];
+    for (const group of groups) {
+        for (const key of reqs[group] ?? []) {
+            out.push(minEvidence ? { group, key, minEvidence } : { group, key });
+        }
+    }
+    return out;
+}
+/** Infer a minimal, lenient (`inferred`-floor) requirement set for an unknown task from request hints. */
+function inferRequirements(req, parts) {
+    const out = [{ group: 'intelligence', key: 'reasoning', minEvidence: 'inferred' }];
+    const fmt = req.output?.format;
+    if (fmt === 'code')
+        out.push({ group: 'intelligence', key: 'code_generation', minEvidence: 'inferred' }, { group: 'output', key: 'code', minEvidence: 'inferred' });
+    if (fmt === 'json' || fmt === 'structured_output')
+        out.push({ group: 'output', key: fmt, minEvidence: 'inferred' });
+    if (parts?.some((p) => p.kind === 'image'))
+        out.push({ group: 'input', key: 'image', minEvidence: 'inferred' });
+    if (parts?.some((p) => p.kind === 'file' || p.kind === 'pdf'))
+        out.push({ group: 'input', key: 'file', minEvidence: 'inferred' });
+    if (req.tools && req.tools.length > 0)
+        out.push({ group: 'agent', key: 'tool_calling', minEvidence: 'inferred' });
+    return out;
+}
+/** Merge requirement lists, de-duplicating by (group,key) and keeping the stricter evidence floor. */
+function mergeRequirements(...lists) {
+    const byKey = new Map();
+    for (const list of lists) {
+        for (const r of list) {
+            const k = `${r.group}:${r.key}`;
+            const existing = byKey.get(k);
+            if (!existing)
+                byKey.set(k, r);
+            else {
+                // keep the stricter floor
+                const rankMap = { unsupported: 0, unknown: 1, inferred: 2, documented: 3, verified: 4 };
+                const a = rankMap[existing.minEvidence ?? 'documented'];
+                const b = rankMap[r.minEvidence ?? 'documented'];
+                if (b > a)
+                    byKey.set(k, r);
+            }
+        }
+    }
+    return [...byKey.values()];
+}
+export function normalize(req, tasks, config) {
+    const def = tasks.lookup(req.task);
+    const input = toInput(req.input);
+    const sensitivity = req.sensitivity ?? config.privacy.defaultSensitivity;
+    const explicitReqs = requirementsFrom(req.requirements);
+    let required;
+    let preferred;
+    let minContextWindow;
+    let output = req.output ?? def?.output;
+    let strategy;
+    let requireLocal = false;
+    let confidence;
+    if (def) {
+        required = mergeRequirements(def.required, explicitReqs);
+        preferred = def.preferred ?? [];
+        minContextWindow = req.requirements?.minContextWindow ?? def.minContextWindow;
+        strategy = req.strategy ?? def.defaultStrategy ?? config.strategy;
+        requireLocal = def.privacy?.requireLocal ?? false;
+        confidence = 1;
+    }
+    else {
+        // Unknown task: infer from hints, keep it lenient, and lower confidence.
+        required = mergeRequirements(inferRequirements(req, input.parts), explicitReqs);
+        preferred = [];
+        minContextWindow = req.requirements?.minContextWindow;
+        strategy = req.strategy ?? config.strategy;
+        confidence = 0.5;
+    }
+    if (req.provider)
+        strategy = 'provider-specific';
+    const template = {
+        taskId: def?.id ?? req.task,
+        input,
+        timeoutMs: config.timeoutMs,
+        sensitivity,
+    };
+    if (req.system !== undefined)
+        template.system = req.system;
+    if (output !== undefined)
+        template.output = output;
+    if (req.tools !== undefined)
+        template.tools = req.tools;
+    if (req.params !== undefined)
+        template.params = req.params;
+    const task = {
+        id: def?.id ?? req.task,
+        required,
+        preferred,
+        strategy,
+        sensitivity,
+        requireLocal,
+        confidence,
+    };
+    if (minContextWindow !== undefined)
+        task.minContextWindow = minContextWindow;
+    if (output !== undefined)
+        task.output = output;
+    return { task, template };
+}

package/dist/core/router/request.d.ts

@@ -0,0 +1,4 @@
+/** Complete a request template into a concrete AIRequest for one model. */
+import type { AIRequest } from '../../types.js';
+import type { RequestTemplate } from './normalize.js';
+export declare function buildRequest(template: RequestTemplate, model: string, signal?: AbortSignal): AIRequest;

package/dist/core/router/request.js

@@ -0,0 +1,21 @@
+/** Complete a request template into a concrete AIRequest for one model. */
+export function buildRequest(template, model, signal) {
+    const req = {
+        taskId: template.taskId,
+        model,
+        input: template.input,
+        timeoutMs: template.timeoutMs,
+        sensitivity: template.sensitivity,
+    };
+    if (template.system !== undefined)
+        req.system = template.system;
+    if (template.output !== undefined)
+        req.output = template.output;
+    if (template.tools !== undefined)
+        req.tools = template.tools;
+    if (template.params !== undefined)
+        req.params = template.params;
+    if (signal !== undefined)
+        req.signal = signal;
+    return req;
+}

package/dist/core/router/router.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The router — the vendor-agnostic 7-phase pipeline. It holds only a provider registry, a task
+ * registry, resolved config, and a telemetry sink; it reaches providers exclusively through the
+ * `AIProvider` contract. No vendor name appears here.
+ *
+ *   1 normalize → 2 filter → 3 score → 4 select → 5 execute → 6 (validate: later stage) → 7 fallback
+ */
+import type { ProviderRegistry } from '../registry/registry.js';
+import type { TaskRegistry } from '../registry/taskRegistry.js';
+import type { ResolvedConfig } from '../../config/defaults.js';
+import type { TelemetrySink } from '../../telemetry/telemetry.js';
+import type { HealthMonitor } from '../health/monitor.js';
+import type { PerformanceStore } from '../../learning/performanceStore.js';
+import type { CapabilityOverlay } from '../capabilities/overlay.js';
+import type { Clock } from '../../util/clock.js';
+import type { RunRequest, RunResult } from '../../types.js';
+export interface RouterDeps {
+    registry: ProviderRegistry;
+    tasks: TaskRegistry;
+    config: ResolvedConfig;
+    telemetry: TelemetrySink;
+    health?: HealthMonitor;
+    performance?: PerformanceStore;
+    overlay?: CapabilityOverlay;
+    clock?: Clock;
+}
+export declare class Router {
+    private readonly deps;
+    private readonly clock;
+    constructor(deps: RouterDeps);
+    run(req: RunRequest): Promise<RunResult>;
+}

package/dist/core/router/router.js

@@ -0,0 +1,195 @@
+/**
+ * The router — the vendor-agnostic 7-phase pipeline. It holds only a provider registry, a task
+ * registry, resolved config, and a telemetry sink; it reaches providers exclusively through the
+ * `AIProvider` contract. No vendor name appears here.
+ *
+ *   1 normalize → 2 filter → 3 score → 4 select → 5 execute → 6 (validate: later stage) → 7 fallback
+ */
+import { mergeProfiles } from '../capabilities/evidence.js';
+import { systemClock } from '../../util/clock.js';
+import { AIError } from '../fallback/errors.js';
+import { normalize } from './normalize.js';
+import { filterCandidates } from './filter.js';
+import { scoreCandidates } from './scorer.js';
+import { runWithFallback } from '../fallback/fallback.js';
+import { deriveConfidence } from './confidence.js';
+import { validate as validateResponse } from '../validation/validator.js';
+import { BudgetTracker } from '../policies/budget.js';
+import { buildRequest } from './request.js';
+import { runVerification } from '../../verification/verify.js';
+export class Router {
+    deps;
+    clock;
+    constructor(deps) {
+        this.deps = deps;
+        this.clock = deps.clock ?? systemClock;
+    }
+    async run(req) {
+        const runStarted = this.clock.now();
+        const { registry, tasks, config, telemetry } = this.deps;
+        const getProvider = (id) => registry.get(id);
+        // Phase 1 — normalize
+        const { task, template } = normalize(req, tasks, config);
+        const pin = { provider: req.provider, model: req.model };
+        // Team policy (org-level guardrails) merged over per-run constraints.
+        const policy = config.policy;
+        if (policy.requireLocal)
+            task.requireLocal = true;
+        if (policy.strategy && !req.provider && req.strategy === undefined)
+            task.strategy = policy.strategy;
+        const effectiveConstraints = {
+            ...req.constraints,
+            denyProviders: [...(req.constraints?.denyProviders ?? []), ...(policy.denyProviders ?? [])],
+            ...(policy.allowProviders ? { allowProviders: intersectAllow(req.constraints?.allowProviders, policy.allowProviders) } : req.constraints?.allowProviders ? { allowProviders: req.constraints.allowProviders } : {}),
+            ...(minDefined(req.constraints?.maxCostUsd, policy.maxCostUsd) !== undefined ? { maxCostUsd: minDefined(req.constraints?.maxCostUsd, policy.maxCostUsd) } : {}),
+        };
+        // Gather candidates from enabled providers (provider-owned model + capability resolution)
+        const candidates = [];
+        for (const provider of registry.enabled()) {
+            const models = await provider.listModels();
+            for (const model of models) {
+                if (!model.enabled)
+                    continue;
+                const overlayProfile = this.deps.overlay?.get(provider.id, model.id);
+                const enriched = overlayProfile ? { ...model, capabilities: mergeProfiles(model.capabilities, overlayProfile) } : model;
+                candidates.push({ providerId: provider.id, model: enriched });
+            }
+        }
+        const preFilter = [];
+        if (pin.provider && !candidates.some((c) => c.providerId === pin.provider)) {
+            preFilter.push({ providerId: pin.provider, model: pin.model ?? '*', reason: 'pinned provider not configured or not enabled' });
+        }
+        // Phase 2 — filter
+        const { eligible, filteredOut } = await filterCandidates({
+            candidates,
+            task,
+            config,
+            template,
+            getProvider,
+            pin,
+            ...(this.deps.health ? { health: this.deps.health } : {}),
+            constraints: effectiveConstraints,
+            ...(req.routing ? { routing: req.routing } : {}),
+        });
+        // Phase 3 — score (blends learned performance when available)
+        const history = this.deps.performance
+            ? (pid, mid) => this.deps.performance.forTask(task.id, pid, mid)
+            : undefined;
+        const scored = scoreCandidates(eligible, task, config.weights, task.strategy, { ...(history ? { history } : {}), ...(req.routing ? { prefer: req.routing } : {}) });
+        const ranked = scored.map((s) => ({
+            providerId: s.candidate.providerId,
+            model: s.candidate.model.id,
+            score: s.score,
+            breakdown: s.breakdown,
+        }));
+        const baseReport = {
+            taskId: task.id,
+            strategy: task.strategy,
+            weights: config.weights,
+            requiredCapabilities: task.required,
+            consideredCount: candidates.length,
+            filteredOut: [...preFilter, ...filteredOut],
+            ranked,
+            attempts: [],
+        };
+        // No eligible candidate — actionable NO_CAPABLE_PROVIDER
+        if (scored.length === 0) {
+            const error = new AIError(describeNoCapable(task.id, baseReport.filteredOut), {
+                category: 'NO_CAPABLE_PROVIDER',
+                retryable: false,
+            });
+            telemetry.emit({ type: 'route.decision', ts: this.clock.now(), taskId: task.id, strategy: task.strategy, considered: candidates.length });
+            const result = { ok: false, error: error.toInfo(), confidence: 0, routing: baseReport };
+            telemetry.emit({ type: 'route.result', ts: this.clock.now(), taskId: task.id, ok: false, confidence: 0, totalLatencyMs: this.clock.now() - runStarted, fallbackCount: 0 });
+            return result;
+        }
+        telemetry.emit({
+            type: 'route.decision',
+            ts: this.clock.now(),
+            taskId: task.id,
+            strategy: task.strategy,
+            considered: candidates.length,
+            selected: { providerId: scored[0].candidate.providerId, model: scored[0].candidate.model.id },
+            topScore: scored[0].score,
+        });
+        // Phases 4/5/7 — select top, execute, fall back
+        const onAttempt = (record) => {
+            this.deps.health?.recordOutcome(record.providerId, record.outcome === 'success', record.category);
+            this.deps.performance?.record(task.id, record.providerId, record.model, record.outcome === 'success', record.latencyMs);
+            telemetry.emit({ type: 'route.attempt', ts: this.clock.now(), taskId: task.id, providerId: record.providerId, model: record.model, outcome: record.outcome, ...(record.category !== undefined ? { category: record.category } : {}), latencyMs: record.latencyMs });
+        };
+        // Budget guardrail (per-run override merged over config)
+        const maxCalls = req.budget?.maxCalls ?? config.budget.maxCalls;
+        const maxCostUsd = req.budget?.maxCostUsd ?? config.budget.maxCostUsd;
+        const budget = maxCalls !== undefined || maxCostUsd !== undefined ? new BudgetTracker(maxCalls, maxCostUsd) : undefined;
+        const costOf = async (pid, mid) => {
+            const p = getProvider(pid);
+            if (!p)
+                return 0;
+            const est = await p.estimate(buildRequest(template, mid));
+            return est.estCost?.amount ?? 0;
+        };
+        const fb = await runWithFallback({
+            ranked: scored,
+            template,
+            getProvider,
+            maxFallbacks: config.maxFallbacks,
+            clock: this.clock,
+            onAttempt,
+            validate: (response) => validateResponse({ response, ...(template.output ? { output: template.output } : {}), ...(template.tools ? { tools: template.tools } : {}) }),
+            ...(budget ? { budget, costOf } : {}),
+        });
+        baseReport.attempts = fb.attempts;
+        const fallbackCount = Math.max(0, fb.attempts.length - 1);
+        if (!fb.ok) {
+            telemetry.emit({ type: 'route.result', ts: this.clock.now(), taskId: task.id, ok: false, confidence: 0, totalLatencyMs: this.clock.now() - runStarted, fallbackCount });
+            return { ok: false, error: fb.error.toInfo(), confidence: 0, routing: baseReport };
+        }
+        baseReport.selected = { providerId: fb.used.candidate.providerId, model: fb.used.candidate.model.id };
+        if (fb.validation)
+            baseReport.validation = fb.validation;
+        let confidence = deriveConfidence(fb.used.score, fb.used.candidate.model, task);
+        // Phase-2 multi-model verification (opt-in): a second model judges the primary answer.
+        const wantVerify = req.verification ?? config.verification.enabled;
+        if (wantVerify) {
+            const verification = await runVerification({
+                task,
+                template,
+                primary: { providerId: fb.used.candidate.providerId, model: fb.used.candidate.model.id, response: fb.response },
+                ranked: scored,
+                getProvider,
+                ...(budget ? { budget, costOf } : {}),
+            });
+            if (verification) {
+                baseReport.verification = verification;
+                // A disagreeing verifier lowers confidence; agreement modestly raises it.
+                if (verification.agreement === 'disagree')
+                    confidence = Math.min(confidence, config.minConfidence * 0.9);
+                else if (verification.agreement === 'agree')
+                    confidence = Math.min(1, confidence + 0.05);
+            }
+        }
+        baseReport.belowConfidenceThreshold = confidence < config.minConfidence;
+        telemetry.emit({ type: 'route.result', ts: this.clock.now(), taskId: task.id, ok: true, confidence, totalLatencyMs: this.clock.now() - runStarted, fallbackCount });
+        return { ok: true, response: fb.response, confidence, routing: baseReport };
+    }
+}
+/** Intersect a per-run allow list with a policy allow list (both must permit). */
+function intersectAllow(runAllow, policyAllow) {
+    if (!runAllow)
+        return policyAllow;
+    return runAllow.filter((id) => policyAllow.includes(id));
+}
+function minDefined(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return Math.min(a, b);
+}
+function describeNoCapable(taskId, filteredOut) {
+    if (filteredOut.length === 0)
+        return `No provider is configured for task '${taskId}'.`;
+    const lines = filteredOut.map((f) => `  - ${f.providerId}${f.model && f.model !== '*' ? `/${f.model}` : ''}: ${f.reason}`);
+    return `No compatible AI provider is available for task '${taskId}'.\nExcluded:\n${lines.join('\n')}`;
+}

package/dist/core/router/routingPrefs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared matchers for user exclude/prefer routing (Phase 9). EXCLUDE is consumed by the filter (a hard
+ * gate); PREFER by the scorer (a soft nudge). A model entry is either `provider:model` (exact) or a bare
+ * `model` id (matches that model under any provider). Kept tiny and pure so both the filter and scorer
+ * apply identical matching semantics.
+ */
+import type { RoutingPreferences } from '../../types.js';
+/** True when routing hard-excludes this (provider, model) — by provider id or a model entry. */
+export declare function isExcluded(routing: RoutingPreferences | undefined, providerId: string, modelId: string): boolean;
+/** True when routing soft-prefers this (provider, model) — by provider id or a model entry. */
+export declare function isPreferred(routing: RoutingPreferences | undefined, providerId: string, modelId: string): boolean;

package/dist/core/router/routingPrefs.js

@@ -0,0 +1,30 @@
+/**
+ * Shared matchers for user exclude/prefer routing (Phase 9). EXCLUDE is consumed by the filter (a hard
+ * gate); PREFER by the scorer (a soft nudge). A model entry is either `provider:model` (exact) or a bare
+ * `model` id (matches that model under any provider). Kept tiny and pure so both the filter and scorer
+ * apply identical matching semantics.
+ */
+function modelEntryMatches(entry, providerId, modelId) {
+    // Bare whole-string match FIRST, so a model id that itself contains a colon (e.g. a Bedrock
+    // "…-v1:0" or an OpenRouter "…:free") is still matched. Otherwise fall back to `provider:model`.
+    if (entry === modelId)
+        return true;
+    const i = entry.indexOf(':');
+    return i > 0 && entry.slice(0, i) === providerId && entry.slice(i + 1) === modelId;
+}
+/** True when routing hard-excludes this (provider, model) — by provider id or a model entry. */
+export function isExcluded(routing, providerId, modelId) {
+    if (!routing)
+        return false;
+    if (routing.excludeProviders?.includes(providerId))
+        return true;
+    return (routing.excludeModels ?? []).some((e) => modelEntryMatches(e, providerId, modelId));
+}
+/** True when routing soft-prefers this (provider, model) — by provider id or a model entry. */
+export function isPreferred(routing, providerId, modelId) {
+    if (!routing)
+        return false;
+    if (routing.preferProviders?.includes(providerId))
+        return true;
+    return (routing.preferModels ?? []).some((e) => modelEntryMatches(e, providerId, modelId));
+}

package/dist/core/router/scorer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Phase 3 — scoring. Combines the per-dimension scores with strategy-adjusted weights into a single
+ * 0..1 score per candidate, normalized by the weight sum so weights need not total 100. Deterministic
+ * ordering: score desc, then quality, then latency, then providerId/model for stability.
+ */
+import type { Candidate, NormalizedTask, RoutingPreferences, ScoreBreakdown, ScoreWeights, Strategy } from '../../types.js';
+import type { HistoryLookup } from '../../learning/performanceStore.js';
+export interface ScoredCandidate {
+    candidate: Candidate;
+    score: number;
+    breakdown: ScoreBreakdown;
+}
+export interface ScoreOptions {
+    preferences?: Record<string, number>;
+    /** User prefer routing — a SOFT nudge to the userPreference dimension (never a hard override). */
+    prefer?: RoutingPreferences;
+    history?: HistoryLookup;
+}
+export declare function scoreCandidates(candidates: Candidate[], task: NormalizedTask, baseWeights: ScoreWeights, strategy: Strategy, options?: ScoreOptions): ScoredCandidate[];

package/dist/core/router/scorer.js

@@ -0,0 +1,50 @@
+/**
+ * Phase 3 — scoring. Combines the per-dimension scores with strategy-adjusted weights into a single
+ * 0..1 score per candidate, normalized by the weight sum so weights need not total 100. Deterministic
+ * ordering: score desc, then quality, then latency, then providerId/model for stability.
+ */
+import * as dim from './dimensions.js';
+import { strategyWeights, weightSum } from './weights.js';
+import { isPreferred } from './routingPrefs.js';
+/** The userPreference input for a candidate: 1 when user-preferred, else any provider-level preference. */
+function preferenceValue(candidate, options) {
+    if (isPreferred(options.prefer, candidate.providerId, candidate.model.id))
+        return 1;
+    return options.preferences?.[candidate.providerId];
+}
+export function scoreCandidates(candidates, task, baseWeights, strategy, options = {}) {
+    const w = strategyWeights(strategy, baseWeights);
+    const total = weightSum(w) || 1;
+    const scored = candidates.map((candidate) => {
+        const m = candidate.model;
+        const observed = options.history?.(candidate.providerId, m.id);
+        const breakdown = {
+            capabilityFit: dim.capabilityFit(m, task),
+            quality: dim.quality(m),
+            reliability: dim.reliability(m),
+            historicalSuccess: dim.historicalSuccess(m, observed),
+            latency: dim.latency(m, observed),
+            cost: dim.cost(m),
+            userPreference: dim.userPreference(m, preferenceValue(candidate, options)),
+        };
+        const score = (w.capabilityFit * breakdown.capabilityFit +
+            w.quality * breakdown.quality +
+            w.reliability * breakdown.reliability +
+            w.historicalSuccess * breakdown.historicalSuccess +
+            w.latency * breakdown.latency +
+            w.cost * breakdown.cost +
+            w.userPreference * breakdown.userPreference) /
+            total;
+        return { candidate, score, breakdown };
+    });
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (b.breakdown.quality !== a.breakdown.quality)
+            return b.breakdown.quality - a.breakdown.quality;
+        if (b.breakdown.latency !== a.breakdown.latency)
+            return b.breakdown.latency - a.breakdown.latency;
+        return `${a.candidate.providerId}/${a.candidate.model.id}`.localeCompare(`${b.candidate.providerId}/${b.candidate.model.id}`);
+    });
+    return scored;
+}

package/dist/core/router/weights.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Strategy → weight adjustments. Scores are normalized by the sum of weights, so a preset simply
+ * amplifies the dimension a strategy cares about; strategies that are really FILTERS (local-only,
+ * cloud-only, privacy-first, provider-specific) leave the weights at their base and let the filter
+ * phase do the work.
+ */
+import type { ScoreWeights, Strategy } from '../../types.js';
+export declare function strategyWeights(strategy: Strategy, base: ScoreWeights): ScoreWeights;
+export declare function weightSum(w: ScoreWeights): number;

package/dist/core/router/weights.js

@@ -0,0 +1,31 @@
+/**
+ * Strategy → weight adjustments. Scores are normalized by the sum of weights, so a preset simply
+ * amplifies the dimension a strategy cares about; strategies that are really FILTERS (local-only,
+ * cloud-only, privacy-first, provider-specific) leave the weights at their base and let the filter
+ * phase do the work.
+ */
+export function strategyWeights(strategy, base) {
+    const w = { ...base };
+    switch (strategy) {
+        case 'fastest':
+            w.latency = base.latency * 4;
+            break;
+        case 'cheapest':
+            w.cost = base.cost * 4;
+            break;
+        case 'highest-quality':
+            w.quality = base.quality * 2.5;
+            break;
+        case 'best':
+        case 'local-only':
+        case 'cloud-only':
+        case 'privacy-first':
+        case 'provider-specific':
+        case 'fallback-only':
+            break;
+    }
+    return w;
+}
+export function weightSum(w) {
+    return w.capabilityFit + w.quality + w.reliability + w.historicalSuccess + w.latency + w.cost + w.userPreference;
+}

package/dist/core/validation/validator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Phase 6 — response validation. Checks the normalized response against the task's declared output
+ * contract: JSON presence, optional schema (any object exposing `safeParse`, e.g. a zod schema),
+ * tool-call validity, and a basic non-empty signal. Returns a structured report; the router treats a
+ * failing report as a reason to fall through to the next candidate.
+ */
+import type { AIResponse, OutputFormat, ToolSpec, ValidationReport } from '../../types.js';
+export interface ValidateInput {
+    response: AIResponse;
+    output?: {
+        format: OutputFormat;
+        schema?: unknown;
+    };
+    tools?: ToolSpec[];
+}
+export declare function validate(input: ValidateInput): ValidationReport;

package/dist/core/validation/validator.js

@@ -0,0 +1,33 @@
+/**
+ * Phase 6 — response validation. Checks the normalized response against the task's declared output
+ * contract: JSON presence, optional schema (any object exposing `safeParse`, e.g. a zod schema),
+ * tool-call validity, and a basic non-empty signal. Returns a structured report; the router treats a
+ * failing report as a reason to fall through to the next candidate.
+ */
+function isSafeParser(schema) {
+    return typeof schema === 'object' && schema !== null && typeof schema.safeParse === 'function';
+}
+export function validate(input) {
+    const checks = [];
+    const { response, output, tools } = input;
+    const fmt = output?.format;
+    if (fmt === 'json' || fmt === 'structured_output') {
+        const hasJson = response.json !== undefined;
+        checks.push({ name: 'json-present', ok: hasJson, ...(hasJson ? {} : { why: 'expected JSON output but none was produced' }) });
+        if (hasJson && output?.schema && isSafeParser(output.schema)) {
+            const result = output.schema.safeParse(response.json);
+            checks.push({ name: 'schema', ok: result.success, ...(result.success ? {} : { why: 'output did not match the provided schema' }) });
+        }
+    }
+    else if (response.finishReason !== 'tool_calls') {
+        // A tool-call response legitimately has no text; only require text otherwise.
+        const hasText = Boolean(response.text && response.text.trim());
+        checks.push({ name: 'text-present', ok: hasText, ...(hasText ? {} : { why: 'empty text response' }) });
+    }
+    if (tools && tools.length > 0 && response.finishReason === 'tool_calls') {
+        const calls = response.toolCalls ?? [];
+        const ok = calls.length > 0 && calls.every((c) => tools.some((t) => t.name === c.name));
+        checks.push({ name: 'tool-calls', ok, ...(ok ? {} : { why: 'missing or unknown tool call' }) });
+    }
+    return { ok: checks.every((c) => c.ok), checks };
+}

package/dist/discovery/modelCatalog.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Hand-curated, `documented`-tier facts for well-known models. This is the ONLY place vendor model
+ * knowledge lives, and it is in the discovery layer — providers call `resolveModelMetadata`, `core/`
+ * never imports this. A model with no catalog entry and no operator-declared capabilities resolves to
+ * an all-`unknown` profile (routable only via an explicit pin), honoring the never-promote rule.
+ */
+import type { BooleanCapabilityGroup } from '../core/capabilities/taxonomy.js';
+import type { DeclaredCapabilities, ModelMetadata, Pricing, ProviderKind, QualityTier } from '../types.js';
+export interface CatalogEntry {
+    caps: Partial<Record<BooleanCapabilityGroup, string[]>>;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    pricing?: Pricing;
+    quality?: {
+        tier?: QualityTier;
+        score?: number;
+    };
+    latencyP50Ms?: number;
+    successRate?: number;
+    family?: string;
+    displayName?: string;
+}
+export declare function lookupCatalog(kind: ProviderKind, modelId: string): CatalogEntry | undefined;
+/**
+ * Build normalized ModelMetadata for one model by merging catalog facts with operator-declared
+ * capabilities (both `documented`). No source → all-`unknown` capabilities and `source: 'unknown'`.
+ */
+export declare function resolveModelMetadata(providerId: string, kind: ProviderKind, modelId: string, declared?: DeclaredCapabilities, enabled?: boolean): ModelMetadata;