@absolutejs/voice 0.0.22-beta.125 → 0.0.22-beta.126

package/README.md

@@ -1534,6 +1534,40 @@ const policy = resolveVoiceProviderRoutingPolicyPreset('cost-cap', {
 });
 ```
 
+Use `runVoiceProviderRoutingContract(...)` when provider fallback needs to be certified before production. The contract reads provider routing trace events and verifies the expected selected provider, fallback provider, status, and kind in order.
+
+```ts
+import { runVoiceProviderRoutingContract } from '@absolutejs/voice';
+
+const report = await runVoiceProviderRoutingContract({
+	store: runtime.traces,
+	contract: {
+		id: 'openai-to-anthropic-fallback',
+		expect: [
+			{
+				kind: 'llm',
+				provider: 'openai',
+				selectedProvider: 'openai',
+				fallbackProvider: 'anthropic',
+				status: 'error'
+			},
+			{
+				kind: 'llm',
+				provider: 'anthropic',
+				selectedProvider: 'openai',
+				status: 'fallback'
+			}
+		]
+	}
+});
+
+if (!report.pass) {
+	throw new Error(report.issues.map((issue) => issue.message).join('\n'));
+}
+```
+
+Pass provider routing contract reports into production readiness through `providerRoutingContracts`. Readiness fails when a fallback contract fails, so model-routing regressions become deploy blockers instead of dashboard-only surprises.
+
 For full control, pass an object policy:
 
 ```ts

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, cr
 export { createOpenAIVoiceTTS } from './openaiTTS';
 export { createVoiceProviderHealthHTMLHandler, createVoiceProviderHealthJSONHandler, createVoiceProviderHealthRoutes, renderVoiceProviderHealthHTML, summarizeVoiceProviderHealth } from './providerHealth';
 export { createVoiceProviderCapabilityHTMLHandler, createVoiceProviderCapabilityJSONHandler, createVoiceProviderCapabilityRoutes, renderVoiceProviderCapabilityHTML, summarizeVoiceProviderCapabilities } from './providerCapabilities';
+export { assertVoiceProviderRoutingContract, runVoiceProviderRoutingContract } from './providerRoutingContract';
 export { buildVoiceProductionReadinessReport, createVoiceProductionReadinessRoutes, renderVoiceProductionReadinessHTML } from './productionReadiness';
 export { buildVoiceOpsConsoleReport, createVoiceOpsConsoleRoutes, renderVoiceOpsConsoleHTML } from './opsConsoleRoutes';
 export { createVoiceQualityRoutes, evaluateVoiceQuality, renderVoiceQualityHTML } from './qualityRoutes';
@@ -71,6 +72,7 @@ export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOpti
 export type { OpenAIVoiceTTSOptions, OpenAIVoiceTTSVoice } from './openaiTTS';
 export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProviderHealthSummaryOptions } from './providerHealth';
 export type { VoiceProviderCapabilityDefinition, VoiceProviderCapabilityHandlerOptions, VoiceProviderCapabilityHTMLHandlerOptions, VoiceProviderCapabilityKind, VoiceProviderCapabilityOptions, VoiceProviderCapabilityReport, VoiceProviderCapabilityRoutesOptions, VoiceProviderCapabilitySummary } from './providerCapabilities';
+export type { VoiceProviderRoutingContractDefinition, VoiceProviderRoutingContractIssue, VoiceProviderRoutingContractReport, VoiceProviderRoutingContractRunOptions, VoiceProviderRoutingExpectation, VoiceProviderRoutingStatus } from './providerRoutingContract';
 export type { VoiceTurnLatencyHTMLHandlerOptions, VoiceTurnLatencyItem, VoiceTurnLatencyOptions, VoiceTurnLatencyReport, VoiceTurnLatencyRoutesOptions, VoiceTurnLatencyStage, VoiceTurnLatencyStatus } from './turnLatency';
 export type { VoiceLiveLatencyOptions, VoiceLiveLatencyReport, VoiceLiveLatencyRoutesOptions, VoiceLiveLatencySample, VoiceLiveLatencyStatus } from './liveLatency';
 export type { VoiceTurnQualityHTMLHandlerOptions, VoiceTurnQualityItem, VoiceTurnQualityOptions, VoiceTurnQualityReport, VoiceTurnQualityRoutesOptions, VoiceTurnQualityStatus } from './turnQuality';

