redmine-context 1.0.0

package/dist/cache/get-or-compute.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `getOrCompute` — padrão de acesso ao cache dos extratores (M3-04, ADR-004).
+ *
+ * Encapsula o fluxo canônico "leia; se faltar, extraia sob lock; grave" que TODOS
+ * os extratores do M3/M4 usarão, garantindo que uma extração CARA rode UMA única
+ * vez mesmo sob concorrência na mesma chave. O helper depende apenas do contrato
+ * {@link CacheStore} (lock por chave + get/put), logo funciona com QUALQUER
+ * implementação — memória ou disco — sem alteração.
+ *
+ * Duas checagens complementares evitam recomputar:
+ * - fast-path: um `get` ANTES do lock resolve o caso comum (hit) sem serializar;
+ * - double-check: após ADQUIRIR o lock, um novo `get` cobre a corrida em que outro
+ *   waiter da mesma chave já gravou o valor enquanto esperávamos — nesse caso
+ *   retornamos sem recomputar.
+ *
+ * POLÍTICA DE ERRO (decisão desta issue): se `compute` lançar, o erro propaga ao
+ * DONO do lock (quem chamou `compute`); nada é gravado. Os waiters, ao adquirirem
+ * o lock em seguida, veem o miss no double-check e RECOMPUTAM — não herdam a falha
+ * do dono. Isso mantém a falha localizada e permite recuperação transparente.
+ */
+import type { CacheKey, CacheStore } from './contract.js';
+/**
+ * Retorna o valor cacheado de `key`, computando-o sob lock caso ausente.
+ *
+ * @typeParam V - Tipo do valor cacheado.
+ * @param store - Backend de cache (memória ou disco) — ver {@link CacheStore}.
+ * @param key - Chave de qualquer camada (ADR-004).
+ * @param compute - Produz o valor quando há cache-miss; roda no máximo uma vez por
+ *   vencedor do lock. Sob concorrência na mesma chave, apenas o dono a executa.
+ * @returns O valor cacheado (existente ou recém-computado).
+ * @throws Propaga qualquer erro lançado por `compute` ao chamador que a executou;
+ *   nesse caso nada é gravado e os demais waiters recomputam.
+ * @example
+ * const extracao = await getOrCompute(store, key, () => extrairAudio(anexo));
+ */
+export declare function getOrCompute<V>(store: CacheStore<V>, key: CacheKey, compute: () => Promise<V>): Promise<V>;

package/dist/cache/get-or-compute.js

