redmine-context 1.0.0

package/dist/cache/disk.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Implementação em DISCO do {@link CacheStore} (M3-02, ADR-004).
+ *
+ * Persiste cada entrada como um arquivo JSON num layout isolado por instância:
+ *
+ * - attachment: `<cache_dir>/<instance_hash>/attachments/<id>-<digest8>/<hash>.json`
+ * - issue:      `<cache_dir>/issues/<issue_id>/<hash>.json`
+ *
+ * O `<id>-<digest8>/` segue exatamente o path do ADR-004; `<hash>` é o SHA-256
+ * (hex) da chave serializada, garantindo que configurações de extrator distintas
+ * (versão/modelo/params) coexistam sob o mesmo anexo sem colidir. Nomes de
+ * arquivo/diretório derivam APENAS de `id`/`digest`/`hash` — nunca de conteúdo
+ * externo não sanitizado — pois todos esses campos são hex ou inteiros do
+ * contrato ({@link serializeCacheKey}).
+ *
+ * O `cache_dir` padrão vem de `env-paths` (diretório de cache do usuário por SO),
+ * com override pela opção {@link DiskCacheStoreOptions.cacheDir} (que o config/a
+ * CLI pode preencher). Diretórios são criados SOB DEMANDA no primeiro `put`.
+ *
+ * Atomicidade: cada `put` escreve num arquivo `.tmp` único e só então faz
+ * `rename` para o destino — o `rename` é atômico no mesmo filesystem, de modo que
+ * um leitor nunca observa um JSON parcial (crash-safety intra-arquivo).
+ *
+ * ESCOPO (nota da suíte de contrato, review #129): o lock por chave é HERDADO da
+ * implementação in-memory ({@link InMemoryCacheStore}) e vale apenas INTRA-processo
+ * — locking CROSS-processo NÃO é escopo desta issue (fica para uma issue de lock
+ * de disco). GC/LRU e índice de entradas são #45/#46: {@link gc} apenas aciona o
+ * hook configurado (no-op quando ausente).
+ */
+import { type CacheKey, type CacheStore, type CacheStoreOptions } from './contract.js';
+import { type CacheEntryType } from './disk-index.js';
+/** Opções do {@link DiskCacheStore}. */
+export interface DiskCacheStoreOptions extends CacheStoreOptions {
+    /**
+     * Raiz do cache em disco. Default: diretório de cache do usuário via
+     * `env-paths` ({@link defaultCacheDir}). Preenchível por config/CLI ou testes.
+     */
+    cacheDir?: string;
+    /**
+     * Teto GLOBAL do cache em bytes para o GC/LRU (#47, ADR-004). Ao ser estourado
+     * após um `put` ou num `gc()`, o store despeja entradas por `last_accessed_at`
+     * com quotas separadas: originais (recuperáveis) de forma agressiva, extrações
+     * (caras) só quando necessário. Default {@link DEFAULT_MAX_BYTES} (2 GB);
+     * `Infinity` desabilita o despejo.
+     */
+    maxBytes?: number;
+}
+/**
+ * Raiz de cache padrão do projeto (diretório de cache do usuário por SO, via
+ * `env-paths`). Ex.: `~/Library/Caches/redmine-context` no macOS.
+ *
+ * @returns Caminho absoluto do diretório de cache padrão.
+ */
+export declare function defaultCacheDir(): string;
+/**
+ * {@link CacheStore} persistente em disco (ADR-004). Entradas sobrevivem à
+ * reinicialização do processo: uma nova instância apontando para o mesmo
+ * `cacheDir` enxerga tudo o que foi gravado.
+ *
+ * @typeParam V - Tipo do valor cacheado (serializado como JSON).
+ */
+export declare class DiskCacheStore<V = unknown> implements CacheStore<V> {
+    private readonly root;
+    private readonly onGc;
+    /** Teto global (bytes) do GC/LRU; `Infinity` desabilita o despejo (#47). */
+    private readonly maxBytes;
+    /**
+     * Total de bytes indexados conhecido (curto-circuito do GC no put — review
+     * #137). `undefined` = ainda não computado: a primeira passada completa
+     * inicializa; depois, puts/invalidates/evictions mantêm incrementalmente.
+     */
+    private knownBytes;
+    /**
+     * Provedor de lock por chave — HERDADO do in-memory (intra-processo). Não é
+     * usado para armazenar valores, apenas para serializar seções críticas por
+     * chave com o mesmo comportamento (stale-lock TTL, aviso) do contrato.
+     */
+    private readonly locks;
+    private readonly logger;
+    /** Índice por instância (M3-05.1) — alimenta o GC/LRU (#47). */
+    private readonly index;
+    /** @param options - Ver {@link DiskCacheStoreOptions}. */
+    constructor(options?: DiskCacheStoreOptions);
+    /** @inheritdoc */
+    get(key: CacheKey): Promise<V | undefined>;
+    /**
+     * @inheritdoc
+     * @param options - `type` classifica a entrada no índice por instância
+     *   (`extraction` default; `original` para bytes baixados) — quotas do GC #47.
+     */
+    put(key: CacheKey, value: V, options?: {
+        type?: CacheEntryType;
+    }): Promise<void>;
+    /** @inheritdoc */
+    invalidate(key: CacheKey): Promise<void>;
+    /** @inheritdoc */
+    lock<T>(key: CacheKey, critical: () => Promise<T>): Promise<T>;
+    /** @inheritdoc */
+    gc(): Promise<void>;
+    /** Diretórios de instância existentes no disco (exclui `issues/`). */
+    private listInstanceDirs;
+    /**
+     * Resolve o caminho absoluto do arquivo de valor de uma chave, seguindo o
+     * layout do ADR-004. O nome do arquivo é o SHA-256 hex da chave serializada,
+     * distinguindo configurações de extrator sob o mesmo `<id>-<digest8>/`.
+     */
+    /** Partes do caminho de uma chave attachment: dir `<id>-<digest8>` e arquivo. */
+    private attachmentParts;
+    private pathFor;
+    /**
+     * Executa o GC/LRU (#47): despeja o necessário para respeitar {@link maxBytes}
+     * (com quotas separadas — ver {@link planGc}) e, em seguida, aciona o hook de
+     * observação, se configurado, com a contagem REAL de entradas PÓS-despejo.
+     */
+    private runGc;
+    /**
+     * Coleta as entradas indexadas de TODAS as instâncias, aplica a política pura
+     * ({@link planGc}) e remove (arquivo + registro) o que ela decidir. No-op
+     * quando o teto é `Infinity` (despejo desabilitado) ou nada excede o limite.
+     */
+    private enforceQuotas;
+    /** Ajusta o total conhecido após uma escrita/remoção pontual. */
+    private adjustKnownBytes;
+    /**
+     * Remove com segurança UMA entrada de attachment: apaga o arquivo de valor
+     * (apenas se resolver DENTRO de `<cache_dir>/<instance_hash>/` — guard
+     * anti-traversal do {@link resolveEvictionTarget}) e tira o registro do índice,
+     * mantendo o `index.json` consistente pós-GC.
+     */
+    private evict;
+    /** Conta recursivamente os arquivos de valor (`.json`) sob `dir`. */
+    private countEntries;
+}

package/dist/cache/disk.js

@@ -0,0 +1,313 @@
+/**
+ * Implementação em DISCO do {@link CacheStore} (M3-02, ADR-004).
+ *
+ * Persiste cada entrada como um arquivo JSON num layout isolado por instância:
+ *
+ * - attachment: `<cache_dir>/<instance_hash>/attachments/<id>-<digest8>/<hash>.json`
+ * - issue:      `<cache_dir>/issues/<issue_id>/<hash>.json`
+ *
+ * O `<id>-<digest8>/` segue exatamente o path do ADR-004; `<hash>` é o SHA-256
+ * (hex) da chave serializada, garantindo que configurações de extrator distintas
+ * (versão/modelo/params) coexistam sob o mesmo anexo sem colidir. Nomes de
+ * arquivo/diretório derivam APENAS de `id`/`digest`/`hash` — nunca de conteúdo
+ * externo não sanitizado — pois todos esses campos são hex ou inteiros do
+ * contrato ({@link serializeCacheKey}).
+ *
+ * O `cache_dir` padrão vem de `env-paths` (diretório de cache do usuário por SO),
+ * com override pela opção {@link DiskCacheStoreOptions.cacheDir} (que o config/a
+ * CLI pode preencher). Diretórios são criados SOB DEMANDA no primeiro `put`.
+ *
+ * Atomicidade: cada `put` escreve num arquivo `.tmp` único e só então faz
+ * `rename` para o destino — o `rename` é atômico no mesmo filesystem, de modo que
+ * um leitor nunca observa um JSON parcial (crash-safety intra-arquivo).
+ *
+ * ESCOPO (nota da suíte de contrato, review #129): o lock por chave é HERDADO da
+ * implementação in-memory ({@link InMemoryCacheStore}) e vale apenas INTRA-processo
+ * — locking CROSS-processo NÃO é escopo desta issue (fica para uma issue de lock
+ * de disco). GC/LRU e índice de entradas são #45/#46: {@link gc} apenas aciona o
+ * hook configurado (no-op quando ausente).
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import envPaths from 'env-paths';
+import { serializeCacheKey, } from './contract.js';
+import { InMemoryCacheStore } from './memory.js';
+import { DiskCacheIndex, INDEX_FILE_NAME } from './disk-index.js';
+import { DEFAULT_MAX_BYTES, planGc, resolveEvictionTarget } from './gc.js';
+/** Comprimento (chars hex) do digest usado no path do anexo (ADR-004). */
+const DIGEST_PATH_LENGTH = 8;
+/** Subdiretório da camada de issue (bundle/metadados baratos). */
+const ISSUES_DIR = 'issues';
+/** Subdiretório da camada de attachment sob cada instância. */
+const ATTACHMENTS_DIR = 'attachments';
+/** Extensão dos arquivos de valor persistidos. */
+const VALUE_EXTENSION = '.json';
+/**
+ * Raiz de cache padrão do projeto (diretório de cache do usuário por SO, via
+ * `env-paths`). Ex.: `~/Library/Caches/redmine-context` no macOS.
+ *
+ * @returns Caminho absoluto do diretório de cache padrão.
+ */
+export function defaultCacheDir() {
+    return envPaths('redmine-context').cache;
+}
+/**
+ * {@link CacheStore} persistente em disco (ADR-004). Entradas sobrevivem à
+ * reinicialização do processo: uma nova instância apontando para o mesmo
+ * `cacheDir` enxerga tudo o que foi gravado.
+ *
+ * @typeParam V - Tipo do valor cacheado (serializado como JSON).
+ */
+export class DiskCacheStore {
+    root;
+    onGc;
+    /** Teto global (bytes) do GC/LRU; `Infinity` desabilita o despejo (#47). */
+    maxBytes;
+    /**
+     * Total de bytes indexados conhecido (curto-circuito do GC no put — review
+     * #137). `undefined` = ainda não computado: a primeira passada completa
+     * inicializa; depois, puts/invalidates/evictions mantêm incrementalmente.
+     */
+    knownBytes;
+    /**
+     * Provedor de lock por chave — HERDADO do in-memory (intra-processo). Não é
+     * usado para armazenar valores, apenas para serializar seções críticas por
+     * chave com o mesmo comportamento (stale-lock TTL, aviso) do contrato.
+     */
+    locks;
+    logger;
+    /** Índice por instância (M3-05.1) — alimenta o GC/LRU (#47). */
+    index;
+    /** @param options - Ver {@link DiskCacheStoreOptions}. */
+    constructor(options = {}) {
+        this.root = options.cacheDir ?? defaultCacheDir();
+        this.onGc = options.onGc;
+        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.logger = options.logger ?? { warn: () => undefined };
+        this.index = new DiskCacheIndex(this.root, this.logger);
+        // Repassa apenas as opções de lock; o GC é responsabilidade deste store.
+        this.locks = new InMemoryCacheStore({
+            ...(options.logger !== undefined ? { logger: options.logger } : {}),
+            ...(options.staleLockTtlMs !== undefined ? { staleLockTtlMs: options.staleLockTtlMs } : {}),
+        });
+    }
+    /** @inheritdoc */
+    async get(key) {
+        let raw;
+        try {
+            raw = await readFile(this.pathFor(key), 'utf8');
+        }
+        catch (cause) {
+            if (isNotFound(cause)) {
+                return undefined;
+            }
+            throw cause;
+        }
+        if (key.kind === 'attachment') {
+            const parts = this.attachmentParts(key);
+            this.index.recordAccess(key.instanceHash, join(parts.dirName, parts.fileName));
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // Arquivo corrompido (ex.: crash antes de um rename antigo): trata como
+            // cache-miss auto-curável — o próximo put sobrescreve. Nunca crasha nem
+            // se confunde com erro de IO real (fix review #131).
+            this.logger.warn(`cache: entrada corrompida ignorada (${this.pathFor(key)})`);
+            return undefined;
+        }
+    }
+    /**
+     * @inheritdoc
+     * @param options - `type` classifica a entrada no índice por instância
+     *   (`extraction` default; `original` para bytes baixados) — quotas do GC #47.
+     */
+    async put(key, value, options = {}) {
+        const filePath = this.pathFor(key);
+        await mkdir(dirname(filePath), { recursive: true });
+        // Escreve-e-renomeia: o destino só passa a existir de forma completa após o
+        // rename atômico; leitores nunca observam um JSON pela metade.
+        const serialized = JSON.stringify(value);
+        const tmpPath = `${filePath}.${randomBytes(6).toString('hex')}.tmp`;
+        await writeFile(tmpPath, serialized);
+        await rename(tmpPath, filePath);
+        if (key.kind === 'attachment') {
+            const parts = this.attachmentParts(key);
+            const size = Buffer.byteLength(serialized);
+            const previousSize = await this.index.recordPut(key.instanceHash, join(parts.dirName, parts.fileName), {
+                key: serializeCacheKey(key),
+                size,
+                type: options.type ?? 'extraction',
+                lastAccessedAt: new Date().toISOString(),
+            });
+            this.adjustKnownBytes(size - previousSize);
+        }
+        await this.runGc('put');
+    }
+    /** @inheritdoc */
+    async invalidate(key) {
+        await rm(this.pathFor(key), { force: true });
+        if (key.kind === 'attachment') {
+            const parts = this.attachmentParts(key);
+            const removedSize = await this.index.remove(key.instanceHash, join(parts.dirName, parts.fileName));
+            this.adjustKnownBytes(-removedSize);
+        }
+    }
+    /** @inheritdoc */
+    async lock(key, critical) {
+        return this.locks.lock(key, critical);
+    }
+    /** @inheritdoc */
+    async gc() {
+        // Flush do buffer de last_accessed_at (M3-05.1) antes de observar o estado,
+        // e reconciliação de órfãos (crash entre rename e recordPut — review #135).
+        await this.index.flushAll();
+        for (const instanceHash of await this.listInstanceDirs()) {
+            await this.index.reconcile(instanceHash);
+        }
+        await this.runGc('manual');
+    }
+    /** Diretórios de instância existentes no disco (exclui `issues/`). */
+    async listInstanceDirs() {
+        let entries;
+        try {
+            entries = await readdir(this.root, { withFileTypes: true });
+        }
+        catch (cause) {
+            if (isNotFound(cause)) {
+                return [];
+            }
+            throw cause;
+        }
+        return entries.filter((e) => e.isDirectory() && e.name !== ISSUES_DIR).map((e) => e.name);
+    }
+    /**
+     * Resolve o caminho absoluto do arquivo de valor de uma chave, seguindo o
+     * layout do ADR-004. O nome do arquivo é o SHA-256 hex da chave serializada,
+     * distinguindo configurações de extrator sob o mesmo `<id>-<digest8>/`.
+     */
+    /** Partes do caminho de uma chave attachment: dir `<id>-<digest8>` e arquivo. */
+    attachmentParts(key) {
+        const fileName = createHash('sha256').update(serializeCacheKey(key)).digest('hex') + VALUE_EXTENSION;
+        const hexDigest = /^[0-9a-fA-F]{8,64}$/.test(key.digest)
+            ? key.digest.toLowerCase()
+            : createHash('sha256').update(key.digest).digest('hex');
+        return { dirName: `${key.attachmentId}-${hexDigest.slice(0, DIGEST_PATH_LENGTH)}`, fileName };
+    }
+    pathFor(key) {
+        const fileName = createHash('sha256').update(serializeCacheKey(key)).digest('hex') + VALUE_EXTENSION;
+        if (key.kind === 'attachment') {
+            // O digest vem da API (conteúdo EXTERNO): só entra no path se for hex
+            // puro; qualquer outra forma (fallback id+filesize+created_on de
+            // Redmine antigo, ou valor malicioso com `../`) é normalizada por
+            // sha256 — traversal impossível por construção (fix review #131).
+            const hexDigest = /^[0-9a-fA-F]{8,64}$/.test(key.digest)
+                ? key.digest.toLowerCase()
+                : createHash('sha256').update(key.digest).digest('hex');
+            const digest8 = hexDigest.slice(0, DIGEST_PATH_LENGTH);
+            const dir = join(this.root, key.instanceHash, ATTACHMENTS_DIR, `${key.attachmentId}-${digest8}`);
+            return join(dir, fileName);
+        }
+        return join(this.root, ISSUES_DIR, String(key.issueId), fileName);
+    }
+    /**
+     * Executa o GC/LRU (#47): despeja o necessário para respeitar {@link maxBytes}
+     * (com quotas separadas — ver {@link planGc}) e, em seguida, aciona o hook de
+     * observação, se configurado, com a contagem REAL de entradas PÓS-despejo.
+     */
+    async runGc(reason) {
+        await this.enforceQuotas(reason === 'manual');
+        if (this.onGc === undefined) {
+            return;
+        }
+        await this.onGc({ reason, entryCount: await this.countEntries(this.root) });
+    }
+    /**
+     * Coleta as entradas indexadas de TODAS as instâncias, aplica a política pura
+     * ({@link planGc}) e remove (arquivo + registro) o que ela decidir. No-op
+     * quando o teto é `Infinity` (despejo desabilitado) ou nada excede o limite.
+     */
+    async enforceQuotas(force = false) {
+        if (!Number.isFinite(this.maxBytes)) {
+            return;
+        }
+        // Curto-circuito (review #137): com o total conhecido abaixo do teto, um
+        // put não paga coleta+sort de todas as entradas. gc() manual força a
+        // passada completa (que também reconcilia o total).
+        if (!force && this.knownBytes !== undefined && this.knownBytes <= this.maxBytes) {
+            return;
+        }
+        const candidates = [];
+        for (const instanceHash of await this.listInstanceDirs()) {
+            const entries = await this.index.entriesOf(instanceHash);
+            for (const [recordKey, entry] of entries) {
+                candidates.push({
+                    instanceHash,
+                    recordKey,
+                    size: entry.size,
+                    type: entry.type,
+                    lastAccessedAt: entry.lastAccessedAt,
+                });
+            }
+        }
+        const { remove } = planGc(candidates, { maxBytes: this.maxBytes });
+        for (const candidate of remove) {
+            await this.evict(candidate.instanceHash, candidate.recordKey);
+        }
+        const total = candidates.reduce((sum, c) => sum + c.size, 0);
+        const evicted = remove.reduce((sum, c) => sum + c.size, 0);
+        this.knownBytes = total - evicted;
+    }
+    /** Ajusta o total conhecido após uma escrita/remoção pontual. */
+    adjustKnownBytes(delta) {
+        if (this.knownBytes !== undefined) {
+            this.knownBytes = Math.max(0, this.knownBytes + delta);
+        }
+    }
+    /**
+     * Remove com segurança UMA entrada de attachment: apaga o arquivo de valor
+     * (apenas se resolver DENTRO de `<cache_dir>/<instance_hash>/` — guard
+     * anti-traversal do {@link resolveEvictionTarget}) e tira o registro do índice,
+     * mantendo o `index.json` consistente pós-GC.
+     */
+    async evict(instanceHash, recordKey) {
+        const instanceRoot = join(this.root, instanceHash);
+        const target = resolveEvictionTarget(instanceRoot, join(ATTACHMENTS_DIR, recordKey));
+        if (target === undefined) {
+            // Registro apontando para fora da instância: nunca apaga; só avisa.
+            this.logger.warn(`cache: GC recusou remover caminho fora da instância (${recordKey})`);
+            return;
+        }
+        await rm(target, { force: true });
+        await this.index.remove(instanceHash, recordKey);
+    }
+    /** Conta recursivamente os arquivos de valor (`.json`) sob `dir`. */
+    async countEntries(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (cause) {
+            if (isNotFound(cause)) {
+                return 0;
+            }
+            throw cause;
+        }
+        let count = 0;
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                count += await this.countEntries(join(dir, entry.name));
+            }
+            else if (entry.isFile() && entry.name.endsWith(VALUE_EXTENSION) && entry.name !== INDEX_FILE_NAME) {
+                count += 1;
+            }
+        }
+        return count;
+    }
+}
+/** Verifica se um erro do fs é "arquivo não encontrado" (ENOENT). */
+function isNotFound(cause) {
+    return (typeof cause === 'object' && cause !== null && cause.code === 'ENOENT');
+}

