redmine-context 1.0.0

package/dist/extract/audio-extractor.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Extrator de ÁUDIO que encadeia conversão → transcrição (M4-14, #73, ADR-002).
+ *
+ * Fecha a lacuna do gap analysis: o whisper.cpp (#61) só consome WAV PCM 16 kHz
+ * mono, mas os anexos de áudio chegam crus (MP3/M4A/OGG/WAV arbitrário). Este
+ * extrator implementa o contrato {@link Extractor} e orquestra, num único job:
+ *
+ *   arquivo de áudio cru → {@link convertAudioToWav} (#60) → {@link WhisperExtractor} (#61)
+ *
+ * Registrá-lo no registry default (em vez do whisper direto — MINOR-2 do QA) faz o
+ * `dispatchExtraction` rotear áudio automaticamente por magic bytes, produzindo a
+ * transcrição no caminho REAL (`extractIssueAttachments`), não mais `unsupported`.
+ *
+ * DECISÕES (ADR-002/ADR-004):
+ * - CONVERSÃO SEMPRE: mesmo um `.wav` é reprocessado pelo ffmpeg para GARANTIR 16
+ *   kHz mono PCM (um WAV 44,1 kHz estéreo transcreveria errado). É a mesma política
+ *   do pipeline de vídeo ({@link convertVideoToWav}); o ganho de pular a conversão
+ *   de um WAV já-16k não compensa o risco de silenciosamente transcrever mal.
+ * - CACHE (ADR-004): `version`/`model`/`params` são DELEGADOS ao transcritor whisper
+ *   — a chave attachment-level reflete o modelo GGUF e o idioma, então trocar o
+ *   modelo reprocessa e o mesmo modelo é cache-hit (mesma invariante da #72).
+ * - DEGRADAÇÃO GRACIOSA: ffmpeg/whisper/modelo ausente ou timeout → `failed` com
+ *   motivo, NUNCA lança (o bundle segue). O WAV intermediário é sempre limpo.
+ * - SEGURANÇA: reusa a invocação segura da #60/#61 (execFile sem shell,
+ *   `-protocol_whitelist file`, env sanitizado, watchdog) — nada de spawn novo aqui.
+ */
+import type { ExtractorParams } from '../cache/contract.js';
+import type { ExtractionResult } from '../contract.js';
+import { type ConvertAudioToWavOptions, type WavConversionResult } from './audio.js';
+import type { ExtractOptions, Extractor } from './dispatcher.js';
+/**
+ * MIMEs REAIS de áudio roteados para este extrator. Reusa a lista do whisper (#61)
+ * para cobertura idêntica à que o whisper cobria quando registrado diretamente.
+ */
+export declare const AUDIO_MIMES: readonly string[];
+/** Opções de construção do {@link AudioExtractor}. */
+export interface AudioExtractorOptions {
+    /**
+     * Extrator whisper (#61) que transcreve o WAV. `version`/`model`/`params` dele
+     * definem a identidade de cache deste extrator (ADR-004).
+     */
+    readonly transcriber: Extractor;
+    /**
+     * Conversão áudio → WAV; default: {@link convertAudioToWav} (com o `logger`
+     * repassado). Injetável para testes herméticos sem ffmpeg real.
+     */
+    readonly convert?: (inputPath: string) => Promise<WavConversionResult>;
+    /** Opções repassadas à conversão default (binário, timeouts, tempDir). */
+    readonly convertOptions?: ConvertAudioToWavOptions;
+    /** Remove o WAV intermediário após a transcrição (best-effort); default `fs.rm` com `force`. */
+    readonly rm?: (path: string) => Promise<void>;
+}
+/**
+ * Extrator de áudio (ADR-002) que converte o anexo para WAV 16 kHz mono e o
+ * transcreve via whisper.cpp. Implementa {@link Extractor} e expõe `version`/
+ * `model`/`params` do transcritor para {@link buildAttachmentKey} (ADR-004).
+ */
+export declare class AudioExtractor implements Extractor {
+    readonly id = "audio-transcribe";
+    readonly version: string;
+    readonly supportedMimes: readonly string[];
+    /** Modelo lógico da chave de cache — herdado do whisper (GGUF), fallback no id. */
+    readonly model: string;
+    /** Parâmetros da chave de cache — herdados do whisper (ex.: `{ language }`). */
+    readonly params: ExtractorParams;
+    private readonly transcriber;
+    private readonly convert;
+    private readonly convertOptions;
+    private readonly rm;
+    /**
+     * @param options - Ver {@link AudioExtractorOptions}.
+     */
+    constructor(options: AudioExtractorOptions);
+    /**
+     * Transcreve o áudio em `filePath`: converte para WAV 16 kHz mono e passa ao
+     * whisper. Nunca lança — falha de conversão (ffmpeg ausente/timeout) ou de
+     * transcrição vira `{ status: 'failed', reason }` (ADR-002). O WAV intermediário
+     * é sempre removido (best-effort).
+     *
+     * @param filePath - Caminho absoluto do áudio baixado no cache.
+     * @param options - MIME real + logger — ver {@link ExtractOptions}.
+     * @returns `done` com `text` no sucesso; `failed` com motivo claro na falha.
+     */
+    extract(filePath: string, options: ExtractOptions): Promise<ExtractionResult>;
+    /**
+     * Roda a conversão áudio → WAV (injetável nos testes; default: ffmpeg real da #60).
+     *
+     * @param filePath - Caminho do áudio cru.
+     * @param logger - Logger repassado à conversão default.
+     * @param signal - Sinal de cancelamento (#69/#73) fiado ao ffmpeg da conversão default.
+     * @returns Resultado da conversão (`done` com `wavPath` ou `failed` com motivo).
+     */
+    private runConvert;
+}
+/**
+ * Cria um {@link AudioExtractor} a partir de um transcritor whisper. Fino wrapper
+ * de composição — ponto de entrada consumido por {@link createDefaultRegistry}.
+ *
+ * @param options - Transcritor + deps injetáveis — ver {@link AudioExtractorOptions}.
+ * @returns O extrator pronto para registro no {@link ExtractorRegistry}.
+ * @example
+ * const whisper = await createWhisperExtractor();
+ * const audio = createAudioExtractor({ transcriber: whisper });
+ */
+export declare function createAudioExtractor(options: AudioExtractorOptions): AudioExtractor;

package/dist/extract/audio-extractor.js

@@ -0,0 +1,156 @@
+/**
+ * Extrator de ÁUDIO que encadeia conversão → transcrição (M4-14, #73, ADR-002).
+ *
+ * Fecha a lacuna do gap analysis: o whisper.cpp (#61) só consome WAV PCM 16 kHz
+ * mono, mas os anexos de áudio chegam crus (MP3/M4A/OGG/WAV arbitrário). Este
+ * extrator implementa o contrato {@link Extractor} e orquestra, num único job:
+ *
+ *   arquivo de áudio cru → {@link convertAudioToWav} (#60) → {@link WhisperExtractor} (#61)
+ *
+ * Registrá-lo no registry default (em vez do whisper direto — MINOR-2 do QA) faz o
+ * `dispatchExtraction` rotear áudio automaticamente por magic bytes, produzindo a
+ * transcrição no caminho REAL (`extractIssueAttachments`), não mais `unsupported`.
+ *
+ * DECISÕES (ADR-002/ADR-004):
+ * - CONVERSÃO SEMPRE: mesmo um `.wav` é reprocessado pelo ffmpeg para GARANTIR 16
+ *   kHz mono PCM (um WAV 44,1 kHz estéreo transcreveria errado). É a mesma política
+ *   do pipeline de vídeo ({@link convertVideoToWav}); o ganho de pular a conversão
+ *   de um WAV já-16k não compensa o risco de silenciosamente transcrever mal.
+ * - CACHE (ADR-004): `version`/`model`/`params` são DELEGADOS ao transcritor whisper
+ *   — a chave attachment-level reflete o modelo GGUF e o idioma, então trocar o
+ *   modelo reprocessa e o mesmo modelo é cache-hit (mesma invariante da #72).
+ * - DEGRADAÇÃO GRACIOSA: ffmpeg/whisper/modelo ausente ou timeout → `failed` com
+ *   motivo, NUNCA lança (o bundle segue). O WAV intermediário é sempre limpo.
+ * - SEGURANÇA: reusa a invocação segura da #60/#61 (execFile sem shell,
+ *   `-protocol_whitelist file`, env sanitizado, watchdog) — nada de spawn novo aqui.
+ */
+import { rm as fsRm } from 'node:fs/promises';
+import { convertAudioToWav, } from './audio.js';
+import { WHISPER_MIMES } from './whisper-extract.js';
+/** Identificador estável do extrator (entra em metadados/cache-key como fallback). */
+const EXTRACTOR_ID = 'audio-transcribe';
+/**
+ * MIMEs REAIS de áudio roteados para este extrator. Reusa a lista do whisper (#61)
+ * para cobertura idêntica à que o whisper cobria quando registrado diretamente.
+ */
+export const AUDIO_MIMES = WHISPER_MIMES;
+/**
+ * Extrator de áudio (ADR-002) que converte o anexo para WAV 16 kHz mono e o
+ * transcreve via whisper.cpp. Implementa {@link Extractor} e expõe `version`/
+ * `model`/`params` do transcritor para {@link buildAttachmentKey} (ADR-004).
+ */
+export class AudioExtractor {
+    id = EXTRACTOR_ID;
+    version;
+    supportedMimes = AUDIO_MIMES;
+    /** Modelo lógico da chave de cache — herdado do whisper (GGUF), fallback no id. */
+    model;
+    /** Parâmetros da chave de cache — herdados do whisper (ex.: `{ language }`). */
+    params;
+    transcriber;
+    convert;
+    convertOptions;
+    rm;
+    /**
+     * @param options - Ver {@link AudioExtractorOptions}.
+     */
+    constructor(options) {
+        this.transcriber = options.transcriber;
+        this.version = options.transcriber.version;
+        // Reason (ADR-004): a identidade de cache deste extrator É a do whisper — trocar
+        // o GGUF/idioma reprocessa; sem model/params no transcritor, cai no id estável.
+        this.model = options.transcriber.model ?? EXTRACTOR_ID;
+        this.params = options.transcriber.params ?? {};
+        this.convert = options.convert;
+        this.convertOptions = options.convertOptions;
+        this.rm = options.rm ?? ((path) => fsRm(path, { force: true }));
+    }
+    /**
+     * Transcreve o áudio em `filePath`: converte para WAV 16 kHz mono e passa ao
+     * whisper. Nunca lança — falha de conversão (ffmpeg ausente/timeout) ou de
+     * transcrição vira `{ status: 'failed', reason }` (ADR-002). O WAV intermediário
+     * é sempre removido (best-effort).
+     *
+     * @param filePath - Caminho absoluto do áudio baixado no cache.
+     * @param options - MIME real + logger — ver {@link ExtractOptions}.
+     * @returns `done` com `text` no sucesso; `failed` com motivo claro na falha.
+     */
+    async extract(filePath, options) {
+        const conversion = await this.runConvert(filePath, options.logger, options.signal);
+        if (conversion.status === 'failed') {
+            return conversionFailure(this.id, options.mime, conversion);
+        }
+        const wavPath = conversion.wavPath;
+        try {
+            // `options` (com o `signal` de #69/#73) é repassado ao transcritor: o abort
+            // alcança o whisper e MATA o subprocesso via `runWithWatchdog`.
+            return await this.transcriber.extract(wavPath, options);
+        }
+        catch (error) {
+            // Reason: o whisper é gracioso por contrato, mas um transcritor injetado
+            // hostil/quebrado não pode derrubar o bundle — degrada para failed (ADR-002).
+            return {
+                status: 'failed',
+                mime: options.mime,
+                metadata: {
+                    extractorId: this.id,
+                    reason: 'erro-transcricao',
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+        finally {
+            // O WAV é um artefato intermediário do cache temp; descarta em qualquer
+            // desfecho para não acumular lixo (convenção de `audio.ts`/`video.ts`).
+            await this.rm(wavPath).catch(() => undefined);
+        }
+    }
+    /**
+     * Roda a conversão áudio → WAV (injetável nos testes; default: ffmpeg real da #60).
+     *
+     * @param filePath - Caminho do áudio cru.
+     * @param logger - Logger repassado à conversão default.
+     * @param signal - Sinal de cancelamento (#69/#73) fiado ao ffmpeg da conversão default.
+     * @returns Resultado da conversão (`done` com `wavPath` ou `failed` com motivo).
+     */
+    runConvert(filePath, logger, signal) {
+        if (this.convert !== undefined) {
+            return this.convert(filePath);
+        }
+        return convertAudioToWav(filePath, {
+            ...(this.convertOptions ?? {}),
+            ...(logger !== undefined ? { logger } : {}),
+            ...(signal !== undefined ? { signal } : {}),
+        });
+    }
+}
+/**
+ * Monta um {@link ExtractionResult} `failed` a partir de uma falha de conversão,
+ * sem injetar chaves `undefined` (respeita `exactOptionalPropertyTypes`).
+ *
+ * @param extractorId - Id do extrator que reporta a falha.
+ * @param mime - MIME real do áudio.
+ * @param failure - Falha devolvida pela conversão áudio → WAV.
+ * @returns Resultado `failed` com `reason`/`error`/`hint` preservados.
+ */
+function conversionFailure(extractorId, mime, failure) {
+    const metadata = { extractorId, reason: failure.reason };
+    if (failure.error !== undefined)
+        metadata.error = failure.error;
+    if (failure.hint !== undefined)
+        metadata.hint = failure.hint;
+    return { status: 'failed', mime, metadata };
+}
+/**
+ * Cria um {@link AudioExtractor} a partir de um transcritor whisper. Fino wrapper
+ * de composição — ponto de entrada consumido por {@link createDefaultRegistry}.
+ *
+ * @param options - Transcritor + deps injetáveis — ver {@link AudioExtractorOptions}.
+ * @returns O extrator pronto para registro no {@link ExtractorRegistry}.
+ * @example
+ * const whisper = await createWhisperExtractor();
+ * const audio = createAudioExtractor({ transcriber: whisper });
+ */
+export function createAudioExtractor(options) {
+    return new AudioExtractor(options);
+}

package/dist/extract/audio.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Conversão de áudio para WAV 16 kHz mono via `ffmpeg` (M4-04, #60, ADR-002).
+ *
+ * Prepara um anexo de áudio para a transcrição pelo whisper.cpp (#61, M4-05), que
+ * espera PCM 16-bit, 16 kHz, mono. Esta issue cobre SÓ a conversão áudio → WAV; a
+ * extração de faixa de áudio a partir de vídeo é a #63 (M4-07) e o extrator
+ * whisper é a #61 — nenhum dos dois é implementado aqui.
+ *
+ * DECISÕES DE SEGURANÇA/ROBUSTEZ (ADR-002), todas exercitadas por testes:
+ *
+ * - INVOCAÇÃO SEM SHELL: `execFile` (nunca `exec`/shell) com lista de argumentos
+ *   explícita — o `inputPath` NUNCA é interpolado numa string de shell.
+ * - `-protocol_whitelist file`: o ffmpeg só pode abrir o arquivo local dado, nunca
+ *   protocolos remotos embutidos em playlists/manifests hostis (asserção explícita
+ *   nos args pelo teste).
+ * - ENV SANITIZADO: o subprocesso recebe um env MÍNIMO (só `PATH`) — segredos do
+ *   processo pai (ex.: `REDMINE_API_KEY`) NUNCA vazam para o ffmpeg.
+ * - TIMEOUT + KILL: watchdog envia `SIGTERM` no timeout e, após a graça, `SIGKILL`
+ *   — um ffmpeg travado não pendura a fila de jobs.
+ * - DEGRADAÇÃO GRACIOSA: binário ausente, exit != 0 ou timeout NÃO lançam; devolvem
+ *   {@link WavConversionResult} com `status: 'failed'` + motivo legível, sem quebrar
+ *   o bundle.
+ *
+ * TESTABILIDADE: o executor do subprocesso, o localizador do ffmpeg, o dir temp e o
+ * `mkdir` são INJETÁVEIS — os testes unitários são herméticos (sem ffmpeg/FS reais)
+ * e asseguram os args passados ao executor.
+ */
+import type { Logger } from '../client/index.js';
+import type { ExtractionStatus } from '../contract.js';
+/**
+ * Diretório canônico do cache onde os WAVs temporários são gravados — `env-paths`
+ * cache do usuário (por SO) + `/tmp`. Mesmo mecanismo dos demais módulos de mídia
+ * ({@link whisperModelDir}).
+ *
+ * @returns Caminho absoluto do dir temp (ex.: `~/Library/Caches/redmine-context/tmp`).
+ * @example
+ * const dir = audioTempDir();
+ */
+export declare function audioTempDir(): string;
+/** Invocação concreta do ffmpeg passada ao {@link FfmpegRunner}. */
+export interface FfmpegInvocation {
+    /** Caminho absoluto do binário `ffmpeg` já resolvido. */
+    readonly bin: string;
+    /** Argumentos do ffmpeg (sem shell), incluindo `-protocol_whitelist file`. */
+    readonly args: readonly string[];
+    /** Env SANITIZADO do subprocesso (só `PATH`). */
+    readonly env: NodeJS.ProcessEnv;
+    /** Timeout antes do `SIGTERM` (ms). */
+    readonly timeoutMs: number;
+    /** Graça `SIGTERM` → `SIGKILL` (ms). */
+    readonly killGraceMs: number;
+    /**
+     * Sinal de CANCELAMENTO (#69/#73) repassado ao {@link runWithWatchdog}, que MATA
+     * o ffmpeg (`SIGTERM`→`SIGKILL`) ao abortar. Opcional/aditivo (respeita
+     * `exactOptionalPropertyTypes` — nunca injetado como `undefined`).
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Executor injetável do subprocesso ffmpeg. Resolve no sucesso (exit 0); rejeita
+ * em falha (exit != 0, binário não-executável em runtime) — rejeitando com um erro
+ * de nome `FfmpegTimeoutError` para sinalizar estouro de timeout.
+ */
+export type FfmpegRunner = (invocation: FfmpegInvocation) => Promise<void>;
+/** Sucesso da conversão: caminho do WAV 16 kHz mono gravado no dir temp. */
+export interface WavConversionSuccess {
+    readonly status: Extract<ExtractionStatus, 'done'>;
+    /** Caminho absoluto do WAV produzido no dir temp do cache. */
+    readonly wavPath: string;
+}
+/** Falha graciosa da conversão (ADR-002) — nunca lança, sempre traz um motivo. */
+export interface WavConversionFailure {
+    readonly status: Extract<ExtractionStatus, 'failed'>;
+    /** Motivo canônico da falha (`ffmpeg-nao-instalado` | `erro-conversao` | `timeout`). */
+    readonly reason: string;
+    /** Mensagem de erro subjacente, quando houver. */
+    readonly error?: string;
+    /** Dica de remediação (ex.: como instalar o ffmpeg). */
+    readonly hint?: string;
+}
+/**
+ * Resultado tipado da conversão áudio → WAV. Reutiliza o vocabulário de status do
+ * core ({@link ExtractionStatus}) — sem status paralelo.
+ */
+export type WavConversionResult = WavConversionSuccess | WavConversionFailure;
+/** Opções (todas injetáveis para testes herméticos) de {@link convertAudioToWav}. */
+export interface ConvertAudioToWavOptions {
+    /**
+     * Localizador do binário `ffmpeg`; retorna o caminho absoluto ou `undefined`
+     * (não instalado). Default: {@link findFfmpeg} no ambiente real.
+     */
+    readonly findFfmpegBinary?: () => string | undefined;
+    /** Executor do subprocesso; default: watchdog real com `execFile`. */
+    readonly run?: FfmpegRunner;
+    /** Dir temp de saída; default: {@link audioTempDir}. */
+    readonly tempDir?: string;
+    /** Criador de diretório (recursivo); default: `fs/promises.mkdir`. */
+    readonly mkdir?: (dir: string) => Promise<void>;
+    /** Remove o `.wav` parcial na falha (best-effort); default: `fs/promises.rm` com `force`. */
+    readonly rm?: (path: string) => Promise<void>;
+    /** Timeout antes do `SIGTERM` (ms); default {@link DEFAULT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Graça `SIGTERM` → `SIGKILL` (ms); default {@link DEFAULT_KILL_GRACE_MS}. */
+    readonly killGraceMs?: number;
+    /**
+     * Sinal de CANCELAMENTO (#69/#73) repassado à invocação/`runWithWatchdog`, que
+     * MATA o ffmpeg ao abortar. Opcional/aditivo (respeita `exactOptionalPropertyTypes`).
+     */
+    readonly signal?: AbortSignal;
+    /** Logger para o aviso de binário ausente; sem default de lib (ADR-003). */
+    readonly logger?: Logger;
+}
+/**
+ * Converte um arquivo de áudio para WAV PCM 16-bit, 16 kHz, mono no dir temp do
+ * cache — o formato que o whisper.cpp (#61) consome. NUNCA lança: binário ausente,
+ * exit != 0 ou timeout viram `{ status: 'failed', reason }` (degradação graciosa,
+ * ADR-002), preservando o bundle.
+ *
+ * @param inputPath - Caminho absoluto do áudio de entrada já baixado no cache.
+ * @param options - Deps injetáveis + timeouts + logger — ver {@link ConvertAudioToWavOptions}.
+ * @returns `done` com `wavPath` no sucesso; `failed` com motivo claro na falha.
+ * @example
+ * const result = await convertAudioToWav('/cache/att/original.mp3');
+ * if (result.status === 'done') transcribe(result.wavPath);
+ */
+export declare function convertAudioToWav(inputPath: string, options?: ConvertAudioToWavOptions): Promise<WavConversionResult>;

package/dist/extract/audio.js

@@ -0,0 +1,184 @@
+/**
+ * Conversão de áudio para WAV 16 kHz mono via `ffmpeg` (M4-04, #60, ADR-002).
+ *
+ * Prepara um anexo de áudio para a transcrição pelo whisper.cpp (#61, M4-05), que
+ * espera PCM 16-bit, 16 kHz, mono. Esta issue cobre SÓ a conversão áudio → WAV; a
+ * extração de faixa de áudio a partir de vídeo é a #63 (M4-07) e o extrator
+ * whisper é a #61 — nenhum dos dois é implementado aqui.
+ *
+ * DECISÕES DE SEGURANÇA/ROBUSTEZ (ADR-002), todas exercitadas por testes:
+ *
+ * - INVOCAÇÃO SEM SHELL: `execFile` (nunca `exec`/shell) com lista de argumentos
+ *   explícita — o `inputPath` NUNCA é interpolado numa string de shell.
+ * - `-protocol_whitelist file`: o ffmpeg só pode abrir o arquivo local dado, nunca
+ *   protocolos remotos embutidos em playlists/manifests hostis (asserção explícita
+ *   nos args pelo teste).
+ * - ENV SANITIZADO: o subprocesso recebe um env MÍNIMO (só `PATH`) — segredos do
+ *   processo pai (ex.: `REDMINE_API_KEY`) NUNCA vazam para o ffmpeg.
+ * - TIMEOUT + KILL: watchdog envia `SIGTERM` no timeout e, após a graça, `SIGKILL`
+ *   — um ffmpeg travado não pendura a fila de jobs.
+ * - DEGRADAÇÃO GRACIOSA: binário ausente, exit != 0 ou timeout NÃO lançam; devolvem
+ *   {@link WavConversionResult} com `status: 'failed'` + motivo legível, sem quebrar
+ *   o bundle.
+ *
+ * TESTABILIDADE: o executor do subprocesso, o localizador do ffmpeg, o dir temp e o
+ * `mkdir` são INJETÁVEIS — os testes unitários são herméticos (sem ffmpeg/FS reais)
+ * e asseguram os args passados ao executor.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir as fsMkdir, rm as fsRm } from 'node:fs/promises';
+import { join } from 'node:path';
+import envPaths from 'env-paths';
+import { findFfmpeg } from './ffmpeg.js';
+import { runWithWatchdog, sanitizedEnv } from './subprocess.js';
+/** Nome da aplicação para `env-paths` — em sincronia com o cache de anexos (ADR-004). */
+const APP_NAME = 'redmine-context';
+/** Subdiretório TEMP do cache onde os WAVs transcodificados são gravados. */
+const TEMP_SUBDIR = 'tmp';
+/** Taxa de amostragem alvo (Hz) — o whisper.cpp opera a 16 kHz. */
+const TARGET_SAMPLE_RATE = '16000';
+/** Número de canais alvo — mono (downmix de estéreo quando necessário). */
+const TARGET_CHANNELS = '1';
+/** Timeout default de uma conversão antes do `SIGTERM` (ms). */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Graça entre `SIGTERM` e `SIGKILL` (ms) — dá ao ffmpeg chance de sair limpo. */
+const DEFAULT_KILL_GRACE_MS = 2_000;
+/** Teto do stdout/stderr capturado (8 MiB) — o ffmpeg é conciso em `-loglevel error`. */
+const MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+/**
+ * Diretório canônico do cache onde os WAVs temporários são gravados — `env-paths`
+ * cache do usuário (por SO) + `/tmp`. Mesmo mecanismo dos demais módulos de mídia
+ * ({@link whisperModelDir}).
+ *
+ * @returns Caminho absoluto do dir temp (ex.: `~/Library/Caches/redmine-context/tmp`).
+ * @example
+ * const dir = audioTempDir();
+ */
+export function audioTempDir() {
+    return join(envPaths(APP_NAME).cache, TEMP_SUBDIR);
+}
+/** Erro interno: o watchdog matou o ffmpeg por estourar o timeout. */
+class FfmpegTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`ffmpeg excedeu o timeout de ${timeoutMs}ms e foi encerrado`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'FfmpegTimeoutError';
+    }
+}
+/**
+ * Monta os argumentos do ffmpeg para transcodificar `inputPath` → WAV PCM 16-bit,
+ * 16 kHz, mono em `outputPath`. `-protocol_whitelist file` (opção de INPUT) precede
+ * o `-i`; as opções de saída (`-ar`/`-ac`/`-c:a`/`-f`) vêm depois.
+ *
+ * @param inputPath - Caminho absoluto do áudio de entrada.
+ * @param outputPath - Caminho absoluto do WAV de saída.
+ * @returns Lista de argumentos, na ordem exigida pelo ffmpeg.
+ */
+function buildFfmpegArgs(inputPath, outputPath) {
+    return [
+        '-nostdin', // não consome stdin (execução headless)
+        '-loglevel',
+        'error', // silencioso, exceto erros
+        '-protocol_whitelist',
+        'file', // ADR-002: só o arquivo local dado, nada remoto
+        '-i',
+        inputPath,
+        '-vn', // descarta qualquer faixa de vídeo do container
+        '-ar',
+        TARGET_SAMPLE_RATE,
+        '-ac',
+        TARGET_CHANNELS,
+        '-c:a',
+        'pcm_s16le', // PCM 16-bit little-endian, o que o whisper.cpp lê
+        '-f',
+        'wav',
+        '-y', // sobrescreve o destino (nome único, mas defensivo)
+        outputPath,
+    ];
+}
+/**
+ * Executor default: delega ao watchdog compartilhado ({@link runWithWatchdog}) —
+ * ffmpeg SEM shell, env sanitizado e escalonamento `SIGTERM` → graça → `SIGKILL`.
+ * O stdout é irrelevante para a conversão (o WAV é escrito em disco); só o exit
+ * importa. O estouro de timeout é sinalizado com {@link FfmpegTimeoutError} para
+ * preservar a classificação de falha (`reason: 'timeout'`).
+ *
+ * @param invocation - Ver {@link FfmpegInvocation}.
+ * @returns Promessa resolvida no sucesso do ffmpeg.
+ */
+function defaultRun(invocation) {
+    const { bin, args, env, timeoutMs, killGraceMs, signal } = invocation;
+    return runWithWatchdog({
+        bin,
+        args,
+        env,
+        timeoutMs,
+        killGraceMs,
+        maxBuffer: MAX_BUFFER_BYTES,
+        ...(signal !== undefined ? { signal } : {}),
+    }, { makeTimeoutError: (ms) => new FfmpegTimeoutError(ms) }).then(() => undefined);
+}
+/** `true` se o erro sinaliza estouro de timeout do watchdog (por nome, robusto a DI). */
+function isTimeoutError(error) {
+    return error instanceof Error && error.name === 'FfmpegTimeoutError';
+}
+/**
+ * Converte um arquivo de áudio para WAV PCM 16-bit, 16 kHz, mono no dir temp do
+ * cache — o formato que o whisper.cpp (#61) consome. NUNCA lança: binário ausente,
+ * exit != 0 ou timeout viram `{ status: 'failed', reason }` (degradação graciosa,
+ * ADR-002), preservando o bundle.
+ *
+ * @param inputPath - Caminho absoluto do áudio de entrada já baixado no cache.
+ * @param options - Deps injetáveis + timeouts + logger — ver {@link ConvertAudioToWavOptions}.
+ * @returns `done` com `wavPath` no sucesso; `failed` com motivo claro na falha.
+ * @example
+ * const result = await convertAudioToWav('/cache/att/original.mp3');
+ * if (result.status === 'done') transcribe(result.wavPath);
+ */
+export async function convertAudioToWav(inputPath, options = {}) {
+    const findBinary = options.findFfmpegBinary ?? (() => findFfmpeg()?.path);
+    const bin = findBinary();
+    if (bin === undefined) {
+        options.logger?.warn('ffmpeg: binário não encontrado no PATH nem em locais convencionais; ' +
+            'instale o ffmpeg (ex.: `brew install ffmpeg`) — veja o doctor');
+        return {
+            status: 'failed',
+            reason: 'ffmpeg-nao-instalado',
+            hint: 'instale o ffmpeg; o doctor (#57) valida a instalação e orienta por SO',
+        };
+    }
+    const run = options.run ?? defaultRun;
+    const tempDir = options.tempDir ?? audioTempDir();
+    const mkdir = options.mkdir ?? ((dir) => fsMkdir(dir, { recursive: true }).then(() => undefined));
+    const rm = options.rm ?? ((path) => fsRm(path, { force: true }));
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+    const signal = options.signal;
+    // Nome único evita colisão entre conversões concorrentes no mesmo dir temp.
+    const outputPath = join(tempDir, `${randomUUID()}.wav`);
+    const args = buildFfmpegArgs(inputPath, outputPath);
+    try {
+        await mkdir(tempDir);
+        await run({
+            bin,
+            args,
+            env: sanitizedEnv(),
+            timeoutMs,
+            killGraceMs,
+            ...(signal !== undefined ? { signal } : {}),
+        });
+        return { status: 'done', wavPath: outputPath };
+    }
+    catch (error) {
+        // O ffmpeg com `-y` pode ter criado um WAV parcial/zerado; descarta-o para não
+        // acumular lixo no cache temp (convenção de `download.ts`). Best-effort.
+        await rm(outputPath).catch(() => undefined);
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            status: 'failed',
+            reason: isTimeoutError(error) ? 'timeout' : 'erro-conversao',
+            error: message,
+        };
+    }
+}