@semacode/cli 2.3.0 → 2.3.1

package/dist/driftCacheIncremental.js

@@ -0,0 +1,596 @@
+// SEMA-GOVERNED: sema.produto.governanca_ia.drift
+// Descricao: cache persistente incremental por arquivo e por grupo semantico, com validacao runtime e fast path por metadados.
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { digestJsonCanonicoCacheDrift, serializarJsonCanonicoCacheDrift, } from "./driftCache.js";
+import { escreverArquivoWorkspaceSeguro, validarDestinosEscritaWorkspace, } from "./workspaceWrite.js";
+export const FILE_INDEX_SCHEMA = 2;
+export const SCHEMA_MANIFESTO_ARQUIVOS_DRIFT = "sema.drift-file-cache/v2";
+export const SCHEMA_GRUPO_INDICE_DRIFT = "sema.drift-index-group-cache/v2";
+export const DIRETORIO_CACHE_INCREMENTAL_DRIFT = path.join(".tmp", "sema-cache", "drift-index", "v2");
+export const DIRETORIO_IDENTIDADES_CACHE_INCREMENTAL_DRIFT = path.join(DIRETORIO_CACHE_INCREMENTAL_DRIFT, "identities");
+const LIMITE_BYTES_CACHE = 64 * 1024 * 1024;
+const PADRAO_DIGEST = /^sha256:[a-f0-9]{64}$/u;
+function sufixoSeguroIdentidade(identidadeDigest) {
+    if (!PADRAO_DIGEST.test(identidadeDigest)) {
+        throw new TypeError(`identidade_digest_cache_drift_invalida:${identidadeDigest}`);
+    }
+    return identidadeDigest.slice("sha256:".length);
+}
+export function caminhoManifestoArquivosDrift(identidadeDigest) {
+    return path.join(DIRETORIO_IDENTIDADES_CACHE_INCREMENTAL_DRIFT, sufixoSeguroIdentidade(identidadeDigest), "files.json");
+}
+export function caminhoManifestoGruposDrift(identidadeDigest) {
+    return path.join(DIRETORIO_IDENTIDADES_CACHE_INCREMENTAL_DRIFT, sufixoSeguroIdentidade(identidadeDigest), "groups.json");
+}
+function registroObjeto(valor) {
+    return typeof valor === "object" && valor !== null && !Array.isArray(valor);
+}
+function emitirEvento(observador, evento) {
+    try {
+        observador?.(evento);
+    }
+    catch {
+        // Observabilidade nao altera o resultado funcional do drift.
+    }
+}
+function paraJson(valor) {
+    return JSON.parse(JSON.stringify(valor));
+}
+function assinaturasIguais(a, b) {
+    return a.size === b.size
+        && a.mtimeNs === b.mtimeNs
+        && a.ctimeNs === b.ctimeNs
+        && a.dev === b.dev
+        && a.ino === b.ino;
+}
+function assinaturaValida(valor) {
+    if (!registroObjeto(valor)) {
+        return false;
+    }
+    return ["size", "mtimeNs", "ctimeNs", "dev", "ino"]
+        .every((campo) => typeof valor[campo] === "string" && /^\d+$/u.test(valor[campo]));
+}
+function caminhoRelativoSeguro(baseProjeto, arquivo) {
+    const relativo = path.relative(baseProjeto, path.resolve(arquivo)).replace(/\\/g, "/");
+    if (!relativo || relativo === "." || relativo === ".." || relativo.startsWith("../") || path.isAbsolute(relativo)) {
+        throw new Error(`arquivo_cache_drift_fora_workspace:${arquivo}`);
+    }
+    return relativo;
+}
+function caminhoRelativoValido(caminho) {
+    return typeof caminho === "string"
+        && caminho.length > 0
+        && caminho !== "."
+        && caminho !== ".."
+        && !caminho.startsWith("../")
+        && !caminho.includes("\\")
+        && !path.posix.isAbsolute(caminho);
+}
+function chaveEstavel(valor) {
+    return createHash("sha256")
+        .update(serializarJsonCanonicoCacheDrift(valor))
+        .digest("hex");
+}
+function analiseValida(valor) {
+    return registroObjeto(valor)
+        && typeof valor.payloadDigest === "string"
+        && PADRAO_DIGEST.test(valor.payloadDigest)
+        && digestJsonCanonicoCacheDrift(valor.payload) === valor.payloadDigest;
+}
+function entradaArquivoValida(chave, valor) {
+    if (!registroObjeto(valor)
+        || valor.caminho !== chave
+        || !caminhoRelativoValido(valor.caminho)
+        || !assinaturaValida(valor.assinatura)
+        || typeof valor.contentHash !== "string"
+        || !PADRAO_DIGEST.test(valor.contentHash)
+        || !registroObjeto(valor.analises)) {
+        return false;
+    }
+    return Object.values(valor.analises).every(analiseValida);
+}
+function manifestoValido(valor, identidadeDigest) {
+    if (!registroObjeto(valor)
+        || valor.identidadeDigest !== identidadeDigest
+        || !registroObjeto(valor.arquivos)) {
+        return false;
+    }
+    return Object.entries(valor.arquivos).every(([chave, entrada]) => entradaArquivoValida(chave, entrada));
+}
+function membrosGrupoValidos(valor) {
+    return Array.isArray(valor)
+        && valor.every((item) => registroObjeto(item)
+            && caminhoRelativoValido(item.caminho)
+            && typeof item.contentHash === "string"
+            && PADRAO_DIGEST.test(item.contentHash));
+}
+function membrosIguais(a, b) {
+    return a.length === b.length
+        && a.every((item, indice) => (item.caminho === b[indice]?.caminho
+            && item.contentHash === b[indice]?.contentHash));
+}
+function entradaGrupoValida(valor, identidadeDigest) {
+    return registroObjeto(valor)
+        && valor.identidadeDigest === identidadeDigest
+        && membrosGrupoValidos(valor.membros)
+        && typeof valor.resumoDigest === "string"
+        && PADRAO_DIGEST.test(valor.resumoDigest)
+        && digestJsonCanonicoCacheDrift(valor.resumo) === valor.resumoDigest;
+}
+function manifestoGruposValido(valor, identidadeDigest) {
+    return registroObjeto(valor)
+        && valor.identidadeDigest === identidadeDigest
+        && registroObjeto(valor.grupos)
+        && Object.entries(valor.grupos).every(([chave, entrada]) => (/^[a-f0-9]{64}$/u.test(chave)
+            && entradaGrupoValida(entrada, identidadeDigest)));
+}
+function erroEhAusencia(erro) {
+    return ["ENOENT", "ENOTDIR"].includes(erro.code ?? "");
+}
+async function lerEnvelope(baseProjeto, caminhoRelativo, schema, key) {
+    try {
+        const [destino] = await validarDestinosEscritaWorkspace(baseProjeto, [caminhoRelativo]);
+        if (!destino.existe) {
+            return { estado: "miss", motivo: "arquivo_ausente" };
+        }
+        const info = await lstat(destino.caminhoAbsoluto);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > LIMITE_BYTES_CACHE) {
+            return { estado: "corrupt", motivo: "arquivo_cache_invalido" };
+        }
+        const bytes = await readFile(destino.caminhoAbsoluto);
+        if (bytes.byteLength > LIMITE_BYTES_CACHE) {
+            return { estado: "corrupt", motivo: "limite_bytes_excedido" };
+        }
+        let bruto;
+        try {
+            bruto = JSON.parse(bytes.toString("utf8"));
+        }
+        catch {
+            return { estado: "corrupt", motivo: "json_invalido" };
+        }
+        if (!registroObjeto(bruto)
+            || bruto.schema !== schema
+            || bruto.key !== key
+            || typeof bruto.payloadDigest !== "string"
+            || !PADRAO_DIGEST.test(bruto.payloadDigest)) {
+            return { estado: "corrupt", motivo: "envelope_invalido" };
+        }
+        let digest;
+        try {
+            digest = digestJsonCanonicoCacheDrift(bruto.payload);
+        }
+        catch {
+            return { estado: "corrupt", motivo: "payload_nao_canonico" };
+        }
+        if (digest !== bruto.payloadDigest) {
+            return { estado: "corrupt", motivo: "payload_digest_divergente" };
+        }
+        return { estado: "hit", payload: bruto.payload };
+    }
+    catch (erro) {
+        return {
+            estado: "miss",
+            motivo: erroEhAusencia(erro) ? "arquivo_ausente" : "cache_indisponivel",
+        };
+    }
+}
+async function escreverEnvelope(baseProjeto, caminhoRelativo, schema, key, payload) {
+    const envelope = {
+        schema,
+        key,
+        payload,
+        payloadDigest: digestJsonCanonicoCacheDrift(payload),
+    };
+    const conteudo = JSON.stringify(envelope);
+    if (Buffer.byteLength(conteudo, "utf8") > LIMITE_BYTES_CACHE) {
+        throw new Error("limite_bytes_cache_incremental_excedido");
+    }
+    await escreverArquivoWorkspaceSeguro(baseProjeto, caminhoRelativo, conteudo, { sobrescrever: true });
+}
+export async function obterAssinaturaArquivoDrift(arquivo) {
+    const info = await lstat(arquivo, { bigint: true });
+    if (!info.isFile() || info.isSymbolicLink()) {
+        throw new Error(`arquivo_cache_drift_nao_regular:${arquivo}`);
+    }
+    return {
+        size: info.size.toString(),
+        mtimeNs: info.mtimeNs.toString(),
+        ctimeNs: info.ctimeNs.toString(),
+        dev: info.dev.toString(),
+        ino: info.ino.toString(),
+    };
+}
+export class CacheIncrementalDrift {
+    identidadeDigest;
+    politica;
+    baseProjeto;
+    baseProjetoReal;
+    observador;
+    caminhoManifestoArquivos;
+    caminhoManifestoGrupos;
+    manifesto;
+    manifestoEmVoo;
+    manifestoSujo = false;
+    arquivosSujos = new Set();
+    manifestoGrupos;
+    manifestoGruposEmVoo;
+    manifestoGruposSujo = false;
+    gruposSujos = new Set();
+    arquivosEmVoo = new Map();
+    metricasAtuais = {
+        metadataHits: 0,
+        contentHits: 0,
+        fileMisses: 0,
+        groupHits: 0,
+        groupMisses: 0,
+        corruptos: 0,
+        extracoesArquivo: 0,
+        extracoesGrupo: 0,
+        gravacoes: 0,
+        errosGravacao: 0,
+    };
+    constructor(opcoes) {
+        this.baseProjeto = path.resolve(opcoes.baseProjeto);
+        this.baseProjetoReal = realpath(this.baseProjeto);
+        this.politica = opcoes.politica;
+        this.identidadeDigest = digestJsonCanonicoCacheDrift(opcoes.identidade);
+        this.caminhoManifestoArquivos = caminhoManifestoArquivosDrift(this.identidadeDigest);
+        this.caminhoManifestoGrupos = caminhoManifestoGruposDrift(this.identidadeDigest);
+        this.observador = opcoes.observador;
+    }
+    metricas() {
+        return { ...this.metricasAtuais };
+    }
+    async resolverArquivo(opcoes) {
+        const chaveExecucao = `${process.platform === "win32" ? path.resolve(opcoes.arquivo).toLowerCase() : path.resolve(opcoes.arquivo)}\0${opcoes.analise}`;
+        const existenteEmVoo = this.arquivosEmVoo.get(chaveExecucao);
+        if (existenteEmVoo) {
+            return existenteEmVoo;
+        }
+        const execucao = this.resolverArquivoInterno(opcoes);
+        this.arquivosEmVoo.set(chaveExecucao, execucao);
+        void execucao.catch(() => {
+            if (this.arquivosEmVoo.get(chaveExecucao) === execucao) {
+                this.arquivosEmVoo.delete(chaveExecucao);
+            }
+        });
+        return execucao;
+    }
+    async resolverArquivoInterno(opcoes) {
+        await this.validarArquivoNoWorkspace(opcoes.arquivo);
+        const caminho = caminhoRelativoSeguro(this.baseProjeto, opcoes.arquivo);
+        const assinar = opcoes.assinar ?? (() => obterAssinaturaArquivoDrift(opcoes.arquivo));
+        const assinaturaAntes = await assinar();
+        const manifesto = await this.obterManifesto();
+        const existente = manifesto.arquivos[caminho];
+        const analiseExistente = existente?.analises[opcoes.analise];
+        const payloadExistente = analiseExistente?.payload;
+        const payloadValido = analiseExistente !== undefined && opcoes.validar(payloadExistente);
+        if (analiseExistente && !payloadValido) {
+            this.registrarCorrupto(opcoes.arquivo, "payload_schema_invalido");
+        }
+        if (this.politica === "auto"
+            && existente
+            && payloadValido
+            && assinaturasIguais(existente.assinatura, assinaturaAntes)) {
+            this.metricasAtuais.metadataHits += 1;
+            emitirEvento(this.observador, {
+                tipo: "cache.hit",
+                caminho: path.resolve(opcoes.arquivo),
+                motivo: "metadata_hit",
+            });
+            return {
+                caminho,
+                contentHash: existente.contentHash,
+                valor: payloadExistente,
+                origem: "metadata_hit",
+            };
+        }
+        this.metricasAtuais.fileMisses += 1;
+        emitirEvento(this.observador, {
+            tipo: "cache.miss",
+            caminho: path.resolve(opcoes.arquivo),
+            motivo: this.politica === "refresh" ? "politica_refresh" : this.politica === "off" ? "politica_off" : "metadata_miss",
+        });
+        const conteudo = await opcoes.ler();
+        if (this.politica === "auto"
+            && existente
+            && payloadValido
+            && existente.contentHash === conteudo.digest) {
+            const assinaturaDepois = await assinar();
+            if (assinaturasIguais(assinaturaAntes, assinaturaDepois)) {
+                existente.assinatura = assinaturaDepois;
+                this.manifestoSujo = true;
+                this.arquivosSujos.add(caminho);
+            }
+            this.metricasAtuais.contentHits += 1;
+            emitirEvento(this.observador, {
+                tipo: "cache.hit",
+                caminho: path.resolve(opcoes.arquivo),
+                motivo: "content_hit",
+            });
+            return {
+                caminho,
+                contentHash: conteudo.digest,
+                valor: payloadExistente,
+                origem: "content_hit",
+            };
+        }
+        this.metricasAtuais.extracoesArquivo += 1;
+        emitirEvento(this.observador, {
+            tipo: "extractor.run",
+            caminho: path.resolve(opcoes.arquivo),
+            motivo: `arquivo:${opcoes.analise}`,
+        });
+        const valor = paraJson(await opcoes.extrair(conteudo));
+        if (!opcoes.validar(valor)) {
+            throw new Error(`extrator_cache_drift_payload_invalido:${opcoes.analise}:${caminho}`);
+        }
+        if (this.politica !== "off") {
+            const assinaturaDepois = await assinar();
+            if (assinaturasIguais(assinaturaAntes, assinaturaDepois)) {
+                const analises = existente?.contentHash === conteudo.digest
+                    ? { ...existente.analises }
+                    : {};
+                analises[opcoes.analise] = {
+                    payload: valor,
+                    payloadDigest: digestJsonCanonicoCacheDrift(valor),
+                };
+                manifesto.arquivos[caminho] = {
+                    caminho,
+                    assinatura: assinaturaDepois,
+                    contentHash: conteudo.digest,
+                    analises,
+                };
+                this.manifestoSujo = true;
+                this.arquivosSujos.add(caminho);
+            }
+        }
+        return {
+            caminho,
+            contentHash: conteudo.digest,
+            valor,
+            origem: "calculado",
+        };
+    }
+    async resolverGrupo(opcoes) {
+        const membros = opcoes.membros
+            .map((membro) => ({
+            caminho: caminhoRelativoSeguro(this.baseProjeto, membro.caminho),
+            contentHash: membro.contentHash,
+        }))
+            .sort((a, b) => a.caminho.localeCompare(b.caminho, "en"));
+        // A chave e ancorada no primeiro arquivo, nao no conteudo nem na composicao
+        // atual do grupo. Mudancas sobrescrevem a mesma entrada e evitam crescimento
+        // infinito do cache; a lista completa de membros continua validada no envelope.
+        const chave = chaveEstavel({ ancora: membros[0]?.caminho ?? "grupo-vazio" });
+        const caminhoRelativo = this.caminhoManifestoGrupos;
+        if (this.politica === "auto") {
+            const manifesto = await this.obterManifestoGrupos();
+            const payload = manifesto.grupos[chave];
+            if (payload) {
+                const identidadeAtual = payload.identidadeDigest === this.identidadeDigest;
+                const membrosAtuais = membrosIguais(payload.membros, membros);
+                if (identidadeAtual && membrosAtuais) {
+                    if (opcoes.validar(payload.resumo)) {
+                        this.metricasAtuais.groupHits += 1;
+                        emitirEvento(this.observador, {
+                            tipo: "cache.hit",
+                            chave,
+                            caminho: path.resolve(this.baseProjeto, caminhoRelativo),
+                            motivo: "group_content_hit",
+                        });
+                        return { chave, valor: payload.resumo, origem: "cache" };
+                    }
+                    this.registrarCorrupto(path.resolve(this.baseProjeto, caminhoRelativo), "payload_schema_invalido");
+                }
+            }
+        }
+        this.metricasAtuais.groupMisses += 1;
+        emitirEvento(this.observador, {
+            tipo: "cache.miss",
+            chave,
+            caminho: path.resolve(this.baseProjeto, caminhoRelativo),
+            motivo: this.politica === "refresh" ? "politica_refresh" : this.politica === "off" ? "politica_off" : "group_miss",
+        });
+        this.metricasAtuais.extracoesGrupo += 1;
+        emitirEvento(this.observador, {
+            tipo: "extractor.run",
+            chave,
+            caminho: opcoes.membros[0]?.caminho,
+            motivo: `grupo:${membros.length}`,
+        });
+        const valor = paraJson(await opcoes.calcular());
+        if (!opcoes.validar(valor)) {
+            throw new Error(`extrator_grupo_cache_drift_payload_invalido:${chave}`);
+        }
+        if (this.politica !== "off") {
+            const payload = {
+                identidadeDigest: this.identidadeDigest,
+                membros,
+                resumo: valor,
+                resumoDigest: digestJsonCanonicoCacheDrift(valor),
+            };
+            const manifesto = await this.obterManifestoGrupos();
+            manifesto.grupos[chave] = payload;
+            this.manifestoGruposSujo = true;
+            this.gruposSujos.add(chave);
+        }
+        return { chave, valor, origem: "calculado" };
+    }
+    async finalizar() {
+        if (this.politica === "off") {
+            return;
+        }
+        if (this.manifestoSujo && this.manifesto) {
+            try {
+                this.manifesto = await this.gravarManifestoArquivosComMerge(this.manifesto);
+                this.metricasAtuais.gravacoes += 1;
+                this.manifestoSujo = false;
+                this.arquivosSujos.clear();
+            }
+            catch {
+                this.metricasAtuais.errosGravacao += 1;
+            }
+        }
+        if (this.manifestoGruposSujo && this.manifestoGrupos) {
+            try {
+                this.manifestoGrupos = await this.gravarManifestoGruposComMerge(this.manifestoGrupos);
+                this.metricasAtuais.gravacoes += 1;
+                this.manifestoGruposSujo = false;
+                this.gruposSujos.clear();
+            }
+            catch {
+                this.metricasAtuais.errosGravacao += 1;
+            }
+        }
+    }
+    chaveEnvelope(tipo) {
+        return `${tipo}:${this.identidadeDigest}`;
+    }
+    async lerManifestoArquivosAtual() {
+        const leitura = await lerEnvelope(this.baseProjeto, this.caminhoManifestoArquivos, SCHEMA_MANIFESTO_ARQUIVOS_DRIFT, this.chaveEnvelope("files"));
+        return leitura.estado === "hit" && manifestoValido(leitura.payload, this.identidadeDigest)
+            ? leitura.payload
+            : undefined;
+    }
+    async lerManifestoGruposAtual() {
+        const leitura = await lerEnvelope(this.baseProjeto, this.caminhoManifestoGrupos, SCHEMA_GRUPO_INDICE_DRIFT, this.chaveEnvelope("groups"));
+        return leitura.estado === "hit" && manifestoGruposValido(leitura.payload, this.identidadeDigest)
+            ? leitura.payload
+            : undefined;
+    }
+    async gravarManifestoArquivosComMerge(local) {
+        let ultimoErro;
+        for (let tentativa = 0; tentativa < 2; tentativa += 1) {
+            const publicado = await this.lerManifestoArquivosAtual();
+            const mesclado = {
+                identidadeDigest: this.identidadeDigest,
+                arquivos: publicado ? { ...publicado.arquivos } : {},
+            };
+            for (const caminho of this.arquivosSujos) {
+                const entrada = local.arquivos[caminho];
+                if (entrada) {
+                    mesclado.arquivos[caminho] = entrada;
+                }
+            }
+            try {
+                await escreverEnvelope(this.baseProjeto, this.caminhoManifestoArquivos, SCHEMA_MANIFESTO_ARQUIVOS_DRIFT, this.chaveEnvelope("files"), mesclado);
+                return mesclado;
+            }
+            catch (erro) {
+                ultimoErro = erro;
+            }
+        }
+        throw ultimoErro;
+    }
+    async gravarManifestoGruposComMerge(local) {
+        let ultimoErro;
+        for (let tentativa = 0; tentativa < 2; tentativa += 1) {
+            const publicado = await this.lerManifestoGruposAtual();
+            const mesclado = {
+                identidadeDigest: this.identidadeDigest,
+                grupos: publicado ? { ...publicado.grupos } : {},
+            };
+            for (const chave of this.gruposSujos) {
+                const entrada = local.grupos[chave];
+                if (entrada) {
+                    mesclado.grupos[chave] = entrada;
+                }
+            }
+            try {
+                await escreverEnvelope(this.baseProjeto, this.caminhoManifestoGrupos, SCHEMA_GRUPO_INDICE_DRIFT, this.chaveEnvelope("groups"), mesclado);
+                return mesclado;
+            }
+            catch (erro) {
+                ultimoErro = erro;
+            }
+        }
+        throw ultimoErro;
+    }
+    async obterManifesto() {
+        if (this.manifesto) {
+            return this.manifesto;
+        }
+        if (this.manifestoEmVoo) {
+            return this.manifestoEmVoo;
+        }
+        this.manifestoEmVoo = this.carregarManifesto();
+        try {
+            return await this.manifestoEmVoo;
+        }
+        finally {
+            this.manifestoEmVoo = undefined;
+        }
+    }
+    async carregarManifesto() {
+        if (this.politica === "auto") {
+            const leitura = await lerEnvelope(this.baseProjeto, this.caminhoManifestoArquivos, SCHEMA_MANIFESTO_ARQUIVOS_DRIFT, this.chaveEnvelope("files"));
+            if (leitura.estado === "hit" && manifestoValido(leitura.payload, this.identidadeDigest)) {
+                this.manifesto = leitura.payload;
+                return this.manifesto;
+            }
+            if (leitura.estado === "corrupt" || leitura.estado === "hit") {
+                this.registrarCorrupto(path.resolve(this.baseProjeto, this.caminhoManifestoArquivos), leitura.estado === "hit" ? "payload_schema_invalido" : leitura.motivo);
+            }
+        }
+        this.manifesto = {
+            identidadeDigest: this.identidadeDigest,
+            arquivos: {},
+        };
+        return this.manifesto;
+    }
+    async obterManifestoGrupos() {
+        if (this.manifestoGrupos) {
+            return this.manifestoGrupos;
+        }
+        if (this.manifestoGruposEmVoo) {
+            return this.manifestoGruposEmVoo;
+        }
+        this.manifestoGruposEmVoo = this.carregarManifestoGrupos();
+        try {
+            return await this.manifestoGruposEmVoo;
+        }
+        finally {
+            this.manifestoGruposEmVoo = undefined;
+        }
+    }
+    async carregarManifestoGrupos() {
+        if (this.politica === "auto") {
+            const leitura = await lerEnvelope(this.baseProjeto, this.caminhoManifestoGrupos, SCHEMA_GRUPO_INDICE_DRIFT, this.chaveEnvelope("groups"));
+            if (leitura.estado === "hit" && manifestoGruposValido(leitura.payload, this.identidadeDigest)) {
+                this.manifestoGrupos = leitura.payload;
+                return this.manifestoGrupos;
+            }
+            if (leitura.estado === "corrupt" || leitura.estado === "hit") {
+                this.registrarCorrupto(path.resolve(this.baseProjeto, this.caminhoManifestoGrupos), leitura.estado === "hit" ? "payload_schema_invalido" : leitura.motivo);
+            }
+        }
+        this.manifestoGrupos = {
+            identidadeDigest: this.identidadeDigest,
+            grupos: {},
+        };
+        return this.manifestoGrupos;
+    }
+    registrarCorrupto(caminho, motivo) {
+        this.metricasAtuais.corruptos += 1;
+        emitirEvento(this.observador, {
+            tipo: "cache.corrupt",
+            caminho,
+            motivo,
+        });
+    }
+    async validarArquivoNoWorkspace(arquivo) {
+        const [baseReal, arquivoReal] = await Promise.all([
+            this.baseProjetoReal,
+            realpath(arquivo),
+        ]);
+        const relativo = path.relative(baseReal, arquivoReal);
+        if (relativo === ".." || relativo.startsWith(`..${path.sep}`) || path.isAbsolute(relativo)) {
+            throw new Error(`arquivo_cache_drift_fora_workspace_real:${arquivo}`);
+        }
+    }
+}
+//# sourceMappingURL=driftCacheIncremental.js.map

