@absolutejs/voice 0.0.22-beta.634 → 0.0.22-beta.636

package/README.md

@@ -5015,6 +5015,14 @@ That keeps HTMX pages declarative without inventing custom fragment endpoints fo
 
 Performance & accuracy benchmarks (STT, TTS, duplex, telephony, sessions) and head-to-head comparisons against Vapi live in a dedicated repo: **[absolutejs/benchmarks](https://github.com/absolutejs/benchmarks)**. They consume the published `@absolutejs/voice` package and provider adapters.
 
+Reusable eval contracts stay in `@absolutejs/voice/testing`: fixture manifests
+can label critical names, organizations, currency, percentages, phone numbers,
+and other exact fields; benchmark reports score those fields independently from
+WER; confidence calibration reports ECE/Brier scores; and routing reports expose
+fallback improvement and harm rates. Audio corpora and executable provider runs
+remain separate so applications can consume the same contracts without shipping
+benchmark media in the runtime package.
+
 ## Adapter Contract
 
 Adapters normalize vendor behavior into a core event model so the plugin never branches on vendor names.
@@ -5035,6 +5043,7 @@ type STTAdapterSession = {
     handler: (payload: STTSessionEventMap[K]) => void | Promise<void>,
   ) => () => void;
   send: (audio: AudioChunk) => Promise<void>;
+  configure?: (configuration: VoiceSTTSessionConfiguration) => Promise<void>;
   close: (reason?: string) => Promise<void>;
 };
 ```

package/dist/core/types.d.ts

@@ -90,6 +90,15 @@ export type TranscriptWord = {
     startedAtMs?: number;
     text: string;
 };
+/** Provider token evidence. Tokens are intentionally kept separate from words:
+ * subword log probabilities are useful for calibration and routing, but are not
+ * word-level timestamps or confidence scores. */
+export type TranscriptToken = {
+    bytes?: number[];
+    confidence?: number;
+    logProbability?: number;
+    text: string;
+};
 export type Transcript = {
     id: string;
     text: string;
@@ -101,8 +110,15 @@ export type Transcript = {
     startedAtMs?: number;
     endedAtMs?: number;
     vendor?: string;
+    tokens?: TranscriptToken[];
     words?: TranscriptWord[];
 };
+export type VoiceSTTSessionConfiguration = {
+    languageHints?: string[];
+    lexicon?: VoiceLexiconEntry[];
+    phraseHints?: VoicePhraseHint[];
+    turnDetection?: Partial<VoiceTurnDetectionConfig>;
+};
 export type VoiceTranscriptQuality = {
     averageConfidence?: number;
     confidenceSampleCount: number;
@@ -133,7 +149,7 @@ export type VoiceTurnCostEstimate = {
     primaryAudioMs: number;
     totalBillableAudioMs: number;
 };
-export type VoiceFallbackSelectionReason = "fallback-empty" | "primary-empty" | "word-count-margin" | "confidence-margin" | "word-count-tiebreak" | "kept-primary";
+export type VoiceFallbackSelectionReason = "fallback-empty" | "primary-empty" | "word-count-margin" | "confidence-margin" | "word-count-tiebreak" | "policy-preference" | "kept-primary";
 export type VoiceFallbackDiagnostics = {
     attempted: boolean;
     fallbackConfidence?: number;
@@ -184,6 +200,8 @@ export type STTSessionEventMap = {
 export type STTAdapterSession = {
     on: <K extends keyof STTSessionEventMap>(event: K, handler: (payload: STTSessionEventMap[K]) => void | Promise<void>) => () => void;
     send: (audio: AudioChunk) => Promise<void>;
+    /** Update provider-supported STT context without restarting the stream. */
+    configure?: (configuration: VoiceSTTSessionConfiguration) => Promise<void>;
     close: (reason?: string) => Promise<void>;
 };
 export type STTAdapterOpenOptions = {
@@ -240,6 +258,8 @@ export type RealtimeSessionEventMap = STTSessionEventMap & {
 export type RealtimeAdapterSession = {
     on: <K extends keyof RealtimeSessionEventMap>(event: K, handler: (payload: RealtimeSessionEventMap[K]) => void | Promise<void>) => () => void;
     send: (input: AudioChunk | string) => Promise<void>;
+    /** Update provider-supported input transcription context in place. */
+    configure?: (configuration: VoiceSTTSessionConfiguration) => Promise<void>;
     close: (reason?: string) => Promise<void>;
 };
 export type RealtimeAdapterOpenOptions = {
@@ -458,6 +478,9 @@ export type VoiceSTTFallbackConfig = {
      * language that should receive a second transcription pass regardless of the
      * aggregate confidence. */
     riskPolicy?: VoiceSTTFallbackRiskPolicy;
+    /** Prefer a non-empty independent fallback for these audited trigger reasons,
+     * including providers that do not expose comparable confidence scores. */
+    preferFallbackOn?: VoiceFallbackTriggerReason[];
 };
 export type VoiceResolvedSTTFallbackConfig = {
     adapter: STTAdapter;
@@ -470,6 +493,7 @@ export type VoiceResolvedSTTFallbackConfig = {
     maxAttemptsPerTurn: number;
     wordConfidenceThreshold?: number;
     riskPolicy?: VoiceSTTFallbackRiskPolicy;
+    preferFallbackOn?: VoiceFallbackTriggerReason[];
 };
 export type VoiceTurnDetectionConfig = {
     profile?: VoiceTurnProfile;
@@ -580,6 +604,9 @@ export type VoiceSessionHandle<TContext = unknown, TSession extends VoiceSession
         speechThreshold: number;
         transcriptStabilityMs: number;
     }>;
+    /** Refresh vocabulary, language hints, or provider turn settings while a
+     * call is active. Unsupported fields are ignored by the active adapter. */
+    configureSTT: (configuration: VoiceSTTSessionConfiguration) => Promise<void>;
 };
 export type VoiceLLMUsage = {
     provider?: string;

package/dist/index.js

@@ -4260,7 +4260,8 @@ var createVoiceSession = (options) => {
     settleMs: options.sttFallback.settleMs ?? DEFAULT_FALLBACK_SETTLE_MS,
     trigger: options.sttFallback.trigger ?? "empty-or-low-confidence",
     wordConfidenceThreshold: options.sttFallback.wordConfidenceThreshold,
-    riskPolicy: options.sttFallback.riskPolicy
+    riskPolicy: options.sttFallback.riskPolicy,
+    preferFallbackOn: options.sttFallback.preferFallbackOn
   } : undefined;
   const appendTrace = async (input) => {
     await options.trace?.append({
@@ -5524,7 +5525,11 @@ var createVoiceSession = (options) => {
       text: primaryText,
       wordCount: countWords2(normalizeText2(primaryText))
     };
-    const selection = selectBetterTurnText(primaryCandidate, fallbackCandidate);
+    const policyPrefersFallback = fallbackCandidate.text.length > 0 && fallbackNeed.reason !== undefined && sttFallback.preferFallbackOn?.includes(fallbackNeed.reason);
+    const selection = policyPrefersFallback ? {
+      reason: "policy-preference",
+      winner: fallbackCandidate
+    } : selectBetterTurnText(primaryCandidate, fallbackCandidate);
     const diagnostics = {
       attempted: true,
       fallbackConfidence: fallbackCandidate.confidence,
@@ -7036,6 +7041,10 @@ var createVoiceSession = (options) => {
     commitTurn: async (reason = "manual") => runSerial("api.commitTurn", async () => {
       await commitTurnInternal(reason);
     }),
+    configureSTT: async (configuration) => runSerial("api.configureSTT", async () => {
+      const adapter = await ensureAdapter();
+      await adapter.configure?.(configuration);
+    }),
     complete: async (result) => runSerial("api.complete", async () => {
       await completeInternal(result);
     }),
@@ -44488,6 +44497,7 @@ var createContractApi = (session) => ({
   id: session.id,
   attachUserMedia: async () => {},
   close: async () => {},
+  configureSTT: async () => {},
   commitTurn: async () => {},
   complete: async () => {},
   connect: async () => {},
@@ -49553,6 +49563,44 @@ var runSTTAdapterFixture = async (adapter, fixture, options = {}) => {
   };
 };
 
+// src/testing/criticalFields.ts
+var normalizeText4 = (value) => value.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}@.%+$'-]+/gu, " ").replace(/\s+/g, " ").trim();
+var normalizeDigits = (value) => normalizeSpokenNumbers(value).replace(/\D/g, "");
+var normalizeSemanticNumber = (value) => normalizeSpokenNumbers(value).toLowerCase().replace(/\bdollars?\b|\busd\b|\bpercent(age)?\b|[%,$]/g, "").replace(/\s+/g, "").trim();
+var matchesCandidate = (actual, candidate, kind) => {
+  if (kind === "phone") {
+    const expectedDigits = normalizeDigits(candidate);
+    return expectedDigits.length > 0 && normalizeDigits(actual).includes(expectedDigits);
+  }
+  if (kind === "currency" || kind === "number" || kind === "percentage") {
+    const expectedNumber = normalizeSemanticNumber(candidate);
+    return expectedNumber.length > 0 && normalizeSemanticNumber(actual).includes(expectedNumber);
+  }
+  const normalizedCandidate = normalizeText4(candidate);
+  return normalizedCandidate.length > 0 && normalizeText4(actual).includes(normalizedCandidate);
+};
+var scoreVoiceCriticalFields = (actualText, expectedFields = []) => {
+  const fields = expectedFields.map((field) => {
+    const candidates = [field.value, ...field.aliases ?? []];
+    const matchedAlias = candidates.find((candidate) => matchesCandidate(actualText, candidate, field.kind));
+    return {
+      ...field,
+      matched: matchedAlias !== undefined,
+      matchedAlias
+    };
+  });
+  const matchedCount = fields.filter((field) => field.matched).length;
+  const totalCount = fields.length;
+  return {
+    accuracy: totalCount > 0 ? matchedCount / totalCount : 1,
+    fields,
+    matchedCount,
+    missingFieldIds: fields.filter((field) => !field.matched).map((field) => field.id),
+    passesRequired: fields.every((field) => field.required === false || field.matched),
+    totalCount
+  };
+};
+
 // src/testing/benchmark.ts
 var resolveFixtureEnvironment = (fixture) => {
   const tags = new Set(fixture.tags ?? []);
@@ -49783,10 +49831,12 @@ var toFixtureBenchmarkResult = (fixture, result, elapsedMs) => {
   const postSpeechTimeToFirstFinalMs = toPostSpeechLatency(result.finalEvents[0]?.receivedAt);
   const postSpeechTimeToEndOfTurnMs = toPostSpeechLatency(result.endOfTurnEvents[0]?.receivedAt);
   const expectedTerms = scoreExpectedTerms(result.finalText, fixture.expectedTerms);
+  const criticalFields = scoreVoiceCriticalFields(result.finalText, fixture.expectedCriticalFields);
   const speakerTurns = scoreSpeakerTurns(fixture, result);
   return {
     accuracy: result.accuracy,
     closeCount: result.closeEvents.length,
+    criticalFields,
     difficulty: fixture.difficulty,
     elapsedMs,
     endOfTurnCount: result.endOfTurnEvents.length,
@@ -49797,7 +49847,7 @@ var toFixtureBenchmarkResult = (fixture, result, elapsedMs) => {
     fixtureId: fixture.id,
     fragmentationCount: Math.max(0, result.finalEvents.length - 1),
     group: resolveFixtureEnvironment(fixture),
-    passes: result.errorEvents.length === 0 && result.finalText.trim().length > 0 && result.accuracy.passesThreshold && (speakerTurns ? speakerTurns.passes : true),
+    passes: result.errorEvents.length === 0 && result.finalText.trim().length > 0 && result.accuracy.passesThreshold && criticalFields.passesRequired && (speakerTurns ? speakerTurns.passes : true),
     partialCount: result.partialEvents.length,
     speakerTurns,
     postSpeechTimeToEndOfTurnMs,
@@ -49925,6 +49975,8 @@ var summarizeSTTBenchmark = (adapterId, fixtures) => {
     averageFinalCount: roundMetric4(average2(fixtures.map((fixture) => fixture.finalCount)), 2) ?? 0,
     averageSpeakerTurnMatchRate: roundMetric4(average2(fixtures.map((fixture) => fixture.speakerTurns?.patternMatchRate))),
     averageTermRecall: roundMetric4(average2(fixtures.map((fixture) => fixture.expectedTerms.recall))) ?? 0,
+    averageCriticalFieldAccuracy: roundMetric4(average2(fixtures.map((fixture) => fixture.criticalFields?.accuracy ?? 1))) ?? 0,
+    requiredCriticalFieldPassRate: fixtureCount > 0 ? roundMetric4(fixtures.filter((fixture) => fixture.criticalFields?.passesRequired ?? true).length / fixtureCount) ?? 0 : 0,
     averagePostSpeechTimeToEndOfTurnMs: roundMetric4(average2(fixtures.map((fixture) => fixture.postSpeechTimeToEndOfTurnMs)), 2),
     averagePostSpeechTimeToFirstFinalMs: roundMetric4(average2(fixtures.map((fixture) => fixture.postSpeechTimeToFirstFinalMs)), 2),
     averageTimeToEndOfTurnMs: roundMetric4(average2(fixtures.map((fixture) => fixture.timeToEndOfTurnMs)), 2),

package/dist/testing/benchmark.d.ts

@@ -1,6 +1,7 @@
 import type { STTAdapter, STTAdapterOpenOptions } from "../core/types";
 import { type VoiceSTTAdapterHarnessOptions, type VoiceSTTAdapterHarnessResult } from "./stt";
 import type { VoiceTestFixture } from "./fixtures";
+import { type VoiceCriticalFieldAccuracy } from "./criticalFields";
 export type VoiceExpectedTermAccuracy = {
     allMatched: boolean;
     expectedTerms: string[];
@@ -25,6 +26,7 @@ export type VoiceSTTBenchmarkFixtureResult = {
     endOfTurnCount: number;
     errorCount: number;
     expectedTerms: VoiceExpectedTermAccuracy;
+    criticalFields?: VoiceCriticalFieldAccuracy;
     finalCount: number;
     finalText: string;
     fixtureId: string;
@@ -49,6 +51,8 @@ export type VoiceSTTBenchmarkSummary = {
     averageFinalCount: number;
     averageSpeakerTurnMatchRate?: number;
     averageTermRecall: number;
+    averageCriticalFieldAccuracy: number;
+    requiredCriticalFieldPassRate: number;
     averagePostSpeechTimeToEndOfTurnMs?: number;
     averagePostSpeechTimeToFirstFinalMs?: number;
     averageTimeToEndOfTurnMs?: number;

package/dist/testing/confidenceCalibration.d.ts

@@ -0,0 +1,19 @@
+export type VoiceConfidenceCalibrationSample = {
+    confidence: number;
+    correct: boolean;
+    metadata?: Record<string, unknown>;
+};
+export type VoiceConfidenceCalibrationBin = {
+    accuracy: number;
+    averageConfidence: number;
+    count: number;
+    lowerBound: number;
+    upperBound: number;
+};
+export type VoiceConfidenceCalibrationReport = {
+    bins: VoiceConfidenceCalibrationBin[];
+    brierScore: number;
+    expectedCalibrationError: number;
+    sampleCount: number;
+};
+export declare const calibrateVoiceConfidence: (samples: VoiceConfidenceCalibrationSample[], binCount?: number) => VoiceConfidenceCalibrationReport;

package/dist/testing/criticalFields.d.ts

@@ -0,0 +1,22 @@
+export type VoiceCriticalFieldKind = "acronym" | "brand" | "currency" | "custom" | "email" | "number" | "organization" | "percentage" | "person-name" | "phone";
+export type VoiceExpectedCriticalField = {
+    aliases?: string[];
+    id: string;
+    kind: VoiceCriticalFieldKind;
+    metadata?: Record<string, unknown>;
+    required?: boolean;
+    value: string;
+};
+export type VoiceCriticalFieldResult = VoiceExpectedCriticalField & {
+    matched: boolean;
+    matchedAlias?: string;
+};
+export type VoiceCriticalFieldAccuracy = {
+    accuracy: number;
+    fields: VoiceCriticalFieldResult[];
+    matchedCount: number;
+    missingFieldIds: string[];
+    passesRequired: boolean;
+    totalCount: number;
+};
+export declare const scoreVoiceCriticalFields: (actualText: string, expectedFields?: VoiceExpectedCriticalField[]) => VoiceCriticalFieldAccuracy;

package/dist/testing/fixtures.d.ts

@@ -1,10 +1,12 @@
 import type { AudioFormat, VoiceExpectedSpeakerTurn } from "../core/types";
+import type { VoiceExpectedCriticalField } from "./criticalFields";
 export type VoiceTestFixtureManifestEntry = {
     id: string;
     title: string;
     audioPath: string;
     expectedText: string;
     expectedTerms?: string[];
+    expectedCriticalFields?: VoiceExpectedCriticalField[];
     expectedSpeakerTurns?: VoiceExpectedSpeakerTurn[];
     expectedTurnTexts?: string[];
     chunkDurationMs?: number;

package/dist/testing/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./accuracy";
 export * from "./benchmark";
+export * from "./confidenceCalibration";
+export * from "./criticalFields";
 export * from "./corrected";
 export * from "./duplex";
 export * from "./fixtures";
@@ -7,6 +9,7 @@ export * from "./ioProviderSimulator";
 export * from "./providerSimulator";
 export * from "./resilience";
 export * from "./review";
+export * from "./routingBenchmark";
 export * from "./sessionBenchmark";
 export * from "./stt";
 export * from "./telephony";

package/dist/testing/index.js

@@ -367,6 +367,229 @@ var runSTTAdapterFixture = async (adapter, fixture, options = {}) => {
   };
 };
 
+// src/core/numberNormalizer.ts
+var ONES = {
+  eight: 8,
+  eighteen: 18,
+  eleven: 11,
+  fifteen: 15,
+  five: 5,
+  four: 4,
+  fourteen: 14,
+  nine: 9,
+  nineteen: 19,
+  one: 1,
+  seven: 7,
+  seventeen: 17,
+  six: 6,
+  sixteen: 16,
+  ten: 10,
+  thirteen: 13,
+  three: 3,
+  twelve: 12,
+  two: 2,
+  zero: 0
+};
+var TENS = {
+  eighty: 80,
+  fifty: 50,
+  forty: 40,
+  ninety: 90,
+  seventy: 70,
+  sixty: 60,
+  thirty: 30,
+  twenty: 20
+};
+var SCALES = {
+  billion: 1e9,
+  million: 1e6,
+  thousand: 1000,
+  trillion: 1000000000000
+};
+var MAGNITUDE_WORDS = [
+  [1000000000000, "trillion"],
+  [1e9, "billion"],
+  [1e6, "million"]
+];
+var FILLER = new Set(["and", "a", "an"]);
+var DECIMAL_PLACES = 3;
+var isValueWord = (word) => (word in ONES) || (word in TENS) || word === "hundred";
+var isScaleWord = (word) => (word in SCALES);
+var isNumberWord = (word) => isValueWord(word) || isScaleWord(word) || word === "point" || FILLER.has(word);
+var trimNumber = (value) => {
+  if (Number.isInteger(value))
+    return value.toLocaleString("en-US");
+  return String(Number(value.toFixed(DECIMAL_PLACES)));
+};
+var renderValue = (value, usedMagnitude) => {
+  if (usedMagnitude) {
+    for (const [scale, word] of MAGNITUDE_WORDS) {
+      if (value >= scale) {
+        const scaled = value / scale;
+        if (Number(scaled.toFixed(DECIMAL_PLACES)) === scaled) {
+          return `${trimNumber(scaled)} ${word}`;
+        }
+      }
+    }
+  }
+  return trimNumber(value);
+};
+var parseNumberWords = (words) => {
+  let total = 0;
+  let current = 0;
+  let usedMagnitude = false;
+  let sawNumber = false;
+  let decimal = null;
+  const foldDecimal = () => {
+    if (decimal && decimal.length > 0)
+      current += Number(`0.${decimal}`);
+    decimal = null;
+  };
+  for (const word of words) {
+    if (word === "point") {
+      decimal = "";
+      continue;
+    }
+    const one = ONES[word];
+    const ten = TENS[word];
+    const scale = SCALES[word];
+    if (decimal !== null) {
+      if (one !== undefined && one <= 9) {
+        decimal += String(one);
+        sawNumber = true;
+        continue;
+      }
+      foldDecimal();
+    }
+    if (FILLER.has(word))
+      continue;
+    if (one !== undefined) {
+      current += one;
+      sawNumber = true;
+    } else if (ten !== undefined) {
+      current += ten;
+      sawNumber = true;
+    } else if (word === "hundred") {
+      current = (current === 0 ? 1 : current) * 100;
+      sawNumber = true;
+    } else if (scale !== undefined) {
+      total += (current === 0 ? 1 : current) * scale;
+      current = 0;
+      sawNumber = true;
+      usedMagnitude = true;
+    }
+  }
+  foldDecimal();
+  if (!sawNumber)
+    return null;
+  return { usedMagnitude, value: total + current };
+};
+var PERCENT_RE = /^(per ?cent|percent|percentage)$/;
+var CURRENCY_RE = /^(dollars?|bucks?|usd)$/;
+var WORD_RE = /^[A-Za-z]+(?:-[A-Za-z]+)*$/;
+var wordsOf = (token) => token.toLowerCase().split("-");
+var isNumberToken = (token) => WORD_RE.test(token) && wordsOf(token).every(isNumberWord);
+var startsNumber = (token) => WORD_RE.test(token) && wordsOf(token).some(isValueWord);
+var isSpace = (token) => /^\s+$/.test(token);
+var normalizeSpokenNumbers = (input) => {
+  if (!input)
+    return input;
+  const parts = input.match(/[A-Za-z]+(?:-[A-Za-z]+)*|[^A-Za-z]+/g);
+  if (!parts)
+    return input;
+  const at = (idx) => parts[idx] ?? "";
+  const out = [];
+  let i = 0;
+  while (i < parts.length) {
+    const token = at(i);
+    const lower = token.toLowerCase();
+    if (lower === "a" || lower === "an") {
+      const nextWord = at(i + 2);
+      const nextHead = wordsOf(nextWord)[0] ?? "";
+      const nextIsScale = isSpace(at(i + 1)) && WORD_RE.test(nextWord) && (nextHead === "hundred" || isScaleWord(nextHead));
+      if (!nextIsScale) {
+        out.push(token);
+        i += 1;
+        continue;
+      }
+    } else if (!startsNumber(token)) {
+      out.push(token);
+      i += 1;
+      continue;
+    }
+    const spanIdx = [i];
+    let j = i + 1;
+    while (isSpace(at(j)) && isNumberToken(at(j + 1))) {
+      spanIdx.push(j + 1);
+      j += 2;
+    }
+    const words = spanIdx.flatMap((k) => wordsOf(at(k)));
+    while (words.length > 0 && FILLER.has(words[words.length - 1] ?? "")) {
+      words.pop();
+    }
+    const parsed = parseNumberWords(words);
+    if (!parsed) {
+      out.push(token);
+      i += 1;
+      continue;
+    }
+    let rendered = renderValue(parsed.value, parsed.usedMagnitude);
+    let lastIdx = spanIdx[spanIdx.length - 1] ?? i;
+    const unitWord = at(lastIdx + 2);
+    if (isSpace(at(lastIdx + 1)) && WORD_RE.test(unitWord)) {
+      const unit = unitWord.toLowerCase();
+      if (PERCENT_RE.test(unit)) {
+        rendered = `${rendered}%`;
+        lastIdx += 2;
+      } else if (CURRENCY_RE.test(unit)) {
+        rendered = rendered.startsWith("$") ? rendered : `$${rendered}`;
+        lastIdx += 2;
+      }
+    }
+    out.push(rendered);
+    i = lastIdx + 1;
+  }
+  return out.join("");
+};
+
+// src/testing/criticalFields.ts
+var normalizeText2 = (value) => value.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}@.%+$'-]+/gu, " ").replace(/\s+/g, " ").trim();
+var normalizeDigits = (value) => normalizeSpokenNumbers(value).replace(/\D/g, "");
+var normalizeSemanticNumber = (value) => normalizeSpokenNumbers(value).toLowerCase().replace(/\bdollars?\b|\busd\b|\bpercent(age)?\b|[%,$]/g, "").replace(/\s+/g, "").trim();
+var matchesCandidate = (actual, candidate, kind) => {
+  if (kind === "phone") {
+    const expectedDigits = normalizeDigits(candidate);
+    return expectedDigits.length > 0 && normalizeDigits(actual).includes(expectedDigits);
+  }
+  if (kind === "currency" || kind === "number" || kind === "percentage") {
+    const expectedNumber = normalizeSemanticNumber(candidate);
+    return expectedNumber.length > 0 && normalizeSemanticNumber(actual).includes(expectedNumber);
+  }
+  const normalizedCandidate = normalizeText2(candidate);
+  return normalizedCandidate.length > 0 && normalizeText2(actual).includes(normalizedCandidate);
+};
+var scoreVoiceCriticalFields = (actualText, expectedFields = []) => {
+  const fields = expectedFields.map((field) => {
+    const candidates = [field.value, ...field.aliases ?? []];
+    const matchedAlias = candidates.find((candidate) => matchesCandidate(actualText, candidate, field.kind));
+    return {
+      ...field,
+      matched: matchedAlias !== undefined,
+      matchedAlias
+    };
+  });
+  const matchedCount = fields.filter((field) => field.matched).length;
+  const totalCount = fields.length;
+  return {
+    accuracy: totalCount > 0 ? matchedCount / totalCount : 1,
+    fields,
+    matchedCount,
+    missingFieldIds: fields.filter((field) => !field.matched).map((field) => field.id),
+    passesRequired: fields.every((field) => field.required === false || field.matched),
+    totalCount
+  };
+};
+
 // src/testing/benchmark.ts
 var resolveFixtureEnvironment = (fixture) => {
   const tags = new Set(fixture.tags ?? []);
@@ -597,10 +820,12 @@ var toFixtureBenchmarkResult = (fixture, result, elapsedMs) => {
   const postSpeechTimeToFirstFinalMs = toPostSpeechLatency(result.finalEvents[0]?.receivedAt);
   const postSpeechTimeToEndOfTurnMs = toPostSpeechLatency(result.endOfTurnEvents[0]?.receivedAt);
   const expectedTerms = scoreExpectedTerms(result.finalText, fixture.expectedTerms);
+  const criticalFields = scoreVoiceCriticalFields(result.finalText, fixture.expectedCriticalFields);
   const speakerTurns = scoreSpeakerTurns(fixture, result);
   return {
     accuracy: result.accuracy,
     closeCount: result.closeEvents.length,
+    criticalFields,
     difficulty: fixture.difficulty,
     elapsedMs,
     endOfTurnCount: result.endOfTurnEvents.length,
@@ -611,7 +836,7 @@ var toFixtureBenchmarkResult = (fixture, result, elapsedMs) => {
     fixtureId: fixture.id,
     fragmentationCount: Math.max(0, result.finalEvents.length - 1),
     group: resolveFixtureEnvironment(fixture),
-    passes: result.errorEvents.length === 0 && result.finalText.trim().length > 0 && result.accuracy.passesThreshold && (speakerTurns ? speakerTurns.passes : true),
+    passes: result.errorEvents.length === 0 && result.finalText.trim().length > 0 && result.accuracy.passesThreshold && criticalFields.passesRequired && (speakerTurns ? speakerTurns.passes : true),
     partialCount: result.partialEvents.length,
     speakerTurns,
     postSpeechTimeToEndOfTurnMs,
@@ -739,6 +964,8 @@ var summarizeSTTBenchmark = (adapterId, fixtures) => {
     averageFinalCount: roundMetric(average(fixtures.map((fixture) => fixture.finalCount)), 2) ?? 0,
     averageSpeakerTurnMatchRate: roundMetric(average(fixtures.map((fixture) => fixture.speakerTurns?.patternMatchRate))),
     averageTermRecall: roundMetric(average(fixtures.map((fixture) => fixture.expectedTerms.recall))) ?? 0,
+    averageCriticalFieldAccuracy: roundMetric(average(fixtures.map((fixture) => fixture.criticalFields?.accuracy ?? 1))) ?? 0,
+    requiredCriticalFieldPassRate: fixtureCount > 0 ? roundMetric(fixtures.filter((fixture) => fixture.criticalFields?.passesRequired ?? true).length / fixtureCount) ?? 0 : 0,
     averagePostSpeechTimeToEndOfTurnMs: roundMetric(average(fixtures.map((fixture) => fixture.postSpeechTimeToEndOfTurnMs)), 2),
     averagePostSpeechTimeToFirstFinalMs: roundMetric(average(fixtures.map((fixture) => fixture.postSpeechTimeToFirstFinalMs)), 2),
     averageTimeToEndOfTurnMs: roundMetric(average(fixtures.map((fixture) => fixture.timeToEndOfTurnMs)), 2),
@@ -803,6 +1030,45 @@ var summarizeSTTBenchmarkSeries = (input) => {
     }
   };
 };
+// src/testing/confidenceCalibration.ts
+var clampConfidence = (value) => Math.max(0, Math.min(1, value));
+var calibrateVoiceConfidence = (samples, binCount = 10) => {
+  const safeBinCount = Math.max(1, Math.round(binCount));
+  const bins = Array.from({ length: safeBinCount }, (_, index) => {
+    const lowerBound = index / safeBinCount;
+    return {
+      accuracy: 0,
+      averageConfidence: 0,
+      count: 0,
+      lowerBound,
+      upperBound: (index + 1) / safeBinCount
+    };
+  });
+  let brierTotal = 0;
+  for (const sample of samples) {
+    const confidence = clampConfidence(sample.confidence);
+    const binIndex = Math.min(safeBinCount - 1, Math.floor(confidence * safeBinCount));
+    const bin = bins[binIndex];
+    bin.count += 1;
+    bin.averageConfidence += confidence;
+    bin.accuracy += sample.correct ? 1 : 0;
+    brierTotal += (confidence - (sample.correct ? 1 : 0)) ** 2;
+  }
+  let expectedCalibrationError = 0;
+  for (const bin of bins) {
+    if (bin.count === 0)
+      continue;
+    bin.averageConfidence /= bin.count;
+    bin.accuracy /= bin.count;
+    expectedCalibrationError += bin.count / Math.max(1, samples.length) * Math.abs(bin.accuracy - bin.averageConfidence);
+  }
+  return {
+    bins,
+    brierScore: samples.length > 0 ? brierTotal / samples.length : 0,
+    expectedCalibrationError,
+    sampleCount: samples.length
+  };
+};
 // src/core/correction.ts
 var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 var buildAliasMatcher = (alias) => new RegExp(`(?<![\\p{L}\\p{N}'])${escapeRegExp(alias)}(?![\\p{L}\\p{N}'])`, "giu");
@@ -5599,191 +5865,6 @@ var createVoiceMemoryStore = () => {
 // src/core/session.ts
 import { Buffer as Buffer2 } from "buffer";
 
-// src/core/numberNormalizer.ts
-var ONES = {
-  eight: 8,
-  eighteen: 18,
-  eleven: 11,
-  fifteen: 15,
-  five: 5,
-  four: 4,
-  fourteen: 14,
-  nine: 9,
-  nineteen: 19,
-  one: 1,
-  seven: 7,
-  seventeen: 17,
-  six: 6,
-  sixteen: 16,
-  ten: 10,
-  thirteen: 13,
-  three: 3,
-  twelve: 12,
-  two: 2,
-  zero: 0
-};
-var TENS = {
-  eighty: 80,
-  fifty: 50,
-  forty: 40,
-  ninety: 90,
-  seventy: 70,
-  sixty: 60,
-  thirty: 30,
-  twenty: 20
-};
-var SCALES = {
-  billion: 1e9,
-  million: 1e6,
-  thousand: 1000,
-  trillion: 1000000000000
-};
-var MAGNITUDE_WORDS = [
-  [1000000000000, "trillion"],
-  [1e9, "billion"],
-  [1e6, "million"]
-];
-var FILLER = new Set(["and", "a", "an"]);
-var DECIMAL_PLACES = 3;
-var isValueWord = (word) => (word in ONES) || (word in TENS) || word === "hundred";
-var isScaleWord = (word) => (word in SCALES);
-var isNumberWord = (word) => isValueWord(word) || isScaleWord(word) || word === "point" || FILLER.has(word);
-var trimNumber = (value) => {
-  if (Number.isInteger(value))
-    return value.toLocaleString("en-US");
-  return String(Number(value.toFixed(DECIMAL_PLACES)));
-};
-var renderValue = (value, usedMagnitude) => {
-  if (usedMagnitude) {
-    for (const [scale, word] of MAGNITUDE_WORDS) {
-      if (value >= scale) {
-        const scaled = value / scale;
-        if (Number(scaled.toFixed(DECIMAL_PLACES)) === scaled) {
-          return `${trimNumber(scaled)} ${word}`;
-        }
-      }
-    }
-  }
-  return trimNumber(value);
-};
-var parseNumberWords = (words) => {
-  let total = 0;
-  let current = 0;
-  let usedMagnitude = false;
-  let sawNumber = false;
-  let decimal = null;
-  const foldDecimal = () => {
-    if (decimal && decimal.length > 0)
-      current += Number(`0.${decimal}`);
-    decimal = null;
-  };
-  for (const word of words) {
-    if (word === "point") {
-      decimal = "";
-      continue;
-    }
-    const one = ONES[word];
-    const ten = TENS[word];
-    const scale = SCALES[word];
-    if (decimal !== null) {
-      if (one !== undefined && one <= 9) {
-        decimal += String(one);
-        sawNumber = true;
-        continue;
-      }
-      foldDecimal();
-    }
-    if (FILLER.has(word))
-      continue;
-    if (one !== undefined) {
-      current += one;
-      sawNumber = true;
-    } else if (ten !== undefined) {
-      current += ten;
-      sawNumber = true;
-    } else if (word === "hundred") {
-      current = (current === 0 ? 1 : current) * 100;
-      sawNumber = true;
-    } else if (scale !== undefined) {
-      total += (current === 0 ? 1 : current) * scale;
-      current = 0;
-      sawNumber = true;
-      usedMagnitude = true;
-    }
-  }
-  foldDecimal();
-  if (!sawNumber)
-    return null;
-  return { usedMagnitude, value: total + current };
-};
-var PERCENT_RE = /^(per ?cent|percent|percentage)$/;
-var CURRENCY_RE = /^(dollars?|bucks?|usd)$/;
-var WORD_RE = /^[A-Za-z]+(?:-[A-Za-z]+)*$/;
-var wordsOf = (token) => token.toLowerCase().split("-");
-var isNumberToken = (token) => WORD_RE.test(token) && wordsOf(token).every(isNumberWord);
-var startsNumber = (token) => WORD_RE.test(token) && wordsOf(token).some(isValueWord);
-var isSpace = (token) => /^\s+$/.test(token);
-var normalizeSpokenNumbers = (input) => {
-  if (!input)
-    return input;
-  const parts = input.match(/[A-Za-z]+(?:-[A-Za-z]+)*|[^A-Za-z]+/g);
-  if (!parts)
-    return input;
-  const at = (idx) => parts[idx] ?? "";
-  const out = [];
-  let i = 0;
-  while (i < parts.length) {
-    const token = at(i);
-    const lower = token.toLowerCase();
-    if (lower === "a" || lower === "an") {
-      const nextWord = at(i + 2);
-      const nextHead = wordsOf(nextWord)[0] ?? "";
-      const nextIsScale = isSpace(at(i + 1)) && WORD_RE.test(nextWord) && (nextHead === "hundred" || isScaleWord(nextHead));
-      if (!nextIsScale) {
-        out.push(token);
-        i += 1;
-        continue;
-      }
-    } else if (!startsNumber(token)) {
-      out.push(token);
-      i += 1;
-      continue;
-    }
-    const spanIdx = [i];
-    let j = i + 1;
-    while (isSpace(at(j)) && isNumberToken(at(j + 1))) {
-      spanIdx.push(j + 1);
-      j += 2;
-    }
-    const words = spanIdx.flatMap((k) => wordsOf(at(k)));
-    while (words.length > 0 && FILLER.has(words[words.length - 1] ?? "")) {
-      words.pop();
-    }
-    const parsed = parseNumberWords(words);
-    if (!parsed) {
-      out.push(token);
-      i += 1;
-      continue;
-    }
-    let rendered = renderValue(parsed.value, parsed.usedMagnitude);
-    let lastIdx = spanIdx[spanIdx.length - 1] ?? i;
-    const unitWord = at(lastIdx + 2);
-    if (isSpace(at(lastIdx + 1)) && WORD_RE.test(unitWord)) {
-      const unit = unitWord.toLowerCase();
-      if (PERCENT_RE.test(unit)) {
-        rendered = `${rendered}%`;
-        lastIdx += 2;
-      } else if (CURRENCY_RE.test(unit)) {
-        rendered = rendered.startsWith("$") ? rendered : `$${rendered}`;
-        lastIdx += 2;
-      }
-    }
-    out.push(rendered);
-    i = lastIdx + 1;
-  }
-  return out.join("");
-};
-
 // src/core/backchannel.ts
 var DEFAULT_CUES = [
   { text: "mm-hmm" },
@@ -6414,7 +6495,7 @@ var cloneTranscript = (transcript) => ({
 });
 var encodeBase64 = (chunk) => Buffer2.from(chunk).toString("base64");
 var countWords2 = (text) => text.trim().split(/\s+/).filter(Boolean).length;
-var normalizeText2 = (text) => text.trim().replace(/\s+/g, " ");
+var normalizeText3 = (text) => text.trim().replace(/\s+/g, " ");
 var getAudioChunkDurationMs = (chunk) => chunk.byteLength / (DEFAULT_FORMAT.sampleRateHz * DEFAULT_FORMAT.channels * 2) * 1000;
 var getBufferedAudioDurationMs = (chunks) => chunks.reduce((total, chunk) => total + getAudioChunkDurationMs(chunk), 0);
 var STREAM_SENTENCE_BOUNDARY = /[.!?\u2026]['")\]]*\s/;
@@ -6490,9 +6571,9 @@ var createTurnCostEstimate = (input) => {
     totalBillableAudioMs: Math.max(0, input.primaryAudioMs) + Math.max(0, input.fallbackReplayAudioMs)
   };
 };
-var normalizeCorrectionText = (text) => normalizeText2(text);
+var normalizeCorrectionText = (text) => normalizeText3(text);
 var evaluateFallbackNeed = (candidate, config) => {
-  const trimmed = normalizeText2(candidate.text);
+  const trimmed = normalizeText3(candidate.text);
   const wordCount = countWords2(trimmed);
   const averageConfidence = calculateMeanConfidence(candidate.transcripts);
   const words = collectTranscriptWords(candidate.transcripts);
@@ -6643,7 +6724,8 @@ var createVoiceSession = (options) => {
     settleMs: options.sttFallback.settleMs ?? DEFAULT_FALLBACK_SETTLE_MS,
     trigger: options.sttFallback.trigger ?? "empty-or-low-confidence",
     wordConfidenceThreshold: options.sttFallback.wordConfidenceThreshold,
-    riskPolicy: options.sttFallback.riskPolicy
+    riskPolicy: options.sttFallback.riskPolicy,
+    preferFallbackOn: options.sttFallback.preferFallbackOn
   } : undefined;
   const appendTrace = async (input) => {
     await options.trace?.append({
@@ -7900,14 +7982,18 @@ var createVoiceSession = (options) => {
     const fallbackCandidate = {
       confidence: fallbackConfidence,
       text: fallbackText,
-      wordCount: countWords2(normalizeText2(fallbackText))
+      wordCount: countWords2(normalizeText3(fallbackText))
     };
     const primaryCandidate = {
       confidence: calculateMeanConfidence(primaryTranscripts),
       text: primaryText,
-      wordCount: countWords2(normalizeText2(primaryText))
+      wordCount: countWords2(normalizeText3(primaryText))
     };
-    const selection = selectBetterTurnText(primaryCandidate, fallbackCandidate);
+    const policyPrefersFallback = fallbackCandidate.text.length > 0 && fallbackNeed.reason !== undefined && sttFallback.preferFallbackOn?.includes(fallbackNeed.reason);
+    const selection = policyPrefersFallback ? {
+      reason: "policy-preference",
+      winner: fallbackCandidate
+    } : selectBetterTurnText(primaryCandidate, fallbackCandidate);
     const diagnostics = {
       attempted: true,
       fallbackConfidence: fallbackCandidate.confidence,
@@ -7994,7 +8080,7 @@ var createVoiceSession = (options) => {
   };
   const buildTurnSignature = (session, finalText, transcriptIdsOverride) => {
     const finalTranscriptIds = transcriptIdsOverride ?? getFinalTranscriptIds(session.currentTurn.transcripts);
-    return `${normalizeText2(finalText)}|${finalTranscriptIds.join(",")}`;
+    return `${normalizeText3(finalText)}|${finalTranscriptIds.join(",")}`;
   };
   const isDuplicateTurnCommit = (session, finalText) => {
     const signature = buildTurnSignature(session, finalText);
@@ -8002,8 +8088,8 @@ var createVoiceSession = (options) => {
     const isRecent = committedTurn && committedTurn.committedAt > 0 && Date.now() - committedTurn.committedAt < DEFAULT_DUPLICATE_TURN_WINDOW_MS;
     const committedSignature = committedTurn?.signature ?? "";
     const committedTranscriptIds = committedTurn?.transcriptIds ?? [];
-    const committedText = normalizeText2(committedTurn?.text ?? "");
-    const isSameText = normalizeText2(finalText) === committedText;
+    const committedText = normalizeText3(committedTurn?.text ?? "");
+    const isSameText = normalizeText3(finalText) === committedText;
     const hasNoNewAudioSinceCommit = (session.currentTurn.lastAudioAt ?? 0) <= (committedTurn?.committedAt ?? 0);
     if (!isRecent) {
       return false;
@@ -8023,7 +8109,7 @@ var createVoiceSession = (options) => {
       ...session.lastCommittedTurn ?? {},
       committedAt: Date.now(),
       signature: buildTurnSignature(session, finalText, getFinalTranscriptIds(committedTranscripts)),
-      text: normalizeText2(finalText),
+      text: normalizeText3(finalText),
       transcriptIds: getFinalTranscriptIds(committedTranscripts)
     };
   };
@@ -9419,6 +9505,10 @@ var createVoiceSession = (options) => {
     commitTurn: async (reason = "manual") => runSerial("api.commitTurn", async () => {
       await commitTurnInternal(reason);
     }),
+    configureSTT: async (configuration) => runSerial("api.configureSTT", async () => {
+      const adapter = await ensureAdapter();
+      await adapter.configure?.(configuration);
+    }),
     complete: async (result) => runSerial("api.complete", async () => {
       await completeInternal(result);
     }),
@@ -10252,6 +10342,22 @@ var renderVoiceCallReviewMarkdown = (artifact) => {
   ].filter((value) => typeof value === "string").join(`
 `);
 };
+// src/testing/routingBenchmark.ts
+var evaluateVoiceSTTRouting = (fixtures) => {
+  const attempted = fixtures.filter((fixture) => fixture.fallbackUsed);
+  const improved = attempted.filter((fixture) => fixture.fallbackScore > fixture.primaryScore);
+  const harmed = attempted.filter((fixture) => fixture.fallbackScore < fixture.primaryScore);
+  const average3 = (values) => values.length > 0 ? values.reduce((sum, value) => sum + value, 0) / values.length : 0;
+  return {
+    fallbackAttemptRate: fixtures.length > 0 ? attempted.length / fixtures.length : 0,
+    fallbackHarmRate: attempted.length > 0 ? harmed.length / attempted.length : 0,
+    fallbackImprovementRate: attempted.length > 0 ? improved.length / attempted.length : 0,
+    fixtureCount: fixtures.length,
+    oracleScore: average3(fixtures.map((fixture) => Math.max(fixture.primaryScore, fixture.fallbackScore))),
+    primaryScore: average3(fixtures.map((fixture) => fixture.primaryScore)),
+    selectedScore: average3(fixtures.map((fixture) => fixture.fallbackUsed ? fixture.fallbackScore : fixture.primaryScore))
+  };
+};
 // src/testing/sessionBenchmark.ts
 var average3 = (values) => values.length > 0 ? values.reduce((sum, value) => sum + value, 0) / values.length : 0;
 var normalizeTurnText = (value) => value.toLowerCase().replace(/[^\p{L}\p{N}\s']/gu, " ").replace(/\s+/g, " ").trim();
@@ -15684,6 +15790,7 @@ export {
   summarizeTTSBenchmark,
   summarizeSTTBenchmarkSeries,
   summarizeSTTBenchmark,
+  scoreVoiceCriticalFields,
   scoreTranscriptAccuracy,
   scoreCorrectedExpectedTerms,
   runVoiceTelephonyMediaOperationsSmoke,
@@ -15711,6 +15818,7 @@ export {
   getDefaultVoiceTelephonyBenchmarkScenarios,
   getDefaultVoiceDuplexBenchmarkScenarios,
   getDefaultTTSBenchmarkFixtures,
+  evaluateVoiceSTTRouting,
   evaluateSTTBenchmarkAcceptance,
   createVoiceProviderFailureSimulator,
   createVoiceIOProviderFailureSimulator,
@@ -15722,6 +15830,7 @@ export {
   createCodeSwitchBenchmarkCorrectionHandler,
   createBenchmarkCorrectionHandler,
   compareSTTBenchmarks,
+  calibrateVoiceConfidence,
   buildSessionCorrectionAudit,
   buildFixturePhraseHints,
   buildCorrectionBenchmarkAudit,

package/dist/testing/routingBenchmark.d.ts

@@ -0,0 +1,16 @@
+export type VoiceSTTRoutingFixture = {
+    fallbackScore: number;
+    fallbackUsed: boolean;
+    id: string;
+    primaryScore: number;
+};
+export type VoiceSTTRoutingBenchmarkReport = {
+    fallbackAttemptRate: number;
+    fallbackHarmRate: number;
+    fallbackImprovementRate: number;
+    fixtureCount: number;
+    oracleScore: number;
+    primaryScore: number;
+    selectedScore: number;
+};
+export declare const evaluateVoiceSTTRouting: (fixtures: VoiceSTTRoutingFixture[]) => VoiceSTTRoutingBenchmarkReport;

package/package.json

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