@absolutejs/voice 0.0.22-beta.195 → 0.0.22-beta.196

package/dist/index.d.ts

@@ -52,6 +52,7 @@ export { createVoiceReadinessProfile, recommendVoiceReadinessProfile } from './r
 export { buildVoiceProviderContractMatrix, createVoiceProviderContractMatrixHTMLHandler, createVoiceProviderContractMatrixJSONHandler, createVoiceProviderContractMatrixPreset, createVoiceProviderContractMatrixRoutes, evaluateVoiceProviderStackGaps, renderVoiceProviderContractMatrixHTML, recommendVoiceProviderStack } from './providerStackRecommendations';
 export { buildVoiceOpsConsoleReport, createVoiceOpsConsoleRoutes, renderVoiceOpsConsoleHTML } from './opsConsoleRoutes';
 export { buildVoiceOperationsRecord, createVoiceOperationsRecordRoutes, renderVoiceOperationsRecordHTML } from './operationsRecord';
+export { buildVoiceOpsRecoveryReadinessCheck, buildVoiceOpsRecoveryReport, createVoiceOpsRecoveryRoutes, renderVoiceOpsRecoveryHTML, renderVoiceOpsRecoveryMarkdown } from './opsRecovery';
 export { buildVoiceIncidentBundle, createStoredVoiceIncidentBundleArtifact, createVoiceIncidentBundleRoutes, createVoiceMemoryIncidentBundleStore, pruneVoiceIncidentBundleArtifacts, saveVoiceIncidentBundleArtifact } from './incidentBundle';
 export { summarizeVoiceOpsStatus } from './opsStatus';
 export { createVoiceOpsStatusRoutes, renderVoiceOpsStatusHTML } from './opsStatusRoutes';
@@ -114,6 +115,7 @@ export type { VoiceProductionReadinessAction, VoiceProductionReadinessAuditOptio
 export type { VoiceReadinessProfileName, VoiceReadinessProfileOptions, VoiceReadinessProfileRecommendation, VoiceReadinessProfileRecommendationScore, VoiceReadinessProfileRoutesOptions } from './readinessProfiles';
 export type { VoiceProviderStackChoice, VoiceProviderStackCapabilities, VoiceProviderStackCapabilityGap, VoiceProviderStackCapabilityGapInput, VoiceProviderStackCapabilityGapReport, VoiceProviderContractCheck, VoiceProviderContractCheckStatus, VoiceProviderContractDefinition, VoiceProviderContractMatrixHandlerOptions, VoiceProviderContractMatrixHTMLHandlerOptions, VoiceProviderContractMatrixInput, VoiceProviderContractMatrixPresetOptions, VoiceProviderContractMatrixReport, VoiceProviderContractMatrixRoutesOptions, VoiceProviderContractMatrixRow, VoiceProviderStackInput, VoiceProviderStackKind, VoiceProviderStackRecommendation } from './providerStackRecommendations';
 export type { VoiceOperationsRecord, VoiceOperationsRecordAgentHandoff, VoiceOperationsRecordAuditSummary, VoiceOperationsRecordIntegrationEventSummary, VoiceOperationsRecordOptions, VoiceOperationsRecordOutcome, VoiceOperationsRecordReviewSummary, VoiceOperationsRecordRoutesOptions, VoiceOperationsRecordStatus, VoiceOperationsRecordTaskSummary, VoiceOperationsRecordTool } from './operationsRecord';
+export type { VoiceOpsRecoveryFailedSession, VoiceOpsRecoveryInterventionSummary, VoiceOpsRecoveryIssue, VoiceOpsRecoveryIssueCode, VoiceOpsRecoveryLinks, VoiceOpsRecoveryProviderSummary, VoiceOpsRecoveryReport, VoiceOpsRecoveryReportOptions, VoiceOpsRecoveryRoutesOptions, VoiceOpsRecoveryStatus } from './opsRecovery';
 export type { StoredVoiceIncidentBundleArtifact, VoiceIncidentBundle, VoiceIncidentBundleArtifactOptions, VoiceIncidentBundleFormat, VoiceIncidentBundleOptions, VoiceIncidentBundleRetentionOptions, VoiceIncidentBundleRetentionReport, VoiceIncidentBundleRoutesOptions, VoiceIncidentBundleStore, VoiceIncidentBundleStoreFilter, VoiceIncidentBundleSummary } from './incidentBundle';
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';
 export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingKindSummary, VoiceRoutingDecisionSummary, VoiceRoutingDecisionSummaryOptions, VoiceRoutingEvent, VoiceRoutingEventKind, VoiceRoutingSessionSummary, VoiceRoutingSessionSummaryOptions } from './resilienceRoutes';

package/dist/index.js

@@ -24008,8 +24008,248 @@ var createVoiceOperationsRecordRoutes = (options) => {
   }
   return routes;
 };
-// src/incidentBundle.ts
+// src/opsRecovery.ts
 import { Elysia as Elysia40 } from "elysia";
