@absolutejs/voice 0.0.22-beta.2 → 0.0.22-beta.200

package/README.md

@@ -1,11 +1,50 @@
 # `@absolutejs/voice`
 
-`@absolutejs/voice` is the voice session layer for AbsoluteJS. It owns the duplex WebSocket lifecycle, transcript buffering, turn commits, reconnect behavior, and client primitives, while keeping speech vendors and session storage pluggable.
+`@absolutejs/voice` is the self-hosted voice operations layer for AbsoluteJS.
+
+It gives your app the primitives hosted voice platforms usually keep behind their dashboards: browser voice sessions, phone-call routes, provider routing, assistant tools, handoffs, traces, evals, production-readiness checks, latency proof, storage adapters, and framework-native UI helpers.
+
+Use it when you want Vapi/Retell/Bland-style voice-agent capability, but you want the orchestration, data, traces, storage, and UI to live inside the AbsoluteJS server you already operate.
+
+## Why AbsoluteJS Voice
+
+- Self-hosted by default: your app owns sessions, traces, reviews, tasks, handoffs, retention, and provider keys.
+- Provider-neutral: use Deepgram, AssemblyAI, OpenAI, Anthropic, Gemini, ElevenLabs-style TTS, or your own adapters without rewriting app workflow code.
+- Browser and phone surfaces: mount browser WebSocket voice routes plus Twilio, Telnyx, and Plivo telephony routes from the same package.
+- Production proof: ops status, ops recovery, production readiness, operations records, turn quality, turn latency, live browser p50/p95 latency, trace timelines, evals, fixtures, and contracts are package primitives.
+- Framework parity: React, Vue, Svelte, Angular, HTML, HTMX, and plain client entrypoints share the same core behavior.
+- No hosted platform tax: AbsoluteJS Voice does not add a mandatory per-minute orchestration fee between your app and your providers.
+
+## Start Here
+
+Pick the path that matches what you are building:
+
+- Browser voice agent: mount `voice(...)`, choose an STT adapter, and use the React/Vue/Svelte/Angular/HTML/HTMX client helpers for mic, transcript, reconnect, and status UI.
+- Phone voice agent: mount Twilio, Telnyx, or Plivo routes, normalize carrier outcomes, inspect carrier readiness, and persist call lifecycle traces.
+- Outbound campaigns: create self-hosted campaign queues, import CSV/JSON recipients, enforce rate limits/quiet hours/retry backoff, dry-run carrier dialers, and fail production readiness when campaign proof regresses.
+- Production readiness: mount the status and proof primitives you need, such as `createVoiceOpsStatusRoutes(...)`, `createVoiceProductionReadinessRoutes(...)`, quality routes, trace routes, eval routes, and smoke contracts.
+- Support/debug entrypoint: mount `createVoiceOperationsRecordRoutes(...)` so every problematic session has one call-log object linking traces, replay, provider events, tools, handoffs, audit, reviews, tasks, and delivery attempts.
+- Provider routing and fallback: use LLM/STT/TTS provider routers, provider health, provider simulation controls, and cost/latency-aware routing policies.
+- Evals and simulation: mount `createVoiceSimulationSuiteRoutes(...)` to run scenario fixtures, workflow contracts, tool contracts, outcome contracts, baseline comparisons, and saved benchmark artifacts before live traffic.
+
+## How This Differs From Hosted Voice Platforms
+
+Hosted voice-agent platforms are strongest when you want a managed dashboard, phone-number provisioning, hosted orchestration, and campaign tooling out of the box.
+
+AbsoluteJS Voice is strongest when voice is part of your own product and you need code-owned primitives:
+
+- Your app stores the call data instead of a vendor dashboard being the source of truth.
+- Your app controls provider routing, fallback, retries, handoffs, and retention.
+- Your team can inspect and extend every primitive.
+- Your framework UI can render first-class voice state without iframe/dashboard handoffs.
+- Your production checks and evals can run in CI, smoke tests, or your own admin UI.
+
+The goal is not to clone a hosted platform. The goal is to make AbsoluteJS the best place to build and operate self-hosted voice products.
 
 ## Install
 
 ```bash
-bun add @absolutejs/voice
+bun add @absolutejs/voice @absolutejs/voice-deepgram
 ```
 
 Peer dependencies:
@@ -21,57 +60,851 @@ Optional framework entrypoints:
 - `@absolutejs/voice/angular`
 - `@absolutejs/voice/client`
 