@@ -0,0 +1,52 @@
+/**
+ * `getOrCompute` — padrão de acesso ao cache dos extratores (M3-04, ADR-004).
+ *
+ * Encapsula o fluxo canônico "leia; se faltar, extraia sob lock; grave" que TODOS
+ * os extratores do M3/M4 usarão, garantindo que uma extração CARA rode UMA única
+ * vez mesmo sob concorrência na mesma chave. O helper depende apenas do contrato
+ * {@link CacheStore} (lock por chave + get/put), logo funciona com QUALQUER
+ * implementação — memória ou disco — sem alteração.
+ *
+ * Duas checagens complementares evitam recomputar:
+ * - fast-path: um `get` ANTES do lock resolve o caso comum (hit) sem serializar;
+ * - double-check: após ADQUIRIR o lock, um novo `get` cobre a corrida em que outro
+ *   waiter da mesma chave já gravou o valor enquanto esperávamos — nesse caso
+ *   retornamos sem recomputar.
+ *
+ * POLÍTICA DE ERRO (decisão desta issue): se `compute` lançar, o erro propaga ao
+ * DONO do lock (quem chamou `compute`); nada é gravado. Os waiters, ao adquirirem
+ * o lock em seguida, veem o miss no double-check e RECOMPUTAM — não herdam a falha
+ * do dono. Isso mantém a falha localizada e permite recuperação transparente.
+ */
+/**
+ * Retorna o valor cacheado de `key`, computando-o sob lock caso ausente.
+ *
+ * @typeParam V - Tipo do valor cacheado.
+ * @param store - Backend de cache (memória ou disco) — ver {@link CacheStore}.
+ * @param key - Chave de qualquer camada (ADR-004).
+ * @param compute - Produz o valor quando há cache-miss; roda no máximo uma vez por
+ *   vencedor do lock. Sob concorrência na mesma chave, apenas o dono a executa.
+ * @returns O valor cacheado (existente ou recém-computado).
+ * @throws Propaga qualquer erro lançado por `compute` ao chamador que a executou;
+ *   nesse caso nada é gravado e os demais waiters recomputam.
+ * @example
+ * const extracao = await getOrCompute(store, key, () => extrairAudio(anexo));
+ */
+export async function getOrCompute(store, key, compute) {
+    // Fast-path: hit comum não precisa serializar no lock.
+    const cached = await store.get(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    return store.lock(key, async () => {
+        // Double-check: outro waiter da mesma chave pode ter gravado enquanto
+        // esperávamos o lock — reusa o resultado em vez de recomputar.
+        const existing = await store.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const value = await compute();
+        await store.put(key, value);
+        return value;
+    });
+}

package/dist/cache/index.d.ts

@@ -0,0 +1,9 @@
+export declare const MODULE_NAME: "cache";
+export { DEFAULT_STALE_LOCK_TTL_MS, instanceHash, serializeCacheKey, type AttachmentCacheKey, type CacheKey, type CacheStore, type CacheStoreOptions, type ExtractorParams, type GcContext, type GcHook, type IssueCacheKey, } from './contract.js';
+export { getOrCompute } from './get-or-compute.js';
+export { InMemoryCacheStore } from './memory.js';
+export { DiskCacheStore, defaultCacheDir, type DiskCacheStoreOptions } from './disk.js';
+export { buildAttachmentKey, deriveAttachmentDigest, type BuildAttachmentKeyInput, type ExtractorConfig, } from './keys.js';
+export { DiskCacheIndex, INDEX_FILE_NAME } from './disk-index.js';
+export type { CacheIndexEntry, CacheEntryType } from './disk-index.js';
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_ORIGINAL_FRACTION, planGc, resolveEvictionTarget, type GcCandidate, type GcDecision, type GcPolicyOptions, } from './gc.js';

package/dist/cache/index.js

@@ -0,0 +1,8 @@
+export const MODULE_NAME = 'cache';
+export { DEFAULT_STALE_LOCK_TTL_MS, instanceHash, serializeCacheKey, } from './contract.js';
+export { getOrCompute } from './get-or-compute.js';
+export { InMemoryCacheStore } from './memory.js';
+export { DiskCacheStore, defaultCacheDir } from './disk.js';
+export { buildAttachmentKey, deriveAttachmentDigest, } from './keys.js';
+export { DiskCacheIndex, INDEX_FILE_NAME } from './disk-index.js';
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_ORIGINAL_FRACTION, planGc, resolveEvictionTarget, } from './gc.js';

