@absolutejs/voice 0.0.22-beta.160 → 0.0.22-beta.161

package/README.md

@@ -228,6 +228,7 @@ app.use(
 	createVoiceProductionReadinessRoutes({
 		...createVoiceReadinessProfile('meeting-recorder', {
 			bargeInReports: async () => [await buildBargeInReport()],
+			explain: true,
 			providerRoutingContracts: async () => [await runProviderRoutingContract()],
 			reconnectContracts: async () => [await runReconnectContract()]
 		}),
@@ -251,6 +252,7 @@ app.use(
 			auditDeliveries: runtime.auditDeliveries,
 			carriers: loadCarrierMatrixInputs,
 			deliveryRuntime,
+			explain: true,
 			phoneAgentSmokes: async () => [await runPhoneSmoke()],
 			providerRoutingContracts: async () => [await runProviderRoutingContract()],
 			traceDeliveries: runtime.traceDeliveries
@@ -281,6 +283,8 @@ app.use(
 
 The profile helper intentionally does not mount routes, create storage, start workers, or prescribe a deploy workflow. It only returns readiness options so teams can standardize defaults while keeping control over proof sources and route mounting.
 
+Pass `explain: true` when the readiness JSON and HTML should describe the selected profile, its purpose, and which expected proof surfaces are configured or still missing. This is useful for customer demos and internal release reviews where the readiness URL needs to explain what it certifies without sending people to docs.
+
 ## Delivery Runtime Presets
 
 Use `createVoiceDeliveryRuntimePresetConfig(...)` when you want one primitive to create paired audit and trace delivery workers for the same target. The preset returns a normal `VoiceDeliveryRuntimeConfig`, so you can still inspect or override worker options before passing it to `createVoiceDeliveryRuntime(...)`.

package/dist/index.d.ts

@@ -103,7 +103,7 @@ export type { VoicePhoneAgentCarrier, VoicePhoneAgentCarrierSummary, VoicePhoneA
 export type { VoicePhoneAgentProductionSmokeIssue, VoicePhoneAgentProductionSmokeHandlerOptions, VoicePhoneAgentProductionSmokeHTMLHandlerOptions, VoicePhoneAgentProductionSmokeOptions, VoicePhoneAgentProductionSmokeReport, VoicePhoneAgentProductionSmokeRoutesOptions, VoicePhoneAgentProductionSmokeRequirement } from './phoneAgentProductionSmoke';
 export type { VoiceOpsConsoleLink, VoiceOpsConsoleReport, VoiceOpsConsoleRoutesOptions } from './opsConsoleRoutes';
 export type { VoiceOpsStatus, VoiceOpsStatusLink, VoiceOpsStatusOptions, VoiceOpsStatusReport, VoiceOpsStatusRoutesOptions } from './opsStatus';
-export type { VoiceProductionReadinessAction, VoiceProductionReadinessAuditOptions, VoiceProductionReadinessAuditRequirement, VoiceProductionReadinessAuditSummary, VoiceProductionReadinessCheck, VoiceProductionReadinessGateIssue, VoiceProductionReadinessGateOptions, VoiceProductionReadinessGateReport, VoiceProductionReadinessOpsActionHistoryOptions, VoiceProductionReadinessOpsActionHistorySummary, VoiceProductionReadinessProofSource, VoiceProductionReadinessReport, VoiceProductionReadinessRoutesOptions, VoiceProductionReadinessTraceDeliverySummary, VoiceProductionReadinessAuditDeliveryOptions, VoiceProductionReadinessAuditDeliverySummary, VoiceProductionReadinessTraceDeliveryOptions, VoiceProductionReadinessStatus } from './productionReadiness';
+export type { VoiceProductionReadinessAction, VoiceProductionReadinessAuditOptions, VoiceProductionReadinessAuditRequirement, VoiceProductionReadinessAuditSummary, VoiceProductionReadinessCheck, VoiceProductionReadinessGateIssue, VoiceProductionReadinessGateOptions, VoiceProductionReadinessGateReport, VoiceProductionReadinessOpsActionHistoryOptions, VoiceProductionReadinessOpsActionHistorySummary, VoiceProductionReadinessProfileExplanation, VoiceProductionReadinessProfileSurface, VoiceProductionReadinessProofSource, VoiceProductionReadinessReport, VoiceProductionReadinessRoutesOptions, VoiceProductionReadinessTraceDeliverySummary, VoiceProductionReadinessAuditDeliveryOptions, VoiceProductionReadinessAuditDeliverySummary, VoiceProductionReadinessTraceDeliveryOptions, VoiceProductionReadinessStatus } from './productionReadiness';
 export type { VoiceReadinessProfileName, VoiceReadinessProfileOptions, VoiceReadinessProfileRoutesOptions } from './readinessProfiles';
 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

@@ -20847,6 +20847,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
       traceDeliveries: "/traces/deliveries",
       ...options.links
     },
+    profile: options.profile || undefined,
     proofSources,
     status: rollupStatus2(checks),
     summary: {
@@ -20888,6 +20889,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
 var buildVoiceProductionReadinessGate = async (options, input = {}) => summarizeVoiceProductionReadinessGate(await buildVoiceProductionReadinessReport(options, input), options.gate || undefined);
 var renderVoiceProductionReadinessHTML = (report, options = {}) => {
   const title = options.title ?? "AbsoluteJS Voice Production Readiness";
+  const profile = report.profile ? `<section class="profile"><p class="eyebrow">Readiness profile</p><h2>${escapeHtml35(report.profile.name)}</h2><p>${escapeHtml35(report.profile.description)}</p><p>${escapeHtml35(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="${escapeHtml35(surface.href)}">${escapeHtml35(surface.label)}</a>` : escapeHtml35(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="${escapeHtml35(action.href)}">${escapeHtml35(action.label)}</button>` : `<a href="${escapeHtml35(action.href)}">${escapeHtml35(action.label)}</a>`).join("");
     return `<article class="check ${escapeHtml35(check.status)}">
@@ -20902,7 +20904,7 @@ var renderVoiceProductionReadinessHTML = (report, options = {}) => {
         ${check.href ? `<a href="${escapeHtml35(check.href)}">Open surface</a>` : ""}
       </article>`;
   }).join("");
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml35(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{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}.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}.status.pass,.check.pass{border-color:rgba(34,197,94,.55)}.status.warn,.check.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{color:#a8b0b8;font-size:.78rem;font-weight:900;letter-spacing:.08em}.check h2{margin:.2rem 0}.check p{color:#b9c0c8;margin:.2rem 0 0}.check .proof-source{color:#f9d77e;font-weight:800}.check strong{font-size:1.5rem}.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>${escapeHtml35(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 ${escapeHtml35(report.status)}">Overall: ${escapeHtml35(report.status.toUpperCase())}</p><p>Checked ${escapeHtml35(new Date(report.checkedAt).toLocaleString())}</p></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>${escapeHtml35(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,.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}.profile{background:#111722}.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}.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>${escapeHtml35(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 ${escapeHtml35(report.status)}">Overall: ${escapeHtml35(report.status.toUpperCase())}</p><p>Checked ${escapeHtml35(new Date(report.checkedAt).toLocaleString())}</p></section>${profile}<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";
@@ -20956,62 +20958,207 @@ var mergeLinks = (defaults, links) => ({
   ...defaults,
   ...links
 });
+var isConfigured = (value) => value !== undefined && value !== false;
+var profileExplanation = (profile, options, links) => {
+  if (!options.explain) {
+    return;
+  }
+  if (profile === "meeting-recorder") {
+    return {
+      description: "Browser and meeting-recorder readiness for transcript capture, reconnects, barge-in, provider fallback, and live latency proof.",
+      name: "meeting-recorder",
+      purpose: "Certifies the browser voice surfaces a meeting recorder or browser assistant needs before users rely on captured transcripts and summaries.",
+      surfaces: [
+        {
+          configured: true,
+          href: links.liveLatency,
+          key: "liveLatency",
+          label: "Live latency"
+        },
+        {
+          configured: true,
+          href: links.sessions,
+          key: "sessions",
+          label: "Session health"
+        },
+        {
+          configured: true,
+          href: links.resilience,
+          key: "providerFallback",
+          label: "Provider fallback"
+        },
+        {
+          configured: isConfigured(options.providerRoutingContracts),
+          href: links.providerRoutingContracts,
+          key: "providerRoutingContracts",
+          label: "Provider routing contracts"
+        },
+        {
+          configured: isConfigured(options.reconnectContracts),
+          href: links.reconnectContracts,
+          key: "reconnectContracts",
+          label: "Reconnect contracts"
+        },
+        {
+          configured: isConfigured(options.bargeInReports),
+          href: links.bargeIn,
+          key: "bargeInReports",
+          label: "Barge-in proof"
+        }
+      ]
+    };
+  }
+  if (profile === "phone-agent") {
+    return {
+      description: "Carrier-backed phone-agent readiness for setup parity, phone smoke proof, handoffs, routing contracts, and delivery queues.",
+      name: "phone-agent",
+      purpose: "Certifies the proof surfaces a self-hosted phone agent needs before routing real carrier calls through the app.",
+      surfaces: [
+        {
+          configured: isConfigured(options.carriers),
+          href: links.carriers,
+          key: "carriers",
+          label: "Carrier readiness"
+        },
+        {
+          configured: isConfigured(options.phoneAgentSmokes),
+          href: links.phoneAgentSmoke,
+          key: "phoneAgentSmokes",
+          label: "Phone agent smoke"
+        },
+        {
+          configured: true,
+          href: links.handoffs,
+          key: "handoffs",
+          label: "Handoff delivery"
+        },
+        {
+          configured: isConfigured(options.providerRoutingContracts),
+          href: links.providerRoutingContracts,
+          key: "providerRoutingContracts",
+          label: "Provider routing contracts"
+        },
+        {
+          configured: isConfigured(options.deliveryRuntime),
+          href: links.deliveryRuntime,
+          key: "deliveryRuntime",
+          label: "Delivery runtime"
+        },
+        {
+          configured: isConfigured(options.auditDeliveries),
+          href: links.auditDeliveries,
+          key: "auditDeliveries",
+          label: "Audit deliveries"
+        },
+        {
+          configured: isConfigured(options.traceDeliveries),
+          href: links.traceDeliveries,
+          key: "traceDeliveries",
+          label: "Trace deliveries"
+        }
+      ]
+    };
+  }
+  return {
+    description: "Operations-heavy readiness for audit evidence, operator action history, delivery health, runtime queues, and deploy gate status.",
+    name: "ops-heavy",
+    purpose: "Certifies the operational control-plane proof surfaces that should block releases when evidence, queues, or operator actions are unhealthy.",
+    surfaces: [
+      {
+        configured: isConfigured(options.audit),
+        href: links.audit,
+        key: "audit",
+        label: "Audit evidence"
+      },
+      {
+        configured: isConfigured(options.opsActionHistory ?? options.audit),
+        href: links.opsActions,
+        key: "opsActionHistory",
+        label: "Operator action history"
+      },
+      {
+        configured: isConfigured(options.deliveryRuntime),
+        href: links.deliveryRuntime,
+        key: "deliveryRuntime",
+        label: "Delivery runtime"
+      },
+      {
+        configured: isConfigured(options.auditDeliveries),
+        href: links.auditDeliveries,
+        key: "auditDeliveries",
+        label: "Audit deliveries"
+      },
+      {
+        configured: isConfigured(options.traceDeliveries),
+        href: links.traceDeliveries,
+        key: "traceDeliveries",
+        label: "Trace deliveries"
+      }
+    ]
+  };
+};
 var createVoiceReadinessProfile = (profile, options = {}) => {
   if (profile === "meeting-recorder") {
+    const links2 = mergeLinks({
+      bargeIn: "/barge-in",
+      liveLatency: "/live-latency",
+      providerRoutingContracts: "/resilience",
+      quality: "/quality",
+      reconnectContracts: "/voice/reconnect-contract",
+      resilience: "/resilience",
+      sessions: "/sessions"
+    }, options.links);
     return withDefined({
       bargeInReports: options.bargeInReports,
       gate: options.gate,
-      links: mergeLinks({
-        bargeIn: "/barge-in",
-        liveLatency: "/live-latency",
-        providerRoutingContracts: "/resilience",
-        quality: "/quality",
-        reconnectContracts: "/voice/reconnect-contract",
-        resilience: "/resilience",
-        sessions: "/sessions"
-      }, options.links),
+      links: links2,
+      profile: profileExplanation(profile, options, links2),
       proofSources: options.proofSources,
       providerRoutingContracts: options.providerRoutingContracts,
       reconnectContracts: options.reconnectContracts
     });
   }
   if (profile === "phone-agent") {
+    const links2 = mergeLinks({
+      auditDeliveries: "/audit/deliveries",
+      carriers: "/carriers",
+      deliveryRuntime: "/delivery-runtime",
+      handoffs: "/handoffs",
+      phoneAgentSmoke: "/sessions",
+      providerRoutingContracts: "/resilience",
+      resilience: "/resilience",
+      sessions: "/sessions",
+      traceDeliveries: "/traces/deliveries"
+    }, options.links);
     return withDefined({
       auditDeliveries: options.auditDeliveries,
       carriers: options.carriers,
       deliveryRuntime: options.deliveryRuntime,
       gate: options.gate,
-      links: mergeLinks({
-        auditDeliveries: "/audit/deliveries",
-        carriers: "/carriers",
-        deliveryRuntime: "/delivery-runtime",
-        handoffs: "/handoffs",
-        phoneAgentSmoke: "/sessions",
-        providerRoutingContracts: "/resilience",
-        resilience: "/resilience",
-        sessions: "/sessions",
-        traceDeliveries: "/traces/deliveries"
-      }, options.links),
+      links: links2,
       phoneAgentSmokes: options.phoneAgentSmokes,
+      profile: profileExplanation(profile, options, links2),
       proofSources: options.proofSources,
       providerRoutingContracts: options.providerRoutingContracts,
       traceDeliveries: options.traceDeliveries
     });
   }
   const opsActionHistory = options.opsActionHistory ?? auditStoreFromOptions(options.audit);
+  const links = mergeLinks({
+    audit: "/audit",
+    auditDeliveries: "/audit/deliveries",
+    deliveryRuntime: "/delivery-runtime",
+    opsActions: "/voice/ops-actions",
+    traceDeliveries: "/traces/deliveries"
+  }, options.links);
   return withDefined({
     audit: options.audit,
     auditDeliveries: options.auditDeliveries,
     deliveryRuntime: options.deliveryRuntime,
     gate: options.gate,
-    links: mergeLinks({
-      audit: "/audit",
-      auditDeliveries: "/audit/deliveries",
-      deliveryRuntime: "/delivery-runtime",
-      opsActions: "/voice/ops-actions",
-      traceDeliveries: "/traces/deliveries"
-    }, options.links),
+    links,
     opsActionHistory,
+    profile: profileExplanation(profile, options, links),
     proofSources: options.proofSources,
     traceDeliveries: options.traceDeliveries
   });

package/dist/productionReadiness.d.ts

@@ -52,6 +52,18 @@ export type VoiceProductionReadinessProofSource = {
     source: string;
     sourceLabel: string;
 };
+export type VoiceProductionReadinessProfileSurface = {
+    configured: boolean;
+    href?: string;
+    key: string;
+    label: string;
+};
+export type VoiceProductionReadinessProfileExplanation = {
+    description: string;
+    name: string;
+    purpose: string;
+    surfaces: VoiceProductionReadinessProfileSurface[];
+};
 export type VoiceProductionReadinessReport = {
     checkedAt: number;
     checks: VoiceProductionReadinessCheck[];
@@ -74,6 +86,7 @@ export type VoiceProductionReadinessReport = {
         sessions?: string;
         traceDeliveries?: string;
     };
+    profile?: VoiceProductionReadinessProfileExplanation;
     proofSources?: Record<string, VoiceProductionReadinessProofSource>;
     status: VoiceProductionReadinessStatus;
     summary: {
@@ -284,6 +297,7 @@ export type VoiceProductionReadinessRoutesOptions = {
         query: Record<string, unknown>;
         request: Request;
     }) => Promise<Record<string, VoiceProductionReadinessProofSource>> | Record<string, VoiceProductionReadinessProofSource>);
+    profile?: false | VoiceProductionReadinessProfileExplanation;
     render?: (report: VoiceProductionReadinessReport) => string | Promise<string>;
     store: VoiceTraceEventStore;
     sttProviders?: readonly string[];

package/dist/readinessProfiles.d.ts

@@ -6,6 +6,7 @@ export type VoiceReadinessProfileOptions = {
     bargeInReports?: VoiceProductionReadinessRoutesOptions['bargeInReports'];
     carriers?: VoiceProductionReadinessRoutesOptions['carriers'];
     deliveryRuntime?: VoiceProductionReadinessRoutesOptions['deliveryRuntime'];
+    explain?: boolean;
     gate?: VoiceProductionReadinessRoutesOptions['gate'];
     links?: VoiceProductionReadinessRoutesOptions['links'];
     opsActionHistory?: VoiceProductionReadinessOpsActionHistoryOptions;

package/package.json

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