package/dist/index.js

@@ -9837,6 +9837,12 @@ var resolveAgentSquadContracts = async (options, input) => {
   }
   return typeof options.agentSquadContracts === "function" ? await options.agentSquadContracts(input) : options.agentSquadContracts;
 };
+var resolveProviderRoutingContracts = async (options, input) => {
+  if (options.providerRoutingContracts === false || options.providerRoutingContracts === undefined) {
+    return;
+  }
+  return typeof options.providerRoutingContracts === "function" ? await options.providerRoutingContracts(input) : options.providerRoutingContracts;
+};
 var summarizeLiveLatency = (events, options) => {
   const warnAfterMs = options.liveLatencyWarnAfterMs ?? 1800;
   const failAfterMs = options.liveLatencyFailAfterMs ?? 3200;
@@ -9859,7 +9865,15 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
   const routingEvents = listVoiceRoutingEvents(events);
   const routingSessions = summarizeVoiceRoutingSessions(routingEvents);
   const liveLatency = summarizeLiveLatency(events, options);
-  const [quality, providers, sessions, handoffs, carriers, agentSquadContracts] = await Promise.all([
+  const [
+    quality,
+    providers,
+    sessions,
+    handoffs,
+    carriers,
+    agentSquadContracts,
+    providerRoutingContracts
+  ] = await Promise.all([
     evaluateVoiceQuality({ events }),
     Promise.all([
       summarizeVoiceProviderHealth({
@@ -9878,7 +9892,8 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     summarizeVoiceSessions({ events, status: "all" }),
     summarizeVoiceHandoffHealth({ events }),
     resolveCarriers(options, { query, request }),
-    resolveAgentSquadContracts(options, { query, request })
+    resolveAgentSquadContracts(options, { query, request }),
+    resolveProviderRoutingContracts(options, { query, request })
   ]);
   const degradedProviders = providers.filter((provider) => provider.status === "degraded" || provider.status === "rate-limited" || provider.status === "suppressed").length;
   const failedSessions = sessions.filter((session) => session.status === "failed").length;
@@ -9993,6 +10008,12 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     status: agentSquadContracts.some((report) => !report.pass) ? "fail" : agentSquadContracts.length === 0 ? "warn" : "pass",
     total: agentSquadContracts.length
   } : undefined;
+  const providerRoutingContractSummary = providerRoutingContracts ? {
+    failed: providerRoutingContracts.filter((report) => !report.pass).length,
+    passed: providerRoutingContracts.filter((report) => report.pass).length,
+    status: providerRoutingContracts.some((report) => !report.pass) ? "fail" : providerRoutingContracts.length === 0 ? "warn" : "pass",
+    total: providerRoutingContracts.length
+  } : undefined;
   if (agentSquadContractSummary) {
     checks.push({
       detail: agentSquadContractSummary.status === "pass" ? `${agentSquadContractSummary.passed} agent squad contract(s) are passing.` : agentSquadContractSummary.total === 0 ? "No agent squad contracts are configured." : `${agentSquadContractSummary.failed} agent squad contract(s) failed.`,
@@ -10009,6 +10030,22 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
       ]
     });
   }
+  if (providerRoutingContractSummary) {
+    checks.push({
+      detail: providerRoutingContractSummary.status === "pass" ? `${providerRoutingContractSummary.passed} provider routing contract(s) are passing.` : providerRoutingContractSummary.total === 0 ? "No provider routing contracts are configured." : `${providerRoutingContractSummary.failed} provider routing contract(s) failed.`,
+      href: options.links?.providerRoutingContracts ?? options.links?.resilience ?? "/resilience",
+      label: "Provider routing contracts",
+      status: providerRoutingContractSummary.status,
+      value: `${providerRoutingContractSummary.passed}/${providerRoutingContractSummary.total}`,
+      actions: providerRoutingContractSummary.status === "pass" ? [] : [
+        {
+          description: "Open provider routing evidence and inspect failed fallback expectations.",
+          href: options.links?.providerRoutingContracts ?? options.links?.resilience ?? "/resilience",
+          label: "Open provider routing contracts"
+        }
+      ]
+    });
+  }
   if (carriers && carrierSummary) {
     checks.push({
       detail: carrierSummary.status === "pass" ? "Configured carrier setup and contract checks are passing." : `${carrierSummary.failing} carrier(s) failing, ${carrierSummary.warnings} warning(s).`,
@@ -10034,6 +10071,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
       handoffs: "/handoffs",
       handoffRetry: "/api/voice-handoffs/retry",
       liveLatency: "/traces",
+      providerRoutingContracts: "/resilience",
       quality: "/quality",
       resilience: "/resilience",
       sessions: "/sessions",
@@ -10052,6 +10090,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
         degraded: degradedProviders,
         total: providers.length
       },
+      providerRoutingContracts: providerRoutingContractSummary,
       quality: {
         status: quality.status
       },
@@ -17066,6 +17105,43 @@ var createOpenAIVoiceTTS = (options) => {
     }
   };
 };
+// src/providerRoutingContract.ts
+var isRoutingEvent = (event) => Boolean(event && typeof event === "object" && "status" in event && "kind" in event && "sessionId" in event);
+var normalizeEvents = (events) => (events.every(isRoutingEvent) ? [...events] : listVoiceRoutingEvents(events)).sort((left, right) => left.at - right.at);
+var matchesExpectation = (event, expectation) => (expectation.kind === undefined || event.kind === expectation.kind) && (expectation.operation === undefined || event.operation === expectation.operation) && (expectation.provider === undefined || event.provider === expectation.provider) && (expectation.selectedProvider === undefined || event.selectedProvider === expectation.selectedProvider) && (expectation.fallbackProvider === undefined || event.fallbackProvider === expectation.fallbackProvider) && (expectation.status === undefined || event.status === expectation.status);
+var describeExpectation = (expectation) => Object.entries(expectation).map(([key, value]) => `${key}=${String(value)}`).join(", ");
+var runVoiceProviderRoutingContract = async (options) => {
+  const rawEvents = options.events ?? await options.store?.list() ?? [];
+  const events = normalizeEvents(rawEvents).filter((event) => (!options.contract.sessionId || event.sessionId === options.contract.sessionId) && (!options.contract.scenarioId || event.sessionId === options.contract.scenarioId || rawEvents.some((rawEvent) => !isRoutingEvent(rawEvent) && rawEvent.sessionId === event.sessionId && rawEvent.scenarioId === options.contract.scenarioId)));
+  const issues = [];
+  let searchFrom = 0;
+  for (const [index, expectation] of options.contract.expect.entries()) {
+    const matchIndex = events.findIndex((event, eventIndex) => eventIndex >= searchFrom && matchesExpectation(event, expectation));
+    if (matchIndex === -1) {
+      issues.push({
+        code: "provider_routing.expected_event_missing",
+        message: `Expected provider routing event ${index + 1}: ${describeExpectation(expectation)}.`
+      });
+      continue;
+    }
+    searchFrom = matchIndex + 1;
+  }
+  return {
+    contractId: options.contract.id,
+    events,
+    issues,
+    pass: issues.length === 0,
+    scenarioId: options.contract.scenarioId,
+    sessionId: options.contract.sessionId
+  };
+};
+var assertVoiceProviderRoutingContract = async (options) => {
+  const report = await runVoiceProviderRoutingContract(options);
+  if (!report.pass) {
+    throw new Error(`Voice provider routing contract ${report.contractId} failed: ${report.issues.map((issue) => issue.message).join(" ")}`);
+  }
+  return report;
+};
 // src/providerAdapters.ts
 class VoiceIOProviderTimeoutError extends Error {
   provider;
@@ -19965,6 +20041,7 @@ export {
   runVoiceSessionEvals,
   runVoiceScenarioFixtureEvals,
   runVoiceScenarioEvals,
+  runVoiceProviderRoutingContract,
   runVoiceOutcomeContractSuite,
   runVoiceCampaignProof,
   runVoiceCampaignDialerProof,
@@ -20246,6 +20323,7 @@ export {
   buildVoiceDiagnosticsMarkdown,
   buildVoiceCampaignObservabilityReport,
   assignVoiceOpsTask,
+  assertVoiceProviderRoutingContract,
   assertVoiceAgentSquadContract,
   applyVoiceTelephonyOutcome,
   applyVoiceOpsTaskPolicy,

package/dist/productionReadiness.d.ts

@@ -2,6 +2,7 @@ import { Elysia } from 'elysia';
 import { type VoiceTelephonyCarrierMatrixInput } from './telephony/matrix';
 import type { VoiceTraceEventStore } from './trace';
 import type { VoiceAgentSquadContractReport } from './agentSquadContract';
+import type { VoiceProviderRoutingContractReport } from './providerRoutingContract';
 export type VoiceProductionReadinessStatus = 'fail' | 'pass' | 'warn';
 export type VoiceProductionReadinessAction = {
     description?: string;
@@ -26,6 +27,7 @@ export type VoiceProductionReadinessReport = {
         handoffs?: string;
         handoffRetry?: string;
         liveLatency?: string;
+        providerRoutingContracts?: string;
         quality?: string;
         resilience?: string;
         sessions?: string;
@@ -60,6 +62,12 @@ export type VoiceProductionReadinessReport = {
             degraded: number;
             total: number;
         };
+        providerRoutingContracts?: {
+            failed: number;
+            passed: number;
+            status: VoiceProductionReadinessStatus;
+            total: number;
+        };
         quality: {
             status: 'fail' | 'pass';
         };
@@ -88,6 +96,10 @@ export type VoiceProductionReadinessRoutesOptions = {
     llmProviders?: readonly string[];
     name?: string;
     path?: string;
+    providerRoutingContracts?: false | readonly VoiceProviderRoutingContractReport[] | ((input: {
+        query: Record<string, unknown>;
+        request: Request;
+    }) => Promise<readonly VoiceProviderRoutingContractReport[]> | readonly VoiceProviderRoutingContractReport[]);
     render?: (report: VoiceProductionReadinessReport) => string | Promise<string>;
     store: VoiceTraceEventStore;
     sttProviders?: readonly string[];

package/dist/providerRoutingContract.d.ts

@@ -0,0 +1,38 @@
+import { type VoiceRoutingEvent, type VoiceRoutingEventKind } from './resilienceRoutes';
+import type { StoredVoiceTraceEvent, VoiceTraceEventStore } from './trace';
+export type VoiceProviderRoutingStatus = 'error' | 'fallback' | 'success';
+export type VoiceProviderRoutingExpectation = {
+    fallbackProvider?: string;
+    kind?: VoiceRoutingEventKind;
+    operation?: string;
+    provider?: string;
+    selectedProvider?: string;
+    status?: VoiceProviderRoutingStatus;
+};
+export type VoiceProviderRoutingContractDefinition = {
+    description?: string;
+    expect: VoiceProviderRoutingExpectation[];
+    id: string;
+    label?: string;
+    scenarioId?: string;
+    sessionId?: string;
+};
+export type VoiceProviderRoutingContractIssue = {
+    code: string;
+    message: string;
+};
+export type VoiceProviderRoutingContractReport = {
+    contractId: string;
+    events: VoiceRoutingEvent[];
+    issues: VoiceProviderRoutingContractIssue[];
+    pass: boolean;
+    scenarioId?: string;
+    sessionId?: string;
+};
+export type VoiceProviderRoutingContractRunOptions = {
+    contract: VoiceProviderRoutingContractDefinition;
+    events?: StoredVoiceTraceEvent[] | VoiceRoutingEvent[];
+    store?: VoiceTraceEventStore;
+};
+export declare const runVoiceProviderRoutingContract: (options: VoiceProviderRoutingContractRunOptions) => Promise<VoiceProviderRoutingContractReport>;
+export declare const assertVoiceProviderRoutingContract: (options: VoiceProviderRoutingContractRunOptions) => Promise<VoiceProviderRoutingContractReport>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.125",
+	"version": "0.0.22-beta.126",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",