-## Route Setup
+Common optional adapters:
+
+- `@absolutejs/voice-deepgram`
+- `@absolutejs/voice-assemblyai`
+
+## Browser Voice Agent
+
+```ts
+import { Elysia } from 'elysia';
+import {
+	voice,
+	createVoiceMemoryStore,
+	createPhraseHintCorrectionHandler
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const app = new Elysia()
+	.use(
+		voice({
+			path: '/voice',
+			preset: 'guided-intake',
+			lexicon: [
+				{
+					text: 'AbsoluteJS',
+					aliases: ['absoloot js'],
+					pronunciation: 'ab-so-lute jay ess'
+				}
+			],
+			phraseHints: [
+				{ text: 'AbsoluteJS', aliases: ['absolute js'] },
+				{ text: 'Joe Johnston', aliases: ['joe johnson'] }
+			],
+			correctTurn: createPhraseHintCorrectionHandler(),
+			onComplete: async ({ session }) => {
+				console.log(session.turns);
+			},
+			async onTurn({ turn }) {
+				console.log('turn quality:', {
+					source: turn.quality?.source,
+					fallbackUsed: turn.quality?.fallbackUsed,
+					confidence: turn.quality?.averageConfidence
+				});
+				return {
+					assistantText: `You said: ${turn.text}`
+				};
+			},
+			session: createVoiceMemoryStore(),
+			stt: deepgram({
+				apiKey: process.env.DEEPGRAM_API_KEY!,
+				model: 'nova-3'
+			})
+		})
+	);
+```
+
+`createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
+
+## Production Readiness Path
+
+Once the basic route works, mount the proof routes you need. These give you the self-hosted operational surfaces that hosted platforms usually make mandatory, without forcing a bundled app kit:
+
+```ts
+import {
+	createVoiceAuditDeliveryRoutes,
+	createVoiceDemoReadyRoutes,
+	createVoiceFileRuntimeStorage,
+	createVoiceLiveLatencyRoutes,
+	createVoiceOpsStatusRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceTraceDeliveryRoutes,
+	createVoiceTraceTimelineRoutes,
+	createVoiceTurnLatencyRoutes,
+	createVoiceTurnQualityRoutes
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+app
+	.use(
+		createVoiceOpsStatusRoutes({
+			store: runtime.traces,
+			llmProviders: ['openai', 'anthropic', 'gemini'],
+			sttProviders: ['deepgram', 'assemblyai']
+		})
+	)
+	.use(
+		createVoiceTurnLatencyRoutes({
+			htmlPath: '/turn-latency',
+			path: '/api/turn-latency',
+			store: runtime.session,
+			traceStore: runtime.traces
+		})
+	)
+	.use(
+		createVoiceLiveLatencyRoutes({
+			htmlPath: '/live-latency',
+			path: '/api/live-latency',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceTurnQualityRoutes({
+			htmlPath: '/turn-quality',
+			path: '/api/turn-quality',
+			store: runtime.session
+		})
+	)
+	.use(
+		createVoiceTraceTimelineRoutes({
+			htmlPath: '/traces',
+			path: '/api/voice-traces',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			audit: runtime.audit,
+			auditDeliveries: runtime.auditDeliveries,
+			htmlPath: '/production-readiness',
+			path: '/api/production-readiness',
+			store: runtime.traces,
+			traceDeliveries: runtime.traceDeliveries
+		})
+	)
+	.use(
+		createVoiceAuditDeliveryRoutes({
+			htmlPath: '/audit/deliveries',
+			path: '/api/voice-audit-deliveries',
+			store: runtime.auditDeliveries
+		})
+	)
+	.use(
+		createVoiceTraceDeliveryRoutes({
+			htmlPath: '/traces/deliveries',
+			path: '/api/voice-trace-deliveries',
+			store: runtime.traceDeliveries
+		})
+	);
+```
+
+Recommended proof routes:
+
+- `/api/voice/ops-status`: compact status for hooks, widgets, and customer-facing demos.
+- `/api/voice/ops-status/html`: HTML status card for quick internal review.
+- `/demo-ready`: customer-facing demo readiness checklist.
+- `/production-readiness`: production gate summary.
+- `/audit/deliveries`: audit sink export queue and failed delivery details.
+- `/voice/phone/smoke-contract`: trace-backed phone-agent production smoke proof.
+- `/traces`: per-session trace timelines.
+- `/traces/deliveries`: trace sink export queue and failed delivery details.
+- `/turn-latency`: server-side turn-stage latency.
+- `/live-latency`: browser-measured speech-to-assistant p50/p95 latency.
+- `/turn-quality`: STT confidence, correction, fallback, and transcript diagnostics.
+
+### Readiness Profiles
+
+Use `createVoiceReadinessProfile(...)` when you want production-shaped defaults without adopting an app kit. Profiles are just spreadable route-option bundles for `createVoiceProductionReadinessRoutes(...)`; every option remains explicit and overrideable.
+
+```ts
+import {
+	createVoiceProductionReadinessRoutes,
+	createVoiceReadinessProfile
+} from '@absolutejs/voice';
+
+app.use(
+	createVoiceProductionReadinessRoutes({
+		...createVoiceReadinessProfile('meeting-recorder', {
+			bargeInReports: async () => [await buildBargeInReport()],
+			explain: true,
+			providerRoutingContracts: async () => [await runProviderRoutingContract()],
+			reconnectContracts: async () => [await runReconnectContract()]
+		}),
+		store: runtime.traces
+	})
+);
+```
+
+Built-in profiles:
+
+- `meeting-recorder`: live latency, session health, provider fallback, routing contracts, reconnect proof, and barge-in interruption proof.
+- `phone-agent`: carrier readiness, phone-agent smoke proof, campaign readiness proof, handoffs, provider routing contracts, audit/trace delivery health, and delivery runtime proof.
+- `ops-heavy`: audit evidence, operator action history, audit/trace delivery health, delivery runtime proof, and deploy-gate support.
+
+Phone-agent fast path:
+
+```ts
+app.use(
+	createVoiceProductionReadinessRoutes({
+		...createVoiceReadinessProfile('phone-agent', {
+			auditDeliveries: runtime.auditDeliveries,
+			campaignReadiness: () =>
+				runVoiceCampaignReadinessProof({
+					store: runtime.campaigns
+				}),
+			carriers: loadCarrierMatrixInputs,
+			deliveryRuntime,
+			explain: true,
+			phoneAgentSmokes: async () => [await runPhoneSmoke()],
+			providerRoutingContracts: async () => [await runProviderRoutingContract()],
+			traceDeliveries: runtime.traceDeliveries
+		}),
+		store: runtime.traces
+	})
+);
+```
+
+Ops-heavy fast path:
+
+```ts
+app.use(
+	createVoiceProductionReadinessRoutes({
+		...createVoiceReadinessProfile('ops-heavy', {
+			audit: runtime.audit,
+			auditDeliveries: runtime.auditDeliveries,
+			deliveryRuntime,
+			traceDeliveries: runtime.traceDeliveries
+		}),
+		gate: {
+			failOnWarnings: true
+		},
+		store: runtime.traces
+	})
+);
+```
+
+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(...)`.
+
+### File Delivery
+
+Use file delivery for local demos, dev environments, or self-hosted deployments that collect exports from disk.
+
+```ts
+import {
+	createVoiceDeliveryRuntime,
+	createVoiceDeliveryRuntimePresetConfig,
+	createVoiceDeliveryRuntimeRoutes,
+	createVoiceFileRuntimeStorage
+} from '@absolutejs/voice';
+
+const runtimeStorage = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+const deliveryRuntime = createVoiceDeliveryRuntime(
+	createVoiceDeliveryRuntimePresetConfig({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		directory: '.voice-runtime/support/delivery-exports',
+		leases: createLeaseCoordinator(),
+		mode: 'file',
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+
+app.use(
+	createVoiceDeliveryRuntimeRoutes({
+		runtime: deliveryRuntime
+	})
+);
+```
+
+### Webhook Delivery
+
+Use webhook delivery when audit and trace exports should go to your own ingestion service, SIEM bridge, warehouse collector, or internal ops backend. The built-in HTTP sinks support retries, optional HMAC signing, custom headers, timeouts, and custom envelope bodies.
+
+```ts
+const deliveryRuntime = createVoiceDeliveryRuntime(
+	createVoiceDeliveryRuntimePresetConfig({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		auditSinkId: 'support-audit-webhook',
+		body: {
+			audit: ({ events }) => ({
+				eventCount: events.length,
+				events,
+				source: 'support-app',
+				surface: 'audit-deliveries'
+			}),
+			trace: ({ events }) => ({
+				eventCount: events.length,
+				events,
+				source: 'support-app',
+				surface: 'trace-deliveries'
+			})
+		},
+		failures: {
+			maxFailures: 3
+		},
+		leases: {
+			audit: createLeaseCoordinator(),
+			trace: createLeaseCoordinator()
+		},
+		mode: 'webhook',
+		signingSecret: process.env.VOICE_DELIVERY_WEBHOOK_SECRET,
+		traceDeliveries: runtimeStorage.traceDeliveries,
+		traceSinkId: 'support-trace-webhook',
+		url: process.env.VOICE_DELIVERY_WEBHOOK_URL!
+	})
+);
+```
+
+### S3 Delivery
+
+Use S3 delivery when exports should land directly in object storage through Bun's native S3 client. Set `bucket` and `keyPrefix`; the preset writes audit and trace exports under separate prefixes.
+
+```ts
+const deliveryRuntime = createVoiceDeliveryRuntime(
+	createVoiceDeliveryRuntimePresetConfig({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		auditSinkId: 'support-audit-s3',
+		bucket: process.env.VOICE_DELIVERY_S3_BUCKET,
+		failures: {
+			maxFailures: 3
+		},
+		keyPrefix: 'support/voice-deliveries',
+		leases: {
+			audit: createLeaseCoordinator(),
+			trace: createLeaseCoordinator()
+		},
+		mode: 's3',
+		traceDeliveries: runtimeStorage.traceDeliveries,
+		traceSinkId: 'support-trace-s3'
+	})
+);
+```
+
+Mount `createVoiceDeliveryRuntimeRoutes({ runtime: deliveryRuntime })` to expose:
+
+- `/api/voice-delivery-runtime`: combined audit and trace worker summary.
+- `/api/voice-delivery-runtime/tick`: manual tick for both workers.
+- `/delivery-runtime`: HTML worker control plane.
+
+Pass the same runtime to production readiness so failed, dead-lettered, or pending export queues become deploy-blocking evidence:
+
+```ts
+app.use(
+	createVoiceProductionReadinessRoutes({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		deliveryRuntime,
+		links: {
+			deliveryRuntime: '/delivery-runtime'
+		},
+		store: runtimeStorage.traces,
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+```
+
+## Simulation Suite Path
+
+Use `createVoiceSimulationSuiteRoutes(...)` when you want one pre-production proof surface for the things that usually live in separate dashboards or scripts:
+
+```ts
+import {
+	createVoiceSimulationSuiteRoutes,
+	createVoiceFileRuntimeStorage
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+app.use(
+	createVoiceSimulationSuiteRoutes({
+		htmlPath: '/voice/simulations',
+		path: '/api/voice/simulations',
+		store: runtime.traces,
+		scenarios: workflowScenarios,
+		fixtureStore: scenarioFixtureStore,
+		tools: toolContracts,
+		outcomes: {
+			contracts: outcomeContracts,
+			events: runtime.events,
+			reviews: runtime.reviews,
+			sessions: runtime.session,
+			tasks: runtime.tasks
+		}
+	})
+);
+```
+
+The suite rolls up session quality, scenario evals, fixture simulations, tool contracts, and outcome contracts into one pass/fail report. It is the code-owned equivalent of "test this voice flow before production" without requiring a hosted voice-agent dashboard.
+
+## Self-Hosted Campaigns
+
+Use `createVoiceCampaignRoutes(...)` when you need Retell/Bland-style outbound campaign primitives without giving a hosted dialer ownership of recipients, attempts, outcomes, or readiness proof.
+
+```ts
+import {
+	createVoiceCampaignRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceReadinessProfile,
+	createVoiceSQLiteCampaignStore,
+	runVoiceCampaignReadinessProof
+} from '@absolutejs/voice';
+
+const campaigns = createVoiceSQLiteCampaignStore({
+	path: '.voice-runtime/campaigns.sqlite'
+});
+
+app.use(
+	createVoiceCampaignRoutes({
+		htmlPath: '/voice/campaigns',
+		path: '/api/voice/campaigns',
+		store: campaigns,
+		title: 'Outbound Campaigns'
+	})
+);
+```
+
+The campaign runtime gives you explicit primitives instead of a campaign app kit:
+
+- `importVoiceCampaignRecipients(...)`: validates CSV/JSON rows, phone numbers, consent, duplicates, variables, and metadata.
+- `VoiceCampaignRuntime.importRecipients(...)`: persists accepted recipients and returns rejected-row evidence.
+- `tick(...)`: enforces campaign status, max concurrency, attempt windows, quiet hours, rolling rate limits, retry backoff, and `maxAttempts`.
+- `pause(...)`, `resume(...)`, `cancel(...)`: operator-safe campaign controls.
+- `applyVoiceCampaignTelephonyOutcome(...)`: maps Twilio/Telnyx/Plivo webhook decisions back into campaign attempts.
+- `buildVoiceCampaignObservabilityReport(...)`: queue depth, active attempts, leases, attempt rates, failures, and stuck work.
+
+Import recipients through the route API:
+
+```ts
+await fetch('/api/voice/campaigns/campaign-1/recipients/import', {
+	body: JSON.stringify({
+		csv: `id,name,phone,consent,segment
+recipient-1,Ada,+15550001001,yes,trial
+recipient-2,Grace,+15550001002,true,enterprise`,
+		requireConsent: true,
+		variableColumns: ['segment']
+	}),
+	headers: {
+		'content-type': 'application/json'
+	},
+	method: 'POST'
+});
+```
+
+Create campaigns with scheduling controls:
+
+```ts
+await runtime.create({
+	maxAttempts: 3,
+	maxConcurrentAttempts: 10,
+	name: 'Renewal outreach',
+	schedule: {
+		attemptWindow: { startHour: 9, endHour: 17 },
+		quietHours: { startHour: 12, endHour: 13 },
+		rateLimit: { maxAttempts: 60, windowMs: 60_000 },
+		retryPolicy: { backoffMs: [5 * 60_000, 30 * 60_000] }
+	}
+});
+```
+
+Certify the campaign path without live carrier traffic:
+
+```ts
+const campaignReadiness = await runVoiceCampaignReadinessProof({
+	store: campaigns
+});
+
+if (!campaignReadiness.ok) {
+	throw new Error(
+		campaignReadiness.checks
+			.filter((check) => check.status !== 'pass')
+			.map((check) => check.name)
+			.join('\n')
+	);
+}
+```
+
+Pass that proof into production readiness so campaign regressions block deploys:
+
+```ts
+app.use(
+	createVoiceProductionReadinessRoutes({
+		...createVoiceReadinessProfile('phone-agent', {
+			campaignReadiness: () =>
+				runVoiceCampaignReadinessProof({
+					store: campaigns
+				}),
+			explain: true
+		}),
+		store: runtime.traces
+	})
+);
+```
+
+For carrier-specific outbound dialing, use `createVoiceTwilioCampaignDialer(...)`, `createVoiceTelnyxCampaignDialer(...)`, or `createVoicePlivoCampaignDialer(...)` as the campaign `dialer`. `runVoiceCampaignDialerProof(...)` dry-runs those provider requests with intercepted fetch calls and synthetic webhook outcomes, so you can prove metadata and outcome application before a real campaign sends traffic.
+
+## Phone Voice Agent In 20 Minutes
+
+Use `createVoicePhoneAgent(...)` when the agent needs to answer or place calls through your own Twilio, Telnyx, or Plivo account. This is the self-hosted alternative to a hosted phone-agent dashboard: your app owns the carrier routes, stream URLs, webhooks, traces, readiness checks, and lifecycle outcomes.
+
+```ts
+import {
+	createVoicePhoneAgent,
+	createVoiceTelephonyOutcomePolicy,
+	runVoicePhoneAgentProductionSmokeContract
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const outcomePolicy = createVoiceTelephonyOutcomePolicy({
+	transferTarget: '+15551234567'
+});
+
+app
+	.use(
+		createVoicePhoneAgent({
+			setup: {
+				path: '/api/voice/phone/setup',
+				title: 'Support Phone Agent'
+			},
+			matrix: {
+				path: '/api/carriers',
+				title: 'AbsoluteJS Voice Carrier Matrix'
+			},
+			productionSmoke: {
+				maxAgeMs: 24 * 60 * 60 * 1000,
+				required: [
+					'carrier-contract',
+					'media-started',
+					'transcript',
+					'assistant-response',
+					'lifecycle-outcome',
+					'no-session-error',
+					'fresh-trace'
+				],
+				store: runtime.traces
+			},
+			carriers: [
+				{
+					provider: 'twilio',
+					options: {
+						context: {},
+						outcomePolicy,
+						session: runtime.session,
+						stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+						streamPath: '/api/voice/twilio/stream',
+						twiml: {
+							path: '/api/voice/twilio',
+							streamUrl: process.env.TWILIO_STREAM_URL
+						},
+						webhook: {
+							path: '/api/voice/twilio/webhook',
+							signingSecret: process.env.TWILIO_AUTH_TOKEN
+						},
+						async onTurn({ turn }) {
+							return { assistantText: `I heard: ${turn.text}` };
+						},
+						onComplete: async () => {}
+					}
+				}
+			]
+		}).routes
+	);
+```
+
+The wrapper mounts selected carrier routes plus two proof surfaces:
+
+- `/api/voice/phone/setup`: one setup report with carrier URLs, smoke links, lifecycle stages, and readiness.
+- `/api/voice/phone/setup?format=html`: copy/paste setup page for carrier dashboards.
+- `/api/carriers`: carrier matrix JSON for Twilio, Telnyx, and Plivo.
+- `/api/carriers?format=html`: side-by-side carrier readiness matrix.
+- `/api/voice/phone/smoke-contract?sessionId=...`: trace-backed production smoke contract.
+- `/voice/phone/smoke-contract?sessionId=...`: HTML production smoke contract.
+
+The setup page tells you exactly what to copy into the carrier dashboard:
+
+- Twilio: set the phone number voice webhook/TwiML URL to the reported TwiML URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
+- Telnyx: set the connection TeXML URL to the reported TeXML URL, set the status webhook to the reported webhook URL, and allow the reported `wss://` media stream.
+- Plivo: set the answer URL to the reported answer URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
+
+Each configured carrier can also expose its own setup and smoke pages, for example:
+
+- `/api/voice/twilio/setup?format=html`
+- `/api/voice/twilio/smoke?format=html`
+- `/api/voice/telnyx/setup?format=html`
+- `/api/voice/telnyx/smoke?format=html`
+- `/api/voice/plivo/setup?format=html`
+- `/api/voice/plivo/smoke?format=html`
+
+The phone-agent report normalizes the lifecycle schema across carriers:
+
+- `ringing`
+- `answered`
+- `media-started`
+- `transcript`
+- `assistant-response`
+- `transfer`
+- `voicemail`
+- `no-answer`
+- `completed`
+- `failed`
+
+That is the important Vapi/Retell/Bland gap this primitive closes: a team can mount one phone-agent entrypoint, bring its own carrier account, verify readiness before live calls, and keep call traces and lifecycle outcomes inside its own AbsoluteJS app. Telnyx and Plivo use the same wrapper with `{ provider: 'telnyx', options: ... }` or `{ provider: 'plivo', options: ... }`. The lower-level `createTwilioVoiceRoutes(...)`, `createTelnyxVoiceRoutes(...)`, and `createPlivoVoiceRoutes(...)` helpers remain available when you need carrier-specific control.
+
+After running a real smoke call, certify the phone-agent path from traces:
+
+```ts
+const smoke = await runVoicePhoneAgentProductionSmokeContract({
+	maxAgeMs: 24 * 60 * 60 * 1000,
+	required: [
+		'media-started',
+		'transcript',
+		'assistant-response',
+		'lifecycle-outcome',
+		'no-session-error',
+		'fresh-trace'
+	],
+	sessionId: 'phone-smoke-session',
+	store: runtime.traces
+});
+
+if (!smoke.pass) {
+	throw new Error(smoke.issues.map((issue) => issue.message).join('\n'));
+}
+```
+
+Pass those reports into production readiness through `phoneAgentSmokes`. This makes deployment fail when the carrier setup exists but the actual phone-agent call path did not produce media start, transcript, assistant response, terminal lifecycle outcome, and clean trace evidence.
+
+When `productionSmoke` is enabled on `createVoicePhoneAgent(...)`, the wrapper mounts `/api/voice/phone/smoke-contract?sessionId=...` for JSON and `/voice/phone/smoke-contract?sessionId=...` for HTML. It also derives carrier contract evidence from the existing carrier matrix unless you provide a custom `getContract`.
+
+## Ops Status Hooks And Widgets
+
+Use `createVoiceOpsStatusRoutes(...)` when you want a small status endpoint for demos, admin pages, and framework widgets. It is intentionally not a route bundle: mount quality gates, eval routes, provider health, session replay, phone-agent smoke proof, handoff health, and diagnostics explicitly when your app needs them.
+
+```ts
+import {
+	createVoiceDemoReadyRoutes,
+	createVoiceFileRuntimeStorage,
+	createVoiceOpsStatusRoutes,
+	summarizeVoiceOpsStatus
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({ directory: '.voice-runtime/support' });
+
+app.use(
+	createVoiceOpsStatusRoutes({
+		store: runtime.traces,
+		llmProviders: ['openai', 'anthropic', 'gemini'],
+		sttProviders: ['deepgram', 'assemblyai']
+	})
+);
+```
+
+The status endpoint is intentionally small enough for customer-facing demos. It can report fixture-backed workflow readiness while leaving deeper live quality/session failures visible on the proof routes you mount separately.
+
+For a single demo page that rolls up ops status, production readiness, phone setup, and phone smoke proof, mount `createVoiceDemoReadyRoutes(...)` with the same reports you already expose elsewhere:
+
+```ts
+app.use(
+	createVoiceDemoReadyRoutes({
+		opsStatus: {
+			href: '/api/voice/ops-status',
+			load: () => summarizeVoiceOpsStatus(opsStatusOptions)
+		},
+		phoneSetup: {
+			href: '/api/voice/phone/setup?format=html',
+			load: () => phoneAgentSetupReport
+		},
+		phoneSmoke: {
+			href: '/voice/phone/smoke-contract',
+			load: () => phoneSmokeReport
+		},
+		productionReadiness: {
+			href: '/production-readiness',
+			load: () => productionReadinessReport
+		}
+	})
+);
+```
+
+```ts
+app.use(
+	createVoiceOpsStatusRoutes({
+		include: { quality: false, sessions: false },
+		preferFixtureWorkflows: true,
+		store: runtime.traces
+	})
+);
+```
+
+### React Status Widget
+
+```tsx
+import { VoiceOpsStatus } from '@absolutejs/voice/react';
+
+export function OpsBadge() {
+	return <VoiceOpsStatus intervalMs={5000} />;
+}
+```
+
+### Vue Status Widget
+
+```vue
+<script setup lang="ts">
+import { VoiceOpsStatus } from '@absolutejs/voice/vue';
+</script>
+
+<template>
+	<VoiceOpsStatus :interval-ms="5000" />
+</template>
+```
+
+### Svelte Status Widget
+
+```svelte
+<script lang="ts">
+	import { onDestroy, onMount } from 'svelte';
+	import { createVoiceOpsStatus } from '@absolutejs/voice/svelte';
+
+	const status = createVoiceOpsStatus('/api/voice/ops-status', { intervalMs: 5000 });
+	let html = '';
+	onMount(() => status.subscribe(() => (html = status.getHTML())));
+	onDestroy(() => status.close());
+</script>
+
+{@html html}
+```
+
+### Angular Status Widget
+
+```ts
+import { VoiceOpsStatusService } from '@absolutejs/voice/angular';
+
+status = inject(VoiceOpsStatusService).connect('/api/voice/ops-status', {
+	intervalMs: 5000
+});
+```
+
+```html
+<h2>{{ status.report()?.status === 'pass' ? 'Passing' : 'Needs attention' }}</h2>
+<p>{{ status.report()?.passed ?? 0 }} passing checks</p>
+```
+
+### HTML Or HTMX Status Widget
+
+```html
+<div id="voice-ops-status"></div>
+<script type="module">
+	import { mountVoiceOpsStatus } from '@absolutejs/voice/client';
+
+	mountVoiceOpsStatus(document.querySelector('#voice-ops-status'), '/api/voice/ops-status', {
+		intervalMs: 5000
+	});
+</script>
+```
+
+For custom elements:
+
+```html
+<absolute-voice-ops-status interval-ms="5000"></absolute-voice-ops-status>
+<script type="module">
+	import { defineVoiceOpsStatusElement } from '@absolutejs/voice/client';
+	defineVoiceOpsStatusElement();
+</script>
+```
+
+## Delivery Runtime Widgets
+
+After mounting `createVoiceDeliveryRuntimeRoutes(...)`, apps can expose audit and trace worker health through the same framework-native primitives:
+
+```tsx
+import { VoiceDeliveryRuntime } from '@absolutejs/voice/react';
+
+export function DeliveryWorkers() {
+	return <VoiceDeliveryRuntime intervalMs={5000} />;
+}
+```
+
+The widget includes operator actions by default: `Tick workers` drains pending/failed deliveries, and `Requeue dead letters` moves reviewed dead-lettered audit/trace deliveries back into the live queues. Pass `includeActions={false}` when you only want a read-only status card.
+
+```ts
+import { VoiceDeliveryRuntime } from '@absolutejs/voice/vue';
+import { createVoiceDeliveryRuntime } from '@absolutejs/voice/svelte';
+import { VoiceDeliveryRuntimeService } from '@absolutejs/voice/angular';
+```
+
+For HTML or HTMX pages:
+
+```html
+<absolute-voice-delivery-runtime interval-ms="5000"></absolute-voice-delivery-runtime>
+<script type="module">
+	import { defineVoiceDeliveryRuntimeElement } from '@absolutejs/voice/client';
+	defineVoiceDeliveryRuntimeElement();
+</script>
+```
+
+## Voice Ops Action Center
+
+Use `VoiceOpsActionCenter` when you want one primitive operator panel for production proofs and recovery actions without building a dashboard. The default action builder can include production readiness refresh, delivery worker ticks, dead-letter requeue, turn-latency proof, and provider failover simulation.
+
+```tsx
+import { VoiceOpsActionCenter } from '@absolutejs/voice/react';
+import { createVoiceOpsActionCenterActions } from '@absolutejs/voice/client';
+
+export function OperatorPanel() {
+	return (
+		<VoiceOpsActionCenter
+			actions={createVoiceOpsActionCenterActions({
+				providers: ['deepgram', 'assemblyai']
+			})}
+		/>
+	);
+}
+```
+
+Mount `createVoiceOpsActionAuditRoutes(...)` to make every action-center click auditable. The client posts successful and failed action results to `/api/voice/ops-actions/audit` by default, and the route records both `operator.action` audit events and `operator.action` trace events.
 
 ```ts
-import { Elysia } from 'elysia';
-import {
-	voice,
-	createVoiceMemoryStore,
-	createPhraseHintCorrectionHandler
-} from '@absolutejs/voice';
-import { deepgram } from '@absolutejs/voice-deepgram';
+import { createVoiceOpsActionAuditRoutes } from '@absolutejs/voice';
 
-const app = new Elysia()
-	.use(
-		voice({
-			path: '/voice',
-			preset: 'guided-intake',
-			lexicon: [
-				{
-					text: 'AbsoluteJS',
-					aliases: ['absoloot js'],
-					pronunciation: 'ab-so-lute jay ess'
-				}
-			],
-			phraseHints: [
-				{ text: 'AbsoluteJS', aliases: ['absolute js'] },
-				{ text: 'Joe Johnston', aliases: ['joe johnson'] }
-			],
-			correctTurn: createPhraseHintCorrectionHandler(),
-			onComplete: async ({ session }) => {
-				console.log(session.turns);
-			},
-			async onTurn({ turn }) {
-				console.log('turn quality:', {
-					source: turn.quality?.source,
-					fallbackUsed: turn.quality?.fallbackUsed,
-					confidence: turn.quality?.averageConfidence
-				});
-				return {
-					assistantText: `You said: ${turn.text}`
-				};
-			},
-			session: createVoiceMemoryStore(),
-			stt: deepgram({
-				apiKey: process.env.DEEPGRAM_API_KEY!,
-				model: 'nova-3'
-			})
-		})
-	);
+app.use(
+	createVoiceOpsActionAuditRoutes({
+		audit: runtimeStorage.audit,
+		trace: runtimeStorage.traces
+	})
+);
 ```
 
-`createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
+The same route exposes `GET /api/voice/ops-actions/history` and `/voice/ops-actions` so apps can show recent operator actions beside the action center. For HTML or HTMX pages, use `mountVoiceOpsActionHistory(...)` from `@absolutejs/voice/client`.
+
+For HTML or HTMX pages:
+
+```html
+<div id="voice-ops-actions"></div>
+<script type="module">
+	import {
+		createVoiceOpsActionCenterActions,
+		mountVoiceOpsActionCenter
+	} from '@absolutejs/voice/client';
+
+	mountVoiceOpsActionCenter(document.querySelector('#voice-ops-actions'), {
+		actions: createVoiceOpsActionCenterActions({
+			providers: ['deepgram']
+		})
+	});
+</script>
+```
 
 ## Voice Assistants
 
@@ -212,7 +1045,34 @@ const billingAgent = createVoiceAgent({
 const frontDesk = createVoiceAgentSquad({
 	id: 'front-desk',
 	defaultAgentId: 'support',
-	agents: [supportAgent, billingAgent]
+	agents: [supportAgent, billingAgent],
+	contextPolicy: ({ summaryMessage, turn }) => ({
+		messages: [
+			summaryMessage,
+			{
+				content: turn.text,
+				role: 'user'
+			}
+		],
+		metadata: {
+			contextPolicy: 'handoff-summary-and-current-turn'
+		},
+		system: 'Use only the handoff summary and current caller turn.'
+	}),
+	handoffPolicy: ({ handoff }) => {
+		if (handoff.targetAgentId === 'billing') {
+			return {
+				summary: 'Route verified billing requests to the billing specialist.',
+				metadata: { queue: 'billing' }
+			};
+		}
+
+		return {
+			allow: false,
+			reason: `No approved route for ${handoff.targetAgentId}.`,
+			escalate: { reason: 'unsupported-specialist' }
+		};
+	}
 });
 
 voice({
@@ -226,6 +1086,60 @@ voice({
 
 `createVoiceAgentSquad(...)` gives you squad-style specialization without locking your app into a hosted voice platform. An agent can return `handoff: { targetAgentId: 'billing' }`; the squad records the handoff, runs the target agent on the same turn, and still returns a standard `VoiceRouteResult`.
 
+For production call centers, pass `handoffPolicy` to keep routing code-owned instead of dashboard-owned. The policy can allow a handoff, reroute it to a different specialist, merge handoff metadata, summarize the reason for the target agent, or block the handoff and return an escalation. Squad traces mark each handoff as `allowed`, `blocked`, `unknown-target`, or `max-exceeded`, so support teams can audit why a caller moved between specialists.
+
+Pass `contextPolicy` when a specialist should receive a controlled context window. The default behavior preserves the accumulated conversation plus a system handoff summary. A context policy can trim that to a handoff summary and current turn, add a specialist-specific system prompt, or attach metadata that appears in the returned squad state. This is the code-owned equivalent of Vapi Squads context controls: the app decides what each specialist sees, and `agent.context` traces show whether default or custom context was applied.
+
+Each specialist owns its own `tools`, so tool permissions stay explicit per agent. For example, support can have `lookup_order`, billing can have `refund_invoice`, and scheduling can have `book_appointment`. The squad only routes; it does not give every specialist every tool by default.
+
+Use `runVoiceAgentSquadContract(...)` in tests or readiness checks when you need proof that a specialist graph still routes correctly:
+
+```ts
+import {
+	createVoiceMemoryTraceEventStore,
+	runVoiceAgentSquadContract
+} from '@absolutejs/voice';
+
+const trace = createVoiceMemoryTraceEventStore();
+const frontDesk = createVoiceAgentSquad({
+	id: 'front-desk',
+	defaultAgentId: 'support',
+	agents: [supportAgent, billingAgent],
+	trace
+});
+
+const report = await runVoiceAgentSquadContract({
+	context: {},
+	squad: frontDesk,
+	trace,
+	contract: {
+		id: 'billing-route',
+		scenarioId: 'billing-route',
+		turns: [
+			{
+				text: 'I have a billing question.',
+				expect: {
+					finalAgentId: 'billing',
+					outcome: 'assistant',
+					assistantIncludes: ['billing'],
+					handoffs: [
+						{
+							fromAgentId: 'support',
+							targetAgentId: 'billing',
+							status: 'allowed'
+						}
+					]
+				}
+			}
+		]
+	}
+});
+
+if (!report.pass) {
+	throw new Error(report.issues.map((issue) => issue.message).join('\n'));
+}
+```
+
 ## Traces And Replay
 
 Use trace stores when you want every call to be inspectable outside a hosted platform. Trace events are append-only records for model passes, tool calls, handoffs, agent results, call lifecycle, turn timing, errors, and cost telemetry.
@@ -233,13 +1147,22 @@ Use trace stores when you want every call to be inspectable outside a hosted pla
 ```ts
 import {
 	buildVoiceTraceReplay,
+	buildVoiceAuditExport,
+	createVoiceAuditHTTPSink,
+	createVoiceAuditLogger,
+	createVoiceAuditSinkDeliveryWorker,
+	createVoiceAuditSinkStore,
+	createVoiceAuditTrailRoutes,
 	createVoiceAgent,
 	createVoiceFileRuntimeStorage,
 	createVoiceRedisTaskLeaseCoordinator,
+	createVoiceTraceDeliveryRoutes,
 	createVoiceTraceHTTPSink,
 	createVoiceTraceSinkStore,
 	createVoiceTraceSinkDeliveryWorker,
+	buildVoiceDataRetentionPlan,
 	exportVoiceTrace,
+	applyVoiceDataRetentionPolicy,
 	pruneVoiceTraceEvents,
 	voice
 } from '@absolutejs/voice';
@@ -251,6 +1174,30 @@ const runtimeStorage = createVoiceFileRuntimeStorage({
 const redisLeases = createVoiceRedisTaskLeaseCoordinator({
 	url: process.env.REDIS_URL
 });
+const auditStore = createVoiceAuditSinkStore({
+	store: runtimeStorage.audit,
+	deliveryQueue: runtimeStorage.auditDeliveries,
+	sinks: [
+		createVoiceAuditHTTPSink({
+			id: 'security-warehouse',
+			signingSecret: process.env.VOICE_AUDIT_SINK_SECRET,
+			url: process.env.VOICE_AUDIT_SINK_URL!
+		})
+	]
+});
+const audit = createVoiceAuditLogger(auditStore);
+const auditSinkWorker = createVoiceAuditSinkDeliveryWorker({
+	deliveries: runtimeStorage.auditDeliveries,
+	leases: redisLeases,
+	sinks: [
+		createVoiceAuditHTTPSink({
+			id: 'security-warehouse',
+			signingSecret: process.env.VOICE_AUDIT_SINK_SECRET,
+			url: process.env.VOICE_AUDIT_SINK_URL!
+		})
+	],
+	workerId: 'audit-sink-worker'
+});
 const trace = createVoiceTraceSinkStore({
 	store: runtimeStorage.traces,
 	deliveryQueue: runtimeStorage.traceDeliveries,
@@ -277,6 +1224,9 @@ const traceSinkWorker = createVoiceTraceSinkDeliveryWorker({
 
 const supportAgent = createVoiceAgent({
 	id: 'support',
+	audit,
+	auditProvider: 'openai',
+	auditModel: 'gpt-4.1',
 	trace,
 	model: {
 		async generate() {
@@ -293,6 +1243,17 @@ voice({
 	onTurn: supportAgent.onTurn,
 	onComplete: async () => {}
 });
+app.use(
+	createVoiceAuditTrailRoutes({
+		store: runtimeStorage.audit
+	})
+);
+app.use(
+	createVoiceTraceDeliveryRoutes({
+		store: runtimeStorage.traceDeliveries,
+		worker: traceSinkWorker
+	})
+);
 
 const replay = await exportVoiceTrace({
 	store: runtimeStorage.traces,
@@ -314,18 +1275,152 @@ await pruneVoiceTraceEvents({
 	store: runtimeStorage.traces,
 	before: Date.now() - 30 * 24 * 60 * 60 * 1000
 });
+
+await audit.operatorAction({
+	action: 'review.approve',
+	actor: { id: 'operator-123', kind: 'operator' },
+	resource: { id: 'review-123', type: 'review' }
+});
 ```
 
 `createVoiceMemoryTraceEventStore(...)`, `createVoiceFileTraceEventStore(...)`, `createVoiceSQLiteTraceEventStore(...)`, and `createVoicePostgresTraceEventStore(...)` all implement the same `VoiceTraceEventStore` contract. File, SQLite, and Postgres runtime storage expose `runtimeStorage.traces` and `runtimeStorage.traceDeliveries` alongside sessions, reviews, tasks, events, and external object mappings. Passing `trace` to `voice(...)` records session lifecycle, transcript, committed-turn, assistant, cost, and error events; passing it to agents records model passes, tools, results, and handoffs.
 
 For self-hosted QA and support workflows, use `summarizeVoiceTrace(...)`, `evaluateVoiceTrace(...)`, `renderVoiceTraceMarkdown(...)`, `renderVoiceTraceHTML(...)`, or `buildVoiceTraceReplay(...)`. They turn raw trace events into portable artifacts you can attach to tickets, inspect locally, or fail in CI when a call has missing transcripts, missing turns, tool errors, session errors, or excessive handoffs.
 
-For observability pipelines, wrap any trace store with `createVoiceTraceSinkStore(...)` and pass sinks such as `createVoiceTraceHTTPSink(...)`. The wrapper still writes to your normal file, SQLite, or Postgres store, then fans out appended events to your warehouse, logs, S3 bridge, or analytics endpoint. Use `awaitDelivery: true` only when you want trace delivery to block append completion. For durable delivery, pass `deliveryQueue` and run `createVoiceTraceSinkDeliveryWorker(...)` or `createVoiceTraceSinkDeliveryWorkerLoop(...)`; the worker uses the same Redis lease/idempotency primitives as ops workers and supports retries plus dead-letter stores.
+For observability pipelines, wrap any trace store with `createVoiceTraceSinkStore(...)` and pass sinks such as `createVoiceTraceHTTPSink(...)`. The wrapper still writes to your normal file, SQLite, or Postgres store, then fans out appended events to your warehouse, logs, S3 bridge, or analytics endpoint. Use `awaitDelivery: true` only when you want trace delivery to block append completion. For durable delivery, pass `deliveryQueue` and run `createVoiceTraceSinkDeliveryWorker(...)` or `createVoiceTraceSinkDeliveryWorkerLoop(...)`; the worker uses the same Redis lease/idempotency primitives as ops workers and supports retries plus dead-letter stores. Mount `createVoiceTraceDeliveryRoutes({ store: runtimeStorage.traceDeliveries, worker })` to expose `/traces/deliveries`, `/api/voice-trace-deliveries`, and an explicit `POST /api/voice-trace-deliveries/drain` retry path.
 
 When traces may leave your private runtime, pass `redact: true` or a redaction config to `exportVoiceTrace(...)`, `renderVoiceTraceMarkdown(...)`, `renderVoiceTraceHTML(...)`, or `buildVoiceTraceReplay(...)`. The built-in redactor scrubs common email addresses, phone numbers, and sensitive keys like `token`, `secret`, `password`, `apiKey`, `authorization`, `phone`, and `email`; you can pass custom keys or replacement text for stricter policies.
 
 For retention jobs, `pruneVoiceTraceEvents(...)` works against any trace store. Use `dryRun: true` before deleting, filter by session, trace, scenario, turn, or event type, cap each run with `limit`, or keep only the newest N matching events with `keepNewest`.
 
+For whole-runtime data control, use `buildVoiceDataRetentionPlan(...)` first and then `applyVoiceDataRetentionPolicy(...)` when the deletion set is correct. The policy works across stores exposed by file, SQLite, or Postgres runtime storage, including sessions, traces, trace deliveries, audit deliveries, reviews, ops tasks, integration events, and campaigns. A cutoff or per-scope `keepNewest` selector is required before anything is deleted, so an empty policy reports skipped scopes instead of wiping data.
+
+```ts
+const plan = await buildVoiceDataRetentionPlan({
+	before: Date.now() - 30 * 24 * 60 * 60 * 1000,
+	...runtimeStorage
+});
+
+console.log(plan.scopes);
+
+await applyVoiceDataRetentionPolicy({
+	audit: runtimeStorage.audit,
+	before: Date.now() - 30 * 24 * 60 * 60 * 1000,
+	...runtimeStorage
+});
+```
+
+For a compliance-facing control surface, mount `createVoiceDataControlRoutes(...)`. It packages the same primitives into a self-hosted report for customer-owned storage, retention dry-runs, guarded deletion, redacted audit export, zero-retention mode, and provider-key handling.
+
+```ts
+import {
+	createVoiceDataControlRoutes,
+	createVoiceZeroRetentionPolicy,
+	voiceComplianceRedactionDefaults
+} from '@absolutejs/voice';
+
+app.use(
+	createVoiceDataControlRoutes({
+		...runtimeStorage,
+		audit: runtimeStorage.audit,
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		path: '/data-control',
+		redact: voiceComplianceRedactionDefaults,
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+
+const zeroRetentionPlan = await buildVoiceDataRetentionPlan(
+	createVoiceZeroRetentionPolicy({
+		...runtimeStorage,
+		audit: runtimeStorage.audit,
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+```
+
+Mounted routes:
+
+- `GET /data-control`: HTML compliance/data-control report.
+- `GET /data-control.json`: JSON report with redaction, storage, retention plan, audit export, and provider-key recommendations.
+- `GET /data-control.md`: Markdown report for release/security reviews.
+- `POST /data-control/retention/plan`: dry-run deletion proof from a JSON policy body.
+- `POST /data-control/retention/apply`: applies retention only when the body includes `confirm: "apply-retention-policy"`.
+- `GET /data-control/audit.json`, `/data-control/audit.md`, `/data-control/audit.html`: redacted audit exports.
+
+`createVoiceZeroRetentionPolicy(...)` intentionally defaults to `dryRun: true`; callers must explicitly apply the generated policy after reviewing the deletion proof. This gives compliance-sensitive deployments a concrete zero-retention recipe without making accidental deletion easy.
+
+Use `createVoiceAuditLogger(...)` when you need append-only compliance evidence outside call traces. The logger records provider calls, tool calls, handoffs, retention runs, and operator actions into `runtimeStorage.audit`, so self-hosted teams can prove who changed what, which provider ran, which tool fired, and what data-control policy deleted.
+
+Pass `audit` directly to `createVoiceAgent(...)` to record model calls as provider-call audit events and tool executions as tool-call audit events. Pass it to `createVoiceAgentSquad(...)` to record squad handoffs automatically. Use `auditProvider` and `auditModel` on agents when you want readiness and compliance reports to show the actual model provider instead of the agent id.
+
+For compliance pipelines, wrap any audit store with `createVoiceAuditSinkStore(...)` and pass sinks such as `createVoiceAuditHTTPSink(...)`. Audit sinks redact by default, support HMAC signing, retries, event-type filters, optional blocking delivery, durable delivery queues through `runtimeStorage.auditDeliveries`, and background workers through `createVoiceAuditSinkDeliveryWorker(...)` or `createVoiceAuditSinkDeliveryWorkerLoop(...)`. File, SQLite, and Postgres runtime storage all expose `auditDeliveries`, so teams can ship evidence to a SIEM, warehouse, or internal security service without a hosted dashboard. Mount `createVoiceAuditDeliveryRoutes({ store: runtimeStorage.auditDeliveries, worker })` to expose `/audit/deliveries`, `/api/voice-audit-deliveries`, and an explicit `POST /api/voice-audit-deliveries/drain` retry path.
+
+Pass `audit: runtimeStorage.audit` into production readiness when audit coverage should block deploys. By default readiness requires provider-call, retention-policy, and operator-action audit evidence; retention-policy evidence must be from the last 7 days so a stale one-time audit event does not certify an active retention job. Override required event types or freshness with `audit: { store: runtimeStorage.audit, require: [{ type: 'retention.policy', maxAgeMs: ... }] }` when a deployment has different compliance gates. Pass `auditDeliveries: runtimeStorage.auditDeliveries` and `traceDeliveries: runtimeStorage.traceDeliveries` when sink export health should also block deploys; failed or dead-lettered deliveries fail readiness, pending deliveries warn, and pending deliveries older than the configured fail window fail readiness.
+
+Mount `createVoiceAuditTrailRoutes(...)` to expose `/api/voice-audit` and `/audit` over the same store. File, SQLite, and Postgres runtime storage all expose `runtimeStorage.audit`. The JSON and HTML surfaces support filters like `type`, `outcome`, `actorId`, `resourceType`, `resourceId`, `sessionId`, `traceId`, and `limit`, so operators can search audit evidence without writing a custom viewer first.
+
+Use `exportVoiceAuditTrail(...)` or `buildVoiceAuditExport(...)` when audit evidence needs to leave the app. Pass `redact: true` to scrub sensitive keys plus common email and phone patterns from payloads and metadata before generating JSON, Markdown, or HTML. Audit trail routes also expose redacted exports at `/api/voice-audit/export`, `/api/voice-audit/export?format=markdown`, `/api/voice-audit/export?format=html`, and `/audit/export`; export routes redact by default unless `redact=false` is passed.
+
+## Operations Records And Recovery
+
+Use operations records as the default support/debug entrypoint. A hosted platform would send an operator to a call log; AbsoluteJS Voice gives the same workflow as a code-owned route:
+
+```ts
+app.use(
+	createVoiceOperationsRecordRoutes({
+		audit: runtimeStorage.audit,
+		htmlPath: '/voice-operations/:sessionId',
+		path: '/api/voice-operations/:sessionId',
+		store: runtimeStorage.traces
+	})
+);
+```
+
+`createVoiceOperationsRecordRoutes(...)` links the call/session timeline, replay, provider events, tools, handoffs, audit, reviews, ops tasks, integration events, and sink delivery attempts into one debuggable object. Use `/voice-operations/:sessionId` as the first place to investigate failed calls, provider failures, handoff failures, slow turns, and campaign attempts.
+
+Mount `createVoiceOpsRecoveryRoutes(...)` beside it when operators need one deploy-checkable recovery signal:
+
+```ts
+app.use(
+	createVoiceOpsRecoveryRoutes({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		handoffDeliveries,
+		links: {
+			operationsRecords: '/voice-operations/:sessionId',
+			traceDeliveries: '/traces/deliveries'
+		},
+		traceDeliveries: runtimeStorage.traceDeliveries,
+		traces: runtimeStorage.traces
+	})
+);
+```
+
+The recovery report summarizes recovered provider fallback, unresolved provider failures, audit/trace delivery backlog, handoff delivery backlog, operator interventions, failed sessions, and latency SLO issues. When `operationsRecords` is configured, provider and latency recovery issues link directly to the impacted operations record instead of a generic dashboard.
+
+Pass the same report into production readiness to make recovery issues a deploy gate:
+
+```ts
+const opsRecovery = await buildVoiceOpsRecoveryReport({
+	links: { operationsRecords: '/voice-operations/:sessionId' },
+	traces: runtimeStorage.traces
+});
+
+app.use(
+	createVoiceProductionReadinessRoutes({
+		links: {
+			operationsRecords: '/voice-operations/:sessionId',
+			opsRecovery: '/ops-recovery'
+		},
+		opsRecovery,
+		store: runtimeStorage.traces
+	})
+);
+```
+
+Readiness emits the stable `voice.readiness.ops_recovery` gate code when unresolved recovery issues remain.
+
 ## Production Voice Ops
 
 The recommended production pattern is:
@@ -733,6 +1828,59 @@ app.use(
 
 Client state now exposes `assistantAudio` on the stream/controller helpers, so apps can buffer or play synthesized chunks without inventing a second transport.
 
+## OpenAI Realtime
+
+Use `createOpenAIRealtimeAdapter(...)` when you want a direct OpenAI Realtime speech-to-speech output path for live smoke tests, duplex benchmarks, or custom realtime orchestration. It implements the same `RealtimeAdapter` contract used by the benchmark harness, so the provider can stream `response.output_audio.delta` audio chunks into AbsoluteJS voice events while still emitting normalized transcript, error, and close events.
+
+```ts
+import { createOpenAIRealtimeAdapter } from '@absolutejs/voice';
+import { runTTSAdapterFixture } from '@absolutejs/voice/testing';
+
+const realtime = createOpenAIRealtimeAdapter({
+	apiKey: process.env.OPENAI_API_KEY!,
+	instructions: 'Answer in one concise sentence.',
+	model: 'gpt-realtime',
+	voice: 'marin'
+});
+
+app.use(
+	voice({
+		path: '/voice',
+		realtime,
+		realtimeInputFormat: {
+			channels: 1,
+			container: 'raw',
+			encoding: 'pcm_s16le',
+			sampleRateHz: 24000
+		},
+		session,
+		onTurn: async ({ turn }) => ({
+			assistantText: `You said: ${turn.text}`
+		}),
+		onComplete: async () => {}
+	})
+);
+
+const report = await runTTSAdapterFixture(
+	realtime,
+	{
+		id: 'openai-realtime-smoke',
+		text: 'Say exactly: AbsoluteJS realtime is online.',
+		title: 'OpenAI Realtime smoke'
+	},
+	{
+		realtimeFormat: {
+			channels: 1,
+			container: 'raw',
+			encoding: 'pcm_s16le',
+			sampleRateHz: 24000
+		}
+	}
+);
+```
+
+For server-to-server use, the adapter opens a WebSocket to OpenAI, sends `session.update`, streams text or base64 PCM input, and emits raw 24kHz mono `pcm_s16le` assistant audio. It requires raw 24kHz mono PCM input because that is the OpenAI Realtime PCM format. The main `voice(...)` route can now run in cascaded mode with `stt` plus optional `tts`, or direct realtime mode with `realtime`. Browser demos should make sure the captured PCM format matches `realtimeInputFormat` or resample before sending audio.
+
 If you want a minimal browser playback path, use the client audio player:
 
 ```ts
@@ -1069,6 +2217,176 @@ app.use(
   - `benchmark-results/sessions-cheap-stt-runs-3.json`
   - `benchmark-results/stt-routing-run-manifest.json`
 
+## LLM Provider Routing
+
+Use `createVoiceProviderRouter(...)` when your assistant can run on more than one LLM provider. The router keeps provider choice inside your app: you define the available model adapters, profile each provider, and choose a policy.
+
+```ts
+import {
+	createAnthropicVoiceAssistantModel,
+	createGeminiVoiceAssistantModel,
+	createOpenAIVoiceAssistantModel,
+	createVoiceProviderRouter,
+	resolveVoiceProviderRoutingPolicyPreset
+} from '@absolutejs/voice';
+
+const model = createVoiceProviderRouter({
+	providers: {
+		openai: createOpenAIVoiceAssistantModel({ apiKey: process.env.OPENAI_API_KEY! }),
+		anthropic: createAnthropicVoiceAssistantModel({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+		gemini: createGeminiVoiceAssistantModel({ apiKey: process.env.GEMINI_API_KEY! })
+	},
+	providerHealth: {
+		failureThreshold: 1,
+		cooldownMs: 30_000,
+		rateLimitCooldownMs: 120_000
+	},
+	providerProfiles: {
+		openai: { cost: 6, latencyMs: 650, quality: 0.92, timeoutMs: 3500 },
+		anthropic: { cost: 7, latencyMs: 850, quality: 0.95, timeoutMs: 4500 },
+		gemini: { cost: 2, latencyMs: 700, quality: 0.86, timeoutMs: 3500 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('balanced')
+});
+```
+
+Built-in policy presets:
+
+- `quality-first`: rank by `providerProfiles[provider].quality`, then priority, latency, and cost.
+- `latency-first`: rank by expected latency.
+- `cost-first`: rank by expected cost.
+- `cost-cap`: rank by cost and reject providers above `maxCost`.
+- `balanced`: weighted score using cost, latency, quality, and priority.
+
+Budget filters are strict. If you pass `maxCost`, `maxLatencyMs`, or `minQuality`, providers outside those limits are removed before ranking, even if they were selected by the request.
+
+```ts
+const policy = resolveVoiceProviderRoutingPolicyPreset('cost-cap', {
+	maxCost: 3,
+	minQuality: 0.82
+});
+```
+
+Use `runVoiceProviderRoutingContract(...)` when provider fallback needs to be certified before production. The contract reads provider routing trace events and verifies the expected selected provider, fallback provider, status, and kind in order.
+
+```ts
+import { runVoiceProviderRoutingContract } from '@absolutejs/voice';
+
+const report = await runVoiceProviderRoutingContract({
+	store: runtime.traces,
+	contract: {
+		id: 'openai-to-anthropic-fallback',
+		expect: [
+			{
+				kind: 'llm',
+				provider: 'openai',
+				selectedProvider: 'openai',
+				fallbackProvider: 'anthropic',
+				status: 'error'
+			},
+			{
+				kind: 'llm',
+				provider: 'anthropic',
+				selectedProvider: 'openai',
+				status: 'fallback'
+			}
+		]
+	}
+});
+
+if (!report.pass) {
+	throw new Error(report.issues.map((issue) => issue.message).join('\n'));
+}
+```
+
+Pass provider routing contract reports into production readiness through `providerRoutingContracts`. Readiness fails when a fallback contract fails, so model-routing regressions become deploy blockers instead of dashboard-only surprises.
+
+Use `createVoiceProviderContractMatrixPreset(...)` when you want readiness proof for the whole provider stack without hand-writing every LLM, STT, and TTS contract row. The preset stays primitive: you still own provider lists, selected providers, latency budgets, env, capabilities, and route mounting.
+
+```ts
+import {
+	buildVoiceProviderContractMatrix,
+	createVoiceProviderContractMatrixPreset,
+	createVoiceProviderContractMatrixRoutes
+} from '@absolutejs/voice';
+
+const providerContracts = () =>
+	createVoiceProviderContractMatrixPreset('phone-agent', {
+		env: process.env,
+		providers: {
+			llm: ['openai', 'anthropic', 'gemini'],
+			stt: ['deepgram', 'assemblyai'],
+			tts: ['openai', 'emergency']
+		},
+		selected: {
+			llm: 'openai',
+			stt: 'deepgram',
+			tts: 'openai'
+		},
+		latencyBudgets: {
+			openai: 900,
+			deepgram: 250,
+			assemblyai: 900,
+			emergency: 80
+		},
+		remediationHref: '/provider-contracts'
+	});
+
+const app = createVoiceProviderContractMatrixRoutes({
+	htmlPath: '/provider-contracts',
+	path: '/api/provider-contracts',
+	load: () => buildVoiceProviderContractMatrix(providerContracts())
+});
+```
+
+The preset maps common provider names to env checks, streaming defaults, fallback rows, and profile-required capabilities. Override `configured`, `capabilities`, `fallbackProviders`, or `streaming` whenever your deployment uses custom adapters or local fallbacks.
+
+For full control, pass an object policy:
+
+```ts
+const model = createVoiceProviderRouter({
+	providers,
+	providerProfiles,
+	policy: {
+		strategy: 'balanced',
+		maxLatencyMs: 1000,
+		weights: { cost: 1, latencyMs: 0.004, quality: 12 }
+	}
+});
+```
+
+The same profile and policy shape also works for STT and TTS provider routers, so a self-hosted app can choose the fastest provider for live calls, cap cost for background work, or require a minimum quality score without hard-coding provider branches.
+
+```ts
+const stt = createVoiceSTTProviderRouter({
+	adapters: {
+		deepgram,
+		assemblyai
+	},
+	providerHealth: { cooldownMs: 30_000 },
+	providerProfiles: {
+		deepgram: { cost: 4, latencyMs: 180, quality: 0.93, timeoutMs: 1500 },
+		assemblyai: { cost: 2, latencyMs: 650, quality: 0.88, timeoutMs: 3000 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('latency-first')
+});
+
+const tts = createVoiceTTSProviderRouter({
+	adapters: {
+		elevenlabs,
+		openai
+	},
+	providerProfiles: {
+		elevenlabs: { cost: 5, latencyMs: 220, quality: 0.94 },
+		openai: { cost: 2, latencyMs: 320, quality: 0.87 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('cost-cap', {
+		maxCost: 3,
+		minQuality: 0.85
+	})
+});
+```
+
 ## Presets
 
 Voice now ships named runtime presets so apps can start from a useful baseline instead of hand-tuning silence and capture settings every time.
@@ -1566,6 +2884,8 @@ Default reconnect strategy is `resume-last-turn`.
 
 If an adapter does not emit native end-of-turn events, core falls back to silence detection with a default `700ms` threshold.
 
+For browser/client proof, use `runVoiceReconnectContract(...)` or mount `createVoiceReconnectContractRoutes(...)` with captured reconnect snapshots. The contract verifies that a reconnect was observed, the stream resumed before exhaustion, and replayed state did not duplicate committed turn IDs.
+
 ## STT Fallback
 
 You can pair a primary vendor with an optional fallback vendor per route when you need extra reliability for accents, edge environments, or short commands.