package/dist/cache/keys.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Builder de alto nível da chave attachment-level (M3-03, ADR-004).
+ *
+ * Monta a {@link AttachmentCacheKey} correta a partir do modelo `Attachment` do
+ * contrato ({@link Attachment}) mais a configuração do extrator
+ * ({@link ExtractorConfig}), escondendo das camadas superiores dois detalhes:
+ *
+ * 1. o cálculo do `instance_hash` a partir da URL da instância
+ *    ({@link instanceHash}); e
+ * 2. a origem do `digest` — usa `attachment.digest` quando presente e, como
+ *    FALLBACK para Redmine < 4.x (que não expõe `digest`), deriva um digest
+ *    DETERMINÍSTICO de `(id, filesize, created_on)`.
+ *
+ * A chave attachment-level NÃO depende de `updated_on` da issue: o builder sequer
+ * o recebe. Assim, editar a issue (novo `updated_on`, comentários) invalida só a
+ * camada de issue e reaproveita 100% das extrações caras dos anexos imutáveis.
+ *
+ * Sanitização hex "por construção": o digest de fallback é o SHA-256 hex do
+ * material derivado — 64 chars `[0-9a-f]`. Ele satisfaz o padrão hex que o
+ * {@link DiskCacheStore} usa ao montar `<id>-<digest8>/`, atravessando o caminho
+ * hex direto (sem o re-hash de escape reservado a valores não-hex/maliciosos).
+ */
+import type { Attachment } from '../contract.js';
+import { type AttachmentCacheKey, type ExtractorParams } from './contract.js';
+/**
+ * Configuração do extrator que participa da identidade da extração (ADR-004).
+ * Trocar qualquer campo invalida corretamente a entrada de cache do anexo.
+ */
+export interface ExtractorConfig {
+    /** Versão do extrator (mapeada para `extractorVersion` na chave). */
+    version: string;
+    /** Modelo usado (ex.: `whisper-large-v3`). */
+    model: string;
+    /** Parâmetros escalares do extrator — ver {@link ExtractorParams}. */
+    params: ExtractorParams;
+}
+/** Entrada de {@link buildAttachmentKey}. */
+export interface BuildAttachmentKeyInput {
+    /** URL base da instância Redmine — vira `instanceHash` na chave. */
+    instanceUrl: string;
+    /** Anexo do contrato; `digest` pode faltar em Redmine < 4.x. */
+    attachment: Attachment;
+    /** Configuração do extrator — ver {@link ExtractorConfig}. */
+    extractor: ExtractorConfig;
+}
+/**
+ * Deriva um digest DETERMINÍSTICO de um anexo sem `digest` (fallback Redmine
+ * < 4.x): SHA-256 hex de `(id, filesize, created_on)` separados por NUL.
+ *
+ * O resultado é hex puro (64 chars), estável entre execuções e distinto sempre
+ * que qualquer um dos três campos muda — servindo como identidade de conteúdo
+ * "boa o suficiente" quando o hash real do anexo não está disponível.
+ *
+ * @param attachment - Anexo do contrato.
+ * @returns Digest hex (SHA-256, 64 chars).
+ * @example
+ * deriveAttachmentDigest({ id: 7, filesize: 12345, created_on: '2026-07-20T00:00:00Z', ... });
+ */
+export declare function deriveAttachmentDigest(attachment: Attachment): string;
+/**
+ * Monta a {@link AttachmentCacheKey} de um anexo para uma configuração de
+ * extrator (ADR-004). Usa `attachment.digest` quando presente; caso ausente
+ * (`undefined` ou `""`, típico de Redmine < 4.x), cai no fallback determinístico
+ * de {@link deriveAttachmentDigest}.
+ *
+ * @param input - Ver {@link BuildAttachmentKeyInput}.
+ * @returns Chave attachment-level pronta para o {@link CacheStore}.
+ * @throws {TypeError} Se `instanceUrl` não for uma URL válida (via {@link instanceHash}).
+ * @example
+ * const key = buildAttachmentKey({
+ *   instanceUrl: 'https://redmine.example',
+ *   attachment,
+ *   extractor: { version: '1.0.0', model: 'whisper-large-v3', params: { language: 'pt' } },
+ * });
+ */
+export declare function buildAttachmentKey({ instanceUrl, attachment, extractor, }: BuildAttachmentKeyInput): AttachmentCacheKey;

package/dist/cache/keys.js

