redmine-context 1.0.0

package/dist/bundle/search-list.js

@@ -0,0 +1,53 @@
+/**
+ * Lista compacta em Markdown dos resultados da tool `search_issues` (M1-13).
+ *
+ * Diferente do bundle completo de uma issue (#16), aqui cada item é UMA linha:
+ * id + status + responsável (metadados estruturais, fora da fence) e o assunto
+ * isolado numa fence `<untrusted-content>` — reutilizando {@link fenceInline}
+ * para manter a MESMA marcação anti prompt-injection do bundle.
+ *
+ * Determinístico: nenhum timestamp; a ordem é a recebida do chamador (que já
+ * reflete a ordenação do Redmine). Avisos de degradação (ex.: `/search`
+ * indisponível) são renderizados no corpo, atendendo ao "aviso no payload".
+ */
+import { fenceInline } from './markdown.js';
+/** Placeholder para assunto ausente na página de listagem. */
+const ABSENT_SUBJECT = '_(sem assunto)_';
+/** Renderiza uma linha compacta de resultado. */
+function renderItem(item) {
+    const subject = item.subject === null ? ABSENT_SUBJECT : fenceInline(item.subject);
+    return `- **#${item.id}** — status: ${item.status} — responsável: ${item.assignee} — ${subject}`;
+}
+/**
+ * Renderiza a lista compacta de resultados de busca em Markdown.
+ *
+ * @param items - Itens já resolvidos (status/responsável em nomes legíveis).
+ * @param meta - Consulta e avisos de degradação (ver {@link SearchListMeta}).
+ * @returns Documento Markdown terminado por uma quebra de linha.
+ * @example
+ * const md = buildSearchListMarkdown(
+ *   [{ id: 1, subject: 'x', status: 'New', assignee: '(nenhum)' }],
+ *   { query: 'x' },
+ * );
+ */
+export function buildSearchListMarkdown(items, meta = {}) {
+    const lines = [`# Resultados da busca (${items.length})`, ''];
+    if (meta.query !== undefined && meta.query.length > 0) {
+        // Consulta é entrada arbitrária do chamador: também vai em fence untrusted.
+        lines.push(`Consulta: ${fenceInline(meta.query)}`, '');
+    }
+    const warnings = meta.warnings ?? [];
+    for (const warning of warnings) {
+        lines.push(`> Aviso: ${warning}`);
+    }
+    if (warnings.length > 0)
+        lines.push('');
+    if (items.length === 0) {
+        lines.push('_(nenhum resultado)_');
+    }
+    else {
+        for (const item of items)
+            lines.push(renderItem(item));
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/bundle/stable-stringify.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Serializador JSON estável para o bundle determinístico (issue #15).
+ *
+ * O contrato do bundle exige que dois empacotamentos do mesmo estado sejam
+ * byte-idênticos. `JSON.stringify` NÃO garante ordem de chaves entre objetos
+ * construídos por caminhos diferentes; este módulo remove essa variável
+ * reordenando as chaves de todo objeto (recursivamente) antes de serializar.
+ * Arrays têm sua ordem preservada — a ordenação semântica das coleções é
+ * responsabilidade de quem monta o corpo (`./json.ts`), não do serializador.
+ *
+ * Sem dependências novas: apenas `JSON.stringify` sobre uma cópia com chaves
+ * ordenadas.
+ */
+/** Valor serializável em JSON (fechado sobre si mesmo, recursivo). */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Serializa um valor em JSON estável (chaves ordenadas, indentação de 2 espaços).
+ *
+ * @param value - Valor JSON a serializar.
+ * @returns String JSON determinística — idêntica para valores semanticamente iguais.
+ * @example
+ * stableStringify({ b: 1, a: 2 }); // '{\n  "a": 2,\n  "b": 1\n}'
+ */
+export declare function stableStringify(value: JsonValue): string;

package/dist/bundle/stable-stringify.js

@@ -0,0 +1,50 @@
+/**
+ * Serializador JSON estável para o bundle determinístico (issue #15).
+ *
+ * O contrato do bundle exige que dois empacotamentos do mesmo estado sejam
+ * byte-idênticos. `JSON.stringify` NÃO garante ordem de chaves entre objetos
+ * construídos por caminhos diferentes; este módulo remove essa variável
+ * reordenando as chaves de todo objeto (recursivamente) antes de serializar.
+ * Arrays têm sua ordem preservada — a ordenação semântica das coleções é
+ * responsabilidade de quem monta o corpo (`./json.ts`), não do serializador.
+ *
+ * Sem dependências novas: apenas `JSON.stringify` sobre uma cópia com chaves
+ * ordenadas.
+ */
+/**
+ * Reordena as chaves de todo objeto alfabeticamente, em profundidade.
+ *
+ * Propriedades `undefined` são descartadas (mesma semântica de `JSON.stringify`),
+ * evitando que a presença/ausência de chaves opcionais dependa do caminho de
+ * construção. A ordem de arrays é mantida intacta.
+ *
+ * @param value - Valor a normalizar.
+ * @returns Cópia com chaves de objeto ordenadas recursivamente.
+ */
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    if (value !== null && typeof value === 'object') {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            const entry = source[key];
+            if (entry !== undefined)
+                sorted[key] = sortKeysDeep(entry);
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Serializa um valor em JSON estável (chaves ordenadas, indentação de 2 espaços).
+ *
+ * @param value - Valor JSON a serializar.
+ * @returns String JSON determinística — idêntica para valores semanticamente iguais.
+ * @example
+ * stableStringify({ b: 1, a: 2 }); // '{\n  "a": 2,\n  "b": 1\n}'
+ */
+export function stableStringify(value) {
+    return JSON.stringify(sortKeysDeep(value), null, 2);
+}

package/dist/cache/contract.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Contrato do módulo Cache (M3-01, ADR-004).
+ *
+ * Define os TIPOS DE CHAVE das duas camadas do cache local e a interface
+ * {@link CacheStore} — comum a qualquer implementação (memória nesta issue,
+ * disco nas seguintes). O acoplamento entre as camadas se dá exclusivamente por
+ * estes tipos e por uma função de SERIALIZAÇÃO ESTÁVEL de chave
+ * ({@link serializeCacheKey}), de modo que a suíte de contrato possa exercitar
+ * qualquer implementação sem conhecer seus detalhes.
+ *
+ * Camadas (ADR-004):
+ * - attachment (extrações caras): chave
+ *   `(instance_hash, attachment_id, digest, extractor_version + model + params)`.
+ *   Trocar o modelo/versão do extrator invalida corretamente; comentários novos
+ *   na issue NUNCA invalidam a extração de um anexo imutável.
+ * - issue (bundle/metadados baratos): chave `(issue_id, updated_on)`.
+ *
+ * O `instance_hash` isola instâncias Redmine distintas: é o SHA-256 truncado da
+ * URL base normalizada ({@link instanceHash}), reusando `normalizeInstanceUrl`
+ * (ADR-003) para que formas equivalentes da mesma URL colapsem numa só chave.
+ */
+import type { Logger } from '../client/index.js';
+/**
+ * Parâmetros do extrator que participam da identidade da extração. São valores
+ * escalares (ex.: `{ language: 'pt', beam_size: 5 }`); a serialização ordena as
+ * chaves para ser estável independentemente da ordem de inserção.
+ */
+export type ExtractorParams = Record<string, string | number | boolean>;
+/**
+ * Chave da camada de attachment (extrações caras, ADR-004). Identifica de forma
+ * única a extração de UM anexo por UMA configuração de extrator. `digest` é o
+ * hash do conteúdo do anexo (imutável no Redmine).
+ */
+export interface AttachmentCacheKey {
+    kind: 'attachment';
+    /** Isolamento por instância — ver {@link instanceHash}. */
+    instanceHash: string;
+    /** `attachment.id` do Redmine (único apenas dentro da instância). */
+    attachmentId: number;
+    /** Digest do conteúdo do anexo (ADR-004: `attachment.digest`). */
+    digest: string;
+    /** Versão do extrator; trocá-la invalida a extração. */
+    extractorVersion: string;
+    /** Modelo usado (ex.: `whisper-large-v3`); trocá-lo invalida a extração. */
+    model: string;
+    /** Parâmetros escalares do extrator — ver {@link ExtractorParams}. */
+    params: ExtractorParams;
+}
+/**
+ * Chave da camada de issue (bundle/metadados baratos, ADR-004). `updated_on`
+ * muda a cada edição da issue; o rebuild reutiliza 100% das extrações da camada
+ * de baixo (que não dependem de `updated_on`).
+ */
+export interface IssueCacheKey {
+    kind: 'issue';
+    /** `issue.id` do Redmine. */
+    issueId: number;
+    /** `issue.updated_on` (timestamp ISO) — muda a cada edição. */
+    updatedOn: string;
+}
+/** União discriminada das chaves das duas camadas do cache (ADR-004). */
+export type CacheKey = AttachmentCacheKey | IssueCacheKey;
+/** Contexto passado ao {@link GcHook} quando o GC é acionado. */
+export interface GcContext {
+    /** Origem do acionamento: após um `put` ou uma chamada manual a `gc()`. */
+    reason: 'put' | 'manual';
+    /** Número de entradas atualmente no store no momento do acionamento. */
+    entryCount: number;
+}
+/**
+ * Hook de garbage collection (ADR-004: LRU com quota). Ponto de extensão comum:
+ * a implementação em disco delega a ele a decisão de despejo; a de memória
+ * apenas o notifica. Pode ser assíncrono.
+ */
+export type GcHook = (context: GcContext) => void | Promise<void>;
+/** Opções comuns a qualquer implementação de {@link CacheStore}. */
+export interface CacheStoreOptions {
+    /** Logger para avisos (ex.: lock estagnado); default no-op. Nunca `console.*`. */
+    logger?: Logger;
+    /** Hook de GC acionado após `put` e por `gc()` — ver {@link GcHook}. */
+    onGc?: GcHook;
+    /**
+     * TTL (ms) de um lock considerado estagnado: um segundo pretendente da MESMA
+     * chave que espere além deste teto assume que o detentor morreu e prossegue
+     * (evita deadlock permanente). `0` desabilita o teto (espera indefinida).
+     * Default: {@link DEFAULT_STALE_LOCK_TTL_MS}.
+     */
+    staleLockTtlMs?: number;
+}
+/**
+ * Contrato de armazenamento do cache local (ADR-004). Qualquer implementação
+ * (memória, disco) o satisfaz; a suíte de contrato (`runCacheContractSuite`)
+ * valida o comportamento observável, não a implementação.
+ *
+ * @typeParam V - Tipo do valor cacheado (ex.: extração, bundle).
+ */
+export interface CacheStore<V = unknown> {
+    /**
+     * Recupera o valor de uma chave, ou `undefined` se ausente/invalidado.
+     * @param key - Chave de qualquer camada.
+     */
+    get(key: CacheKey): Promise<V | undefined>;
+    /**
+     * Grava (ou substitui) o valor de uma chave. Aciona o {@link GcHook} com
+     * `reason: 'put'` após persistir.
+     * @param key - Chave de qualquer camada.
+     * @param value - Valor a armazenar.
+     */
+    put(key: CacheKey, value: V): Promise<void>;
+    /**
+     * Remove a entrada de uma chave; no-op se não existir.
+     * @param key - Chave de qualquer camada.
+     */
+    invalidate(key: CacheKey): Promise<void>;
+    /**
+     * Executa `critical` em exclusão mútua POR CHAVE: uma segunda aquisição da
+     * mesma chave espera a primeira liberar; chaves distintas não se bloqueiam. O
+     * lock é sempre liberado ao final, inclusive se `critical` lançar.
+     *
+     * @typeParam T - Tipo de retorno da seção crítica.
+     * @param key - Chave que serializa o acesso.
+     * @param critical - Função executada sob o lock.
+     * @returns O resultado de `critical`.
+     */
+    lock<T>(key: CacheKey, critical: () => Promise<T>): Promise<T>;
+    /**
+     * Aciona o {@link GcHook} manualmente (`reason: 'manual'`). No-op se nenhum
+     * hook foi configurado.
+     */
+    gc(): Promise<void>;
+}
+/** TTL default (ms) para considerar um lock estagnado. */
+export declare const DEFAULT_STALE_LOCK_TTL_MS = 30000;
+/**
+ * Calcula o `instance_hash` de uma URL base do Redmine (ADR-004): SHA-256
+ * truncado da URL normalizada por `normalizeInstanceUrl` (ADR-003), garantindo
+ * que formas equivalentes (maiúsculas, porta padrão, barra final) colapsem no
+ * mesmo hash e que instâncias distintas nunca colidam.
+ *
+ * @param instanceUrl - URL base da instância (ex.: `https://Redmine.Example/`).
+ * @returns Hash hex truncado (16 chars = 64 bits).
+ * @throws {TypeError} Se `instanceUrl` não for uma URL válida.
+ * @example
+ * instanceHash('https://redmine.example'); // ex.: 'a1b2c3d4e5f60718'
+ */
+export declare function instanceHash(instanceUrl: string): string;
+/**
+ * Serializa uma {@link CacheKey} numa string ESTÁVEL e livre de colisão entre
+ * camadas (prefixo `att`/`iss`) e entre campos (separador NUL). É a fronteira
+ * usada por qualquer implementação para indexar entradas e locks.
+ *
+ * @param key - Chave de qualquer camada.
+ * @returns String determinística que identifica a chave.
+ * @example
+ * serializeCacheKey({ kind: 'issue', issueId: 42, updatedOn: '2026-07-20T00:00:00Z' });
+ */
+export declare function serializeCacheKey(key: CacheKey): string;

package/dist/cache/disk-index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Índice por instância do {@link ../cache/disk.js DiskCacheStore} (M3-05.1,
+ * ADR-004): `<cache_dir>/<instance_hash>/index.json` registra, por entrada da
+ * camada de ATTACHMENT, a chave serializada, o tamanho em bytes, o tipo
+ * (`original` | `extraction`) e o `last_accessed_at` — é o insumo do GC/LRU
+ * (#47). Entradas issue-level NÃO são indexadas (baratas de reconstruir).
+ *
+ * Semântica de escrita:
+ * - `recordPut`/`remove` persistem imediatamente (write-then-rename atômico);
+ * - `recordAccess` (get) só atualiza um BUFFER em memória — a janela de perda
+ *   (acessos entre o último flush e um crash) é aceita: o pior caso é o LRU
+ *   enxergar um item como "mais antigo" do que realmente é. O flush acontece
+ *   no próximo `recordPut`/`remove`/`flushAll` (chamado pelo gc()).
+ *
+ * Resiliência: índice corrompido ou ausente é RECONSTRUÍDO varrendo os
+ * arquivos de valor da instância. As entradas do registro são chaveadas pelo
+ * NOME DO ARQUIVO de valor (sha256 da chave serializada) — assim a
+ * reconstrução (que não consegue reverter o hash para a chave) e as operações
+ * normais colidem no MESMO registro, sem duplicar; `entry.key` guarda a chave
+ * serializada quando conhecida (após reconstrução, o nome do arquivo fica como
+ * valor opaco até o próximo put daquela chave).
+ */
+/** Nome do arquivo de índice, ao lado dos diretórios de anexo da instância. */
+export declare const INDEX_FILE_NAME = "index.json";
+/** Tipo de uma entrada indexada — quotas separadas no GC (#47). */
+export type CacheEntryType = 'original' | 'extraction';
+/** Uma entrada do índice por instância. */
+export interface CacheIndexEntry {
+    /** Chave serializada (opaca — nome do arquivo — após reconstrução). */
+    key: string;
+    /** Tamanho do valor em bytes, como gravado em disco. */
+    size: number;
+    /** Classificação para as quotas do GC. */
+    type: CacheEntryType;
+    /** ISO 8601 do último acesso conhecido (ver janela de perda no topo). */
+    lastAccessedAt: string;
+}
+/** Logger mínimo (padrão do repo). */
+interface IndexLogger {
+    warn(message: string): void;
+}
+/**
+ * Gerência dos índices por instância de um `DiskCacheStore`.
+ * Uma instância desta classe pertence a UM store (mesmo `root`).
+ */
+export declare class DiskCacheIndex {
+    private readonly root;
+    private readonly logger;
+    private readonly instances;
+    constructor(root: string, logger?: IndexLogger);
+    /**
+     * Registra (ou substitui) a entrada de um put — persiste imediatamente.
+     * @returns O tamanho anterior da entrada substituída (0 se era nova) — usado
+     *   pelo total incremental do GC (review #137).
+     */
+    recordPut(instanceHash: string, recordKey: string, entry: CacheIndexEntry): Promise<number>;
+    /** Bufferiza a atualização de `last_accessed_at` de um get (throttled). */
+    recordAccess(instanceHash: string, recordKey: string): void;
+    /**
+     * Remove a entrada de um invalidate — persiste imediatamente.
+     * @returns O tamanho da entrada removida (0 se não existia).
+     */
+    remove(instanceHash: string, recordKey: string): Promise<number>;
+    /** Faz flush de TODOS os buffers pendentes (chamado pelo gc()). */
+    flushAll(): Promise<void>;
+    /**
+     * Reconcilia o índice de uma instância com o DISCO: adiciona entradas para
+     * arquivos órfãos (crash entre o rename do valor e o recordPut — review
+     * #135) sem tocar nas entradas já conhecidas. Chamado pelo gc().
+     */
+    reconcile(instanceHash: string): Promise<void>;
+    /** Entradas atuais de uma instância (para o GC/LRU do #47). */
+    entriesOf(instanceHash: string): Promise<ReadonlyMap<string, CacheIndexEntry>>;
+    private ensure;
+    /** Carrega (lazy) o índice de uma instância, reconstruindo se necessário. */
+    private load;
+    /** Reconstrói o índice varrendo os arquivos de valor da instância. */
+    private rebuild;
+    /** Persiste o índice de uma instância (aplicando o buffer de acessos). */
+    private persist;
+}
+export {};

package/dist/cache/disk-index.js

@@ -0,0 +1,220 @@
+/**
+ * Índice por instância do {@link ../cache/disk.js DiskCacheStore} (M3-05.1,
+ * ADR-004): `<cache_dir>/<instance_hash>/index.json` registra, por entrada da
+ * camada de ATTACHMENT, a chave serializada, o tamanho em bytes, o tipo
+ * (`original` | `extraction`) e o `last_accessed_at` — é o insumo do GC/LRU
+ * (#47). Entradas issue-level NÃO são indexadas (baratas de reconstruir).
+ *
+ * Semântica de escrita:
+ * - `recordPut`/`remove` persistem imediatamente (write-then-rename atômico);
+ * - `recordAccess` (get) só atualiza um BUFFER em memória — a janela de perda
+ *   (acessos entre o último flush e um crash) é aceita: o pior caso é o LRU
+ *   enxergar um item como "mais antigo" do que realmente é. O flush acontece
+ *   no próximo `recordPut`/`remove`/`flushAll` (chamado pelo gc()).
+ *
+ * Resiliência: índice corrompido ou ausente é RECONSTRUÍDO varrendo os
+ * arquivos de valor da instância. As entradas do registro são chaveadas pelo
+ * NOME DO ARQUIVO de valor (sha256 da chave serializada) — assim a
+ * reconstrução (que não consegue reverter o hash para a chave) e as operações
+ * normais colidem no MESMO registro, sem duplicar; `entry.key` guarda a chave
+ * serializada quando conhecida (após reconstrução, o nome do arquivo fica como
+ * valor opaco até o próximo put daquela chave).
+ */
+import { readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+/** Nome do arquivo de índice, ao lado dos diretórios de anexo da instância. */
+export const INDEX_FILE_NAME = 'index.json';
+/** Versão do schema do índice (evolução futura sem quebrar leitores). */
+const INDEX_VERSION = 1;
+/**
+ * Gerência dos índices por instância de um `DiskCacheStore`.
+ * Uma instância desta classe pertence a UM store (mesmo `root`).
+ */
+export class DiskCacheIndex {
+    root;
+    logger;
+    instances = new Map();
+    constructor(root, logger = { warn: () => undefined }) {
+        this.root = root;
+        this.logger = logger;
+    }
+    /**
+     * Registra (ou substitui) a entrada de um put — persiste imediatamente.
+     * @returns O tamanho anterior da entrada substituída (0 se era nova) — usado
+     *   pelo total incremental do GC (review #137).
+     */
+    async recordPut(instanceHash, recordKey, entry) {
+        const index = await this.load(instanceHash);
+        const previousSize = index.entries.get(recordKey)?.size ?? 0;
+        index.entries.set(recordKey, entry);
+        index.pendingAccess.delete(recordKey);
+        await this.persist(instanceHash, index);
+        return previousSize;
+    }
+    /** Bufferiza a atualização de `last_accessed_at` de um get (throttled). */
+    recordAccess(instanceHash, recordKey) {
+        const index = this.instances.get(instanceHash);
+        const at = new Date().toISOString();
+        if (index !== undefined && index.loaded) {
+            index.pendingAccess.set(recordKey, at);
+            return;
+        }
+        // Instância ainda não carregada: registra num índice lazy para o próximo
+        // flush carregar e mesclar.
+        const lazy = this.ensure(instanceHash);
+        lazy.pendingAccess.set(recordKey, at);
+    }
+    /**
+     * Remove a entrada de um invalidate — persiste imediatamente.
+     * @returns O tamanho da entrada removida (0 se não existia).
+     */
+    async remove(instanceHash, recordKey) {
+        const index = await this.load(instanceHash);
+        const removedSize = index.entries.get(recordKey)?.size ?? 0;
+        index.entries.delete(recordKey);
+        index.pendingAccess.delete(recordKey);
+        await this.persist(instanceHash, index);
+        return removedSize;
+    }
+    /** Faz flush de TODOS os buffers pendentes (chamado pelo gc()). */
+    async flushAll() {
+        for (const instanceHash of this.instances.keys()) {
+            const index = await this.load(instanceHash);
+            if (index.pendingAccess.size === 0) {
+                continue;
+            }
+            await this.persist(instanceHash, index);
+        }
+    }
+    /**
+     * Reconcilia o índice de uma instância com o DISCO: adiciona entradas para
+     * arquivos órfãos (crash entre o rename do valor e o recordPut — review
+     * #135) sem tocar nas entradas já conhecidas. Chamado pelo gc().
+     */
+    async reconcile(instanceHash) {
+        const index = await this.load(instanceHash);
+        const before = index.entries.size;
+        const scanned = { entries: new Map(), pendingAccess: new Map(), loaded: true };
+        await this.rebuild(instanceHash, scanned);
+        for (const [recordKey, entry] of scanned.entries) {
+            if (!index.entries.has(recordKey)) {
+                index.entries.set(recordKey, entry);
+            }
+        }
+        if (index.entries.size !== before) {
+            this.logger.warn(`cache: ${index.entries.size - before} entrada(s) órfã(s) reconciliada(s) em ${instanceHash}`);
+            await this.persist(instanceHash, index);
+        }
+    }
+    /** Entradas atuais de uma instância (para o GC/LRU do #47). */
+    async entriesOf(instanceHash) {
+        const index = await this.load(instanceHash);
+        return index.entries;
+    }
+    ensure(instanceHash) {
+        let index = this.instances.get(instanceHash);
+        if (index === undefined) {
+            index = { entries: new Map(), pendingAccess: new Map(), loaded: false };
+            this.instances.set(instanceHash, index);
+        }
+        return index;
+    }
+    /** Carrega (lazy) o índice de uma instância, reconstruindo se necessário. */
+    async load(instanceHash) {
+        const index = this.ensure(instanceHash);
+        if (index.loaded) {
+            return index;
+        }
+        const filePath = join(this.root, instanceHash, INDEX_FILE_NAME);
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(filePath, 'utf8'));
+        }
+        catch (cause) {
+            if (cause.code !== 'ENOENT') {
+                this.logger.warn(`cache: índice corrompido em ${filePath} — reconstruindo do disco`);
+            }
+            parsed = undefined;
+        }
+        if (parsed !== undefined && typeof parsed === 'object' && parsed.entries !== undefined) {
+            for (const [recordKey, entry] of Object.entries(parsed.entries)) {
+                index.entries.set(recordKey, entry);
+            }
+        }
+        else {
+            await this.rebuild(instanceHash, index);
+        }
+        index.loaded = true;
+        return index;
+    }
+    /** Reconstrói o índice varrendo os arquivos de valor da instância. */
+    async rebuild(instanceHash, index) {
+        const attachmentsDir = join(this.root, instanceHash, 'attachments');
+        let dirs;
+        try {
+            dirs = await readdir(attachmentsDir);
+        }
+        catch {
+            return; // instância sem anexos: índice vazio.
+        }
+        const now = new Date().toISOString();
+        for (const dir of dirs) {
+            const full = join(attachmentsDir, dir);
+            let files;
+            try {
+                files = await readdir(full);
+            }
+            catch {
+                continue;
+            }
+            for (const file of files) {
+                if (!file.endsWith('.json') || file.endsWith('.tmp')) {
+                    continue;
+                }
+                try {
+                    const info = await stat(join(full, file));
+                    index.entries.set(join(dir, file), {
+                        // Irrecuperável a partir do hash: o caminho relativo fica como
+                        // identificador opaco até o próximo put desta chave.
+                        key: join(dir, file),
+                        size: info.size,
+                        type: 'extraction',
+                        lastAccessedAt: now,
+                    });
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    }
+    /** Persiste o índice de uma instância (aplicando o buffer de acessos). */
+    async persist(instanceHash, index) {
+        for (const [recordKey, at] of index.pendingAccess) {
+            const entry = index.entries.get(recordKey);
+            if (entry !== undefined) {
+                entry.lastAccessedAt = at;
+            }
+        }
+        index.pendingAccess.clear();
+        const filePath = join(this.root, instanceHash, INDEX_FILE_NAME);
+        const payload = {
+            version: INDEX_VERSION,
+            entries: Object.fromEntries(index.entries),
+        };
+        const tmpPath = `${filePath}.${randomBytes(6).toString('hex')}.tmp`;
+        try {
+            await writeFile(tmpPath, JSON.stringify(payload));
+            await rename(tmpPath, filePath);
+        }
+        catch (cause) {
+            await rm(tmpPath, { force: true });
+            // O diretório da instância pode não existir ainda (só acessos
+            // bufferizados, sem put) — nada a persistir nesse caso.
+            if (cause.code !== 'ENOENT') {
+                throw cause;
+            }
+        }
+    }
+}