@absolutejs/voice 0.0.22-beta.289 → 0.0.22-beta.290

package/dist/index.js

@@ -28269,11 +28269,31 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
       label: "Open calibrated gate source"
     }
   ] : [];
+  const calibratedGateExplanation = (input2) => ({
+    ...input2,
+    sourceHref: options.links?.sloReadinessThresholds
+  });
+  const providerSloMetricForIssue = () => {
+    const issue = providerSlo?.issues[0];
+    if (!issue?.kind) {
+      return;
+    }
+    const metrics = providerSlo?.kinds[issue.kind]?.metrics;
+    return Object.values(metrics ?? {}).find((metric) => metric.label === issue.label || issue.code.endsWith(metric.label.toLowerCase().replace(/[^a-z0-9]+/g, "_")));
+  };
   checks.push({
     detail: liveLatency.total === 0 ? "No browser live-latency measurements are recorded yet." : liveLatency.status === "pass" ? `Live browser turn latency averages ${liveLatency.averageLatencyMs}ms.` : `${liveLatency.failed} failed and ${liveLatency.warnings} warned live-latency measurement(s).`,
     href: firstOperationsRecordHref(operationsRecords.failingLatency) ?? options.links?.liveLatency ?? "/traces",
     label: "Live latency proof",
     proofSource: proofSource("liveLatency", "liveLatencyProof"),
+    gateExplanation: liveLatency.status === "pass" ? undefined : calibratedGateExplanation({
+      evidenceHref: firstOperationsRecordHref(operationsRecords.failingLatency) ?? options.links?.liveLatency ?? "/traces",
+      observed: liveLatency.averageLatencyMs,
+      remediation: "Inspect the slow browser turn, reduce provider/turn latency, then rerun live latency proof so readiness uses fresh samples.",
+      threshold: liveLatency.status === "fail" ? options.liveLatencyFailAfterMs ?? 3200 : options.liveLatencyWarnAfterMs ?? 1800,
+      thresholdLabel: liveLatency.status === "fail" ? "Live latency fail after" : "Live latency warn after",
+      unit: "ms"
+    }),
     status: liveLatency.status,
     value: liveLatency.averageLatencyMs === undefined ? `${liveLatency.total} samples` : `${liveLatency.averageLatencyMs}ms avg`,
     actions: liveLatency.status === "pass" ? [] : [
@@ -28436,11 +28456,20 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
   }
   if (providerSloSummary && providerSlo) {
     const firstIssue = providerSlo.issues[0];
+    const firstMetric = providerSloMetricForIssue();
     checks.push({
       detail: providerSloSummary.status === "pass" ? `${providerSloSummary.eventsWithLatency} provider latency sample(s) are inside LLM/STT/TTS SLO budgets.` : firstIssue?.detail ?? `${providerSloSummary.issues} provider SLO issue(s) need review.`,
       href: firstIssue?.sessionId ? voiceOperationsRecordHref(options.links?.operationsRecords ?? "/voice-operations", firstIssue.sessionId) : options.links?.providerSlo ?? options.links?.resilience ?? "/voice/provider-slos",
       label: "Provider SLO gates",
       proofSource: proofSource("providerSlo", "providerSlos"),
+      gateExplanation: providerSloSummary.status === "pass" ? undefined : calibratedGateExplanation({
+        evidenceHref: firstIssue?.sessionId ? voiceOperationsRecordHref(options.links?.operationsRecords ?? "/voice-operations", firstIssue.sessionId) : options.links?.providerSlo ?? options.links?.resilience ?? "/voice/provider-slos",
+        observed: firstMetric?.actual ?? firstIssue?.value,
+        remediation: "Inspect the provider SLO report, fix slow or failing STT/LLM/TTS behavior, then rerun provider proof so the calibrated budget is met.",
+        threshold: firstMetric?.threshold,
+        thresholdLabel: firstMetric?.label ?? firstIssue?.label ?? "Provider SLO gate",
+        unit: firstMetric?.unit
+      }),
       status: providerSloSummary.status,
       value: `${providerSloSummary.eventsWithLatency}/${providerSloSummary.events}`,
       actions: providerSloSummary.status === "pass" ? [] : [
@@ -28577,6 +28606,14 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
       href: options.links?.reconnectContracts ?? options.links?.sessions ?? "/sessions",
       label: "Reconnect recovery contracts",
       proofSource: proofSource("reconnectContracts", "reconnect"),
+      gateExplanation: reconnectContractSummary.status === "pass" ? undefined : calibratedGateExplanation({
+        evidenceHref: options.links?.reconnectContracts ?? options.links?.sessions ?? "/sessions",
+        observed: reconnectContractSummary.resumeLatencyP95Ms,
+        remediation: "Inspect reconnect lifecycle traces, restore faster resume/replay-safe state, then rerun reconnect proof.",
+        threshold: options.reconnectResumeFailAfterMs,
+        thresholdLabel: "Reconnect resume p95 fail after",
+        unit: "ms"
+      }),
       status: reconnectContractSummary.status,
       value: `${reconnectContractSummary.passed}/${reconnectContractSummary.total}`,
       actions: reconnectContractSummary.status === "pass" ? [] : [
@@ -28595,6 +28632,14 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
       href: options.links?.bargeIn ?? "/barge-in",
       label: "Barge-in interruption proof",
       proofSource: proofSource("bargeInReports", "bargeIn"),
+      gateExplanation: bargeInSummary.status === "pass" ? undefined : calibratedGateExplanation({
+        evidenceHref: options.links?.bargeIn ?? "/barge-in",
+        observed: bargeInReports?.map((report) => report.averageLatencyMs).filter((value) => typeof value === "number").sort((left, right) => right - left)[0] ?? `${bargeInSummary.failed} failed`,
+        remediation: "Inspect barge-in proof, confirm playback cancellation is immediate, then rerun interruption proof against the calibrated threshold.",
+        threshold: bargeInReports?.[0]?.thresholdMs,
+        thresholdLabel: "Barge-in interruption threshold",
+        unit: typeof bargeInReports?.[0]?.thresholdMs === "number" ? "ms" : "count"
+      }),
       status: bargeInSummary.status,
       value: `${bargeInSummary.passed}/${bargeInSummary.total}`,
       actions: bargeInSummary.status === "pass" ? [] : [
@@ -28747,6 +28792,14 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
       detail: monitoringSummary.status === "pass" ? `${monitoringSummary.total} monitor(s) are passing with no open issues.` : options.monitoringRunFailAfterMs !== undefined && monitoringSummary.elapsedMs !== undefined && monitoringSummary.elapsedMs > options.monitoringRunFailAfterMs ? `Monitor run took ${monitoringSummary.elapsedMs}ms, above ${options.monitoringRunFailAfterMs}ms.` : `${monitoringSummary.open} monitor issue(s) open, ${monitoringSummary.criticalOpen} critical.`,
       href: options.links?.monitoring ?? "/voice/monitors",
       label: "Monitoring issues",
+      gateExplanation: monitoringSummary.status === "pass" ? undefined : calibratedGateExplanation({
+        evidenceHref: options.links?.monitoring ?? "/voice/monitors",
+        observed: monitoringSummary.elapsedMs ?? `${monitoringSummary.open} open issue(s)`,
+        remediation: "Inspect monitor issues or slow monitor execution, resolve open blockers, then rerun the monitor proof.",
+        threshold: options.monitoringRunFailAfterMs,
+        thresholdLabel: "Monitor run fail after",
+        unit: monitoringSummary.elapsedMs !== undefined ? "ms" : "count"
+      }),
       status: monitoringSummary.status,
       value: `${monitoring.summary.passed}/${monitoringSummary.total}`,
       actions: monitoringSummary.status === "pass" ? [] : [
@@ -28764,6 +28817,14 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
       detail: monitoringNotifierDeliverySummary.status === "pass" ? `${monitoringNotifierDeliverySummary.sent} monitor notification(s) delivered.` : options.monitoringNotifierDeliveryFailAfterMs !== undefined && monitoringNotifierDeliverySummary.elapsedMs !== undefined && monitoringNotifierDeliverySummary.elapsedMs > options.monitoringNotifierDeliveryFailAfterMs ? `Monitor notification delivery took ${monitoringNotifierDeliverySummary.elapsedMs}ms, above ${options.monitoringNotifierDeliveryFailAfterMs}ms.` : `${monitoringNotifierDeliverySummary.failed} monitor notification delivery failure(s).`,
       href: options.links?.monitoringNotifierDelivery ?? "/api/voice/monitor-issues/notifications",
       label: "Monitor notifier delivery",
+      gateExplanation: monitoringNotifierDeliverySummary.status === "pass" ? undefined : calibratedGateExplanation({
+        evidenceHref: options.links?.monitoringNotifierDelivery ?? "/api/voice/monitor-issues/notifications",
+        observed: monitoringNotifierDeliverySummary.elapsedMs ?? `${monitoringNotifierDeliverySummary.failed} failed`,
+        remediation: "Inspect monitor notification receipts, fix webhook/email/Slack delivery, then rerun notifier proof.",
+        threshold: options.monitoringNotifierDeliveryFailAfterMs,
+        thresholdLabel: "Monitor notifier delivery fail after",
+        unit: monitoringNotifierDeliverySummary.elapsedMs !== undefined ? "ms" : "count"
+      }),
       status: monitoringNotifierDeliverySummary.status,
       value: `${monitoringNotifierDeliverySummary.sent}/${monitoringNotifierDeliverySummary.total}`,
       actions: monitoringNotifierDeliverySummary.status === "pass" ? [] : [
@@ -28873,11 +28934,13 @@ var renderVoiceProductionReadinessHTML = (report, options = {}) => {
   const profile = report.profile ? `<section class="profile"><p class="eyebrow">Readiness profile</p><h2>${escapeHtml41(report.profile.name)}</h2><p>${escapeHtml41(report.profile.description)}</p><p>${escapeHtml41(report.profile.purpose)}</p><div class="profile-surfaces">${report.profile.surfaces.map((surface) => `<article class="${surface.configured ? "pass" : "warn"}"><span>${surface.configured ? "CONFIGURED" : "EXPECTED"}</span><strong>${surface.href ? `<a href="${escapeHtml41(surface.href)}">${escapeHtml41(surface.label)}</a>` : escapeHtml41(surface.label)}</strong></article>`).join("")}</div></section>` : "";
   const checks = report.checks.map((check, index) => {
     const actions = (check.actions ?? []).map((action) => action.method === "POST" ? `<button type="button" data-readiness-action="${index}" data-action-url="${escapeHtml41(action.href)}">${escapeHtml41(action.label)}</button>` : `<a href="${escapeHtml41(action.href)}">${escapeHtml41(action.label)}</a>`).join("");
+    const explanation = check.gateExplanation ? `<p class="gate-explanation">Why this gate is ${escapeHtml41(check.status)}: observed ${escapeHtml41(String(check.gateExplanation.observed ?? "n/a"))}${check.gateExplanation.unit ? ` ${escapeHtml41(check.gateExplanation.unit)}` : ""}; threshold ${escapeHtml41(String(check.gateExplanation.threshold ?? "n/a"))}${check.gateExplanation.unit ? ` ${escapeHtml41(check.gateExplanation.unit)}` : ""}. ${escapeHtml41(check.gateExplanation.remediation)} ${check.gateExplanation.sourceHref ? `<a href="${escapeHtml41(check.gateExplanation.sourceHref)}">Open threshold source</a>` : ""}</p>` : "";
     return `<article class="check ${escapeHtml41(check.status)}">
         <div>
           <span>${escapeHtml41(check.status.toUpperCase())}</span>
           <h2>${escapeHtml41(check.label)}</h2>
           ${check.detail ? `<p>${escapeHtml41(check.detail)}</p>` : ""}
+          ${explanation}
           ${check.proofSource ? `<p class="proof-source">Proof source: ${check.proofSource.href ? `<a href="${escapeHtml41(check.proofSource.href)}">${escapeHtml41(check.proofSource.sourceLabel)}</a>` : escapeHtml41(check.proofSource.sourceLabel)}${check.proofSource.detail ? ` \xB7 ${escapeHtml41(check.proofSource.detail)}` : ""}</p>` : ""}
           ${actions ? `<p class="actions">${actions}</p>` : ""}
         </div>
@@ -28901,7 +28964,7 @@ var renderVoiceProductionReadinessHTML = (report, options = {}) => {
 	providerRoutingContracts: loadProviderRoutingContracts,
 	store: traceStore
 });`);
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml41(title)}</title><style>body{background:#0c0f14;color:#f6f2e8;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1060px;padding:32px}.hero,.primitive,.profile{background:linear-gradient(135deg,rgba(20,184,166,.18),rgba(245,158,11,.12));border:1px solid #26313d;border-radius:28px;margin-bottom:18px;padding:28px}.primitive,.profile{background:#111722}.primitive{border-color:#3a3f2d}.eyebrow{color:#fbbf24;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.4rem,6vw,5rem);line-height:.9;margin:.2rem 0 1rem}.status{display:inline-flex;border:1px solid #3f3f46;border-radius:999px;padding:8px 12px}.primitive code{color:#fde68a}.primitive p{color:#c8ccd3;line-height:1.55;margin:.45rem 0 0}.primitive pre{background:#0b0f16;border:1px solid #2c3440;border-radius:18px;color:#fef3c7;margin:16px 0 0;overflow:auto;padding:16px}.status.pass,.check.pass,.profile-surfaces .pass{border-color:rgba(34,197,94,.55)}.status.warn,.check.warn,.profile-surfaces .warn{border-color:rgba(245,158,11,.65)}.status.fail,.check.fail{border-color:rgba(239,68,68,.75)}.checks{display:grid;gap:14px}.check{align-items:center;background:#141922;border:1px solid #26313d;border-radius:22px;display:grid;gap:16px;grid-template-columns:1fr auto auto;padding:18px}.check span,.profile-surfaces span{color:#a8b0b8;font-size:.78rem;font-weight:900;letter-spacing:.08em}.check h2{margin:.2rem 0}.check p,.profile p{color:#b9c0c8;margin:.2rem 0 0}.check .proof-source{color:#f9d77e;font-weight:800}.check strong{font-size:1.5rem}.profile-surfaces{display:grid;gap:10px;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));margin-top:16px}.profile-surfaces article{background:#141922;border:1px solid #26313d;border-radius:16px;padding:14px}.profile-surfaces strong{display:block;margin-top:6px}.actions{display:flex;flex-wrap:wrap;gap:10px}.check a,a{color:#fbbf24}button{background:#fbbf24;border:0;border-radius:999px;color:#111827;cursor:pointer;font-weight:800;padding:9px 12px}button:disabled{cursor:wait;opacity:.65}@media(max-width:760px){main{padding:20px}.check{grid-template-columns:1fr}}</style></head><body><main><section class="hero"><p class="eyebrow">Self-hosted readiness</p><h1>${escapeHtml41(title)}</h1><p>One deployable pass/fail report for quality gates, provider failover, session health, handoffs, routing evidence, and optional carrier readiness.</p><p class="status ${escapeHtml41(report.status)}">Overall: ${escapeHtml41(report.status.toUpperCase())}</p><p>Checked ${escapeHtml41(new Date(report.checkedAt).toLocaleString())}</p>${thresholdLink}</section>${profile}<section class="primitive"><p class="eyebrow">Copy into your app</p><h2><code>createVoiceProductionReadinessRoutes(...)</code> builds this deploy gate</h2><p>Mount one package primitive to expose JSON readiness, HTML readiness, and a machine-readable gate route. Feed it the proof stores and contract reports your app already owns.</p><pre><code>${snippet}</code></pre></section><section class="checks">${checks}</section></main><script>document.querySelectorAll("[data-readiness-action]").forEach((button)=>{button.addEventListener("click",async()=>{const url=button.getAttribute("data-action-url");if(!url)return;button.disabled=true;const original=button.textContent;button.textContent="Running...";try{const response=await fetch(url,{method:"POST"});button.textContent=response.ok?"Done. Reloading...":"Failed";if(response.ok)setTimeout(()=>location.reload(),500)}catch{button.textContent="Failed"}finally{setTimeout(()=>{button.disabled=false;button.textContent=original},1500)}})});</script></body></html>`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml41(title)}</title><style>body{background:#0c0f14;color:#f6f2e8;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1060px;padding:32px}.hero,.primitive,.profile{background:linear-gradient(135deg,rgba(20,184,166,.18),rgba(245,158,11,.12));border:1px solid #26313d;border-radius:28px;margin-bottom:18px;padding:28px}.primitive,.profile{background:#111722}.primitive{border-color:#3a3f2d}.eyebrow{color:#fbbf24;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.4rem,6vw,5rem);line-height:.9;margin:.2rem 0 1rem}.status{display:inline-flex;border:1px solid #3f3f46;border-radius:999px;padding:8px 12px}.primitive code{color:#fde68a}.primitive p{color:#c8ccd3;line-height:1.55;margin:.45rem 0 0}.primitive pre{background:#0b0f16;border:1px solid #2c3440;border-radius:18px;color:#fef3c7;margin:16px 0 0;overflow:auto;padding:16px}.status.pass,.check.pass,.profile-surfaces .pass{border-color:rgba(34,197,94,.55)}.status.warn,.check.warn,.profile-surfaces .warn{border-color:rgba(245,158,11,.65)}.status.fail,.check.fail{border-color:rgba(239,68,68,.75)}.checks{display:grid;gap:14px}.check{align-items:center;background:#141922;border:1px solid #26313d;border-radius:22px;display:grid;gap:16px;grid-template-columns:1fr auto auto;padding:18px}.check span,.profile-surfaces span{color:#a8b0b8;font-size:.78rem;font-weight:900;letter-spacing:.08em}.check h2{margin:.2rem 0}.check p,.profile p{color:#b9c0c8;margin:.2rem 0 0}.check .proof-source{color:#f9d77e;font-weight:800}.check .gate-explanation{background:#0b0f16;border:1px solid #2c3440;border-radius:14px;color:#fef3c7;margin-top:10px;padding:10px}.check strong{font-size:1.5rem}.profile-surfaces{display:grid;gap:10px;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));margin-top:16px}.profile-surfaces article{background:#141922;border:1px solid #26313d;border-radius:16px;padding:14px}.profile-surfaces strong{display:block;margin-top:6px}.actions{display:flex;flex-wrap:wrap;gap:10px}.check a,a{color:#fbbf24}button{background:#fbbf24;border:0;border-radius:999px;color:#111827;cursor:pointer;font-weight:800;padding:9px 12px}button:disabled{cursor:wait;opacity:.65}@media(max-width:760px){main{padding:20px}.check{grid-template-columns:1fr}}</style></head><body><main><section class="hero"><p class="eyebrow">Self-hosted readiness</p><h1>${escapeHtml41(title)}</h1><p>One deployable pass/fail report for quality gates, provider failover, session health, handoffs, routing evidence, and optional carrier readiness.</p><p class="status ${escapeHtml41(report.status)}">Overall: ${escapeHtml41(report.status.toUpperCase())}</p><p>Checked ${escapeHtml41(new Date(report.checkedAt).toLocaleString())}</p>${thresholdLink}</section>${profile}<section class="primitive"><p class="eyebrow">Copy into your app</p><h2><code>createVoiceProductionReadinessRoutes(...)</code> builds this deploy gate</h2><p>Mount one package primitive to expose JSON readiness, HTML readiness, and a machine-readable gate route. Feed it the proof stores and contract reports your app already owns.</p><pre><code>${snippet}</code></pre></section><section class="checks">${checks}</section></main><script>document.querySelectorAll("[data-readiness-action]").forEach((button)=>{button.addEventListener("click",async()=>{const url=button.getAttribute("data-action-url");if(!url)return;button.disabled=true;const original=button.textContent;button.textContent="Running...";try{const response=await fetch(url,{method:"POST"});button.textContent=response.ok?"Done. Reloading...":"Failed";if(response.ok)setTimeout(()=>location.reload(),500)}catch{button.textContent="Failed"}finally{setTimeout(()=>{button.disabled=false;button.textContent=original},1500)}})});</script></body></html>`;
 };
 var createVoiceProductionReadinessRoutes = (options) => {
   const path = options.path ?? "/api/production-readiness";

package/dist/productionReadiness.d.ts

@@ -32,9 +32,19 @@ export type VoiceProductionReadinessAction = {
     label: string;
     method?: 'GET' | 'POST';
 };
+export type VoiceProductionReadinessGateExplanation = {
+    evidenceHref?: string;
+    observed?: number | string;
+    remediation: string;
+    sourceHref?: string;
+    threshold?: number | string;
+    thresholdLabel?: string;
+    unit?: 'count' | 'ms' | 'rate' | 'status';
+};
 export type VoiceProductionReadinessCheck = {
     actions?: VoiceProductionReadinessAction[];
     detail?: string;
+    gateExplanation?: VoiceProductionReadinessGateExplanation;
     href?: string;
     label: string;
     proofSource?: VoiceProductionReadinessProofSource;

package/package.json

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