@@ -0,0 +1,78 @@
+/**
+ * Builder de alto nível da chave attachment-level (M3-03, ADR-004).
+ *
+ * Monta a {@link AttachmentCacheKey} correta a partir do modelo `Attachment` do
+ * contrato ({@link Attachment}) mais a configuração do extrator
+ * ({@link ExtractorConfig}), escondendo das camadas superiores dois detalhes:
+ *
+ * 1. o cálculo do `instance_hash` a partir da URL da instância
+ *    ({@link instanceHash}); e
+ * 2. a origem do `digest` — usa `attachment.digest` quando presente e, como
+ *    FALLBACK para Redmine < 4.x (que não expõe `digest`), deriva um digest
+ *    DETERMINÍSTICO de `(id, filesize, created_on)`.
+ *
+ * A chave attachment-level NÃO depende de `updated_on` da issue: o builder sequer
+ * o recebe. Assim, editar a issue (novo `updated_on`, comentários) invalida só a
+ * camada de issue e reaproveita 100% das extrações caras dos anexos imutáveis.
+ *
+ * Sanitização hex "por construção": o digest de fallback é o SHA-256 hex do
+ * material derivado — 64 chars `[0-9a-f]`. Ele satisfaz o padrão hex que o
+ * {@link DiskCacheStore} usa ao montar `<id>-<digest8>/`, atravessando o caminho
+ * hex direto (sem o re-hash de escape reservado a valores não-hex/maliciosos).
+ */
+import { createHash } from 'node:crypto';
+import { instanceHash } from './contract.js';
+/**
+ * Separador NUL entre os campos do material de derivação do digest de fallback.
+ * ` ` (NUL) nunca ocorre em inteiros nem em timestamps ISO, evitando que a
+ * concatenação de campos vizinhos colida (ex.: `(1, 23)` vs `(12, 3)`).
+ */
+const FALLBACK_FIELD_SEPARATOR = '\0';
+/**
+ * Deriva um digest DETERMINÍSTICO de um anexo sem `digest` (fallback Redmine
+ * < 4.x): SHA-256 hex de `(id, filesize, created_on)` separados por NUL.
+ *
+ * O resultado é hex puro (64 chars), estável entre execuções e distinto sempre
+ * que qualquer um dos três campos muda — servindo como identidade de conteúdo
+ * "boa o suficiente" quando o hash real do anexo não está disponível.
+ *
+ * @param attachment - Anexo do contrato.
+ * @returns Digest hex (SHA-256, 64 chars).
+ * @example
+ * deriveAttachmentDigest({ id: 7, filesize: 12345, created_on: '2026-07-20T00:00:00Z', ... });
+ */
+export function deriveAttachmentDigest(attachment) {
+    const material = [attachment.id, attachment.filesize, attachment.created_on].join(FALLBACK_FIELD_SEPARATOR);
+    return createHash('sha256').update(material).digest('hex');
+}
+/**
+ * Monta a {@link AttachmentCacheKey} de um anexo para uma configuração de
+ * extrator (ADR-004). Usa `attachment.digest` quando presente; caso ausente
+ * (`undefined` ou `""`, típico de Redmine < 4.x), cai no fallback determinístico
+ * de {@link deriveAttachmentDigest}.
+ *
+ * @param input - Ver {@link BuildAttachmentKeyInput}.
+ * @returns Chave attachment-level pronta para o {@link CacheStore}.
+ * @throws {TypeError} Se `instanceUrl` não for uma URL válida (via {@link instanceHash}).
+ * @example
+ * const key = buildAttachmentKey({
+ *   instanceUrl: 'https://redmine.example',
+ *   attachment,
+ *   extractor: { version: '1.0.0', model: 'whisper-large-v3', params: { language: 'pt' } },
+ * });
+ */
+export function buildAttachmentKey({ instanceUrl, attachment, extractor, }) {
+    // Presente = definido e não-vazio; qualquer outra forma cai no fallback.
+    const digest = attachment.digest !== undefined && attachment.digest !== ''
+        ? attachment.digest
+        : deriveAttachmentDigest(attachment);
+    return {
+        kind: 'attachment',
+        instanceHash: instanceHash(instanceUrl),
+        attachmentId: attachment.id,
+        digest,
+        extractorVersion: extractor.version,
+        model: extractor.model,
+        params: extractor.params,
+    };
+}

package/dist/cache/memory.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Implementação de REFERÊNCIA em memória do {@link CacheStore} (M3-01, ADR-004).
+ *
+ * Serve a dois propósitos: (1) fixar o comportamento esperado que a suíte de
+ * contrato valida e (2) ser um backend real usável em testes de camadas
+ * superiores. A implementação em disco (issues seguintes) satisfará o mesmo
+ * contrato e passará na mesma suíte.
+ *
+ * O lock por chave é promise-based: cada chave mantém a cauda de uma fila
+ * encadeada de promises; um novo pretendente espera a cauda atual antes de
+ * executar sua seção crítica. Um teto de "stale lock" evita deadlock permanente
+ * caso um detentor nunca libere.
+ */
+import { type CacheKey, type CacheStore, type CacheStoreOptions } from './contract.js';
+/**
+ * {@link CacheStore} em memória (referência do contrato ADR-004). Não persiste
+ * entre processos; o isolamento por instância se dá pela própria chave.
+ *
+ * @typeParam V - Tipo do valor cacheado.
+ */
+export declare class InMemoryCacheStore<V = unknown> implements CacheStore<V> {
+    private readonly entries;
+    /** Cauda da fila de locks por chave serializada. */
+    private readonly lockTails;
+    private readonly logger;
+    private readonly onGc;
+    private readonly staleLockTtlMs;
+    /** @param options - Ver {@link CacheStoreOptions}. */
+    constructor(options?: CacheStoreOptions);
+    /** @inheritdoc */
+    get(key: CacheKey): Promise<V | undefined>;
+    /** @inheritdoc */
+    put(key: CacheKey, value: V): Promise<void>;
+    /** @inheritdoc */
+    invalidate(key: CacheKey): Promise<void>;
+    /** @inheritdoc */
+    lock<T>(key: CacheKey, critical: () => Promise<T>): Promise<T>;
+    /** @inheritdoc */
+    gc(): Promise<void>;
+    /**
+     * Espera o detentor anterior liberar, com teto de stale lock: se o detentor
+     * exceder `staleLockTtlMs`, assume-se que ele morreu e a aquisição prossegue
+     * (com aviso). `staleLockTtlMs <= 0` desabilita o teto (espera indefinida).
+     */
+    private awaitHolder;
+    /** Aciona o hook de GC, se configurado, com a origem informada. */
+    private runGc;
+}

