@absolutejs/voice 0.0.22-beta.124 → 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

@@ -9831,6 +9831,18 @@ var resolveCarriers = async (options, input) => {
     providers: [...providers]
   });
 };
+var resolveAgentSquadContracts = async (options, input) => {
+  if (options.agentSquadContracts === false || options.agentSquadContracts === undefined) {
+    return;
+  }
+  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;
@@ -9853,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] = await Promise.all([
+  const [
+    quality,
+    providers,
+    sessions,
+    handoffs,
+    carriers,
+    agentSquadContracts,
+    providerRoutingContracts
+  ] = await Promise.all([
     evaluateVoiceQuality({ events }),
     Promise.all([
       summarizeVoiceProviderHealth({
@@ -9871,7 +9891,9 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     ]).then((groups) => groups.flat()),
     summarizeVoiceSessions({ events, status: "all" }),
     summarizeVoiceHandoffHealth({ events }),
-    resolveCarriers(options, { query, request })
+    resolveCarriers(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;
@@ -9980,6 +10002,50 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     status: carrierStatus(carriers),
     warnings: carriers.summary.warnings
   } : undefined;
+  const agentSquadContractSummary = agentSquadContracts ? {
+    failed: agentSquadContracts.filter((report) => !report.pass).length,
+    passed: agentSquadContracts.filter((report) => report.pass).length,
+    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.`,
+      href: options.links?.agentSquadContracts ?? "/agent-squad-contract",
+      label: "Agent squad contracts",
+      status: agentSquadContractSummary.status,
+      value: `${agentSquadContractSummary.passed}/${agentSquadContractSummary.total}`,
+      actions: agentSquadContractSummary.status === "pass" ? [] : [
+        {
+          description: "Open the specialist routing contract report and inspect failing handoff paths.",
+          href: options.links?.agentSquadContracts ?? "/agent-squad-contract",
+          label: "Open squad contracts"
+        }
+      ]
+    });
+  }
+  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).`,
@@ -10000,10 +10066,12 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     checkedAt: Date.now(),
     checks,
     links: {
+      agentSquadContracts: "/agent-squad-contract",
       carriers: "/carriers",
       handoffs: "/handoffs",
       handoffRetry: "/api/voice-handoffs/retry",
       liveLatency: "/traces",
+      providerRoutingContracts: "/resilience",
       quality: "/quality",
       resilience: "/resilience",
       sessions: "/sessions",
@@ -10011,6 +10079,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     },
     status: rollupStatus(checks),
     summary: {
+      agentSquadContracts: agentSquadContractSummary,
       carriers: carrierSummary,
       handoffs: {
         failed: handoffs.failed,
@@ -10021,6 +10090,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
         degraded: degradedProviders,
         total: providers.length
       },
+      providerRoutingContracts: providerRoutingContractSummary,
       quality: {
         status: quality.status
       },
@@ -17035,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;
@@ -19934,6 +20041,7 @@ export {
   runVoiceSessionEvals,
   runVoiceScenarioFixtureEvals,
   runVoiceScenarioEvals,
+  runVoiceProviderRoutingContract,
   runVoiceOutcomeContractSuite,
   runVoiceCampaignProof,
   runVoiceCampaignDialerProof,
@@ -20215,6 +20323,7 @@ export {
   buildVoiceDiagnosticsMarkdown,
   buildVoiceCampaignObservabilityReport,
   assignVoiceOpsTask,
+  assertVoiceProviderRoutingContract,
   assertVoiceAgentSquadContract,
   applyVoiceTelephonyOutcome,
   applyVoiceOpsTaskPolicy,

package/dist/productionReadiness.d.ts

@@ -1,6 +1,8 @@
 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;
@@ -20,16 +22,24 @@ export type VoiceProductionReadinessReport = {
     checkedAt: number;
     checks: VoiceProductionReadinessCheck[];
     links: {
+        agentSquadContracts?: string;
         carriers?: string;
         handoffs?: string;
         handoffRetry?: string;
         liveLatency?: string;
+        providerRoutingContracts?: string;
         quality?: string;
         resilience?: string;
         sessions?: string;
     };
     status: VoiceProductionReadinessStatus;
     summary: {
+        agentSquadContracts?: {
+            failed: number;
+            passed: number;
+            status: VoiceProductionReadinessStatus;
+            total: number;
+        };
         carriers?: {
             failing: number;
             providers: number;
@@ -52,6 +62,12 @@ export type VoiceProductionReadinessReport = {
             degraded: number;
             total: number;
         };
+        providerRoutingContracts?: {
+            failed: number;
+            passed: number;
+            status: VoiceProductionReadinessStatus;
+            total: number;
+        };
         quality: {
             status: 'fail' | 'pass';
         };
@@ -66,6 +82,10 @@ export type VoiceProductionReadinessReport = {
     };
 };
 export type VoiceProductionReadinessRoutesOptions = {
+    agentSquadContracts?: false | readonly VoiceAgentSquadContractReport[] | ((input: {
+        query: Record<string, unknown>;
+        request: Request;
+    }) => Promise<readonly VoiceAgentSquadContractReport[]> | readonly VoiceAgentSquadContractReport[]);
     carriers?: false | readonly VoiceTelephonyCarrierMatrixInput[] | ((input: {
         query: Record<string, unknown>;
         request: Request;
@@ -76,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.124",
+	"version": "0.0.22-beta.126",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",