+var escapeHtml41 = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+var getString16 = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
+var hrefForSession = (value, sessionId) => typeof value === "function" ? value(sessionId) : value;
+var rollupStatus3 = (issues) => issues.some((issue) => issue.severity === "fail") ? "fail" : issues.some((issue) => issue.severity === "warn") ? "warn" : "pass";
+var providerUnresolved = (provider) => provider.status === "degraded" || provider.status === "rate-limited" || provider.status === "suppressed";
+var collectFailedSessions = (events, limit) => events.filter((event) => {
+  if (event.type !== "session.error") {
+    return false;
+  }
+  const providerStatus = event.payload.providerStatus;
+  return providerStatus !== "success" && providerStatus !== "fallback";
+}).sort((left, right) => right.at - left.at).slice(0, limit).map((event) => ({
+  at: event.at,
+  error: getString16(event.payload.error),
+  provider: getString16(event.payload.provider),
+  sessionId: event.sessionId,
+  traceId: event.traceId
+}));
+var collectInterventions = (events, limit) => {
+  const interventionEvents = events.filter((event) => event.type === "operator.action").sort((left, right) => right.at - left.at);
+  return {
+    events: interventionEvents.slice(0, limit).map((event) => ({
+      action: getString16(event.payload.action),
+      at: event.at,
+      operatorId: getString16(event.payload.operatorId) ?? getString16(event.payload.actorId),
+      sessionId: event.sessionId,
+      traceId: event.traceId
+    })),
+    total: interventionEvents.length
+  };
+};
+var addDeliveryIssues = (issues, input) => {
+  if (!input.summary) {
+    return;
+  }
+  const failed = input.summary.failed + input.summary.deadLettered;
+  if (failed > 0) {
+    issues.push({
+      code: input.failedCode,
+      detail: `${failed} failed or dead-lettered delivery record(s).`,
+      href: input.href,
+      label: input.failedLabel,
+      severity: "fail",
+      value: failed
+    });
+  }
+  const pending = input.summary.pending + input.summary.retryEligible;
+  if (pending > 0) {
+    issues.push({
+      code: input.pendingCode,
+      detail: `${pending} pending or retry-eligible delivery record(s).`,
+      href: input.href,
+      label: input.pendingLabel,
+      severity: "warn",
+      value: pending
+    });
+  }
+};
+var buildVoiceOpsRecoveryReport = async (options = {}) => {
+  const limit = options.limit ?? 50;
+  const events = options.events ?? await options.traces?.list({ limit: Math.max(limit, 500) }) ?? [];
+  const providers = await summarizeVoiceProviderHealth({
+    events,
+    providers: options.providers
+  });
+  const auditDeliveries = options.auditDeliveries ? await summarizeVoiceAuditSinkDeliveries(await options.auditDeliveries.list(), {
+    deadLetters: options.auditDeliveryDeadLetters
+  }) : undefined;
+  const traceDeliveries = options.traceDeliveries ? await summarizeVoiceTraceSinkDeliveries(await options.traceDeliveries.list(), {
+    deadLetters: options.traceDeliveryDeadLetters
+  }) : undefined;
+  const handoffDeliveries = options.handoffDeliveries ? await summarizeVoiceHandoffDeliveries(await options.handoffDeliveries.list(), {
+    deadLetters: options.handoffDeliveryDeadLetters
+  }) : undefined;
+  const latency = options.latency === false ? undefined : await buildVoiceLatencySLOGate({
+    events,
+    ...options.latency ?? {}
+  });
+  const failedSessions = collectFailedSessions(events, limit);
+  const interventions = collectInterventions(events, limit);
+  const issues = [];
+  const unresolvedProviders = providers.filter(providerUnresolved);
+  for (const provider of unresolvedProviders) {
+    issues.push({
+      code: "voice.ops_recovery.provider_unresolved_failure",
+      detail: provider.lastError ?? `${provider.provider} status is ${provider.status}.`,
+      href: options.links?.providers,
+      label: `Provider ${provider.provider} needs recovery`,
+      severity: "fail",
+      value: provider.status
+    });
+  }
+  addDeliveryIssues(issues, {
+    failedCode: "voice.ops_recovery.audit_delivery_failed",
+    failedLabel: "Audit delivery failures",
+    href: options.links?.auditDeliveries,
+    pendingCode: "voice.ops_recovery.audit_delivery_pending",
+    pendingLabel: "Audit delivery backlog",
+    summary: auditDeliveries
+  });
+  addDeliveryIssues(issues, {
+    failedCode: "voice.ops_recovery.trace_delivery_failed",
+    failedLabel: "Trace delivery failures",
+    href: options.links?.traceDeliveries,
+    pendingCode: "voice.ops_recovery.trace_delivery_pending",
+    pendingLabel: "Trace delivery backlog",
+    summary: traceDeliveries
+  });
+  addDeliveryIssues(issues, {
+    failedCode: "voice.ops_recovery.handoff_failed",
+    failedLabel: "Handoff delivery failures",
+    href: options.links?.handoffs,
+    pendingCode: "voice.ops_recovery.handoff_pending",
+    pendingLabel: "Handoff delivery backlog",
+    summary: handoffDeliveries
+  });
+  if (latency?.failed) {
+    issues.push({
+      code: "voice.ops_recovery.latency_slo_failed",
+      detail: `${latency.failed} latency SLO measurement(s) failed.`,
+      href: options.links?.traces ? hrefForSession(options.links.traces, latency.measurements[0]?.sessionId ?? "") : undefined,
+      label: "Latency SLO failures",
+      severity: "fail",
+      value: latency.failed
+    });
+  } else if (latency?.warnings) {
+    issues.push({
+      code: "voice.ops_recovery.latency_slo_warn",
+      detail: `${latency.warnings} latency SLO measurement(s) are warning.`,
+      label: "Latency SLO warnings",
+      severity: "warn",
+      value: latency.warnings
+    });
+  }
+  return {
+    auditDeliveries,
+    checkedAt: Date.now(),
+    failedSessions,
+    handoffDeliveries,
+    interventions,
+    issues,
+    latency,
+    providers: {
+      healthy: providers.filter((provider) => provider.status === "healthy").length,
+      providers,
+      recoveredFallbacks: providers.reduce((total, provider) => total + provider.fallbackCount, 0),
+      unresolvedFailures: unresolvedProviders.length
+    },
+    status: rollupStatus3(issues),
+    traceDeliveries
+  };
+};
+var buildVoiceOpsRecoveryReadinessCheck = (report, options = {}) => ({
+  detail: report.status === "pass" ? `${report.providers.recoveredFallbacks} recovered fallback(s), ${report.interventions.total} operator intervention(s), and no unresolved recovery issues.` : `${report.issues.length} recovery issue(s) require attention.`,
+  href: options.href,
+  label: options.label ?? "Ops recovery",
+  status: report.status,
+  value: report.issues.length
+});
+var renderVoiceOpsRecoveryMarkdown = (report, options = {}) => {
+  const title = options.title ?? "Voice Ops Recovery";
+  const issueRows = report.issues.map((issue) => `| ${issue.severity} | ${issue.code} | ${issue.label} | ${issue.value ?? ""} | ${issue.detail ?? ""} |`).join(`
+`);
+  const providers = report.providers.providers.map((provider) => `| ${provider.provider} | ${provider.status} | ${provider.runCount} | ${provider.errorCount} | ${provider.fallbackCount} | ${provider.lastError ?? ""} |`).join(`
+`);
+  const failedSessions = report.failedSessions.map((session) => `- ${session.sessionId}${session.provider ? ` via ${session.provider}` : ""}${session.error ? `: ${session.error}` : ""}`).join(`
+`);
+  return `# ${title}
+
+Status: ${report.status}
+
+Checked at: ${new Date(report.checkedAt).toISOString()}
+
+Recovered fallbacks: ${report.providers.recoveredFallbacks}
+Unresolved provider failures: ${report.providers.unresolvedFailures}
+Operator interventions: ${report.interventions.total}
+
+## Issues
+
+| Severity | Code | Label | Value | Detail |
+| --- | --- | --- | ---: | --- |
+${issueRows || "| pass | none | No recovery issues | 0 | |"}
+
+## Providers
+
+| Provider | Status | Runs | Errors | Fallbacks | Last error |
+| --- | --- | ---: | ---: | ---: | --- |
+${providers || "| none | idle | 0 | 0 | 0 | |"}
+
+## Failed Sessions
+
+${failedSessions || "None."}
+
+## Latency
+
+${report.latency ? renderVoiceLatencySLOMarkdown(report.latency, { title: "Latency SLO" }) : "Latency SLO disabled."}
+`;
+};
+var renderDeliverySummary = (label, summary) => summary ? `<article><span>${escapeHtml41(label)}</span><strong>${String(summary.failed + summary.deadLettered)} failed</strong><small>${String(summary.pending)} pending \xB7 ${String(summary.retryEligible)} retry eligible \xB7 ${String(summary.total)} total</small></article>` : `<article><span>${escapeHtml41(label)}</span><strong>not configured</strong></article>`;
+var renderVoiceOpsRecoveryHTML = (report, options = {}) => {
+  const title = options.title ?? "Voice Ops Recovery";
+  const issues = report.issues.map((issue) => `<tr><td>${escapeHtml41(issue.severity)}</td><td><code>${escapeHtml41(issue.code)}</code></td><td>${escapeHtml41(issue.label)}</td><td>${escapeHtml41(String(issue.value ?? ""))}</td><td>${escapeHtml41(issue.detail ?? "")}</td></tr>`).join("");
+  const providers = report.providers.providers.map((provider) => `<tr><td>${escapeHtml41(provider.provider)}</td><td>${escapeHtml41(provider.status)}</td><td>${String(provider.runCount)}</td><td>${String(provider.errorCount)}</td><td>${String(provider.fallbackCount)}</td><td>${escapeHtml41(provider.lastError ?? "")}</td></tr>`).join("");
+  const failedSessions = report.failedSessions.map((session) => `<li>${escapeHtml41(session.sessionId)}${session.provider ? ` via ${escapeHtml41(session.provider)}` : ""}${session.error ? `: ${escapeHtml41(session.error)}` : ""}</li>`).join("");
+  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{font-family:ui-sans-serif,system-ui,sans-serif;background:#f8fafc;color:#172033;margin:2rem;line-height:1.45}main{max-width:1180px;margin:auto}.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));gap:.75rem;margin:1rem 0}article{background:white;border:1px solid #dbe3ef;border-radius:14px;padding:1rem;box-shadow:0 10px 28px rgba(15,23,42,.05)}article span{display:block;color:#64748b;font-size:.85rem}article strong{display:block;font-size:1.5rem;margin:.2rem 0}article small{color:#64748b}table{border-collapse:collapse;width:100%;background:white;border:1px solid #dbe3ef;border-radius:14px;overflow:hidden}th,td{border-bottom:1px solid #e2e8f0;padding:.7rem;text-align:left;vertical-align:top}code{font-size:.85em}.status{display:inline-flex;border-radius:999px;padding:.35rem .7rem;background:${report.status === "fail" ? "#fee2e2" : report.status === "warn" ? "#fef3c7" : "#dcfce7"};color:${report.status === "fail" ? "#991b1b" : report.status === "warn" ? "#92400e" : "#166534"};font-weight:700}</style></head><body><main><h1>${escapeHtml41(title)}</h1><p><span class="status">${escapeHtml41(report.status)}</span> Checked ${escapeHtml41(new Date(report.checkedAt).toLocaleString())}</p><section class="grid"><article><span>Recovered fallbacks</span><strong>${String(report.providers.recoveredFallbacks)}</strong></article><article><span>Unresolved providers</span><strong>${String(report.providers.unresolvedFailures)}</strong></article><article><span>Operator interventions</span><strong>${String(report.interventions.total)}</strong></article><article><span>Latency status</span><strong>${escapeHtml41(report.latency?.status ?? "disabled")}</strong></article>${renderDeliverySummary("Audit delivery", report.auditDeliveries)}${renderDeliverySummary("Trace delivery", report.traceDeliveries)}${renderDeliverySummary("Handoff delivery", report.handoffDeliveries)}</section><h2>Issues</h2><table><thead><tr><th>Severity</th><th>Code</th><th>Label</th><th>Value</th><th>Detail</th></tr></thead><tbody>${issues || '<tr><td colspan="5">No recovery issues.</td></tr>'}</tbody></table><h2>Providers</h2><table><thead><tr><th>Provider</th><th>Status</th><th>Runs</th><th>Errors</th><th>Fallbacks</th><th>Last error</th></tr></thead><tbody>${providers || '<tr><td colspan="6">No provider activity.</td></tr>'}</tbody></table><h2>Failed Sessions</h2><ul>${failedSessions || "<li>None.</li>"}</ul></main></body></html>`;
+};
+var createVoiceOpsRecoveryRoutes = (options = {}) => {
+  const path = options.path ?? "/api/voice/ops-recovery";
+  const htmlPath = options.htmlPath === undefined ? "/ops-recovery" : options.htmlPath;
+  const markdownPath = options.markdownPath === undefined ? `${path}.md` : options.markdownPath;
+  const routes = new Elysia40({
+    name: options.name ?? "absolutejs-voice-ops-recovery"
+  }).get(path, async () => buildVoiceOpsRecoveryReport(options));
+  if (htmlPath) {
+    routes.get(htmlPath, async () => {
+      const report = await buildVoiceOpsRecoveryReport(options);
+      const render = options.render ?? renderVoiceOpsRecoveryHTML;
+      return new Response(await render(report), {
+        headers: {
+          "content-type": "text/html; charset=utf-8",
+          ...options.headers
+        }
+      });
+    });
+  }
+  if (markdownPath) {
+    routes.get(markdownPath, async () => {
+      const report = await buildVoiceOpsRecoveryReport(options);
+      return new Response(renderVoiceOpsRecoveryMarkdown(report, { title: options.title }), {
+        headers: {
+          "content-type": "text/markdown; charset=utf-8",
+          ...options.headers
+        }
+      });
+    });
+  }
+  return routes;
+};
+// src/incidentBundle.ts
+import { Elysia as Elysia41 } from "elysia";
 var filterIncidentBundleArtifacts = (artifacts, filter = {}) => artifacts.filter((artifact) => {
   if (filter.sessionId && artifact.sessionId !== filter.sessionId) {
     return false;
@@ -24208,7 +24448,7 @@ var buildVoiceIncidentBundle = async (options) => {
 var createVoiceIncidentBundleRoutes = (options) => {
   const path = options.path ?? "/api/voice-incidents/:sessionId";
   const markdownPath = options.markdownPath === undefined ? "/voice-incidents/:sessionId/markdown" : options.markdownPath;
-  const routes = new Elysia40({
+  const routes = new Elysia41({
     name: options.name ?? "absolutejs-voice-incident-bundle"
   });
   const getSessionId = (params) => params.sessionId ?? "";
@@ -24409,19 +24649,19 @@ var summarizeVoiceOpsStatus = async (options) => {
   };
 };
 // src/opsStatusRoutes.ts
-import { Elysia as Elysia41 } from "elysia";
-var escapeHtml41 = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+import { Elysia as Elysia42 } from "elysia";
+var escapeHtml42 = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 var renderVoiceOpsStatusHTML = (report, options = {}) => {
   const title = options.title ?? "AbsoluteJS Voice Ops Status";
   const surfaces = Object.entries(report.surfaces).map(([key, surface]) => {
     const value = "recovered" in surface ? surface.total === 0 ? "0 events" : `${surface.recovered}/${surface.total}` : ("auditTotal" in surface) ? `${surface.auditTotal + surface.traceTotal} deliveries` : ("total" in surface) ? `${Math.max(surface.total - ("failed" in surface ? surface.failed : ("degraded" in surface) ? surface.degraded : 0), 0)}/${surface.total}` : surface.status;
-    return `<article class="surface ${escapeHtml41(surface.status)}"><span>${escapeHtml41(surface.status.toUpperCase())}</span><h2>${escapeHtml41(key)}</h2><strong>${escapeHtml41(value)}</strong></article>`;
+    return `<article class="surface ${escapeHtml42(surface.status)}"><span>${escapeHtml42(surface.status.toUpperCase())}</span><h2>${escapeHtml42(key)}</h2><strong>${escapeHtml42(value)}</strong></article>`;
   }).join("");
-  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:#0d141b;color:#f8f3e7;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:980px;padding:32px}.hero{background:linear-gradient(135deg,rgba(20,184,166,.2),rgba(245,158,11,.12));border:1px solid #283544;border-radius:28px;margin-bottom:18px;padding:28px}.eyebrow{color:#5eead4;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{border:1px solid #3f3f46;border-radius:999px;display:inline-flex;font-weight:900;padding:8px 12px}.surfaces{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(180px,1fr))}.surface{background:#151d26;border:1px solid #283544;border-radius:20px;padding:18px}.surface span{color:#aab5c0;font-size:.78rem;font-weight:900;letter-spacing:.08em}.surface strong{font-size:1.5rem}.pass{border-color:rgba(34,197,94,.55)}.fail{border-color:rgba(239,68,68,.75)}a{color:#5eead4}</style></head><body><main><section class="hero"><p class="eyebrow">Ops status</p><h1>${escapeHtml41(title)}</h1><p>Compact pass/fail status for framework widgets, demos, and small customer-facing health badges.</p><p class="status ${escapeHtml41(report.status)}">Overall: ${escapeHtml41(report.status.toUpperCase())}</p><p>${report.passed}/${report.total} checks passing</p></section><section class="surfaces">${surfaces || '<article class="surface pass"><span>PASS</span><h2>No checks configured</h2><strong>0/0</strong></article>'}</section></main></body></html>`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml42(title)}</title><style>body{background:#0d141b;color:#f8f3e7;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:980px;padding:32px}.hero{background:linear-gradient(135deg,rgba(20,184,166,.2),rgba(245,158,11,.12));border:1px solid #283544;border-radius:28px;margin-bottom:18px;padding:28px}.eyebrow{color:#5eead4;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{border:1px solid #3f3f46;border-radius:999px;display:inline-flex;font-weight:900;padding:8px 12px}.surfaces{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(180px,1fr))}.surface{background:#151d26;border:1px solid #283544;border-radius:20px;padding:18px}.surface span{color:#aab5c0;font-size:.78rem;font-weight:900;letter-spacing:.08em}.surface strong{font-size:1.5rem}.pass{border-color:rgba(34,197,94,.55)}.fail{border-color:rgba(239,68,68,.75)}a{color:#5eead4}</style></head><body><main><section class="hero"><p class="eyebrow">Ops status</p><h1>${escapeHtml42(title)}</h1><p>Compact pass/fail status for framework widgets, demos, and small customer-facing health badges.</p><p class="status ${escapeHtml42(report.status)}">Overall: ${escapeHtml42(report.status.toUpperCase())}</p><p>${report.passed}/${report.total} checks passing</p></section><section class="surfaces">${surfaces || '<article class="surface pass"><span>PASS</span><h2>No checks configured</h2><strong>0/0</strong></article>'}</section></main></body></html>`;
 };
 var createVoiceOpsStatusRoutes = (options) => {
   const path = options.path ?? "/api/voice/ops-status";
-  const routes = new Elysia41({
+  const routes = new Elysia42({
     name: options.name ?? "absolutejs-voice-ops-status"
   });
   routes.get(path, async () => summarizeVoiceOpsStatus(options));
@@ -24854,9 +25094,9 @@ var createVoiceTTSProviderRouter = (options) => {
   };
 };
 // src/traceDeliveryRoutes.ts
-import { Elysia as Elysia42 } from "elysia";
-var escapeHtml42 = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
-var getString16 = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
+import { Elysia as Elysia43 } from "elysia";
+var escapeHtml43 = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+var getString17 = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
 var getNumber11 = (value) => {
   if (typeof value === "number" && Number.isFinite(value)) {
     return value;
@@ -24868,13 +25108,13 @@ var getNumber11 = (value) => {
   return;
 };
 var parseStatus2 = (value) => {
-  const text = getString16(value);
+  const text = getString17(value);
   return text === "pending" || text === "delivered" || text === "failed" || text === "skipped" || text === "all" ? text : undefined;
 };
 var resolveVoiceTraceDeliveryFilter = (query = {}, base = {}) => ({
   ...base,
   limit: getNumber11(query.limit) ?? base.limit,
-  q: getString16(query.q) ?? base.q,
+  q: getString17(query.q) ?? base.q,
   status: parseStatus2(query.status) ?? base.status
 });
 var deliverySearchText2 = (delivery) => [
@@ -24936,14 +25176,14 @@ var renderSinkResults2 = (delivery) => {
   if (entries.length === 0) {
     return "<p>No sink delivery attempts recorded yet.</p>";
   }
-  return `<ul>${entries.map(([sinkId, result]) => `<li><strong>${escapeHtml42(sinkId)}</strong>: ${escapeHtml42(result.status)}${result.deliveredTo ? ` to ${escapeHtml42(result.deliveredTo)}` : ""}${result.error ? ` (${escapeHtml42(result.error)})` : ""}</li>`).join("")}</ul>`;
+  return `<ul>${entries.map(([sinkId, result]) => `<li><strong>${escapeHtml43(sinkId)}</strong>: ${escapeHtml43(result.status)}${result.deliveredTo ? ` to ${escapeHtml43(result.deliveredTo)}` : ""}${result.error ? ` (${escapeHtml43(result.error)})` : ""}</li>`).join("")}</ul>`;
 };
-var renderEventList2 = (delivery) => delivery.events.length === 0 ? "<p>No trace events in this delivery.</p>" : `<ul>${delivery.events.map((event) => `<li>${escapeHtml42(event.type)} <small>${escapeHtml42(event.id)}</small>${event.sessionId ? ` session=${escapeHtml42(event.sessionId)}` : ""}</li>`).join("")}</ul>`;
+var renderEventList2 = (delivery) => delivery.events.length === 0 ? "<p>No trace events in this delivery.</p>" : `<ul>${delivery.events.map((event) => `<li>${escapeHtml43(event.type)} <small>${escapeHtml43(event.id)}</small>${event.sessionId ? ` session=${escapeHtml43(event.sessionId)}` : ""}</li>`).join("")}</ul>`;
 var renderVoiceTraceDeliveryHTML = (report, options = {}) => {
   const title = options.title ?? "AbsoluteJS Voice Trace Deliveries";
-  const drainAction = options.workerPath === false ? "" : `<form method="post" action="${escapeHtml42(options.workerPath ?? "/api/voice-trace-deliveries/drain")}"><button type="submit">Drain trace deliveries</button></form>`;
-  const rows = report.deliveries.map((delivery) => `<article class="delivery ${escapeHtml42(delivery.deliveryStatus)}"><div class="head"><div><span>${escapeHtml42(delivery.deliveryStatus)}</span><h2>${escapeHtml42(delivery.id)}</h2><p>${escapeHtml42(new Date(delivery.createdAt).toLocaleString())}${delivery.deliveredAt ? ` \xB7 delivered ${escapeHtml42(new Date(delivery.deliveredAt).toLocaleString())}` : ""}</p></div><strong>${String(delivery.deliveryAttempts ?? 0)} attempt(s)</strong></div>${delivery.deliveryError ? `<p class="error">${escapeHtml42(delivery.deliveryError)}</p>` : ""}<h3>Sinks</h3>${renderSinkResults2(delivery)}<h3>Events</h3>${renderEventList2(delivery)}</article>`).join("");
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml42(title)}</title><style>body{background:#0f1318;color:#f4efe1;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1120px;padding:32px}.hero{background:linear-gradient(135deg,rgba(34,197,94,.16),rgba(14,165,233,.14));border:1px solid #26313d;border-radius:28px;margin-bottom:18px;padding:28px}.eyebrow{color:#86efac;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.2rem,5vw,4.8rem);line-height:.92;margin:.2rem 0 1rem}.grid{display:grid;gap:12px;grid-template-columns:repeat(4,1fr);margin-bottom:16px}.grid article,.delivery{background:#151b22;border:1px solid #26313d;border-radius:22px;padding:18px}.grid span,.delivery span{color:#86efac;font-size:.78rem;font-weight:900;letter-spacing:.08em;text-transform:uppercase}.grid strong{display:block;font-size:2rem}.deliveries{display:grid;gap:14px}.delivery.failed{border-color:rgba(239,68,68,.75)}.delivery.pending{border-color:rgba(245,158,11,.7)}.delivery.delivered{border-color:rgba(34,197,94,.55)}.delivery.skipped{border-color:rgba(148,163,184,.6)}.head{align-items:start;display:flex;gap:14px;justify-content:space-between}.delivery h2{font-size:1.05rem;margin:.3rem 0;overflow-wrap:anywhere}.delivery h3{margin:1rem 0 .3rem}.delivery p,.delivery li{color:#c8d0d8}.error{color:#fecaca!important}button{background:#86efac;border:0;border-radius:999px;color:#07111f;cursor:pointer;font-weight:900;margin-top:12px;padding:10px 14px}@media(max-width:760px){main{padding:20px}.grid{grid-template-columns:1fr 1fr}.head{display:block}}</style></head><body><main><section class="hero"><p class="eyebrow">Trace export health</p><h1>${escapeHtml42(title)}</h1><p>Checked ${escapeHtml42(new Date(report.checkedAt).toLocaleString())}. Showing ${String(report.deliveries.length)} delivery item(s).</p>${drainAction}</section>${renderMetricGrid3(report)}<section class="deliveries">${rows || "<p>No trace deliveries match this filter.</p>"}</section></main></body></html>`;
+  const drainAction = options.workerPath === false ? "" : `<form method="post" action="${escapeHtml43(options.workerPath ?? "/api/voice-trace-deliveries/drain")}"><button type="submit">Drain trace deliveries</button></form>`;
+  const rows = report.deliveries.map((delivery) => `<article class="delivery ${escapeHtml43(delivery.deliveryStatus)}"><div class="head"><div><span>${escapeHtml43(delivery.deliveryStatus)}</span><h2>${escapeHtml43(delivery.id)}</h2><p>${escapeHtml43(new Date(delivery.createdAt).toLocaleString())}${delivery.deliveredAt ? ` \xB7 delivered ${escapeHtml43(new Date(delivery.deliveredAt).toLocaleString())}` : ""}</p></div><strong>${String(delivery.deliveryAttempts ?? 0)} attempt(s)</strong></div>${delivery.deliveryError ? `<p class="error">${escapeHtml43(delivery.deliveryError)}</p>` : ""}<h3>Sinks</h3>${renderSinkResults2(delivery)}<h3>Events</h3>${renderEventList2(delivery)}</article>`).join("");
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml43(title)}</title><style>body{background:#0f1318;color:#f4efe1;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1120px;padding:32px}.hero{background:linear-gradient(135deg,rgba(34,197,94,.16),rgba(14,165,233,.14));border:1px solid #26313d;border-radius:28px;margin-bottom:18px;padding:28px}.eyebrow{color:#86efac;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.2rem,5vw,4.8rem);line-height:.92;margin:.2rem 0 1rem}.grid{display:grid;gap:12px;grid-template-columns:repeat(4,1fr);margin-bottom:16px}.grid article,.delivery{background:#151b22;border:1px solid #26313d;border-radius:22px;padding:18px}.grid span,.delivery span{color:#86efac;font-size:.78rem;font-weight:900;letter-spacing:.08em;text-transform:uppercase}.grid strong{display:block;font-size:2rem}.deliveries{display:grid;gap:14px}.delivery.failed{border-color:rgba(239,68,68,.75)}.delivery.pending{border-color:rgba(245,158,11,.7)}.delivery.delivered{border-color:rgba(34,197,94,.55)}.delivery.skipped{border-color:rgba(148,163,184,.6)}.head{align-items:start;display:flex;gap:14px;justify-content:space-between}.delivery h2{font-size:1.05rem;margin:.3rem 0;overflow-wrap:anywhere}.delivery h3{margin:1rem 0 .3rem}.delivery p,.delivery li{color:#c8d0d8}.error{color:#fecaca!important}button{background:#86efac;border:0;border-radius:999px;color:#07111f;cursor:pointer;font-weight:900;margin-top:12px;padding:10px 14px}@media(max-width:760px){main{padding:20px}.grid{grid-template-columns:1fr 1fr}.head{display:block}}</style></head><body><main><section class="hero"><p class="eyebrow">Trace export health</p><h1>${escapeHtml43(title)}</h1><p>Checked ${escapeHtml43(new Date(report.checkedAt).toLocaleString())}. Showing ${String(report.deliveries.length)} delivery item(s).</p>${drainAction}</section>${renderMetricGrid3(report)}<section class="deliveries">${rows || "<p>No trace deliveries match this filter.</p>"}</section></main></body></html>`;
 };
 var createVoiceTraceDeliveryJSONHandler = (options) => async ({ query }) => buildVoiceTraceDeliveryReport(options, resolveVoiceTraceDeliveryFilter(query, options.filter));
 var createVoiceTraceDeliveryHTMLHandler = (options) => async ({ query }) => {
@@ -24963,7 +25203,7 @@ var createVoiceTraceDeliveryRoutes = (options) => {
   const path = options.path ?? "/api/voice-trace-deliveries";
   const htmlPath = options.htmlPath === undefined ? "/traces/deliveries" : options.htmlPath;
   const workerPath = options.workerPath === undefined ? `${path}/drain` : options.workerPath;
-  const routes = new Elysia42({
+  const routes = new Elysia43({
     name: options.name ?? "absolutejs-voice-trace-deliveries"
   }).get(path, createVoiceTraceDeliveryJSONHandler(options));
   if (htmlPath !== false) {
@@ -25587,7 +25827,7 @@ var createVoiceMemoryStore = () => {
   return { get, getOrCreate, list, remove, set };
 };
 // src/opsWebhook.ts
-import { Elysia as Elysia43 } from "elysia";
+import { Elysia as Elysia44 } from "elysia";
 var toHex6 = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
 var signVoiceOpsWebhookBody = async (input) => {
   const encoder = new TextEncoder;
@@ -25717,7 +25957,7 @@ var verifyVoiceOpsWebhookSignature = async (input) => {
 };
 var createVoiceOpsWebhookReceiverRoutes = (options = {}) => {
   const path = options.path ?? "/api/voice-ops/webhook";
-  return new Elysia43().post(path, async ({ body, request, set }) => {
+  return new Elysia44().post(path, async ({ body, request, set }) => {
     const bodyText = typeof body === "string" ? body : JSON.stringify(body);
     if (options.signingSecret) {
       const verification = await verifyVoiceOpsWebhookSignature({
@@ -26660,6 +26900,8 @@ export {
   renderVoicePhoneAgentProductionSmokeHTML,
   renderVoiceOutcomeContractHTML,
   renderVoiceOpsStatusHTML,
+  renderVoiceOpsRecoveryMarkdown,
+  renderVoiceOpsRecoveryHTML,
   renderVoiceOpsConsoleHTML,
   renderVoiceOpsActionHistoryHTML,
   renderVoiceOperationsRecordHTML,
@@ -26856,6 +27098,7 @@ export {
   createVoiceOpsTaskProcessorWorker,
   createVoiceOpsStatusRoutes,
   createVoiceOpsRuntime,
+  createVoiceOpsRecoveryRoutes,
   createVoiceOpsConsoleRoutes,
   createVoiceOpsActionAuditRoutes,
   createVoiceOperationsRecordRoutes,
@@ -26989,6 +27232,8 @@ export {
   buildVoiceProductionReadinessGate,
   buildVoiceOpsTaskFromSLABreach,
   buildVoiceOpsTaskFromReview,
+  buildVoiceOpsRecoveryReport,
+  buildVoiceOpsRecoveryReadinessCheck,
   buildVoiceOpsConsoleReport,
   buildVoiceOpsActionHistoryReport,
   buildVoiceOperationsRecord,

package/dist/opsRecovery.d.ts

@@ -0,0 +1,136 @@
+import { Elysia } from 'elysia';
+import { type VoiceAuditSinkDeliveryQueueSummary, type VoiceAuditSinkDeliveryStore } from './auditSinks';
+import { type VoiceLatencySLOGateOptions, type VoiceLatencySLOGateReport } from './latencySlo';
+import { type VoiceHandoffDeliveryQueueSummary, type VoiceTraceSinkDeliveryQueueSummary } from './queue';
+import { type VoiceProviderHealthSummary } from './providerHealth';
+import type { VoiceProductionReadinessCheck } from './productionReadiness';
+import type { VoiceHandoffDeliveryStore } from './types';
+import type { StoredVoiceTraceEvent, VoiceTraceEventStore, VoiceTraceSinkDeliveryStore } from './trace';
+export type VoiceOpsRecoveryStatus = 'fail' | 'pass' | 'warn';
+export type VoiceOpsRecoveryIssueCode = 'voice.ops_recovery.audit_delivery_failed' | 'voice.ops_recovery.audit_delivery_pending' | 'voice.ops_recovery.handoff_failed' | 'voice.ops_recovery.handoff_pending' | 'voice.ops_recovery.latency_slo_failed' | 'voice.ops_recovery.latency_slo_warn' | 'voice.ops_recovery.provider_unresolved_failure' | 'voice.ops_recovery.trace_delivery_failed' | 'voice.ops_recovery.trace_delivery_pending';
+export type VoiceOpsRecoveryIssue = {
+    code: VoiceOpsRecoveryIssueCode;
+    detail?: string;
+    href?: string;
+    label: string;
+    severity: Exclude<VoiceOpsRecoveryStatus, 'pass'>;
+    value?: number | string;
+};
+export type VoiceOpsRecoveryProviderSummary<TProvider extends string = string> = {
+    healthy: number;
+    providers: VoiceProviderHealthSummary<TProvider>[];
+    recoveredFallbacks: number;
+    unresolvedFailures: number;
+};
+export type VoiceOpsRecoveryInterventionSummary = {
+    events: Array<{
+        action?: string;
+        at: number;
+        operatorId?: string;
+        sessionId: string;
+        traceId?: string;
+    }>;
+    total: number;
+};
+export type VoiceOpsRecoveryFailedSession = {
+    at: number;
+    error?: string;
+    provider?: string;
+    sessionId: string;
+    traceId?: string;
+};
+export type VoiceOpsRecoveryReport<TProvider extends string = string> = {
+    auditDeliveries?: VoiceAuditSinkDeliveryQueueSummary;
+    checkedAt: number;
+    failedSessions: VoiceOpsRecoveryFailedSession[];
+    handoffDeliveries?: VoiceHandoffDeliveryQueueSummary;
+    interventions: VoiceOpsRecoveryInterventionSummary;
+    issues: VoiceOpsRecoveryIssue[];
+    latency?: VoiceLatencySLOGateReport;
+    providers: VoiceOpsRecoveryProviderSummary<TProvider>;
+    status: VoiceOpsRecoveryStatus;
+    traceDeliveries?: VoiceTraceSinkDeliveryQueueSummary;
+};
+export type VoiceOpsRecoveryLinks = {
+    auditDeliveries?: string;
+    handoffs?: string;
+    operationsRecords?: string | ((sessionId: string) => string);
+    providers?: string;
+    sessions?: string | ((sessionId: string) => string);
+    traceDeliveries?: string;
+    traces?: string | ((sessionId: string) => string);
+};
+export type VoiceOpsRecoveryReportOptions<TProvider extends string = string> = {
+    auditDeliveryDeadLetters?: VoiceAuditSinkDeliveryStore;
+    auditDeliveries?: VoiceAuditSinkDeliveryStore;
+    events?: StoredVoiceTraceEvent[];
+    handoffDeliveryDeadLetters?: VoiceHandoffDeliveryStore;
+    handoffDeliveries?: VoiceHandoffDeliveryStore;
+    latency?: VoiceLatencySLOGateOptions | false;
+    limit?: number;
+    links?: VoiceOpsRecoveryLinks;
+    providers?: readonly TProvider[];
+    traceDeliveryDeadLetters?: VoiceTraceSinkDeliveryStore;
+    traceDeliveries?: VoiceTraceSinkDeliveryStore;
+    traces?: VoiceTraceEventStore;
+};
+export type VoiceOpsRecoveryRoutesOptions<TProvider extends string = string> = VoiceOpsRecoveryReportOptions<TProvider> & {
+    headers?: HeadersInit;
+    htmlPath?: false | string;
+    markdownPath?: false | string;
+    name?: string;
+    path?: string;
+    render?: (report: VoiceOpsRecoveryReport<TProvider>) => string | Promise<string>;
+    title?: string;
+};
+export declare const buildVoiceOpsRecoveryReport: <TProvider extends string = string>(options?: VoiceOpsRecoveryReportOptions<TProvider>) => Promise<VoiceOpsRecoveryReport<TProvider>>;
+export declare const buildVoiceOpsRecoveryReadinessCheck: (report: VoiceOpsRecoveryReport, options?: {
+    href?: string;
+    label?: string;
+}) => VoiceProductionReadinessCheck;
+export declare const renderVoiceOpsRecoveryMarkdown: (report: VoiceOpsRecoveryReport, options?: {
+    title?: string;
+}) => string;
+export declare const renderVoiceOpsRecoveryHTML: (report: VoiceOpsRecoveryReport, options?: {
+    title?: string;
+}) => string;
+export declare const createVoiceOpsRecoveryRoutes: <TProvider extends string = string>(options?: VoiceOpsRecoveryRoutesOptions<TProvider>) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: VoiceOpsRecoveryReport<TProvider>;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/package.json

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