package/dist/cache/memory.js

@@ -0,0 +1,110 @@
+/**
+ * Implementação de REFERÊNCIA em memória do {@link CacheStore} (M3-01, ADR-004).
+ *
+ * Serve a dois propósitos: (1) fixar o comportamento esperado que a suíte de
+ * contrato valida e (2) ser um backend real usável em testes de camadas
+ * superiores. A implementação em disco (issues seguintes) satisfará o mesmo
+ * contrato e passará na mesma suíte.
+ *
+ * O lock por chave é promise-based: cada chave mantém a cauda de uma fila
+ * encadeada de promises; um novo pretendente espera a cauda atual antes de
+ * executar sua seção crítica. Um teto de "stale lock" evita deadlock permanente
+ * caso um detentor nunca libere.
+ */
+import { DEFAULT_STALE_LOCK_TTL_MS, serializeCacheKey, } from './contract.js';
+/** Logger no-op: usado quando nenhum logger é injetado. Nunca `console.*`. */
+const noopLogger = { warn: () => undefined };
+/**
+ * {@link CacheStore} em memória (referência do contrato ADR-004). Não persiste
+ * entre processos; o isolamento por instância se dá pela própria chave.
+ *
+ * @typeParam V - Tipo do valor cacheado.
+ */
+export class InMemoryCacheStore {
+    entries = new Map();
+    /** Cauda da fila de locks por chave serializada. */
+    lockTails = new Map();
+    logger;
+    onGc;
+    staleLockTtlMs;
+    /** @param options - Ver {@link CacheStoreOptions}. */
+    constructor(options = {}) {
+        this.logger = options.logger ?? noopLogger;
+        this.onGc = options.onGc;
+        this.staleLockTtlMs = options.staleLockTtlMs ?? DEFAULT_STALE_LOCK_TTL_MS;
+    }
+    /** @inheritdoc */
+    async get(key) {
+        return this.entries.get(serializeCacheKey(key));
+    }
+    /** @inheritdoc */
+    async put(key, value) {
+        this.entries.set(serializeCacheKey(key), value);
+        await this.runGc('put');
+    }
+    /** @inheritdoc */
+    async invalidate(key) {
+        this.entries.delete(serializeCacheKey(key));
+    }
+    /** @inheritdoc */
+    async lock(key, critical) {
+        const serial = serializeCacheKey(key);
+        const previous = this.lockTails.get(serial);
+        // Encadeia esta aquisição na cauda: o próximo pretendente esperará `current`.
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.lockTails.set(serial, current);
+        if (previous !== undefined) {
+            await this.awaitHolder(previous, serial);
+        }
+        try {
+            return await critical();
+        }
+        finally {
+            release();
+            // Só limpa o mapa se ninguém entrou na fila depois de nós (evita vazar
+            // chaves) — caso contrário a cauda ainda é necessária para o próximo.
+            if (this.lockTails.get(serial) === current) {
+                this.lockTails.delete(serial);
+            }
+        }
+    }
+    /** @inheritdoc */
+    async gc() {
+        await this.runGc('manual');
+    }
+    /**
+     * Espera o detentor anterior liberar, com teto de stale lock: se o detentor
+     * exceder `staleLockTtlMs`, assume-se que ele morreu e a aquisição prossegue
+     * (com aviso). `staleLockTtlMs <= 0` desabilita o teto (espera indefinida).
+     */
+    async awaitHolder(previous, serial) {
+        if (this.staleLockTtlMs <= 0) {
+            await previous;
+            return;
+        }
+        let timer;
+        const staleTimeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('stale'), this.staleLockTtlMs);
+        });
+        const outcome = await Promise.race([
+            previous.then(() => 'released'),
+            staleTimeout,
+        ]);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        if (outcome === 'stale') {
+            this.logger.warn(`Lock estagnado para a chave ${serial} após ${this.staleLockTtlMs}ms; prosseguindo.`);
+        }
+    }
+    /** Aciona o hook de GC, se configurado, com a origem informada. */
+    async runGc(reason) {
+        if (this.onGc === undefined) {
+            return;
+        }
+        await this.onGc({ reason, entryCount: this.entries.size });
+    }
+}