package/dist/cache/gc.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Política PURA de GC/LRU do cache em disco (M3-05.2, #47, ADR-004).
+ *
+ * Este módulo NÃO toca no filesystem: recebe uma lista de entradas candidatas
+ * (tamanho, tipo e `last_accessed_at`, vindas do índice por instância do #46) e
+ * DECIDE quais remover para respeitar o teto global (default 2 GB) e as quotas
+ * SEPARADAS por tipo. A integração (leitura do índice, remoção dos arquivos e do
+ * registro) fica no {@link ../cache/disk.js DiskCacheStore}. Separar a decisão da
+ * execução deixa a política totalmente testável com fakes de tamanho.
+ *
+ * Estratégia de quotas (ADR-004, item 4):
+ * - Originais (`type: 'original'`): recuperáveis do Redmine → remoção AGRESSIVA.
+ *   Podem ocupar no máximo {@link DEFAULT_MAX_ORIGINAL_FRACTION} (50%) do teto;
+ *   ao estourar essa quota, saem primeiro (LRU), mesmo que o teto GLOBAL ainda
+ *   não tenha sido violado.
+ * - Extrações (`type: 'extraction'`): caras de reproduzir → remoção CONSERVADORA.
+ *   Só são removidas quando, após despejar TODOS os originais, o total ainda
+ *   excede o teto global. A extração mais recentemente acessada é a última a sair.
+ *
+ * O critério de idade é sempre `last_accessed_at` (LRU): mais antigo sai primeiro;
+ * empates são desfeitos de forma determinística por `instanceHash`+`recordKey`.
+ */
+import type { CacheEntryType } from './disk-index.js';
+/** Teto global default do cache em bytes (2 GB — ADR-004). */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Fração máxima do teto que os originais podem ocupar (quota agressiva). */
+export declare const DEFAULT_MAX_ORIGINAL_FRACTION = 0.5;
+/**
+ * Uma entrada candidata ao GC. Carrega o suficiente para (a) decidir a remoção
+ * pela política e (b) localizar o arquivo/registro na integração.
+ */
+export interface GcCandidate {
+    /** Instância dona da entrada — namespace do índice e do diretório. */
+    instanceHash: string;
+    /** Chave de registro no índice: caminho relativo dentro de `attachments/`. */
+    recordKey: string;
+    /** Tamanho do valor em bytes (do índice). */
+    size: number;
+    /** Classificação para as quotas separadas. */
+    type: CacheEntryType;
+    /** ISO 8601 do último acesso conhecido — critério LRU. */
+    lastAccessedAt: string;
+}
+/** Parâmetros da política de GC. */
+export interface GcPolicyOptions {
+    /** Teto global do cache em bytes. */
+    maxBytes: number;
+    /**
+     * Fração máxima do teto ocupável por originais (0..1). Default
+     * {@link DEFAULT_MAX_ORIGINAL_FRACTION}.
+     */
+    maxOriginalFraction?: number;
+}
+/** Resultado da política: as entradas a remover, já em ordem de despejo (LRU). */
+export interface GcDecision {
+    /** Entradas a remover, da mais antiga (primeira a sair) para a mais recente. */
+    remove: GcCandidate[];
+}
+/**
+ * Decide quais entradas remover para respeitar teto global e quotas separadas.
+ *
+ * @param candidates - Todas as entradas atualmente no cache (qualquer instância).
+ * @param options - Ver {@link GcPolicyOptions}.
+ * @returns As entradas a despejar (vazio se nada precisa sair) — ver {@link GcDecision}.
+ * @example
+ * const { remove } = planGc(entries, { maxBytes: 2 * 1024 ** 3 });
+ */
+export declare function planGc(candidates: readonly GcCandidate[], options: GcPolicyOptions): GcDecision;
+/**
+ * Guard anti-traversal do despejo: resolve o caminho ABSOLUTO de um alvo de
+ * remoção e devolve `undefined` se ele cair FORA de `<instanceRoot>/` (ex.: um
+ * `recordKey` com `../`). Garante que o GC só apaga dentro da instância.
+ *
+ * @param instanceRoot - Raiz absoluta da instância (`<cache_dir>/<instance_hash>`).
+ * @param relativePath - Caminho relativo à raiz da instância (inclui `attachments/`).
+ * @returns Caminho absoluto seguro, ou `undefined` se escaparia da instância.
+ */
+export declare function resolveEvictionTarget(instanceRoot: string, relativePath: string): string | undefined;

package/dist/cache/gc.js

@@ -0,0 +1,123 @@
+/**
+ * Política PURA de GC/LRU do cache em disco (M3-05.2, #47, ADR-004).
+ *
+ * Este módulo NÃO toca no filesystem: recebe uma lista de entradas candidatas
+ * (tamanho, tipo e `last_accessed_at`, vindas do índice por instância do #46) e
+ * DECIDE quais remover para respeitar o teto global (default 2 GB) e as quotas
+ * SEPARADAS por tipo. A integração (leitura do índice, remoção dos arquivos e do
+ * registro) fica no {@link ../cache/disk.js DiskCacheStore}. Separar a decisão da
+ * execução deixa a política totalmente testável com fakes de tamanho.
+ *
+ * Estratégia de quotas (ADR-004, item 4):
+ * - Originais (`type: 'original'`): recuperáveis do Redmine → remoção AGRESSIVA.
+ *   Podem ocupar no máximo {@link DEFAULT_MAX_ORIGINAL_FRACTION} (50%) do teto;
+ *   ao estourar essa quota, saem primeiro (LRU), mesmo que o teto GLOBAL ainda
+ *   não tenha sido violado.
+ * - Extrações (`type: 'extraction'`): caras de reproduzir → remoção CONSERVADORA.
+ *   Só são removidas quando, após despejar TODOS os originais, o total ainda
+ *   excede o teto global. A extração mais recentemente acessada é a última a sair.
+ *
+ * O critério de idade é sempre `last_accessed_at` (LRU): mais antigo sai primeiro;
+ * empates são desfeitos de forma determinística por `instanceHash`+`recordKey`.
+ */
+import { resolve, sep } from 'node:path';
+/** Teto global default do cache em bytes (2 GB — ADR-004). */
+export const DEFAULT_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+/** Fração máxima do teto que os originais podem ocupar (quota agressiva). */
+export const DEFAULT_MAX_ORIGINAL_FRACTION = 0.5;
+/**
+ * Decide quais entradas remover para respeitar teto global e quotas separadas.
+ *
+ * @param candidates - Todas as entradas atualmente no cache (qualquer instância).
+ * @param options - Ver {@link GcPolicyOptions}.
+ * @returns As entradas a despejar (vazio se nada precisa sair) — ver {@link GcDecision}.
+ * @example
+ * const { remove } = planGc(entries, { maxBytes: 2 * 1024 ** 3 });
+ */
+export function planGc(candidates, options) {
+    const maxBytes = options.maxBytes;
+    const fraction = options.maxOriginalFraction ?? DEFAULT_MAX_ORIGINAL_FRACTION;
+    const originalsCap = maxBytes * fraction;
+    // Ordem LRU crescente: o mais antigo (primeiro a sair) na frente. Empate
+    // determinístico por instância+registro para reprodutibilidade.
+    const lruAscending = [...candidates].sort(compareLru);
+    const removed = new Set();
+    let totalSize = sum(candidates);
+    let originalsSize = sum(candidates.filter((c) => c.type === 'original'));
+    // Passo A — quota dos originais: podem ocupar no máx `originalsCap`.
+    for (const candidate of lruAscending) {
+        if (originalsSize <= originalsCap) {
+            break;
+        }
+        if (candidate.type !== 'original' || removed.has(candidate)) {
+            continue;
+        }
+        removed.add(candidate);
+        originalsSize -= candidate.size;
+        totalSize -= candidate.size;
+    }
+    // Passo B — teto global: originais LRU primeiro (recuperáveis)...
+    for (const candidate of lruAscending) {
+        if (totalSize <= maxBytes) {
+            break;
+        }
+        if (candidate.type !== 'original' || removed.has(candidate)) {
+            continue;
+        }
+        removed.add(candidate);
+        totalSize -= candidate.size;
+    }
+    // ...e só então extrações LRU (caras), se ainda exceder.
+    for (const candidate of lruAscending) {
+        if (totalSize <= maxBytes) {
+            break;
+        }
+        if (candidate.type !== 'extraction' || removed.has(candidate)) {
+            continue;
+        }
+        removed.add(candidate);
+        totalSize -= candidate.size;
+    }
+    return { remove: lruAscending.filter((candidate) => removed.has(candidate)) };
+}
+/**
+ * Guard anti-traversal do despejo: resolve o caminho ABSOLUTO de um alvo de
+ * remoção e devolve `undefined` se ele cair FORA de `<instanceRoot>/` (ex.: um
+ * `recordKey` com `../`). Garante que o GC só apaga dentro da instância.
+ *
+ * @param instanceRoot - Raiz absoluta da instância (`<cache_dir>/<instance_hash>`).
+ * @param relativePath - Caminho relativo à raiz da instância (inclui `attachments/`).
+ * @returns Caminho absoluto seguro, ou `undefined` se escaparia da instância.
+ */
+export function resolveEvictionTarget(instanceRoot, relativePath) {
+    const base = resolve(instanceRoot);
+    const target = resolve(base, relativePath);
+    // Estritamente ABAIXO da raiz da instância: nunca a própria raiz nem irmãos.
+    if (target.startsWith(base + sep)) {
+        return target;
+    }
+    return undefined;
+}
+/** Soma dos tamanhos de um conjunto de candidatas. */
+function sum(candidates) {
+    let total = 0;
+    for (const candidate of candidates) {
+        total += candidate.size;
+    }
+    return total;
+}
+/** Comparador LRU crescente com desempate determinístico. */
+function compareLru(a, b) {
+    const ta = Date.parse(a.lastAccessedAt);
+    const tb = Date.parse(b.lastAccessedAt);
+    if (ta !== tb) {
+        return ta - tb;
+    }
+    if (a.instanceHash !== b.instanceHash) {
+        return a.instanceHash < b.instanceHash ? -1 : 1;
+    }
+    if (a.recordKey !== b.recordKey) {
+        return a.recordKey < b.recordKey ? -1 : 1;
+    }
+    return 0;
+}