@absolutejs/voice 0.0.22-beta.249 → 0.0.22-beta.250

package/README.md

@@ -3938,6 +3938,25 @@ app
 
 The provider SLO routes expose JSON at `/api/voice/provider-slos`, HTML at `/voice/provider-slos`, and Markdown at `/voice/provider-slos.md`. Readiness adds a `Provider SLO gates` check when `providerSlo` is configured; failing latency, timeout, fallback, or unresolved-error budgets close the deploy gate.
 
+Use `evaluateVoiceProviderSloEvidence(...)` or `assertVoiceProviderSloEvidence(...)` when a proof pack needs to verify the JSON directly instead of scraping rendered HTML. The assertion can require LLM/STT/TTS evidence, latency samples, fallback events, named providers, and per-kind latency ceilings:
+
+```ts
+const providerReport = await buildVoiceProviderSloReport({
+	requiredKinds: ['llm', 'stt', 'tts'],
+	store: runtime.traces
+});
+
+assertVoiceProviderSloEvidence(providerReport, {
+	fallbackKinds: ['llm'],
+	maxP95ElapsedMs: { llm: 4500, stt: 1500, tts: 2200 },
+	maxStatus: 'pass',
+	minFallbacks: 1,
+	minLatencySamples: 3,
+	requiredKinds: ['llm', 'stt', 'tts'],
+	requiredProviders: ['openai', 'anthropic', 'deepgram']
+});
+```
+
 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

@@ -50,7 +50,7 @@ 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 { buildVoiceProviderSloReport, createVoiceProviderSloRoutes, renderVoiceProviderSloHTML, renderVoiceProviderSloMarkdown } from './providerSlo';
+export { assertVoiceProviderSloEvidence, buildVoiceProviderSloReport, createVoiceProviderSloRoutes, evaluateVoiceProviderSloEvidence, renderVoiceProviderSloHTML, renderVoiceProviderSloMarkdown } from './providerSlo';
 export { createVoicePhoneAgentProductionSmokeHTMLHandler, createVoicePhoneAgentProductionSmokeJSONHandler, createVoicePhoneAgentProductionSmokeRoutes, renderVoicePhoneAgentProductionSmokeHTML, runVoicePhoneAgentProductionSmokeContract } from './phoneAgentProductionSmoke';
 export { buildVoiceProductionReadinessGate, buildVoiceProductionReadinessReport, createVoiceProductionReadinessRoutes, renderVoiceProductionReadinessHTML, summarizeVoiceProductionReadinessGate } from './productionReadiness';
 export { createVoiceReadinessProfile, recommendVoiceReadinessProfile } from './readinessProfiles';
@@ -109,7 +109,7 @@ export type { OpenAIRealtimeAdapterOptions, OpenAIRealtimeModel, OpenAIRealtimeN
 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 { VoiceProviderSloIssue, VoiceProviderSloKindReport, VoiceProviderSloMetric, VoiceProviderSloReport, VoiceProviderSloReportOptions, VoiceProviderSloRoutesOptions, VoiceProviderSloSessionReport, VoiceProviderSloStatus, VoiceProviderSloThresholdConfig, VoiceProviderSloThresholds } from './providerSlo';
+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';
 export type { VoiceLiveLatencyOptions, VoiceLiveLatencyReport, VoiceLiveLatencyRoutesOptions, VoiceLiveLatencySample, VoiceLiveLatencyStatus } from './liveLatency';
 export type { VoiceLatencySLOBudget, VoiceLatencySLOGateError, VoiceLatencySLOGateOptions, VoiceLatencySLOGateReport, VoiceLatencySLOMeasurement, VoiceLatencySLOStage, VoiceLatencySLOStageSummary, VoiceLatencySLOStatus } from './latencySlo';

package/dist/index.js

@@ -22055,9 +22055,17 @@ var defaultThresholds = {
   }
 };
 var providerKinds = ["llm", "stt", "tts"];
+var statusRank = {
+  pass: 0,
+  warn: 1,
+  fail: 2
+};
 var escapeHtml36 = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 var roundMetric3 = (value) => Math.round(value * 1e4) / 1e4;
 var rate3 = (count, total) => count / Math.max(1, total);