package/dist/cache-first.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Leitura CACHE-FIRST não-bloqueante das extrações de anexos (M4-11, ADR-004).
+ *
+ * O núcleo do modo cache-first do MCP (#70): dado uma issue JÁ normalizada, para
+ * cada anexo com extrator registrado LÊ o cache attachment-level e devolve
+ * IMEDIATAMENTE o que já está pronto (`done`/`text`). Quando a extração de um
+ * anexo pesado (vídeo/áudio) ainda NÃO está no cache, NÃO espera a extração
+ * terminar: marca o anexo como {@link ExtractionStatus} `processing` com
+ * metadados e, opcionalmente, dispara o job de extração em SEGUNDO PLANO via a
+ * fila (`runQueue`, #67) — fire-and-forget. Assim nenhuma chamada MCP bloqueia
+ * aguardando mídia (resposta imediata; a continuação que completa na 2ª chamada
+ * é a #71).
+ *
+ * A leitura de cache (índice/`extraction.json`) é barata (ms); só a COMPUTAÇÃO da
+ * extração é cara — e é justamente ela que este módulo evita no caminho síncrono.
+ * A chave attachment-level é montada EXATAMENTE como no caminho bloqueante
+ * ({@link extractIssueAttachments}) — mesmos `probableMime`/`toExtractorConfig` —
+ * garantindo cache-hit coerente com o que o job de background grava.
+ *
+ * Fronteira ADR-005: módulo de core (pipeline de extração). Não importa de
+ * `src/surfaces/**` e nunca usa `console.*` — avisos vão pelo {@link Logger}.
+ */
+import { type AttachmentCacheKey, type CacheStore } from './cache/index.js';
+import type { Logger } from './client/index.js';
+import type { Attachment, ExtractionResult, Issue } from './contract.js';
+import { type Extractor, type ExtractorRegistry } from './extract/index.js';
+/**
+ * Constrói um {@link ExtractionResult} `processing` — o anexo existe e TEM
+ * extrator, mas a extração (cara) ainda não está no cache. Sinaliza à superfície
+ * que o texto virá em uma consulta futura (#71), sem bloquear a atual.
+ *
+ * @returns Resultado `processing` com motivo/dica legíveis (sem texto).
+ */
+export declare function processingResult(): ExtractionResult;
+/** Alvo de uma extração pendente descoberta no caminho cache-first (cache-miss). */
+export interface BackgroundExtractionTarget {
+    /** Anexo cujo texto ainda não está no cache. */
+    readonly attachment: Attachment;
+    /** Extrator resolvido pelo MIME provável do anexo. */
+    readonly extractor: Extractor;
+    /** Chave attachment-level já montada (idêntica à do caminho bloqueante). */
+    readonly key: AttachmentCacheKey;
+}
+/**
+ * Dispatcher de extração em SEGUNDO PLANO (#70/#71). Recebe um anexo com
+ * cache-miss e DEVE retornar imediatamente (fire-and-forget): jamais aguarda a
+ * extração. Injetável para testes (um fake determinístico que não espera de fato).
+ */
+export type BackgroundExtractor = (target: BackgroundExtractionTarget) => void;
+/** Opções de {@link extractIssueAttachmentsCacheFirst}. */
+export interface CacheFirstExtractionOptions {
+    /** URL base da instância — compõe o `instance_hash` da chave (ADR-004). */
+    instanceUrl: string;
+    /** Registry consultado para achar o extrator do MIME provável de cada anexo. */
+    registry: ExtractorRegistry;
+    /** Store de cache attachment-level (memória ou disco) — apenas LIDO aqui. */
+    store: CacheStore<ExtractionResult>;
+    /**
+     * Dispatcher opcional do job em background (#71). Chamado UMA vez por anexo com
+     * cache-miss. Ausente = apenas sinaliza `processing` (o #70 não exige disparar).
+     */
+    background?: BackgroundExtractor;
+    /** Logger para avisos (ex.: falha ao ler o cache); default no-op. Nunca `console.*`. */
+    logger?: Logger;
+}
+/**
+ * Lê o cache das extrações de TODOS os anexos com extrator registrado de uma
+ * issue, SEM computar nenhuma extração (não-bloqueante).
+ *
+ * Para cada anexo:
+ * - sem extrator para o MIME provável → nem entra no mapa (igual ao bloqueante);
+ * - cache-hit → o {@link ExtractionResult} pronto (texto imediato);
+ * - cache-miss → `processing` + (opcional) dispara o job de background.
+ *
+ * @param issue - Issue normalizada cujos anexos serão consultados no cache.
+ * @param options - Ver {@link CacheFirstExtractionOptions}.
+ * @returns `Map<attachmentId, ExtractionResult>` só com anexos que têm extrator.
+ * @example
+ * const map = await extractIssueAttachmentsCacheFirst(issue, {
+ *   instanceUrl, registry, store, background,
+ * });
+ */
+export declare function extractIssueAttachmentsCacheFirst(issue: Issue, options: CacheFirstExtractionOptions): Promise<Map<number, ExtractionResult>>;
+/**
+ * Computa a extração de UM anexo em background. Recebe o alvo do cache-miss e o
+ * `AbortSignal` da fila (#69); deve resolver com o {@link ExtractionResult}
+ * gravado no cache (ou reportar falha por rejeição, isolada pela fila).
+ */
+export type BackgroundCompute = (target: BackgroundExtractionTarget, signal: AbortSignal | undefined) => Promise<ExtractionResult>;
+/** Opções de {@link makeQueueBackgroundExtractor}. */
+export interface QueueBackgroundOptions {
+    /** Logger para avisos de jobs que falharam/abortaram (ADR-005; sem `console.*`). */
+    logger?: Logger;
+    /** Sinal de cancelamento propagado à fila e aos jobs (#69). */
+    signal?: AbortSignal;
+    /**
+     * Store attachment-level onde o resultado do job de background é PERSISTIDO ao
+     * concluir (#71), sob a MESMA chave que a leitura cache-first busca. Fecha o
+     * loop do #70: a 2ª chamada (pós-conclusão) acerta o cache e devolve o resultado
+     * completo — e uma FALHA vira `failed` PERSISTIDO, nunca `processing` eterno.
+     * Ausente = comportamento #70 (fire-and-forget sem persistência de fechamento).
+     */
+    store?: CacheStore<ExtractionResult>;
+}
+/**
+ * Cria um {@link BackgroundExtractor} respaldado pela fila de jobs (#67): cada
+ * anexo com cache-miss vira UM {@link QueueJob} rodado por `runQueue`, cujas
+ * transições são consumidas de forma DESACOPLADA (fire-and-forget). O dispatcher
+ * retorna imediatamente — o trabalho caro acontece na fila, fora do caminho da
+ * resposta MCP. O `AbortSignal` da fila é propagado ao `compute` via
+ * {@link JobContext.signal} (#69), pronto para o kill de subprocesso do #68.
+ *
+ * DEDUP DE IN-FLIGHT (#71): o dispatcher mantém um registro dos jobs em andamento
+ * POR CHAVE attachment-level. Uma 2ª chamada para um anexo cujo job ainda processa
+ * NÃO dispara um job duplicado — reusa o que já corre. O registro é limpo quando o
+ * job conclui (via `finally`), liberando futuras re-extrações (ex.: cache invalidado).
+ *
+ * @param compute - Executa a extração real do anexo — ver {@link BackgroundCompute}.
+ * @param options - Logger/signal/store opcionais — ver {@link QueueBackgroundOptions}.
+ * @returns Um dispatcher fire-and-forget para injetar em {@link CacheFirstExtractionOptions.background}.
+ * @example
+ * const background = makeQueueBackgroundExtractor(async (target) => {
+ *   const map = await extractIssueAttachments(http, single, { store, registry, instanceUrl });
+ *   return map.get(target.attachment.id) ?? processingResult();
+ * }, { store });
+ */
+export declare function makeQueueBackgroundExtractor(compute: BackgroundCompute, options?: QueueBackgroundOptions): BackgroundExtractor;