@absolutejs/voice 0.0.22-beta.297 → 0.0.22-beta.298

package/README.md

@@ -4116,7 +4116,7 @@ app.use(
 );
 ```
 
-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?".
+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?". For proof packs, gate fallback and degradation directly with `minFallbacks`, `minDegraded`, `requiredStatuses`, `requiredFallbackProviders`, and `requiredReasonIncludes` so deploy evidence fails when fallback behavior is missing or unexplained.
 
 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.
 

package/dist/index.js

@@ -13146,7 +13146,7 @@ var uniqueSorted = (values) => [
 ].sort();
 var createVoiceProviderDecisionTraceEvent = (input) => {
   const surface = input.surface ?? surfaceForKind(input.kind);
-  const reason = input.reason ?? (input.status === "fallback" ? `Fallback from ${input.provider} to ${input.fallbackProvider ?? input.selectedProvider ?? "next provider"}.` : input.status === "error" ? `Provider ${input.provider} errored before recovery.` : input.status === "skipped" ? `Provider ${input.provider} was skipped by policy.` : `Provider ${input.selectedProvider ?? input.provider} selected by policy.`);
+  const reason = input.reason ?? (input.status === "degraded" ? `Provider ${input.provider} degraded to ${input.fallbackProvider ?? input.selectedProvider ?? "lower-fidelity fallback"}.` : input.status === "fallback" ? `Fallback from ${input.provider} to ${input.fallbackProvider ?? input.selectedProvider ?? "next provider"}.` : input.status === "error" ? `Provider ${input.provider} errored before recovery.` : input.status === "skipped" ? `Provider ${input.provider} was skipped by policy.` : `Provider ${input.selectedProvider ?? input.provider} selected by policy.`);
   return {
     at: input.at ?? Date.now(),
     payload: {
@@ -13170,7 +13170,7 @@ var listVoiceProviderDecisionTraces = (events) => {
     const provider = getString8(event.payload.provider);
     const status = getString8(event.payload.status);
     const surface = getString8(event.payload.surface);
-    if (!provider || !surface || status !== "error" && status !== "fallback" && status !== "selected" && status !== "skipped" && status !== "success") {
+    if (!provider || !surface || status !== "error" && status !== "fallback" && status !== "degraded" && status !== "selected" && status !== "skipped" && status !== "success") {
       return;
     }
     return {
@@ -13237,6 +13237,18 @@ var buildVoiceProviderDecisionTraceReport = async (options) => {
       });
     }
   }
+  const fallbackCount = decisions.filter((decision) => decision.status === "fallback").length;
+  const degradedCount = decisions.filter((decision) => decision.status === "degraded").length;
+  const statuses = new Set(decisions.map((decision) => decision.status));
+  const providers = uniqueSorted(decisions.flatMap((decision) => [
+    decision.provider,
+    decision.selectedProvider,
+    decision.fallbackProvider
+  ]));
+  const fallbackProviders = uniqueSorted(decisions.flatMap((decision) => [
+    decision.fallbackProvider,
+    decision.status === "fallback" || decision.status === "degraded" ? decision.selectedProvider : undefined
+  ]));
   if (options.minDecisions !== undefined && decisions.length < options.minDecisions) {
     issues.push({
       code: "voice.provider_decision_trace.min_decisions",
@@ -13244,9 +13256,60 @@ var buildVoiceProviderDecisionTraceReport = async (options) => {
       status: "fail"
     });
   }
+  if (options.minFallbacks !== undefined && fallbackCount < options.minFallbacks) {
+    issues.push({
+      code: "voice.provider_decision_trace.min_fallbacks",
+      message: `Found ${String(fallbackCount)} provider fallback trace(s); expected at least ${String(options.minFallbacks)}.`,
+      status: "fail"
+    });
+  }
+  if (options.minDegraded !== undefined && degradedCount < options.minDegraded) {
+    issues.push({
+      code: "voice.provider_decision_trace.min_degraded",
+      message: `Found ${String(degradedCount)} provider degradation trace(s); expected at least ${String(options.minDegraded)}.`,
+      status: "fail"
+    });
+  }
+  for (const status of options.requiredStatuses ?? []) {
+    if (!statuses.has(status)) {
+      issues.push({
+        code: "voice.provider_decision_trace.status_missing",
+        message: `Missing provider decision status: ${status}.`,
+        status: "fail"
+      });
+    }
+  }
+  for (const provider of options.requiredProviders ?? []) {
+    if (!providers.includes(provider)) {
+      issues.push({
+        code: "voice.provider_decision_trace.provider_missing",
+        message: `Missing provider decision provider: ${provider}.`,
+        status: "fail"
+      });
+    }
+  }
+  for (const provider of options.requiredFallbackProviders ?? []) {
+    if (!fallbackProviders.includes(provider)) {
+      issues.push({
+        code: "voice.provider_decision_trace.fallback_provider_missing",
+        message: `Missing provider decision fallback provider: ${provider}.`,
+        status: "fail"
+      });
+    }
+  }
+  for (const phrase of options.requiredReasonIncludes ?? []) {
+    if (!decisions.some((decision) => decision.reason.includes(phrase))) {
+      issues.push({
+        code: "voice.provider_decision_trace.reason_missing",
+        message: `Missing provider decision reason containing: ${phrase}.`,
+        status: "fail"
+      });
+    }
+  }
   const surfaceReports = [...surfaces.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([surface, surfaceDecisions]) => {
     const surfaceIssues = issues.filter((issue) => issue.surface === surface);
     return {
+      degraded: surfaceDecisions.filter((decision) => decision.status === "degraded").length,
       decisions: surfaceDecisions.length,
       errors: surfaceDecisions.filter((decision) => decision.status === "error").length,
       fallbacks: surfaceDecisions.filter((decision) => decision.status === "fallback").length,
@@ -13263,20 +13326,16 @@ var buildVoiceProviderDecisionTraceReport = async (options) => {
       surface
     };
   });
-  const providers = uniqueSorted(decisions.flatMap((decision) => [
-    decision.provider,
-    decision.selectedProvider,
-    decision.fallbackProvider
-  ]));
   return {
     checkedAt: now,
     decisions,
     issues,
     status: reportStatus(issues),
     summary: {
+      degraded: degradedCount,
       decisions: decisions.length,
       errors: decisions.filter((decision) => decision.status === "error").length,
-      fallbacks: decisions.filter((decision) => decision.status === "fallback").length,
+      fallbacks: fallbackCount,
       providers: providers.length,
       selected: decisions.filter((decision) => decision.status === "selected" || decision.status === "success").length,
       surfaces: surfaces.size
@@ -13291,11 +13350,12 @@ var renderVoiceProviderDecisionTraceMarkdown = (report) => [
   `Decisions: ${String(report.summary.decisions)}`,
   `Providers: ${String(report.summary.providers)}`,
   `Fallbacks: ${String(report.summary.fallbacks)}`,
+  `Degraded: ${String(report.summary.degraded)}`,
   `Errors: ${String(report.summary.errors)}`,
   "",
-  "| Surface | Status | Decisions | Selected | Fallbacks | Errors | Providers |",
-  "| --- | --- | ---: | ---: | ---: | ---: | --- |",
-  ...report.surfaces.map((surface) => `| ${surface.surface} | ${surface.status} | ${String(surface.decisions)} | ${String(surface.selected)} | ${String(surface.fallbacks)} | ${String(surface.errors)} | ${surface.providers.join(", ")} |`),
+  "| Surface | Status | Decisions | Selected | Fallbacks | Degraded | Errors | Providers |",
+  "| --- | --- | ---: | ---: | ---: | ---: | ---: | --- |",
+  ...report.surfaces.map((surface) => `| ${surface.surface} | ${surface.status} | ${String(surface.decisions)} | ${String(surface.selected)} | ${String(surface.fallbacks)} | ${String(surface.degraded)} | ${String(surface.errors)} | ${surface.providers.join(", ")} |`),
   "",
   ...report.issues.map((issue) => `- ${issue.status}: ${issue.message}`)
 ].join(`
