@juspay/neurolink 12.48.1 → 12.49.0

package/dist/utils/sttProcessor.d.ts

@@ -6,7 +6,7 @@
  *
  * @module utils/sttProcessor
  */
-import type { STTOptions, STTResult, STTHandler } from "../types/index.js";
+import type { STTCredentials, STTOptions, STTResult, STTHandler } from "../types/index.js";
 /**
  * STT processor class for orchestrating speech-to-text operations
  *
@@ -71,6 +71,19 @@ export declare class STTProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName: string): STTHandler | undefined;
+    /**
+     * The handler a call should use. A credentials slice for a shipped
+     * provider builds a fresh handler for this call; otherwise the registered
+     * one is used, and a shipped provider that was never registered (its key
+     * arrived after registration, or it is the local engine on a registry that
+     * was cleared) is built from the environment rather than reported as
+     * unsupported. Names that are neither registered nor shipped resolve to
+     * `undefined`.
+     *
+     * The handler classes are loaded lazily: `voice/index.ts` imports this
+     * module, so a static import back would be a cycle.
+     */
+    static resolveHandler(provider: string, credentials?: STTCredentials): Promise<STTHandler | undefined>;
     /**
      * List the names of all registered providers.
      */
@@ -107,6 +120,11 @@ export declare class STTProcessor {
      * @param audio - Audio data as Buffer or ArrayBuffer
      * @param provider - Provider identifier
      * @param options - STT configuration options
+     * @param credentials - Per-call credentials (`credentials.stt`). When it
+     *   carries a slice for this provider — even an empty one — a fresh handler
+     *   is built from that slice (environment as fallback) for this call alone,
+     *   instead of the registry's shared instance: per-call beats instance
+     *   beats environment, exactly as for text providers.
      * @returns Transcription result with text and metadata
      * @throws STTError if validation fails or provider not supported/configured
      *
@@ -121,5 +139,5 @@ export declare class STTProcessor {
      * console.log(`Confidence: ${result.confidence}`);
      * ```
      */
-    static transcribe(audio: Buffer | ArrayBuffer, provider: string, options: STTOptions): Promise<STTResult>;
+    static transcribe(audio: Buffer | ArrayBuffer, provider: string, options: STTOptions, credentials?: STTCredentials): Promise<STTResult>;
 }

package/dist/utils/sttProcessor.js

@@ -7,6 +7,8 @@
  * @module utils/sttProcessor
  */
 import { logger } from "./logger.js";
+import { buildSpeakerTurns, listSpeakers } from "./speakerTurns.js";
+import { getSTTProviderDescriptor, resolveCallSTTEndpoints, } from "../factories/sttDescriptors.js";
 import { STT_ERROR_CODES } from "../types/index.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { STTError } from "../voice/errors.js";
@@ -84,6 +86,40 @@ export class STTProcessor {
     static getHandler(providerName) {
         return this.registry.get(providerName);
     }
+    /**
+     * The handler a call should use. A credentials slice for a shipped
+     * provider builds a fresh handler for this call; otherwise the registered
+     * one is used, and a shipped provider that was never registered (its key
+     * arrived after registration, or it is the local engine on a registry that
+     * was cleared) is built from the environment rather than reported as
+     * unsupported. Names that are neither registered nor shipped resolve to
+     * `undefined`.
+     *
+     * The handler classes are loaded lazily: `voice/index.ts` imports this
+     * module, so a static import back would be a cycle.
+     */
+    static async resolveHandler(provider, credentials) {
+        const endpoint = resolveCallSTTEndpoints(credentials)[provider.trim().toLowerCase()];
+        if (endpoint) {
+            // A per-call named endpoint: a fresh handler, never the registry's.
+            const { createSTTHandler } = await import("../voice/index.js");
+            return createSTTHandler(provider, credentials);
+        }
+        const descriptor = getSTTProviderDescriptor(provider);
+        const slice = descriptor
+            ? credentials?.[descriptor.credentialsKey]
+            : undefined;
+        if (descriptor && slice !== undefined) {
+            const { createSTTHandler } = await import("../voice/index.js");
+            return createSTTHandler(descriptor.name, credentials);
+        }
+        const registered = this.getHandler(provider);
+        if (registered || !descriptor) {
+            return registered;
+        }
+        const { createSTTHandler } = await import("../voice/index.js");
+        return createSTTHandler(descriptor.name, credentials);
+    }
     /**
      * List the names of all registered providers.
      */
@@ -134,6 +170,11 @@ export class STTProcessor {
      * @param audio - Audio data as Buffer or ArrayBuffer
      * @param provider - Provider identifier
      * @param options - STT configuration options
+     * @param credentials - Per-call credentials (`credentials.stt`). When it
+     *   carries a slice for this provider — even an empty one — a fresh handler
+     *   is built from that slice (environment as fallback) for this call alone,
+     *   instead of the registry's shared instance: per-call beats instance
+     *   beats environment, exactly as for text providers.
      * @returns Transcription result with text and metadata
      * @throws STTError if validation fails or provider not supported/configured
      *
@@ -148,7 +189,7 @@ export class STTProcessor {
      * console.log(`Confidence: ${result.confidence}`);
      * ```
      */
-    static async transcribe(audio, provider, options) {
+    static async transcribe(audio, provider, options, credentials) {
         // Create span early so preflight failures are captured
         const span = SpanSerializer.createSpan(SpanType.STT, "stt.transcribe", {
             "stt.operation": "transcribe",
@@ -186,7 +227,7 @@ export class STTProcessor {
                 });
             }
             // 2. Handler lookup and error if provider not supported
-            const handler = this.getHandler(provider);
+            const handler = await this.resolveHandler(provider, credentials);
             if (!handler) {
                 logger.error(`[STTProcessor] Provider "${provider}" is not registered`);
                 throw new STTError({
@@ -230,9 +271,12 @@ export class STTProcessor {
             // 4. Configuration check
             if (!handler.isConfigured()) {
                 logger.warn(`[STTProcessor] Provider "${provider}" is not properly configured`);
+                const hint = handler.describeConfiguration?.();
                 throw new STTError({
                     code: STT_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
-                    message: `STT provider "${provider}" is not configured. Please set the required API keys.`,
+                    message: hint
+                        ? `STT provider "${provider}" is not configured. ${hint}`
+                        : `STT provider "${provider}" is not configured. Please set the required API keys.`,
                     category: ErrorCategory.CONFIGURATION,
                     severity: ErrorSeverity.HIGH,
                     retriable: false,
@@ -240,9 +284,20 @@ export class STTProcessor {
                 });
             }
             logger.debug(`[STTProcessor] Starting transcription with provider: ${provider}`);
+            // `diarization` is documented as an alias of `speakerDiarization`, but
+            // every handler reads only the latter; fold it in here so the alias
+            // works for all of them.
+            const handlerOptions = options.diarization && options.speakerDiarization === undefined
+                ? { ...options, speakerDiarization: true }
+                : options;
             // 5. Call handler.transcribe() - providers handle their own timeouts
-            const result = await handler.transcribe(audio, options);
-            // 6. Post-processing: enrich result with provider metadata
+            const result = await handler.transcribe(audio, handlerOptions);
+            // 6. Post-processing: enrich result with provider metadata, and give
+            // every diarizing provider the same shape. Providers label speakers in
+            // different places (per word, per segment); when a handler returned
+            // speaker-labelled words but no speaker-labelled segments, derive the
+            // turns here so callers can read `segments[].speaker` regardless of
+            // provider.
             const enrichedResult = {
                 ...result,
                 metadata: {
@@ -251,6 +306,19 @@ export class STTProcessor {
                     latency: result.metadata?.latency ?? 0,
                 },
             };
+            const hasSpeakerSegments = enrichedResult.segments?.some((segment) => segment.speaker !== undefined);
+            if (!hasSpeakerSegments && enrichedResult.words) {
+                const turns = buildSpeakerTurns(enrichedResult.words);
+                if (turns.length > 0) {
+                    enrichedResult.segments = turns;
+                }
+            }
+            if (!enrichedResult.speakers?.length && enrichedResult.segments) {
+                const speakers = listSpeakers(enrichedResult.segments);
+                if (speakers.length > 0) {
+                    enrichedResult.speakers = speakers;
+                }
+            }
             // Don't log transcript content at INFO — voice transcriptions can carry
             // PII / health / financial data, and INFO is typically persisted in
             // production log aggregation (CloudWatch, Datadog, etc.). GDPR / CCPA

package/dist/voice/correction/dictionary.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dictionary matching for transcript correction.
+ *
+ * A dictionary entry names a term (a person, product, acronym …), the ways
+ * speech engines mis-hear it, and what it means. Every alias found in a
+ * transcript becomes a *candidate*: it is not applied blindly, because the
+ * alias of a name is usually an ordinary word too ("part" for a name that
+ * sounds like it). The guard (`guard.ts`) decides per candidate; this module
+ * only finds them and applies the verdicts.
+ *
+ * Matching is whole-word and script-agnostic: a word boundary is any
+ * character that is not a letter, a combining mark or a digit. Marks matter
+ * for Indic scripts, where vowel signs and viramas are `\p{M}`, not `\p{L}` —
+ * a letters-only boundary would let an alias match the first half of a word.
+ *
+ * @module voice/correction/dictionary
+ */
+import type { STTDecisionRecord, STTDictionaryCandidate, STTDictionaryEntry } from "../../types/index.js";
+/** Whether `text` contains any Indic-script character. */
+export declare function hasIndicScript(text: string): boolean;
+/**
+ * Every alias of every entry that occurs in `text` as a whole word.
+ *
+ * An entry whose term already appears in the text contributes no candidates:
+ * the engine heard the term itself, so an alias elsewhere in the same text is
+ * more likely the ordinary word. An alias in an Indic script is skipped when
+ * the text has none (it cannot match, and the check is cheaper than a regex).
+ * Each (entry, alias) pair is reported once, however often it occurs.
+ */
+export declare function findDictionaryCandidates(text: string, dictionary: readonly STTDictionaryEntry[] | undefined): STTDictionaryCandidate[];
+/**
+ * Replace every candidate the guard did not call `"literal"` with its term.
+ *
+ * `decisions[i]` belongs to `candidates[i]`; a missing decision applies the
+ * term, which is the same fail-open default the guard uses. Every occurrence
+ * is replaced — the decision was asked about the alias in this transcript, so
+ * all of its occurrences share the answer.
+ */
+export declare function applyDictionary(text: string, candidates: readonly STTDictionaryCandidate[], decisions: readonly STTDecisionRecord[]): string;
+/**
+ * The dictionary as a table for the rewrite model's system prompt, or `""`
+ * when there is nothing to show.
+ */
+export declare function dictionaryBlock(dictionary: readonly STTDictionaryEntry[] | undefined): string;
+/**
+ * Distinct dictionary terms, in dictionary order, for engines that bias
+ * recognition on a vocabulary or a context prompt.
+ */
+export declare function dictionaryVocabulary(dictionary: readonly STTDictionaryEntry[] | undefined): string[];

package/dist/voice/correction/dictionary.js

@@ -0,0 +1,134 @@
+/**
+ * Dictionary matching for transcript correction.
+ *
+ * A dictionary entry names a term (a person, product, acronym …), the ways
+ * speech engines mis-hear it, and what it means. Every alias found in a
+ * transcript becomes a *candidate*: it is not applied blindly, because the
+ * alias of a name is usually an ordinary word too ("part" for a name that
+ * sounds like it). The guard (`guard.ts`) decides per candidate; this module
+ * only finds them and applies the verdicts.
+ *
+ * Matching is whole-word and script-agnostic: a word boundary is any
+ * character that is not a letter, a combining mark or a digit. Marks matter
+ * for Indic scripts, where vowel signs and viramas are `\p{M}`, not `\p{L}` —
+ * a letters-only boundary would let an alias match the first half of a word.
+ *
+ * @module voice/correction/dictionary
+ */
+/**
+ * Any Indic script, Devanagari (U+0900) through Sinhala (U+0DFF): Bengali,
+ * Gurmukhi, Gujarati, Odia, Tamil, Telugu, Kannada and Malayalam sit between.
+ */
+const INDIC_SCRIPT_RE = /[ऀ-෿]/u;
+/** Characters that continue a word: letters, combining marks, digits. */
+const WORD_CHAR = "[\\p{L}\\p{M}\\p{N}]";
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Whole-word, case-insensitive matcher for `phrase`. Whitespace inside a
+ * multi-word alias matches any run of whitespace, since engines differ in how
+ * they space words.
+ */
+function wholeWordPattern(phrase, flags = "iu") {
+    const body = escapeRegExp(phrase.trim()).replace(/\s+/g, "\\s+");
+    return new RegExp(`(?<!${WORD_CHAR})${body}(?!${WORD_CHAR})`, flags);
+}
+/** Whether `text` contains any Indic-script character. */
+export function hasIndicScript(text) {
+    return INDIC_SCRIPT_RE.test(text);
+}
+/**
+ * Every alias of every entry that occurs in `text` as a whole word.
+ *
+ * An entry whose term already appears in the text contributes no candidates:
+ * the engine heard the term itself, so an alias elsewhere in the same text is
+ * more likely the ordinary word. An alias in an Indic script is skipped when
+ * the text has none (it cannot match, and the check is cheaper than a regex).
+ * Each (entry, alias) pair is reported once, however often it occurs.
+ */
+export function findDictionaryCandidates(text, dictionary) {
+    if (!text || !dictionary?.length) {
+        return [];
+    }
+    const textHasIndic = hasIndicScript(text);
+    const out = [];
+    for (const entry of dictionary) {
+        const term = entry?.term?.trim();
+        if (!term || !entry.heardAs?.length) {
+            continue;
+        }
+        if (wholeWordPattern(term).test(text)) {
+            continue;
+        }
+        const seen = new Set();
+        for (const alias of entry.heardAs) {
+            const heard = typeof alias === "string" ? alias.trim() : "";
+            if (!heard || seen.has(heard.toLowerCase())) {
+                continue;
+            }
+            seen.add(heard.toLowerCase());
+            if (hasIndicScript(heard) && !textHasIndic) {
+                continue;
+            }
+            if (wholeWordPattern(heard).test(text)) {
+                out.push({ entry, heard });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Replace every candidate the guard did not call `"literal"` with its term.
+ *
+ * `decisions[i]` belongs to `candidates[i]`; a missing decision applies the
+ * term, which is the same fail-open default the guard uses. Every occurrence
+ * is replaced — the decision was asked about the alias in this transcript, so
+ * all of its occurrences share the answer.
+ */
+export function applyDictionary(text, candidates, decisions) {
+    let out = text;
+    candidates.forEach((candidate, index) => {
+        if (decisions[index]?.choice === "literal") {
+            return;
+        }
+        const term = candidate.entry.term.trim();
+        // A function replacement, so a "$" in the term is never read as a group reference.
+        out = out.replace(wholeWordPattern(candidate.heard, "giu"), () => term);
+    });
+    return out;
+}
+/**
+ * The dictionary as a table for the rewrite model's system prompt, or `""`
+ * when there is nothing to show.
+ */
+export function dictionaryBlock(dictionary) {
+    const rows = (dictionary ?? [])
+        .filter((entry) => entry?.term?.trim())
+        .map((entry) => {
+        const heard = (entry.heardAs ?? [])
+            .map((alias) => alias.trim())
+            .filter(Boolean)
+            .join(", ");
+        return `${entry.term.trim()} | ${heard || "-"} | ${entry.meaning?.trim() || "-"}`;
+    });
+    return rows.length
+        ? `Dictionary (term | also heard as | meaning):\n${rows.join("\n")}`
+        : "";
+}
+/**
+ * Distinct dictionary terms, in dictionary order, for engines that bias
+ * recognition on a vocabulary or a context prompt.
+ */
+export function dictionaryVocabulary(dictionary) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of dictionary ?? []) {
+        const term = entry?.term?.trim();
+        if (term && !seen.has(term.toLowerCase())) {
+            seen.add(term.toLowerCase());
+            out.push(term);
+        }
+    }
+    return out;
+}

package/dist/voice/correction/guard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Decision-model guard for dictionary substitutions.
+ *
+ * An alias is usually an ordinary word as well ("part" is how engines hear a
+ * name that sounds like it), so applying the dictionary blindly rewrites the
+ * literal word every time it is said. The guard asks a decision model, in one
+ * request, one question per candidate: did the speaker mean the term, or the
+ * word as written?
+ *
+ * Why a `choice` and not a yes/no: a boolean "is this the name X?" question
+ * was measured to be leading — it said yes to nearly everything. A choice
+ * between the term and the literal reading, each with its own rubric,
+ * discriminates: "my name is part" → the term at 97%, "part of the plan" →
+ * literal. Answers are matched by position (`candidate__N`), never by the
+ * alias text, so an alias the wire normalises cannot misroute an answer.
+ *
+ * Fail-open, like every other `decide` consumer: with no decision provider,
+ * on timeout (default 4 s) or on any error the dictionary is applied as is,
+ * and each record says why in `note`.
+ *
+ * @module voice/correction/guard
+ */
+import type { STTCorrectionDeps, STTDecisionRecord, STTDictionaryCandidate } from "../../types/index.js";
+/** Default guard timeout; on expiry the dictionary is applied as is. */
+export declare const DEFAULT_DECIDE_TIMEOUT_MS = 4000;
+/**
+ * Judge every candidate in one decision request. Returns one record per
+ * candidate, in candidate order; a candidate the guard could not judge is
+ * recorded as `"term"` with a `note` saying why, so `applyDictionary` applies
+ * it exactly as it would without a guard.
+ */
+export declare function decideCandidates(text: string, candidates: readonly STTDictionaryCandidate[], decide: STTCorrectionDeps["decide"] | undefined, options?: {
+    context?: string;
+    timeoutMs?: number;
+}): Promise<STTDecisionRecord[]>;

package/dist/voice/correction/guard.js

@@ -0,0 +1,161 @@
+/**
+ * Decision-model guard for dictionary substitutions.
+ *
+ * An alias is usually an ordinary word as well ("part" is how engines hear a
+ * name that sounds like it), so applying the dictionary blindly rewrites the
+ * literal word every time it is said. The guard asks a decision model, in one
+ * request, one question per candidate: did the speaker mean the term, or the
+ * word as written?
+ *
+ * Why a `choice` and not a yes/no: a boolean "is this the name X?" question
+ * was measured to be leading — it said yes to nearly everything. A choice
+ * between the term and the literal reading, each with its own rubric,
+ * discriminates: "my name is part" → the term at 97%, "part of the plan" →
+ * literal. Answers are matched by position (`candidate__N`), never by the
+ * alias text, so an alias the wire normalises cannot misroute an answer.
+ *
+ * Fail-open, like every other `decide` consumer: with no decision provider,
+ * on timeout (default 4 s) or on any error the dictionary is applied as is,
+ * and each record says why in `note`.
+ *
+ * @module voice/correction/guard
+ */
+import { decisionKey } from "../../utils/decisionAnswers.js";
+import { TimeoutError, withTimeout } from "../../utils/async/withTimeout.js";
+import { logger } from "../../utils/logger.js";
+/** Namespace for the per-candidate questions. */
+const CANDIDATE_NAMESPACE = "candidate";
+/** Default guard timeout; on expiry the dictionary is applied as is. */
+export const DEFAULT_DECIDE_TIMEOUT_MS = 4000;
+/** Sent as `context` when the caller gave none. */
+const DEFAULT_CONTEXT = "Speech transcript; names and product terms are often misheard.";
+/**
+ * Upper bound on the transcript sent as state. Decision providers declare
+ * state windows (some well under 1,000 tokens); an over-limit request is
+ * refused before any network call and the guard fails open, so a long
+ * transcript costs nothing but the decision — still, the words around a
+ * candidate carry the signal, and a bounded state keeps the request cheap.
+ */
+const MAX_STATE_CHARS = 4000;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const finiteNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+function candidateQuestion(candidate) {
+    const { entry, heard } = candidate;
+    const meaning = entry.meaning?.trim();
+    return {
+        type: "choice",
+        instructions: `The speech recognizer wrote "${heard}". Which did the speaker mean?`,
+        criteria: {
+            term: `the term "${entry.term.trim()}"${meaning ? `: ${meaning}` : ""}`,
+            literal: `"${heard}" as an ordinary word or other name, meant literally`,
+        },
+    };
+}
+/**
+ * Read one choice answer without trusting its shape: the deps type hands the
+ * answer map over as `unknown`, and a provider may omit an id or answer with
+ * a different type. Returns undefined when there is no usable term/literal
+ * verdict.
+ */
+function readTermOrLiteral(answer) {
+    if (!isRecord(answer) ||
+        (answer.type !== undefined && answer.type !== "choice")) {
+        return undefined;
+    }
+    const probabilities = isRecord(answer.probabilities)
+        ? answer.probabilities
+        : {};
+    const pTerm = finiteNumber(probabilities.term);
+    const pLiteral = finiteNumber(probabilities.literal);
+    let choice;
+    if (answer.choice === "term" || answer.choice === "literal") {
+        choice = answer.choice;
+    }
+    else if (pTerm !== undefined || pLiteral !== undefined) {
+        // No winner named, but a distribution: take its argmax.
+        const term = pTerm ?? 1 - (pLiteral ?? 0);
+        const literal = pLiteral ?? 1 - term;
+        choice = term >= literal ? "term" : "literal";
+    }
+    if (!choice) {
+        return undefined;
+    }
+    const probability = choice === "term"
+        ? (pTerm ?? (pLiteral !== undefined ? 1 - pLiteral : undefined))
+        : (pLiteral ?? (pTerm !== undefined ? 1 - pTerm : undefined));
+    return { choice, probability, confidence: finiteNumber(answer.confidence) };
+}
+/**
+ * Judge every candidate in one decision request. Returns one record per
+ * candidate, in candidate order; a candidate the guard could not judge is
+ * recorded as `"term"` with a `note` saying why, so `applyDictionary` applies
+ * it exactly as it would without a guard.
+ */
+export async function decideCandidates(text, candidates, decide, options) {
+    if (candidates.length === 0) {
+        return [];
+    }
+    const asIs = (note) => candidates.map((candidate) => ({
+        heard: candidate.heard,
+        term: candidate.entry.term.trim(),
+        choice: "term",
+        note,
+    }));
+    if (typeof decide !== "function") {
+        return asIs("no decision provider");
+    }
+    const questions = {};
+    candidates.forEach((candidate, index) => {
+        questions[decisionKey(CANDIDATE_NAMESPACE, index)] =
+            candidateQuestion(candidate);
+    });
+    const timeoutMs = options?.timeoutMs && options.timeoutMs > 0
+        ? options.timeoutMs
+        : DEFAULT_DECIDE_TIMEOUT_MS;
+    let result;
+    try {
+        // The provider gets the timeout too, but the race is what guarantees it:
+        // a decide implementation that ignores `timeoutMs` must not stall the
+        // transcript.
+        result = await withTimeout(decide({
+            state: {
+                transcript: text.slice(0, MAX_STATE_CHARS),
+                context: options?.context?.trim() || DEFAULT_CONTEXT,
+            },
+            questions,
+            timeoutMs,
+        }), timeoutMs);
+    }
+    catch (error) {
+        const timedOut = error instanceof TimeoutError;
+        logger.debug("[transcribe] decision guard failed open", {
+            candidates: candidates.length,
+            timedOut,
+        });
+        return asIs(timedOut ? "decision timed out" : "decision unavailable");
+    }
+    // `tryDecide` returns null both when no decision provider is configured and
+    // when the call failed; the two are indistinguishable from here.
+    if (!result || !isRecord(result.answers)) {
+        return asIs("decision unavailable");
+    }
+    const answers = result.answers;
+    return candidates.map((candidate, index) => {
+        const verdict = readTermOrLiteral(answers[decisionKey(CANDIDATE_NAMESPACE, index)]);
+        const record = {
+            heard: candidate.heard,
+            term: candidate.entry.term.trim(),
+            choice: verdict?.choice ?? "term",
+        };
+        if (verdict?.probability !== undefined) {
+            record.probability = verdict.probability;
+        }
+        if (verdict?.confidence !== undefined) {
+            record.confidence = verdict.confidence;
+        }
+        if (!verdict) {
+            record.note = "no answer · applied as is";
+        }
+        return record;
+    });
+}

package/dist/voice/correction/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Transcript correction: dictionary candidates → decision-model guard → LLM
+ * rewrite.
+ *
+ * Every layer fails open and none may lose words. With no decision provider,
+ * on a guard timeout or error, the dictionary is applied as is; on a rewrite
+ * timeout or error, or a rewrite that drops too many words, the
+ * dictionary-applied text is kept. The result's `steps` say which of those
+ * happened, so a silently degraded path is still visible to the caller.
+ *
+ * @module voice/correction
+ */
+import { applyDictionary, dictionaryBlock, dictionaryVocabulary, findDictionaryCandidates } from "./dictionary.js";
+import { decideCandidates } from "./guard.js";
+import { buildRewriteSystemPrompt, buildRewriteUserPrompt, rewriteLines, rewriteTranscript } from "./rewrite.js";
+import type { STTCorrectionDeps, STTCorrectionInput, STTCorrectionOptions, STTCorrectionOutput, STTDecisionRecord, STTDictionaryEntry } from "../../types/index.js";
+export { applyDictionary, buildRewriteSystemPrompt, buildRewriteUserPrompt, decideCandidates, dictionaryBlock, dictionaryVocabulary, findDictionaryCandidates, rewriteLines, rewriteTranscript, };
+/** Correction is on when asked for, or by default when a dictionary or a rewrite is configured. */
+export declare function isCorrectionEnabled(dictionary: readonly STTDictionaryEntry[] | undefined, options: STTCorrectionOptions | undefined): boolean;
+/**
+ * Correct one transcript (a whole short recording, or one final utterance
+ * when streaming). Never throws on a layer's failure and never returns empty
+ * text when either transcript had words.
+ *
+ * When the primary engine reported a low language score
+ * (`languageDetected === false`) and a second opinion exists, the second
+ * opinion leads: an Indic engine on English speech produces confident-looking
+ * nonsense, and the English-oriented engine's text is the better base. The
+ * engine text then goes to the rewrite as the secondary transcript, so
+ * Indian-language words it did catch are not lost.
+ */
+export declare function correctTranscript(input: STTCorrectionInput, deps: STTCorrectionDeps): Promise<STTCorrectionOutput>;
+/**
+ * Correct a long transcript line by line (file transcription, diarized
+ * turns). With the rewrite on, lines go to the model in numbered batches of
+ * 25 and the dictionary travels in the prompt — the model sees each alias in
+ * its sentence, which is the context the guard would otherwise supply. With
+ * `rewrite: false`, each line with candidates gets its own guard call (up to
+ * four at a time) and the dictionary is applied per line. The result always
+ * has exactly as many lines as the input.
+ */
+export declare function correctTranscriptLines(lines: readonly string[], dictionary: readonly STTDictionaryEntry[] | undefined, options: STTCorrectionOptions | undefined, deps: STTCorrectionDeps): Promise<{
+    lines: string[];
+    decisions: STTDecisionRecord[];
+    steps: string[];
+    timings: STTCorrectionOutput["timings"];
+}>;