@absolutejs/voice 0.0.22-beta.292 → 0.0.22-beta.294

package/README.md

@@ -3941,6 +3941,55 @@ const summaryModel = createVoiceProviderRouter({
 });
 ```
 
+Mount `createVoiceProviderOrchestrationRoutes(...)` and pass the report into production readiness when provider policy should be deploy-gated. This proves that required surfaces have enough providers, explicit fallback order, circuit-breaker settings, timeout budgets, and cost/latency/quality bounds.
+
+```ts
+import {
+	buildVoiceProviderOrchestrationReport,
+	createVoiceProviderOrchestrationRoutes,
+	createVoiceProductionReadinessRoutes
+} from '@absolutejs/voice';
+
+const providerOrchestration = () =>
+	buildVoiceProviderOrchestrationReport({
+		profile: providerProfile,
+		requirements: {
+			'live-call': {
+				minProviders: 2,
+				requireBudgetPolicy: true,
+				requireCircuitBreaker: true,
+				requireFallback: true,
+				requireTimeoutBudget: true
+			}
+		}
+	});
+
+app
+	.use(
+		createVoiceProviderOrchestrationRoutes({
+			profile: providerProfile,
+			requirements: {
+				'live-call': {
+					minProviders: 2,
+					requireBudgetPolicy: true,
+					requireCircuitBreaker: true,
+					requireFallback: true,
+					requireTimeoutBudget: true
+				}
+			}
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			store: runtime.traces,
+			providerOrchestration,
+			links: {
+				providerOrchestration: '/voice/provider-orchestration'
+			}
+		})
+	);
+```
+
 Budget filters are strict. If you pass `maxCost`, `maxLatencyMs`, or `minQuality`, providers outside those limits are removed before ranking, even if they were selected by the request.
 
 ```ts