@@ -13326,12 +13386,13 @@ code{background:#e2e8f0;border-radius:8px;padding:2px 6px}
 <article class="card"><strong>${String(report.summary.decisions)}</strong><p>decisions</p></article>
 <article class="card"><strong>${String(report.summary.providers)}</strong><p>providers</p></article>
 <article class="card"><strong>${String(report.summary.fallbacks)}</strong><p>fallbacks</p></article>
+<article class="card"><strong>${String(report.summary.degraded)}</strong><p>degraded</p></article>
 <article class="card"><strong>${String(report.summary.errors)}</strong><p>errors</p></article>
 </section>
 <section class="surfaces">
 ${report.surfaces.map((surface) => `<article class="surface">
 <header><strong>${escapeHtml17(surface.surface)}</strong> <span class="status ${surface.status}">${escapeHtml17(surface.status)}</span></header>
-<p>${String(surface.decisions)} decision(s), ${String(surface.fallbacks)} fallback(s), ${String(surface.errors)} error(s).</p>
+<p>${String(surface.decisions)} decision(s), ${String(surface.fallbacks)} fallback(s), ${String(surface.degraded)} degraded decision(s), ${String(surface.errors)} error(s).</p>
 <p class="muted">Providers: ${escapeHtml17(surface.providers.join(", ") || "none")}</p>
 <p>${surface.reasons.map((reason) => `<code>${escapeHtml17(reason)}</code>`).join(" ")}</p>
 </article>`).join(`

package/dist/providerDecisionTraces.d.ts

@@ -1,7 +1,7 @@
 import { Elysia } from 'elysia';
 import { type VoiceRoutingEventKind } from './resilienceRoutes';
 import type { StoredVoiceTraceEvent, VoiceTraceEvent, VoiceTraceEventStore } from './trace';
-export type VoiceProviderDecisionStatus = 'error' | 'fallback' | 'selected' | 'skipped' | 'success';
+export type VoiceProviderDecisionStatus = 'degraded' | 'error' | 'fallback' | 'selected' | 'skipped' | 'success';
 export type VoiceProviderDecisionTrace = {
     at: number;
     elapsedMs?: number;
@@ -31,6 +31,7 @@ export type VoiceProviderDecisionTraceIssue = {
     surface?: string;
 };
 export type VoiceProviderDecisionSurfaceReport = {
+    degraded: number;
     decisions: number;
     errors: number;
     fallbacks: number;
@@ -48,6 +49,7 @@ export type VoiceProviderDecisionTraceReport = {
     issues: VoiceProviderDecisionTraceIssue[];
     status: 'fail' | 'pass' | 'warn';
     summary: {
+        degraded: number;
         decisions: number;
         errors: number;
         fallbacks: number;
@@ -60,9 +62,15 @@ export type VoiceProviderDecisionTraceReport = {
 export type VoiceProviderDecisionTraceReportOptions = {
     events?: StoredVoiceTraceEvent[] | VoiceProviderDecisionTrace[];
     maxAgeMs?: number;
+    minDegraded?: number;
     minDecisions?: number;
+    minFallbacks?: number;
     now?: number;
+    requiredFallbackProviders?: readonly string[];
+    requiredProviders?: readonly string[];
+    requiredReasonIncludes?: readonly string[];
     requiredSurfaces?: readonly string[];
+    requiredStatuses?: readonly VoiceProviderDecisionStatus[];
     sessionId?: string;
     store?: VoiceTraceEventStore;
 };

package/package.json

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