+var uniqueSorted = (values) => [
+  ...new Set(values.filter((value) => typeof value === "string"))
+].sort();
 var percentile3 = (values, rank) => {
   if (values.length === 0) {
     return 0;
@@ -22235,6 +22243,85 @@ var buildVoiceProviderSloReport = async (options = {}) => {
     thresholds
   };
 };
+var evaluateVoiceProviderSloEvidence = (report, input = {}) => {
+  const issues = [];
+  const kindReports = Object.values(report.kinds);
+  const providers = uniqueSorted(kindReports.flatMap((kind) => kind.providers));
+  const kinds = providerKinds.filter((kind) => report.kinds[kind].events > 0);
+  const fallbacks = kindReports.reduce((total, kind) => total + kind.fallbacks, 0);
+  const timeouts = kindReports.reduce((total, kind) => total + kind.timeouts, 0);
+  const unresolvedErrors = kindReports.reduce((total, kind) => total + kind.unresolvedErrors, 0);
+  const maxStatus = input.maxStatus ?? "pass";
+  if (statusRank[report.status] > statusRank[maxStatus]) {
+    issues.push(`Expected provider SLO status at most ${maxStatus}, found ${report.status}.`);
+  }
+  if (input.minEvents !== undefined && report.events < input.minEvents) {
+    issues.push(`Expected at least ${String(input.minEvents)} provider routing events, found ${String(report.events)}.`);
+  }
+  if (input.minLatencySamples !== undefined && report.eventsWithLatency < input.minLatencySamples) {
+    issues.push(`Expected at least ${String(input.minLatencySamples)} provider latency samples, found ${String(report.eventsWithLatency)}.`);
+  }
+  if (input.minFallbacks !== undefined && fallbacks < input.minFallbacks) {
+    issues.push(`Expected at least ${String(input.minFallbacks)} provider fallback events, found ${String(fallbacks)}.`);
+  }
+  if (input.maxUnresolvedErrors !== undefined && unresolvedErrors > input.maxUnresolvedErrors) {
+    issues.push(`Expected at most ${String(input.maxUnresolvedErrors)} unresolved provider errors, found ${String(unresolvedErrors)}.`);
+  }
+  if (input.maxTimeouts !== undefined && timeouts > input.maxTimeouts) {
+    issues.push(`Expected at most ${String(input.maxTimeouts)} provider timeouts, found ${String(timeouts)}.`);
+  }
+  if (input.maxIssues !== undefined && report.issues.length > input.maxIssues) {
+    issues.push(`Expected at most ${String(input.maxIssues)} provider SLO issues, found ${String(report.issues.length)}.`);
+  }
+  for (const kind of input.requiredKinds ?? []) {
+    if (report.kinds[kind].events === 0) {
+      issues.push(`Missing provider SLO kind evidence: ${kind}.`);
+    }
+  }
+  for (const kind of input.fallbackKinds ?? []) {
+    if (report.kinds[kind].fallbacks === 0) {
+      issues.push(`Missing provider fallback evidence for kind: ${kind}.`);
+    }
+  }
+  for (const provider of input.requiredProviders ?? []) {
+    if (!providers.includes(provider)) {
+      issues.push(`Missing provider SLO provider evidence: ${provider}.`);
+    }
+  }
+  for (const [kind, maxAverageElapsedMs] of Object.entries(input.maxAverageElapsedMs ?? {})) {
+    const metric = report.kinds[kind].metrics.averageElapsedMs;
+    const actual = metric?.actual ?? 0;
+    if (actual > maxAverageElapsedMs) {
+      issues.push(`Expected ${kind} average provider latency <= ${String(maxAverageElapsedMs)}ms, found ${String(actual)}ms.`);
+    }
+  }
+  for (const [kind, maxP95ElapsedMs] of Object.entries(input.maxP95ElapsedMs ?? {})) {
+    const metric = report.kinds[kind].metrics.p95ElapsedMs;
+    const actual = metric?.actual ?? 0;
+    if (actual > maxP95ElapsedMs) {
+      issues.push(`Expected ${kind} p95 provider latency <= ${String(maxP95ElapsedMs)}ms, found ${String(actual)}ms.`);
+    }
+  }
+  return {
+    events: report.events,
+    eventsWithLatency: report.eventsWithLatency,
+    fallbacks,
+    issues,
+    kinds,
+    ok: issues.length === 0,
+    providers,
+    status: report.status,
+    timeouts,
+    unresolvedErrors
+  };
+};
+var assertVoiceProviderSloEvidence = (report, input = {}) => {
+  const assertion = evaluateVoiceProviderSloEvidence(report, input);
+  if (!assertion.ok) {
+    throw new Error(`Voice provider SLO assertion failed: ${assertion.issues.join(" ")}`);
+  }
+  return assertion;
+};
 var formatMetricValue2 = (metric) => metric.unit === "rate" ? `${(metric.actual * 100).toFixed(2)}%` : metric.unit === "ms" ? `${Math.round(metric.actual)}ms` : String(metric.actual);
 var formatMetricThreshold = (metric) => metric.unit === "rate" ? `${(metric.threshold * 100).toFixed(2)}%` : metric.unit === "ms" ? `${Math.round(metric.threshold)}ms` : String(metric.threshold);
 var getMetric = (report, key) => report.metrics[key];
@@ -22880,7 +22967,7 @@ var hasPayloadValue = (payload, key, values) => {
   return typeof value === "string" && values.has(value);
 };
 var countIntegrationDeliveryStatus = (events, status) => events.filter((event) => event.deliveryStatus === status).length;
-var uniqueSorted = (values) => [
+var uniqueSorted2 = (values) => [
   ...new Set(values.filter((value) => typeof value === "string"))
 ].sort();
 var pushMissingValuesIssue = (input) => {
@@ -23059,11 +23146,11 @@ var buildVoiceOperationsRecord = async (options) => {
 var evaluateVoiceOperationsRecordGuardrails = (record, input = {}) => {
   const issues = [];
   const decisions = record.guardrails.decisions;
-  const proofs = uniqueSorted(decisions.map((decision) => decision.proof));
-  const ruleIds = uniqueSorted(decisions.flatMap((decision) => decision.findings.map((finding) => finding.ruleId)));
-  const stages = uniqueSorted(decisions.map((decision) => decision.stage));
-  const statuses = uniqueSorted(decisions.map((decision) => decision.status));
-  const toolNames = uniqueSorted(decisions.map((decision) => decision.toolName));
+  const proofs = uniqueSorted2(decisions.map((decision) => decision.proof));
+  const ruleIds = uniqueSorted2(decisions.flatMap((decision) => decision.findings.map((finding) => finding.ruleId)));
+  const stages = uniqueSorted2(decisions.map((decision) => decision.stage));
+  const statuses = uniqueSorted2(decisions.map((decision) => decision.status));
+  const toolNames = uniqueSorted2(decisions.map((decision) => decision.toolName));
   const minDecisions = input.minDecisions ?? 1;
   if (record.guardrails.total < minDecisions) {
     issues.push(`Expected at least ${String(minDecisions)} guardrail decisions, found ${String(record.guardrails.total)}.`);
@@ -29986,6 +30073,7 @@ export {
   evaluateVoiceTelephonyContract,
   evaluateVoiceQuality,
   evaluateVoiceProviderStackGaps,
+  evaluateVoiceProviderSloEvidence,
   evaluateVoiceOperationsRecordGuardrails,
   evaluateVoiceGuardrailPolicy,
   encodeTwilioMulawBase64,
@@ -30299,6 +30387,7 @@ export {
   buildVoiceAuditDeliveryReport,
   buildEmptyVoiceProofTrendReport,
   assignVoiceOpsTask,
+  assertVoiceProviderSloEvidence,
   assertVoiceProviderRoutingContract,
   assertVoiceOperationsRecordGuardrails,
   assertVoiceObservabilityExportSchema,

package/dist/providerSlo.d.ts

@@ -79,7 +79,35 @@ export type VoiceProviderSloRoutesOptions = VoiceProviderSloReportOptions & {
     render?: (report: VoiceProviderSloReport) => string | Promise<string>;
     title?: string;
 };
+export type VoiceProviderSloAssertionInput = {
+    fallbackKinds?: VoiceRoutingEventKind[];
+    maxAverageElapsedMs?: Partial<Record<VoiceRoutingEventKind, number>>;
+    maxIssues?: number;
+    maxP95ElapsedMs?: Partial<Record<VoiceRoutingEventKind, number>>;
+    maxStatus?: VoiceProviderSloStatus;
+    maxTimeouts?: number;
+    maxUnresolvedErrors?: number;
+    minEvents?: number;
+    minFallbacks?: number;
+    minLatencySamples?: number;
+    requiredKinds?: VoiceRoutingEventKind[];
+    requiredProviders?: string[];
+};
+export type VoiceProviderSloAssertionReport = {
+    events: number;
+    eventsWithLatency: number;
+    fallbacks: number;
+    issues: string[];
+    kinds: VoiceRoutingEventKind[];
+    ok: boolean;
+    providers: string[];
+    status: VoiceProviderSloStatus;
+    timeouts: number;
+    unresolvedErrors: number;
+};
 export declare const buildVoiceProviderSloReport: (options?: VoiceProviderSloReportOptions) => Promise<VoiceProviderSloReport>;
+export declare const evaluateVoiceProviderSloEvidence: (report: VoiceProviderSloReport, input?: VoiceProviderSloAssertionInput) => VoiceProviderSloAssertionReport;
+export declare const assertVoiceProviderSloEvidence: (report: VoiceProviderSloReport, input?: VoiceProviderSloAssertionInput) => VoiceProviderSloAssertionReport;
 export declare const renderVoiceProviderSloMarkdown: (report: VoiceProviderSloReport) => string;
 export declare const renderVoiceProviderSloHTML: (report: VoiceProviderSloReport, options?: {
     title?: string;

package/package.json

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