@@ -4040,6 +4089,35 @@ assertVoiceProviderSloEvidence(providerReport, {
 });
 ```
 
+Use `createVoiceProviderDecisionTraceEvent(...)` and `createVoiceProviderDecisionTraceRoutes(...)` when you need runtime proof for why a provider won, failed, was skipped, or recovered by fallback. This is the per-call decision trail behind provider orchestration: it can read explicit `provider.decision` trace events or normalize existing provider routing events.
+
+```ts
+import {
+	createVoiceProviderDecisionTraceEvent,
+	createVoiceProviderDecisionTraceRoutes
+} from '@absolutejs/voice';
+
+await traces.append(
+	createVoiceProviderDecisionTraceEvent({
+		provider: 'deepgram',
+		selectedProvider: 'assemblyai',
+		fallbackProvider: 'assemblyai',
+		status: 'fallback',
+		surface: 'live-stt',
+		reason: 'Deepgram timed out, AssemblyAI recovered the live STT turn.'
+	})
+);
+
+app.use(
+	createVoiceProviderDecisionTraceRoutes({
+		store: traces,
+		requiredSurfaces: ['live-call', 'live-stt', 'telephony-tts']
+	})
+);
+```
+
+The routes expose JSON at `/api/voice/provider-decisions`, HTML at `/voice/provider-decisions`, and Markdown at `/voice/provider-decisions.md`. Use this next to provider SLOs when a customer asks not just "is fallback working?" but "why did the system choose this provider for this call?".
+
 Use `createVoiceProviderContractMatrixPreset(...)` when you want readiness proof for the whole provider stack without hand-writing every LLM, STT, and TTS contract row. The preset stays primitive: you still own provider lists, selected providers, latency budgets, env, capabilities, and route mounting.
 
 ```ts

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export { buildVoiceOpsActionHistoryReport, createVoiceOpsActionAuditRoutes, reco
 export { assertVoicePlatformCoverage, buildVoicePlatformCoverageSummary, createVoicePlatformCoverageRoutes, evaluateVoicePlatformCoverage } from './platformCoverage';
 export type { VoicePlatformCoverageAssertionInput, VoicePlatformCoverageAssertionReport, VoicePlatformCoverageEvidence, VoicePlatformCoverageRoutesOptions, VoicePlatformCoverageStatus, VoicePlatformCoverageSummary, VoicePlatformCoverageSummaryInput, VoicePlatformCoverageSurface } from './platformCoverage';
 export { assertVoiceProofTrendEvidence, buildEmptyVoiceProofTrendReport, buildVoiceProofTrendReport, createVoiceProofTrendRoutes, DEFAULT_VOICE_PROOF_TRENDS_MAX_AGE_MS, evaluateVoiceProofTrendEvidence, formatVoiceProofTrendAge, normalizeVoiceProofTrendReport, readVoiceProofTrendReportFile } from './proofTrends';
+export { buildVoiceProviderDecisionTraceReport, createVoiceProviderDecisionTraceEvent, createVoiceProviderDecisionTraceRoutes, listVoiceProviderDecisionTraces, renderVoiceProviderDecisionTraceHTML, renderVoiceProviderDecisionTraceMarkdown } from './providerDecisionTraces';
+export type { VoiceProviderDecisionStatus, VoiceProviderDecisionSurfaceReport, VoiceProviderDecisionTrace, VoiceProviderDecisionTraceInput, VoiceProviderDecisionTraceIssue, VoiceProviderDecisionTraceReport, VoiceProviderDecisionTraceReportOptions, VoiceProviderDecisionTraceRoutesOptions } from './providerDecisionTraces';
 export type { VoiceProofTrendAssertionInput, VoiceProofTrendAssertionReport, VoiceProofTrendCycle, VoiceProofTrendReport, VoiceProofTrendReportInput, VoiceProofTrendRoutesOptions, VoiceProofTrendStatus, VoiceProofTrendSummary } from './proofTrends';
 export { assertVoiceSloCalibration, buildVoiceSloCalibrationReport, buildVoiceSloReadinessThresholdReport, createVoiceSloReadinessThresholdOptions, createVoiceSloReadinessThresholdRoutes, createVoiceSloThresholdProfile, createVoiceSloCalibrationRoutes, renderVoiceSloCalibrationMarkdown, renderVoiceSloReadinessThresholdHTML, renderVoiceSloReadinessThresholdMarkdown } from './sloCalibration';
 export type { VoiceSloCalibrationMetricKey, VoiceSloCalibrationOptions, VoiceSloCalibrationReport, VoiceSloCalibrationRoutesOptions, VoiceSloCalibrationSample, VoiceSloCalibrationStatus, VoiceSloCalibrationThreshold, VoiceSloCalibrationThresholds, VoiceSloReadinessThresholdReport, VoiceSloReadinessThresholdReportOptions, VoiceSloReadinessThresholdOptions, VoiceSloReadinessThresholdRoutesOptions, VoiceSloThresholdProfile } from './sloCalibration';
@@ -51,6 +53,7 @@ export { createOpenAIRealtimeAdapter } from './openaiRealtime';
 export { createOpenAIVoiceTTS } from './openaiTTS';
 export { createVoiceProviderHealthHTMLHandler, createVoiceProviderHealthJSONHandler, createVoiceProviderHealthRoutes, renderVoiceProviderHealthHTML, summarizeVoiceProviderHealth } from './providerHealth';
 export { createVoiceProviderCapabilityHTMLHandler, createVoiceProviderCapabilityJSONHandler, createVoiceProviderCapabilityRoutes, renderVoiceProviderCapabilityHTML, summarizeVoiceProviderCapabilities } from './providerCapabilities';
+export { buildVoiceProviderOrchestrationReport, createVoiceProviderOrchestrationRoutes, renderVoiceProviderOrchestrationHTML, renderVoiceProviderOrchestrationMarkdown } from './providerOrchestration';
 export { assertVoiceProviderRoutingContractEvidence, assertVoiceProviderRoutingContract, evaluateVoiceProviderRoutingContractEvidence, runVoiceProviderRoutingContract } from './providerRoutingContract';
 export { assertVoiceProviderSloEvidence, buildVoiceProviderSloReport, createVoiceProviderSloRoutes, evaluateVoiceProviderSloEvidence, renderVoiceProviderSloHTML, renderVoiceProviderSloMarkdown } from './providerSlo';
 export { createVoicePhoneAgentProductionSmokeHTMLHandler, createVoicePhoneAgentProductionSmokeJSONHandler, createVoicePhoneAgentProductionSmokeRoutes, renderVoicePhoneAgentProductionSmokeHTML, runVoicePhoneAgentProductionSmokeContract } from './phoneAgentProductionSmoke';
@@ -111,6 +114,7 @@ export type { OpenAIVoiceTTSOptions, OpenAIVoiceTTSVoice } from './openaiTTS';
 export type { OpenAIRealtimeAdapterOptions, OpenAIRealtimeModel, OpenAIRealtimeNoiseReduction, OpenAIRealtimeResponseMode, OpenAIRealtimeTranscriptionModel, OpenAIRealtimeVoice } from './openaiRealtime';
 export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProviderHealthSummaryOptions } from './providerHealth';
 export type { VoiceProviderCapabilityDefinition, VoiceProviderCapabilityHandlerOptions, VoiceProviderCapabilityHTMLHandlerOptions, VoiceProviderCapabilityKind, VoiceProviderCapabilityOptions, VoiceProviderCapabilityReport, VoiceProviderCapabilityRoutesOptions, VoiceProviderCapabilitySummary } from './providerCapabilities';
+export type { VoiceProviderOrchestrationIssue, VoiceProviderOrchestrationReport, VoiceProviderOrchestrationReportOptions, VoiceProviderOrchestrationRequirement, VoiceProviderOrchestrationRoutesOptions, VoiceProviderOrchestrationStatus, VoiceProviderOrchestrationSurfaceReport } from './providerOrchestration';
 export type { VoiceProviderRoutingContractAssertionInput, VoiceProviderRoutingContractAssertionReport, VoiceProviderRoutingContractDefinition, VoiceProviderRoutingContractIssue, VoiceProviderRoutingContractReport, VoiceProviderRoutingContractRunOptions, VoiceProviderRoutingExpectation, VoiceProviderRoutingStatus } from './providerRoutingContract';
 export type { VoiceProviderSloAssertionInput, VoiceProviderSloAssertionReport, VoiceProviderSloIssue, VoiceProviderSloKindReport, VoiceProviderSloMetric, VoiceProviderSloReport, VoiceProviderSloReportOptions, VoiceProviderSloRoutesOptions, VoiceProviderSloSessionReport, VoiceProviderSloStatus, VoiceProviderSloThresholdConfig, VoiceProviderSloThresholds } from './providerSlo';
 export type { VoiceTurnLatencyHTMLHandlerOptions, VoiceTurnLatencyItem, VoiceTurnLatencyOptions, VoiceTurnLatencyReport, VoiceTurnLatencyRoutesOptions, VoiceTurnLatencyStage, VoiceTurnLatencyStatus } from './turnLatency';