@absolutejs/voice 0.0.22-beta.355 → 0.0.22-beta.357

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-export type VoiceAuditEventType = 'handoff' | 'operator.action' | 'provider.call' | 'retention.policy' | 'tool.call';
+export type VoiceAuditEventType = 'handoff' | 'operator.action' | 'profile.switch' | 'provider.call' | 'retention.policy' | 'tool.call';
 export type VoiceAuditActor = {
     id: string;
     kind: 'agent' | 'operator' | 'system' | 'worker';

package/dist/index.d.ts

@@ -31,8 +31,8 @@ export { assertVoiceCompetitiveCoverage, buildVoiceCompetitiveCoverageReport, cr
 export type { VoiceCompetitiveCoverageAssertionInput, VoiceCompetitiveCoverageAssertionReport, VoiceCompetitiveCoverageIssue, VoiceCompetitiveCoverageLevel, VoiceCompetitiveCoverageReport, VoiceCompetitiveCoverageReportInput, VoiceCompetitiveCoverageRoutesOptions, VoiceCompetitiveCoverageStatus, VoiceCompetitiveCoverageSummary, VoiceCompetitiveDepthLevel, VoiceCompetitiveEvidence, VoiceCompetitiveSurface } from './competitiveCoverage';
 export type { VoicePlatformCoverageAssertionInput, VoicePlatformCoverageAssertionReport, VoicePlatformCoverageEvidence, VoicePlatformCoverageRoutesOptions, VoicePlatformCoverageStatus, VoicePlatformCoverageSummary, VoicePlatformCoverageSummaryInput, VoicePlatformCoverageSurface } from './platformCoverage';
 export { assertVoiceProofTrendEvidence, buildEmptyVoiceProofTrendReport, buildVoiceProofTrendProfileSummaries, buildVoiceProofTrendRecommendationReport, buildVoiceProofTrendReportFromRealCallProfiles, buildVoiceProofTrendReport, buildVoiceRealCallProfileDefaults, buildVoiceRealCallProfileHistoryReport, createVoiceProofTrendRecommendationRoutes, createVoiceProofTrendRoutes, createVoiceRealCallProfileHistoryRoutes, DEFAULT_VOICE_PROOF_TREND_PROFILE_DEFINITIONS, DEFAULT_VOICE_PROOF_TRENDS_MAX_AGE_MS, evaluateVoiceProofTrendEvidence, formatVoiceProofTrendAge, normalizeVoiceProofTrendReport, readVoiceProofTrendReportFile, renderVoiceProofTrendRecommendationHTML, renderVoiceProofTrendRecommendationMarkdown, renderVoiceRealCallProfileHistoryHTML, renderVoiceRealCallProfileHistoryMarkdown, resolveVoiceRealCallProfileProviderRoute } from './proofTrends';
-export { recommendVoiceProfileSwitch } from './profileSwitchRecommendation';
-export type { VoiceProfileSwitchObservedSignals, VoiceProfileSwitchRecommendation, VoiceProfileSwitchRecommendationOptions } from './profileSwitchRecommendation';
+export { applyVoiceProfileSwitchGuard, recommendVoiceProfileSwitch } from './profileSwitchRecommendation';
+export type { VoiceProfileSwitchGuardAction, VoiceProfileSwitchGuardDecision, VoiceProfileSwitchGuardMode, VoiceProfileSwitchGuardOptions, VoiceProfileSwitchObservedSignals, VoiceProfileSwitchRecommendation, VoiceProfileSwitchRecommendationOptions } from './profileSwitchRecommendation';
 export { buildVoiceProviderDecisionTraceReport, createVoiceProviderDecisionTraceEvent, createVoiceProviderDecisionTraceRoutes, listVoiceProviderDecisionTraces, renderVoiceProviderDecisionTraceHTML, renderVoiceProviderDecisionTraceMarkdown } from './providerDecisionTraces';
 export type { VoiceProviderDecisionStatus, VoiceProviderDecisionSurfaceReport, VoiceProviderDecisionTrace, VoiceProviderDecisionTraceInput, VoiceProviderDecisionTraceIssue, VoiceProviderDecisionTraceReport, VoiceProviderDecisionTraceReportOptions, VoiceProviderDecisionTraceRoutesOptions } from './providerDecisionTraces';
 export type { VoiceProofTrendAssertionInput, VoiceProofTrendAssertionReport, VoiceProofTrendCycle, VoiceProofTrendProfileDefinition, VoiceProofTrendProfileRecommendation, VoiceProofTrendProfileSummaryOptions, VoiceProofTrendProfileSummary, VoiceProofTrendProviderRecommendation, VoiceProofTrendProviderSummary, VoiceProofTrendRecommendation, VoiceProofTrendRecommendationOptions, VoiceProofTrendRecommendationReport, VoiceProofTrendRecommendationRoutesOptions, VoiceProofTrendRecommendationStatus, VoiceProofTrendRecommendationSurface, VoiceProofTrendRealCallProfileEvidence, VoiceProofTrendRealCallProfileReportOptions, VoiceProofTrendReport, VoiceProofTrendReportInput, VoiceProofTrendRoutesOptions, VoiceProofTrendRuntimeChannelSummary, VoiceProofTrendStatus, VoiceProofTrendSummary, VoiceRealCallProfileDefault, VoiceRealCallProfileDefaultsOptions, VoiceRealCallProfileDefaultsReport, VoiceRealCallProfileHistoryOptions, VoiceRealCallProfileHistoryReport, VoiceRealCallProfileHistoryRoutesOptions, VoiceRealCallProfileProviderRouteOptions } from './proofTrends';

package/dist/index.js

@@ -4994,6 +4994,12 @@ var createVoiceSession = (options) => {
     if (options.scenarioId && session.scenarioId !== options.scenarioId) {
       session.scenarioId = options.scenarioId;
     }
+    if (options.sessionMetadata) {
+      session.metadata = {
+        ...session.metadata && typeof session.metadata === "object" ? session.metadata : {},
+        ...options.sessionMetadata
+      };
+    }
     ensureCommittedTurnGuard(session);
     let shouldFireOnSession = !existingSession;
     if (existingSession?.scenarioId && options.scenarioId && existingSession.scenarioId !== options.scenarioId) {
@@ -5200,6 +5206,319 @@ var createVoiceSession = (options) => {
   return api;
 };
 
+// src/audit.ts
+var includes = (filter, value) => {
+  if (!filter) {
+    return true;
+  }
+  if (!value) {
+    return false;
+  }
+  return Array.isArray(filter) ? filter.includes(value) : filter === value;
+};
+var createVoiceAuditEvent = (event) => ({
+  ...event,
+  at: event.at ?? Date.now(),
+  id: event.id ?? crypto.randomUUID()
+});
+var filterVoiceAuditEvents = (events, filter = {}) => {
+  const sorted = events.filter((event) => {
+    if (!includes(filter.type, event.type)) {
+      return false;
+    }
+    if (!includes(filter.outcome, event.outcome)) {
+      return false;
+    }
+    if (filter.actorId && event.actor?.id !== filter.actorId) {
+      return false;
+    }
+    if (filter.resourceId && event.resource?.id !== filter.resourceId) {
+      return false;
+    }
+    if (filter.resourceType && event.resource?.type !== filter.resourceType) {
+      return false;
+    }
+    if (filter.sessionId && event.sessionId !== filter.sessionId) {
+      return false;
+    }
+    if (filter.traceId && event.traceId !== filter.traceId) {
+      return false;
+    }
+    if (typeof filter.after === "number" && event.at <= filter.after) {
+      return false;
+    }
+    if (typeof filter.afterOrAt === "number" && event.at < filter.afterOrAt) {
+      return false;
+    }
+    if (typeof filter.before === "number" && event.at >= filter.before) {
+      return false;
+    }
+    if (typeof filter.beforeOrAt === "number" && event.at > filter.beforeOrAt) {
+      return false;
+    }
+    return true;
+  }).sort((left, right) => left.at - right.at || left.id.localeCompare(right.id));
+  return typeof filter.limit === "number" && filter.limit >= 0 ? sorted.slice(0, filter.limit) : sorted;
+};
+var createVoiceMemoryAuditEventStore = () => {
+  const events = new Map;
+  return {
+    append: (event) => {
+      const stored = createVoiceAuditEvent(event);
+      events.set(stored.id, stored);
+      return stored;
+    },
+    get: (id) => events.get(id),
+    list: (filter) => filterVoiceAuditEvents([...events.values()], filter)
+  };
+};
+var recordVoiceAuditEvent = (store, event) => store.append(createVoiceAuditEvent(event));
+var recordVoiceProviderAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
+  action: `${input.kind}.provider.call`,
+  actor: input.actor,
+  metadata: input.metadata,
+  outcome: input.outcome,
+  payload: {
+    cost: input.cost,
+    elapsedMs: input.elapsedMs,
+    error: input.error,
+    kind: input.kind,
+    model: input.model,
+    provider: input.provider
+  },
+  resource: {
+    id: input.provider,
+    type: "provider"
+  },
+  sessionId: input.sessionId,
+  traceId: input.traceId,
+  type: "provider.call"
+});
+var recordVoiceToolAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
+  action: "tool.call",
+  actor: input.actor,
+  metadata: input.metadata,
+  outcome: input.outcome,
+  payload: {
+    elapsedMs: input.elapsedMs,
+    error: input.error,
+    toolCallId: input.toolCallId,
+    toolName: input.toolName
+  },
+  resource: {
+    id: input.toolName,
+    type: "tool"
+  },
+  sessionId: input.sessionId,
+  traceId: input.traceId,
+  type: "tool.call"
+});
+var recordVoiceHandoffAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
+  action: "handoff",
+  actor: input.actor,
+  metadata: input.metadata,
+  outcome: input.outcome,
+  payload: {
+    fromAgentId: input.fromAgentId,
+    reason: input.reason,
+    target: input.target,
+    toAgentId: input.toAgentId
+  },
+  resource: {
+    id: input.toAgentId ?? input.target,
+    type: "handoff"
+  },
+  sessionId: input.sessionId,
+  traceId: input.traceId,
+  type: "handoff"
+});
+var recordVoiceRetentionAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
+  action: input.dryRun ? "retention.plan" : "retention.apply",
+  actor: input.actor ?? {
+    id: "voice-retention",
+    kind: "system"
+  },
+  metadata: input.metadata,
+  outcome: "success",
+  payload: {
+    deletedCount: input.report.deletedCount,
+    dryRun: input.dryRun,
+    scopes: input.report.scopes
+  },
+  resource: {
+    type: "retention-policy"
+  },
+  type: "retention.policy"
+});
+var recordVoiceOperatorAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
+  action: input.action,
+  actor: input.actor,
+  metadata: input.metadata,
+  outcome: input.outcome ?? "success",
+  payload: input.payload,
+  resource: input.resource,
+  sessionId: input.sessionId,
+  traceId: input.traceId,
+  type: "operator.action"
+});
+var createVoiceAuditLogger = (store) => ({
+  handoff: (input) => recordVoiceHandoffAuditEvent({ ...input, store }),
+  operatorAction: (input) => recordVoiceOperatorAuditEvent({ ...input, store }),
+  providerCall: (input) => recordVoiceProviderAuditEvent({ ...input, store }),
+  record: (event) => recordVoiceAuditEvent(store, event),
+  retention: (input) => recordVoiceRetentionAuditEvent({ ...input, store }),
+  toolCall: (input) => recordVoiceToolAuditEvent({ ...input, store })
+});
+
+// src/profileSwitchRecommendation.ts
+var readDefaults = (input) => ("defaults" in input) ? input.defaults : input;
+var isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+var exceeds = (observed, budget) => isNumber(observed) && isNumber(budget) && observed > budget;
+var scoreProfile = (profile, observed) => {
+  const evidence = profile.evidence;
+  const live = evidence.liveP95Ms ?? observed.liveP95Ms ?? 0;
+  const provider = evidence.providerP95Ms ?? observed.providerP95Ms ?? 0;
+  const turn = evidence.turnP95Ms ?? observed.turnP95Ms ?? 0;
+  const statusPenalty = profile.status === "pass" ? 0 : profile.status === "warn" ? 1e4 : 25000;
+  const noisyBonus = (observed.fallbackUsed || (observed.turnWarnings ?? 0) > 0) && /noisy|phone/i.test(`${profile.profileId} ${profile.label ?? ""}`) ? -1000 : 0;
+  return live + provider + turn + statusPenalty + noisyBonus;
+};
+var clampConfidence = (value) => Math.max(0, Math.min(0.99, Number(value.toFixed(2))));
+var estimateSwitchConfidence = (recommendation) => {
+  if (!recommendation.ok || recommendation.status !== "switch") {
+    return recommendation.status === "stay" && recommendation.ok ? 0.99 : 0;
+  }
+  const observed = recommendation.observed;
+  const currentStatus = recommendation.currentProfile?.status;
+  const recommendedStatus = recommendation.recommendedProfile?.status;
+  let confidence = 0.58;
+  if (currentStatus && currentStatus !== "pass") {
+    confidence += 0.12;
+  }
+  if (recommendedStatus === "pass") {
+    confidence += 0.1;
+  }
+  if (observed.fallbackUsed) {
+    confidence += 0.08;
+  }
+  if ((observed.turnWarnings ?? 0) > 0) {
+    confidence += 0.08;
+  }
+  if (recommendation.reasons.some((reason) => /budget|strongest measured fit/i.test(reason))) {
+    confidence += 0.08;
+  }
+  return clampConfidence(confidence);
+};
+var recommendVoiceProfileSwitch = (options) => {
+  const defaults = readDefaults(options.defaults);
+  const observed = options.observed ?? {};
+  const currentProfileId = observed.currentProfileId ?? options.defaultProfileId ?? defaults.profiles[0]?.profileId;
+  const currentProfile = defaults.profiles.find((profile) => profile.profileId === currentProfileId);
+  const candidates = defaults.profiles.filter((profile) => profile.status !== "fail");
+  const recommended = candidates.slice().sort((left, right) => scoreProfile(left, observed) - scoreProfile(right, observed))[0];
+  const issues = [
+    ...defaults.profiles.length === 0 ? ["No measured profile defaults are available."] : [],
+    ...!currentProfile && currentProfileId ? [`Current profile ${currentProfileId} is not present in measured defaults.`] : [],
+    ...!recommended ? ["No non-failing measured profile can be recommended."] : []
+  ];
+  const currentOverBudget = currentProfile ? [
+    exceeds(observed.liveP95Ms, currentProfile.latencyBudgets.maxLiveP95Ms) ? "live p95 exceeds this profile budget" : undefined,
+    exceeds(observed.providerP95Ms, currentProfile.latencyBudgets.maxProviderP95Ms) ? "provider p95 exceeds this profile budget" : undefined,
+    exceeds(observed.turnP95Ms, currentProfile.latencyBudgets.maxTurnP95Ms) ? "turn p95 exceeds this profile budget" : undefined
+  ].filter((reason) => Boolean(reason)) : [];
+  const minImprovementMs = options.minImprovementMs ?? 250;
+  const currentScore = currentProfile ? scoreProfile(currentProfile, observed) : Number.POSITIVE_INFINITY;
+  const recommendedScore = recommended ? scoreProfile(recommended, observed) : Number.POSITIVE_INFINITY;
+  const shouldSwitch = Boolean(recommended) && recommended?.profileId !== currentProfile?.profileId && (!currentProfile || currentProfile.status !== "pass" || currentOverBudget.length > 0 || currentScore - recommendedScore >= minImprovementMs);
+  const reasons = [
+    ...currentOverBudget,
+    ...currentProfile?.status && currentProfile.status !== "pass" ? [`current profile is ${currentProfile.status}`] : [],
+    ...observed.fallbackUsed ? ["current session used provider fallback"] : [],
+    ...(observed.turnWarnings ?? 0) > 0 ? [`${observed.turnWarnings} turn quality warning(s) observed`] : [],
+    ...shouldSwitch && recommended ? [
+      `${recommended.label ?? recommended.profileId} has the strongest measured fit for these signals`
+    ] : []
+  ];
+  return {
+    currentProfile: currentProfile ? {
+      label: currentProfile.label,
+      profileId: currentProfile.profileId,
+      status: currentProfile.status
+    } : undefined,
+    generatedAt: new Date().toISOString(),
+    issues,
+    nextMove: issues.length > 0 ? "Collect fresh real-call profile evidence before switching automatically." : shouldSwitch && recommended ? `Switch to ${recommended.label ?? recommended.profileId} for this session profile.` : "Keep the current measured profile unless new session evidence drifts.",
+    ok: issues.length === 0,
+    observed,
+    reasons: reasons.length > 0 ? reasons : ["current profile matches measured defaults and observed budgets"],
+    recommendedProfile: recommended ? {
+      evidence: recommended.evidence,
+      label: recommended.label,
+      latencyBudgets: recommended.latencyBudgets,
+      profileId: recommended.profileId,
+      providerRoutes: recommended.providerRoutes,
+      status: recommended.status
+    } : undefined,
+    status: issues.length > 0 ? "warn" : shouldSwitch ? "switch" : "stay"
+  };
+};
+var applyVoiceProfileSwitchGuard = async (options) => {
+  const mode = options.mode ?? "recommend";
+  const minConfidence = options.minConfidence ?? 0.75;
+  const recommendation = recommendVoiceProfileSwitch(options);
+  const confidence = estimateSwitchConfidence(recommendation);
+  const previousProfileId = recommendation.currentProfile?.profileId;
+  const recommendedProfileId = recommendation.recommendedProfile?.profileId;
+  const canSwitch = recommendation.status === "switch" && recommendation.ok && Boolean(recommendedProfileId) && confidence >= minConfidence;
+  const action = recommendation.status === "stay" ? "stay" : canSwitch ? mode === "auto" ? "switch" : "recommend" : "blocked";
+  const selectedProfileId = action === "switch" ? recommendedProfileId : previousProfileId ?? recommendedProfileId;
+  const reason = action === "switch" ? `Auto-switched from ${previousProfileId ?? "unknown"} to ${recommendedProfileId}.` : action === "recommend" ? `Recommended ${recommendedProfileId} but left selection unchanged because mode is recommend.` : action === "blocked" ? `Blocked profile switch because confidence ${confidence} is below ${minConfidence} or evidence is incomplete.` : "Kept current profile because measured evidence does not require a switch.";
+  const decision = {
+    action,
+    autoApplied: action === "switch",
+    confidence,
+    minConfidence,
+    mode,
+    previousProfileId,
+    reason,
+    recommendation,
+    recommendedProfileId,
+    selectedProfileId
+  };
+  if (options.audit) {
+    const auditEvent = await options.audit.append(createVoiceAuditEvent({
+      action: `profile.switch.${action}`,
+      actor: options.actor ?? {
+        id: "absolutejs-voice-profile-switch-guard",
+        kind: "system",
+        name: "AbsoluteJS Voice Profile Switch Guard"
+      },
+      metadata: options.metadata,
+      outcome: action === "blocked" ? "skipped" : "success",
+      payload: {
+        autoApplied: decision.autoApplied,
+        confidence,
+        minConfidence,
+        mode,
+        previousProfileId,
+        reasons: recommendation.reasons,
+        recommendedProfileId,
+        selectedProfileId,
+        status: recommendation.status
+      },
+      resource: {
+        id: selectedProfileId,
+        type: "voice-profile"
+      },
+      sessionId: options.sessionId,
+      traceId: options.traceId,
+      type: "profile.switch"
+    }));
+    decision.auditEvent = auditEvent;
+  }
+  return decision;
+};
+
 // src/plugin.ts
 var resolveQueryScenario = (query) => {
   if (typeof query?.scenarioId === "string" && query.scenarioId.trim()) {
@@ -5322,6 +5641,7 @@ var resolveSessionId = (runtime, ws) => {
   runtime.socketSessions.set(ws, resolved);
   return resolved;
 };
+var resolveMaybeFunction = async (value, input) => typeof value === "function" ? await value(input) : value;
 var toAudioChunk = (raw) => {
   if (raw instanceof ArrayBuffer) {
     return raw;
@@ -5395,6 +5715,69 @@ var resolveLexicon = async (config, input) => {
   }
   return normalizeLexicon(config.lexicon);
 };
+var resolveProfileSwitchGuard = async (config, runtime, input) => {
+  const guard = config.profileSwitchGuard;
+  if (!guard || runtime.profileSwitchGuardedSessions.has(input.sessionId)) {
+    return;
+  }
+  runtime.profileSwitchGuardedSessions.add(input.sessionId);
+  const resolverInput = input;
+  const defaults = await resolveMaybeFunction(guard.defaults, resolverInput);
+  if (!defaults) {
+    throw new Error("voice profileSwitchGuard requires measured profile defaults.");
+  }
+  const observed = await resolveMaybeFunction(guard.observed, resolverInput);
+  const currentProfileId = await resolveMaybeFunction(guard.currentProfileId, resolverInput);
+  const metadata = await resolveMaybeFunction(guard.metadata, resolverInput);
+  const minConfidence = await resolveMaybeFunction(guard.minConfidence, resolverInput);
+  const mode = await resolveMaybeFunction(guard.mode, resolverInput);
+  const decision = await applyVoiceProfileSwitchGuard({
+    actor: guard.actor,
+    audit: guard.audit,
+    defaultProfileId: guard.defaultProfileId,
+    defaults,
+    metadata,
+    minConfidence,
+    mode,
+    observed: {
+      ...observed,
+      currentProfileId: observed?.currentProfileId ?? currentProfileId
+    },
+    sessionId: input.sessionId
+  });
+  await guard.onDecision?.({
+    context: input.context,
+    decision,
+    scenarioId: input.scenarioId,
+    sessionId: input.sessionId
+  });
+  const trace = guard.trace === false ? undefined : guard.trace ?? config.trace;
+  if (trace) {
+    await trace.append({
+      at: Date.now(),
+      metadata: {
+        ...metadata,
+        source: "profile-switch-guard"
+      },
+      payload: {
+        action: decision.action,
+        autoApplied: decision.autoApplied,
+        confidence: decision.confidence,
+        minConfidence: decision.minConfidence,
+        mode: decision.mode,
+        previousProfileId: decision.previousProfileId,
+        reason: decision.reason,
+        recommendedProfileId: decision.recommendedProfileId,
+        selectedProfileId: decision.selectedProfileId,
+        status: decision.recommendation.status
+      },
+      scenarioId: input.scenarioId,
+      sessionId: input.sessionId,
+      type: "provider.decision"
+    });
+  }
+  return decision;
+};
 var voice = (config) => {
   if (!config.stt && !config.realtime) {
     throw new Error("voice requires either an stt or realtime adapter.");
@@ -5402,6 +5785,7 @@ var voice = (config) => {
   const runtime = {
     activeSessions: new Map,
     logger: resolveLogger(config.logger),
+    profileSwitchGuardedSessions: new Set,
     socketSessions: new WeakMap
   };
   const onTurn = normalizeOnTurn(config.onTurn);
@@ -5413,6 +5797,11 @@ var voice = (config) => {
   const htmxTargets = resolveVoiceHTMXTargets(htmxOptions?.targets);
   const createManagedSession = async (ws, sessionId, scenarioId) => {
     const context = ws.data;
+    const profileSwitchDecision = await resolveProfileSwitchGuard(config, runtime, {
+      context,
+      scenarioId,
+      sessionId
+    });
     const phraseHints = await resolvePhraseHints(config, {
       context,
       scenarioId,
@@ -5470,6 +5859,9 @@ var voice = (config) => {
         onTurn,
         onVoicemail: config.onVoicemail
       },
+      sessionMetadata: profileSwitchDecision && config.profileSwitchGuard?.sessionMetadataKey !== false ? {
+        [config.profileSwitchGuard?.sessionMetadataKey ?? "profileSwitchGuard"]: profileSwitchDecision
+      } : undefined,
       scenarioId,
       socket: createSocketAdapter(ws),
       store: config.session,
@@ -7198,170 +7590,6 @@ var assertVoiceCampaignDialerProofEvidence = (report, input = {}) => {
   }
   return assertion;
 };
-// src/audit.ts
-var includes = (filter, value) => {
-  if (!filter) {
-    return true;
-  }
-  if (!value) {
-    return false;
-  }
-  return Array.isArray(filter) ? filter.includes(value) : filter === value;
-};
-var createVoiceAuditEvent = (event) => ({
-  ...event,
-  at: event.at ?? Date.now(),
-  id: event.id ?? crypto.randomUUID()
-});
-var filterVoiceAuditEvents = (events, filter = {}) => {
-  const sorted = events.filter((event) => {
-    if (!includes(filter.type, event.type)) {
-      return false;
-    }
-    if (!includes(filter.outcome, event.outcome)) {
-      return false;
-    }
-    if (filter.actorId && event.actor?.id !== filter.actorId) {
-      return false;
-    }
-    if (filter.resourceId && event.resource?.id !== filter.resourceId) {
-      return false;
-    }
-    if (filter.resourceType && event.resource?.type !== filter.resourceType) {
-      return false;
-    }
-    if (filter.sessionId && event.sessionId !== filter.sessionId) {
-      return false;
-    }
-    if (filter.traceId && event.traceId !== filter.traceId) {
-      return false;
-    }
-    if (typeof filter.after === "number" && event.at <= filter.after) {
-      return false;
-    }
-    if (typeof filter.afterOrAt === "number" && event.at < filter.afterOrAt) {
-      return false;
-    }
-    if (typeof filter.before === "number" && event.at >= filter.before) {
-      return false;
-    }
-    if (typeof filter.beforeOrAt === "number" && event.at > filter.beforeOrAt) {
-      return false;
-    }
-    return true;
-  }).sort((left, right) => left.at - right.at || left.id.localeCompare(right.id));
-  return typeof filter.limit === "number" && filter.limit >= 0 ? sorted.slice(0, filter.limit) : sorted;
-};
-var createVoiceMemoryAuditEventStore = () => {
-  const events = new Map;
-  return {
-    append: (event) => {
-      const stored = createVoiceAuditEvent(event);
-      events.set(stored.id, stored);
-      return stored;
-    },
-    get: (id) => events.get(id),
-    list: (filter) => filterVoiceAuditEvents([...events.values()], filter)
-  };
-};
-var recordVoiceAuditEvent = (store, event) => store.append(createVoiceAuditEvent(event));
-var recordVoiceProviderAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
-  action: `${input.kind}.provider.call`,
-  actor: input.actor,
-  metadata: input.metadata,
-  outcome: input.outcome,
-  payload: {
-    cost: input.cost,
-    elapsedMs: input.elapsedMs,
-    error: input.error,
-    kind: input.kind,
-    model: input.model,
-    provider: input.provider
-  },
-  resource: {
-    id: input.provider,
-    type: "provider"
-  },
-  sessionId: input.sessionId,
-  traceId: input.traceId,
-  type: "provider.call"
-});
-var recordVoiceToolAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
-  action: "tool.call",
-  actor: input.actor,
-  metadata: input.metadata,
-  outcome: input.outcome,
-  payload: {
-    elapsedMs: input.elapsedMs,
-    error: input.error,
-    toolCallId: input.toolCallId,
-    toolName: input.toolName
-  },
-  resource: {
-    id: input.toolName,
-    type: "tool"
-  },
-  sessionId: input.sessionId,
-  traceId: input.traceId,
-  type: "tool.call"
-});
-var recordVoiceHandoffAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
-  action: "handoff",
-  actor: input.actor,
-  metadata: input.metadata,
-  outcome: input.outcome,
-  payload: {
-    fromAgentId: input.fromAgentId,
-    reason: input.reason,
-    target: input.target,
-    toAgentId: input.toAgentId
-  },
-  resource: {
-    id: input.toAgentId ?? input.target,
-    type: "handoff"
-  },
-  sessionId: input.sessionId,
-  traceId: input.traceId,
-  type: "handoff"
-});
-var recordVoiceRetentionAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
-  action: input.dryRun ? "retention.plan" : "retention.apply",
-  actor: input.actor ?? {
-    id: "voice-retention",
-    kind: "system"
-  },
-  metadata: input.metadata,
-  outcome: "success",
-  payload: {
-    deletedCount: input.report.deletedCount,
-    dryRun: input.dryRun,
-    scopes: input.report.scopes
-  },
-  resource: {
-    type: "retention-policy"
-  },
-  type: "retention.policy"
-});
-var recordVoiceOperatorAuditEvent = (input) => recordVoiceAuditEvent(input.store, {
-  action: input.action,
-  actor: input.actor,
-  metadata: input.metadata,
-  outcome: input.outcome ?? "success",
-  payload: input.payload,
-  resource: input.resource,
-  sessionId: input.sessionId,
-  traceId: input.traceId,
-  type: "operator.action"
-});
-var createVoiceAuditLogger = (store) => ({
-  handoff: (input) => recordVoiceHandoffAuditEvent({ ...input, store }),
-  operatorAction: (input) => recordVoiceOperatorAuditEvent({ ...input, store }),
-  providerCall: (input) => recordVoiceProviderAuditEvent({ ...input, store }),
-  record: (event) => recordVoiceAuditEvent(store, event),
-  retention: (input) => recordVoiceRetentionAuditEvent({ ...input, store }),
-  toolCall: (input) => recordVoiceToolAuditEvent({ ...input, store })
-});
-
 // src/agent.ts
 var normalizeText3 = (value) => typeof value === "string" ? value.trim() : "";
 var toErrorMessage3 = (error) => error instanceof Error ? error.message : String(error);
@@ -15694,72 +15922,6 @@ var formatVoiceProofTrendAge = (ageMs) => {
   const days = Math.floor(hours / 24);
   return `${days}d ${hours % 24}h`;
 };
-// src/profileSwitchRecommendation.ts
-var readDefaults = (input) => ("defaults" in input) ? input.defaults : input;
-var isNumber = (value) => typeof value === "number" && Number.isFinite(value);
-var exceeds = (observed, budget) => isNumber(observed) && isNumber(budget) && observed > budget;
-var scoreProfile = (profile, observed) => {
-  const evidence = profile.evidence;
-  const live = evidence.liveP95Ms ?? observed.liveP95Ms ?? 0;
-  const provider = evidence.providerP95Ms ?? observed.providerP95Ms ?? 0;
-  const turn = evidence.turnP95Ms ?? observed.turnP95Ms ?? 0;
-  const statusPenalty = profile.status === "pass" ? 0 : profile.status === "warn" ? 1e4 : 25000;
-  const noisyBonus = (observed.fallbackUsed || (observed.turnWarnings ?? 0) > 0) && /noisy|phone/i.test(`${profile.profileId} ${profile.label ?? ""}`) ? -1000 : 0;
-  return live + provider + turn + statusPenalty + noisyBonus;
-};
-var recommendVoiceProfileSwitch = (options) => {
-  const defaults = readDefaults(options.defaults);
-  const observed = options.observed ?? {};
-  const currentProfileId = observed.currentProfileId ?? options.defaultProfileId ?? defaults.profiles[0]?.profileId;
-  const currentProfile = defaults.profiles.find((profile) => profile.profileId === currentProfileId);
-  const candidates = defaults.profiles.filter((profile) => profile.status !== "fail");
-  const recommended = candidates.slice().sort((left, right) => scoreProfile(left, observed) - scoreProfile(right, observed))[0];
-  const issues = [
-    ...defaults.profiles.length === 0 ? ["No measured profile defaults are available."] : [],
-    ...!currentProfile && currentProfileId ? [`Current profile ${currentProfileId} is not present in measured defaults.`] : [],
-    ...!recommended ? ["No non-failing measured profile can be recommended."] : []
-  ];
-  const currentOverBudget = currentProfile ? [
-    exceeds(observed.liveP95Ms, currentProfile.latencyBudgets.maxLiveP95Ms) ? "live p95 exceeds this profile budget" : undefined,
-    exceeds(observed.providerP95Ms, currentProfile.latencyBudgets.maxProviderP95Ms) ? "provider p95 exceeds this profile budget" : undefined,
-    exceeds(observed.turnP95Ms, currentProfile.latencyBudgets.maxTurnP95Ms) ? "turn p95 exceeds this profile budget" : undefined
-  ].filter((reason) => Boolean(reason)) : [];
-  const minImprovementMs = options.minImprovementMs ?? 250;
-  const currentScore = currentProfile ? scoreProfile(currentProfile, observed) : Number.POSITIVE_INFINITY;
-  const recommendedScore = recommended ? scoreProfile(recommended, observed) : Number.POSITIVE_INFINITY;
-  const shouldSwitch = Boolean(recommended) && recommended?.profileId !== currentProfile?.profileId && (!currentProfile || currentProfile.status !== "pass" || currentOverBudget.length > 0 || currentScore - recommendedScore >= minImprovementMs);
-  const reasons = [
-    ...currentOverBudget,
-    ...currentProfile?.status && currentProfile.status !== "pass" ? [`current profile is ${currentProfile.status}`] : [],
-    ...observed.fallbackUsed ? ["current session used provider fallback"] : [],
-    ...(observed.turnWarnings ?? 0) > 0 ? [`${observed.turnWarnings} turn quality warning(s) observed`] : [],
-    ...shouldSwitch && recommended ? [
-      `${recommended.label ?? recommended.profileId} has the strongest measured fit for these signals`
-    ] : []
-  ];
-  return {
-    currentProfile: currentProfile ? {
-      label: currentProfile.label,
-      profileId: currentProfile.profileId,
-      status: currentProfile.status
-    } : undefined,
-    generatedAt: new Date().toISOString(),
-    issues,
-    nextMove: issues.length > 0 ? "Collect fresh real-call profile evidence before switching automatically." : shouldSwitch && recommended ? `Switch to ${recommended.label ?? recommended.profileId} for this session profile.` : "Keep the current measured profile unless new session evidence drifts.",
-    ok: issues.length === 0,
-    observed,
-    reasons: reasons.length > 0 ? reasons : ["current profile matches measured defaults and observed budgets"],
-    recommendedProfile: recommended ? {
-      evidence: recommended.evidence,
-      label: recommended.label,
-      latencyBudgets: recommended.latencyBudgets,
-      profileId: recommended.profileId,
-      providerRoutes: recommended.providerRoutes,
-      status: recommended.status
-    } : undefined,
-    status: issues.length > 0 ? "warn" : shouldSwitch ? "switch" : "stay"
-  };
-};
 // src/providerDecisionTraces.ts
 import { Elysia as Elysia23 } from "elysia";
 
@@ -37846,6 +38008,7 @@ export {
   assertVoiceAgentSquadContractEvidence,
   assertVoiceAgentSquadContract,
   applyVoiceTelephonyOutcome,
+  applyVoiceProfileSwitchGuard,
   applyVoiceOpsTaskPolicy,
   applyVoiceOpsTaskAssignmentRule,
   applyVoiceHandoffDeliveryResult,

package/dist/profileSwitchRecommendation.d.ts

@@ -1,4 +1,5 @@
 import type { VoiceRealCallProfileDefault, VoiceRealCallProfileDefaultsReport, VoiceRealCallProfileHistoryReport } from './proofTrends';
+import { type StoredVoiceAuditEvent, type VoiceAuditActor, type VoiceAuditEventStore } from './audit';
 export type VoiceProfileSwitchObservedSignals = {
     currentProfileId?: string;
     fallbackUsed?: boolean;
@@ -35,4 +36,29 @@ export type VoiceProfileSwitchRecommendationOptions = {
     minImprovementMs?: number;
     observed?: VoiceProfileSwitchObservedSignals;
 };
+export type VoiceProfileSwitchGuardMode = 'auto' | 'recommend';
+export type VoiceProfileSwitchGuardAction = 'blocked' | 'recommend' | 'stay' | 'switch';
+export type VoiceProfileSwitchGuardDecision = {
+    action: VoiceProfileSwitchGuardAction;
+    auditEvent?: StoredVoiceAuditEvent;
+    autoApplied: boolean;
+    confidence: number;
+    minConfidence: number;
+    mode: VoiceProfileSwitchGuardMode;
+    previousProfileId?: string;
+    reason: string;
+    recommendation: VoiceProfileSwitchRecommendation;
+    recommendedProfileId?: string;
+    selectedProfileId?: string;
+};
+export type VoiceProfileSwitchGuardOptions = VoiceProfileSwitchRecommendationOptions & {
+    actor?: VoiceAuditActor;
+    audit?: VoiceAuditEventStore;
+    metadata?: Record<string, unknown>;
+    minConfidence?: number;
+    mode?: VoiceProfileSwitchGuardMode;
+    sessionId?: string;
+    traceId?: string;
+};
 export declare const recommendVoiceProfileSwitch: (options: VoiceProfileSwitchRecommendationOptions) => VoiceProfileSwitchRecommendation;
+export declare const applyVoiceProfileSwitchGuard: (options: VoiceProfileSwitchGuardOptions) => Promise<VoiceProfileSwitchGuardDecision>;

package/dist/testing/index.js

@@ -7563,6 +7563,12 @@ var createVoiceSession = (options) => {
     if (options.scenarioId && session.scenarioId !== options.scenarioId) {
       session.scenarioId = options.scenarioId;
     }
+    if (options.sessionMetadata) {
+      session.metadata = {
+        ...session.metadata && typeof session.metadata === "object" ? session.metadata : {},
+        ...options.sessionMetadata
+      };
+    }
     ensureCommittedTurnGuard(session);
     let shouldFireOnSession = !existingSession;
     if (existingSession?.scenarioId && options.scenarioId && existingSession.scenarioId !== options.scenarioId) {

package/dist/types.d.ts

@@ -5,6 +5,9 @@ import type { VoiceIntegrationSink } from './opsSinks';
 import type { StoredVoiceCallReviewArtifact, VoiceCallReviewArtifact, VoiceCallReviewStore } from './testing/review';
 import type { VoiceTraceEventStore } from './trace';
 import type { VoiceLiveOpsControlState } from './liveOps';
+import type { VoiceAuditActor, VoiceAuditEventStore } from './audit';
+import type { VoiceProfileSwitchGuardDecision, VoiceProfileSwitchGuardMode, VoiceProfileSwitchObservedSignals } from './profileSwitchRecommendation';
+import type { VoiceRealCallProfileDefaultsReport, VoiceRealCallProfileHistoryReport } from './proofTrends';
 export type AudioFormat = {
     container: 'raw';
     encoding: 'alaw' | 'mulaw' | 'pcm_s16le';
@@ -614,6 +617,30 @@ export type VoiceRuntimeOpsConfig<TContext = unknown, TSession extends VoiceSess
 export type VoiceLiveOpsRuntimeConfig = {
     getControl: (sessionId: string) => Promise<VoiceLiveOpsControlState | null | undefined> | VoiceLiveOpsControlState | null | undefined;
 };
+export type VoiceProfileSwitchGuardResolverInput<TContext = unknown> = {
+    context: TContext;
+    scenarioId?: string;
+    sessionId: string;
+};
+export type VoicePluginProfileSwitchGuardConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    actor?: VoiceAuditActor;
+    audit?: VoiceAuditEventStore;
+    currentProfileId?: string | ((input: VoiceProfileSwitchGuardResolverInput<TContext>) => Promise<string | undefined> | string | undefined);
+    defaultProfileId?: string;
+    defaults: VoiceRealCallProfileDefaultsReport | VoiceRealCallProfileHistoryReport | ((input: VoiceProfileSwitchGuardResolverInput<TContext>) => Promise<VoiceRealCallProfileDefaultsReport | VoiceRealCallProfileHistoryReport> | VoiceRealCallProfileDefaultsReport | VoiceRealCallProfileHistoryReport);
+    metadata?: Record<string, unknown> | ((input: VoiceProfileSwitchGuardResolverInput<TContext>) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined);
+    minConfidence?: number | ((input: VoiceProfileSwitchGuardResolverInput<TContext>) => Promise<number | undefined> | number | undefined);
+    mode?: VoiceProfileSwitchGuardMode | ((input: VoiceProfileSwitchGuardResolverInput<TContext>) => Promise<VoiceProfileSwitchGuardMode | undefined> | VoiceProfileSwitchGuardMode | undefined);
+    observed?: VoiceProfileSwitchObservedSignals | ((input: VoiceProfileSwitchGuardResolverInput<TContext>) => Promise<VoiceProfileSwitchObservedSignals | undefined> | VoiceProfileSwitchObservedSignals | undefined);
+    onDecision?: (input: {
+        context: TContext;
+        decision: VoiceProfileSwitchGuardDecision;
+        scenarioId?: string;
+        sessionId: string;
+    }) => Promise<void> | void;
+    sessionMetadataKey?: string | false;
+    trace?: false | VoiceTraceEventStore;
+};
 export type VoiceNormalizedRouteConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Omit<VoiceRouteConfig<TContext, TSession, TResult>, 'onTurn'> & {
     onTurn: VoiceOnTurnObjectHandler<TContext, TSession, TResult>;
 };
@@ -649,6 +676,7 @@ export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionR
     handoff?: VoiceHandoffConfig<TContext, TSession, TResult>;
     ops?: VoiceRuntimeOpsConfig<TContext, TSession, TResult>;
     liveOps?: VoiceLiveOpsRuntimeConfig;
+    profileSwitchGuard?: VoicePluginProfileSwitchGuardConfig<TContext, TSession, TResult>;
     trace?: VoiceTraceEventStore;
 } & VoiceRouteConfig<TContext, TSession, TResult>;
 export type CreateVoiceSessionOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
@@ -667,6 +695,7 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     trace?: VoiceTraceEventStore;
     reconnect: Required<VoiceReconnectConfig>;
     phraseHints?: VoicePhraseHint[];
+    sessionMetadata?: Record<string, unknown>;
     scenarioId?: string;
     sttLifecycle: VoiceSTTLifecycle;
     turnDetection: VoiceResolvedTurnDetectionConfig;

package/dist/vue/useVoiceReadinessFailures.d.ts

@@ -146,6 +146,7 @@ export declare const useVoiceReadinessFailures: (path?: string, options?: VoiceR
                 readonly present: {
                     readonly "operator.action": number;
                     readonly handoff: number;
+                    readonly "profile.switch": number;
                     readonly "provider.call": number;
                     readonly "retention.policy": number;
                     readonly "tool.call": number;
@@ -578,6 +579,7 @@ export declare const useVoiceReadinessFailures: (path?: string, options?: VoiceR
                 readonly present: {
                     readonly "operator.action": number;
                     readonly handoff: number;
+                    readonly "profile.switch": number;
                     readonly "provider.call": number;
                     readonly "retention.policy": number;
                     readonly "tool.call": number;

package/package.json

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