package/dist/driftCatalogo.d.ts

@@ -0,0 +1,91 @@
+export declare const SCHEMA_SNAPSHOT_CATALOGO_DRIFT: "sema.drift-catalog/v1";
+export type TipoEventoOperacaoDrift = "catalog.visit" | "content.open" | "content.read" | "ast.create" | "extractor.run" | "cache.hit" | "cache.miss" | "cache.corrupt";
+export interface EventoOperacaoDrift {
+    tipo: TipoEventoOperacaoDrift;
+    caminho?: string;
+    raiz?: string;
+    chave?: string;
+    categoria?: "arquivo" | "diretorio";
+    bytes?: number;
+    digest?: string;
+    motivo?: string;
+}
+export type ObservadorOperacaoDrift = (evento: EventoOperacaoDrift) => void;
+export type ObservadorDrift = ObservadorOperacaoDrift;
+export interface ArquivoCatalogadoDrift {
+    caminho: string;
+    extensao: string;
+    explicito: boolean;
+    raizes: string[];
+}
+export interface ConteudoArquivoDrift {
+    caminho: string;
+    bytes: Buffer;
+    texto: string;
+    digest: string;
+}
+export interface MetricasCatalogoDrift {
+    diretoriosVisitados: number;
+    arquivosCatalogados: number;
+    leiturasConteudo: number;
+    bytesLidos: number;
+    acertosMemoriaConteudo: number;
+    origem: "plano_explicito" | "caminhada" | "snapshot";
+    diretoriosValidadosCache: number;
+}
+export interface AssinaturaDiretorioCatalogoDrift {
+    mtimeNs: string;
+    ctimeNs: string;
+    dev: string;
+    ino: string;
+}
+export interface SnapshotCatalogoDrift {
+    schema: typeof SCHEMA_SNAPSHOT_CATALOGO_DRIFT;
+    raizes: string[];
+    extensoes: string[] | null;
+    diretoriosIgnorados: string[];
+    diretorios: Array<{
+        caminho: string;
+        assinatura: AssinaturaDiretorioCatalogoDrift;
+    }>;
+    arquivos: Array<{
+        caminho: string;
+        explicito: boolean;
+    }>;
+}
+export interface FiltroCatalogoDrift {
+    extensoes?: readonly string[];
+    raiz?: string;
+}
+export interface OpcoesCatalogoDrift {
+    baseDiretorio?: string;
+    arquivos?: readonly string[];
+    raizes?: readonly string[];
+    extensoes?: readonly string[];
+    diretoriosIgnorados?: ReadonlySet<string> | readonly string[];
+    concorrencia?: number;
+    observador?: ObservadorOperacaoDrift;
+    snapshot?: SnapshotCatalogoDrift;
+}
+export interface CatalogoDrift {
+    readonly baseDiretorio: string;
+    readonly raizes: readonly string[];
+    listar(filtro?: FiltroCatalogoDrift): string[];
+    listar(extensoes?: readonly string[], raizes?: readonly string[]): string[];
+    listarEntradas(filtro?: FiltroCatalogoDrift): ArquivoCatalogadoDrift[];
+    listarPorExtensoes(extensoes: readonly string[], raiz?: string): string[];
+    listarPorRaiz(raiz: string, extensoes?: readonly string[]): string[];
+    arquivosCatalogados(): string[];
+    incluir(arquivos: readonly string[]): Promise<void>;
+    contem(caminho: string): boolean;
+    ler(caminho: string): Promise<ConteudoArquivoDrift>;
+    lerTexto(caminho: string): Promise<string>;
+    digest(caminho: string): Promise<string>;
+    fingerprint(caminhos?: readonly string[]): Promise<string>;
+    obterFingerprint(caminhos?: readonly string[]): Promise<string>;
+    emitir(tipo: TipoEventoOperacaoDrift, arquivo?: string): void;
+    metricas(): MetricasCatalogoDrift;
+    snapshot(): SnapshotCatalogoDrift;
+}
+export type CatalogoArquivosDrift = CatalogoDrift;
+export declare function criarCatalogoDrift(opcoes: OpcoesCatalogoDrift): Promise<CatalogoDrift>;