@semacode/cli 2.3.0 → 3.0.0

package/dist/driftCacheFilesystem.js

@@ -0,0 +1,313 @@
+// SEMA-GOVERNED: sema.produto.governanca_ia.drift.cache.store
+// Descrição: confina a árvore externa de cache por identidade física e realpath antes e depois de cada I/O.
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export class FalhaFilesystemCacheDrift extends Error {
+    codigo;
+    constructor(codigo) {
+        super(codigo);
+        this.codigo = codigo;
+        this.name = "FalhaFilesystemCacheDrift";
+    }
+}
+function apiPath(plataforma) {
+    return plataforma === "win32" ? path.win32 : path.posix;
+}
+export function resolverRaizCacheSema(opcoes = {}) {
+    const plataforma = opcoes.plataforma ?? process.platform;
+    const caminhos = apiPath(plataforma);
+    const ambiente = opcoes.ambiente ?? process.env;
+    const diretorioUsuario = opcoes.diretorioUsuario ?? os.homedir();
+    if (opcoes.raizCache !== undefined) {
+        if (!caminhos.isAbsolute(opcoes.raizCache)) {
+            return { disponivel: false, codigo: "cache_root_relativa" };
+        }
+        return {
+            disponivel: true,
+            raiz: caminhos.normalize(opcoes.raizCache),
+            origem: "explicita",
+        };
+    }
+    if (!caminhos.isAbsolute(diretorioUsuario)) {
+        return { disponivel: false, codigo: "cache_home_invalido" };
+    }
+    if (plataforma === "win32") {
+        const localAppData = ambiente.LOCALAPPDATA;
+        if (localAppData && caminhos.isAbsolute(localAppData)) {
+            return {
+                disponivel: true,
+                raiz: caminhos.join(localAppData, "Sema", "Cache"),
+                origem: "localappdata",
+            };
+        }
+        return {
+            disponivel: true,
+            raiz: caminhos.join(diretorioUsuario, "AppData", "Local", "Sema", "Cache"),
+            origem: "windows_fallback",
+        };
+    }
+    if (plataforma === "darwin") {
+        return {
+            disponivel: true,
+            raiz: caminhos.join(diretorioUsuario, "Library", "Caches", "Sema"),
+            origem: "macos_cache",
+        };
+    }
+    const xdg = ambiente.XDG_CACHE_HOME;
+    if (xdg && caminhos.isAbsolute(xdg)) {
+        return {
+            disponivel: true,
+            raiz: caminhos.join(xdg, "sema"),
+            origem: "xdg_cache",
+        };
+    }
+    return {
+        disponivel: true,
+        raiz: caminhos.join(diretorioUsuario, ".cache", "sema"),
+        origem: "unix_fallback",
+    };
+}
+export function caminhoContido(base, alvo) {
+    const relativo = path.relative(base, alvo);
+    return relativo === "" || (relativo !== ".."
+        && !relativo.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relativo));
+}
+export function caminhosSobrepostos(a, b) {
+    return caminhoContido(a, b) || caminhoContido(b, a);
+}
+export function identidadeDe(info) {
+    return { dev: info.dev, ino: info.ino };
+}
+export function mesmaIdentidade(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+export function erroEhAusencia(erro) {
+    return ["ENOENT", "ENOTDIR"].includes(erro.code ?? "");
+}
+export async function lstatOuNull(caminho) {
+    try {
+        return await lstat(caminho, { bigint: true });
+    }
+    catch (erro) {
+        if (erroEhAusencia(erro))
+            return null;
+        throw erro;
+    }
+}
+function caminhoComparavel(caminho) {
+    const normalizado = path.normalize(path.resolve(caminho));
+    return process.platform === "win32" ? normalizado.toLocaleLowerCase("en-US") : normalizado;
+}
+function caminhosIguais(a, b) {
+    return caminhoComparavel(a) === caminhoComparavel(b);
+}
+function tipoEntrada(info) {
+    if (info.isSymbolicLink())
+        return "link";
+    if (info.isFile())
+        return "arquivo";
+    if (info.isDirectory())
+        return "diretorio";
+    return "outro";
+}
+export function estadoEntrada(info) {
+    return {
+        dev: info.dev,
+        ino: info.ino,
+        size: info.size,
+        mtimeNs: info.mtimeNs,
+        ctimeNs: info.ctimeNs,
+        nlink: info.nlink,
+        tipo: tipoEntrada(info),
+    };
+}
+export function mesmoEstadoEntrada(a, b) {
+    if (!a || !b)
+        return a === b;
+    return a.dev === b.dev
+        && a.ino === b.ino
+        && a.size === b.size
+        && a.mtimeNs === b.mtimeNs
+        && a.ctimeNs === b.ctimeNs
+        && a.nlink === b.nlink
+        && a.tipo === b.tipo;
+}
+async function validarComponenteDiretorio(caminho, identidadeEsperada) {
+    const info = await lstat(caminho, { bigint: true });
+    if (info.isSymbolicLink())
+        throw new FalhaFilesystemCacheDrift("cache_root_link");
+    if (!info.isDirectory()) {
+        if (info.nlink > 1n)
+            throw new FalhaFilesystemCacheDrift("cache_root_hardlink");
+        throw new FalhaFilesystemCacheDrift("cache_root_nao_diretorio");
+    }
+    const identidade = identidadeDe(info);
+    if (identidadeEsperada && !mesmaIdentidade(identidadeEsperada, identidade)) {
+        throw new FalhaFilesystemCacheDrift("cache_root_link");
+    }
+    const caminhoReal = await realpath(caminho);
+    if (!caminhosIguais(caminhoReal, caminho)) {
+        throw new FalhaFilesystemCacheDrift("cache_root_link");
+    }
+    return { caminho: path.resolve(caminho), identidade };
+}
+export async function capturarGuardaCadeia(raiz, identidadeRaiz, destino) {
+    const raizAbsoluta = path.resolve(raiz);
+    const destinoAbsoluto = path.resolve(destino);
+    if (!caminhoContido(raizAbsoluta, destinoAbsoluto)) {
+        throw new FalhaFilesystemCacheDrift("cache_root_indisponivel");
+    }
+    const segmentos = path.relative(raizAbsoluta, destinoAbsoluto).split(path.sep).filter(Boolean);
+    const caminhos = [
+        raizAbsoluta,
+        ...segmentos.map((_, indice) => path.join(raizAbsoluta, ...segmentos.slice(0, indice + 1))),
+    ];
+    const componentes = [];
+    for (let indice = 0; indice < caminhos.length; indice += 1) {
+        componentes.push(await validarComponenteDiretorio(caminhos[indice], indice === 0 ? identidadeRaiz : undefined));
+    }
+    return { raiz: raizAbsoluta, destino: destinoAbsoluto, componentes };
+}
+export async function confirmarGuardaCadeia(guarda) {
+    for (const componente of guarda.componentes) {
+        await validarComponenteDiretorio(componente.caminho, componente.identidade);
+    }
+}
+async function aplicarPermissaoDiretorio(caminho) {
+    if (process.platform === "win32")
+        return;
+    const infoAntes = await lstat(caminho, { bigint: true });
+    if (!infoAntes.isDirectory() || infoAntes.isSymbolicLink()) {
+        throw new FalhaFilesystemCacheDrift("cache_root_link");
+    }
+    const flags = constants.O_RDONLY
+        | (constants.O_DIRECTORY ?? 0)
+        | (constants.O_NOFOLLOW ?? 0);
+    const handle = await open(caminho, flags);
+    try {
+        const infoHandle = await handle.stat({ bigint: true });
+        if (!infoHandle.isDirectory()
+            || !mesmaIdentidade(identidadeDe(infoAntes), identidadeDe(infoHandle))) {
+            throw new FalhaFilesystemCacheDrift("cache_root_link");
+        }
+        await handle.chmod(0o700);
+        const infoDepois = await lstat(caminho, { bigint: true });
+        if (!infoDepois.isDirectory()
+            || infoDepois.isSymbolicLink()
+            || !mesmaIdentidade(identidadeDe(infoHandle), identidadeDe(infoDepois))) {
+            throw new FalhaFilesystemCacheDrift("cache_root_link");
+        }
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+export async function aplicarPermissaoArquivo(handle) {
+    if (process.platform !== "win32")
+        await handle.chmod(0o600);
+}
+export async function lerHandleLimitado(handle, limiteBytes) {
+    if (!Number.isSafeInteger(limiteBytes) || limiteBytes < 0) {
+        throw new RangeError("limite_cache_invalido");
+    }
+    const capacidade = limiteBytes + 1;
+    const buffer = Buffer.allocUnsafe(capacidade);
+    let total = 0;
+    while (total < capacidade) {
+        const { bytesRead } = await handle.read(buffer, total, capacidade - total, null);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    return buffer.subarray(0, total);
+}
+async function garantirCadeiaDiretoriosSegura(raiz, identidadeRaiz, destino, permissaoPrivada) {
+    const raizAbsoluta = path.resolve(raiz);
+    const destinoAbsoluto = path.resolve(destino);
+    if (!caminhoContido(raizAbsoluta, destinoAbsoluto)) {
+        throw new FalhaFilesystemCacheDrift("cache_root_indisponivel");
+    }
+    let guarda = await capturarGuardaCadeia(raizAbsoluta, identidadeRaiz, raizAbsoluta);
+    const segmentos = path.relative(raizAbsoluta, destinoAbsoluto).split(path.sep).filter(Boolean);
+    let atual = raizAbsoluta;
+    for (const segmento of segmentos) {
+        atual = path.join(atual, segmento);
+        await confirmarGuardaCadeia(guarda);
+        if (!await lstatOuNull(atual)) {
+            await confirmarGuardaCadeia(guarda);
+            try {
+                await mkdir(atual, { mode: 0o700 });
+            }
+            catch (erro) {
+                if (erro.code !== "EEXIST")
+                    throw erro;
+            }
+            await confirmarGuardaCadeia(guarda);
+        }
+        const componente = await validarComponenteDiretorio(atual);
+        guarda = {
+            raiz: raizAbsoluta,
+            destino: path.resolve(atual),
+            componentes: [...guarda.componentes, componente],
+        };
+        await confirmarGuardaCadeia(guarda);
+        if (permissaoPrivada) {
+            await aplicarPermissaoDiretorio(atual);
+            await confirmarGuardaCadeia(guarda);
+        }
+    }
+    return guarda;
+}
+export async function validarComponentesExistentesSemLink(alvo) {
+    const absoluto = path.resolve(alvo);
+    const raiz = path.parse(absoluto).root;
+    const raizGuardada = await validarComponenteDiretorio(raiz);
+    let guarda = { raiz, destino: raiz, componentes: [raizGuardada] };
+    let atual = raiz;
+    for (const segmento of path.relative(raiz, absoluto).split(path.sep).filter(Boolean)) {
+        atual = path.join(atual, segmento);
+        if (!await lstatOuNull(atual))
+            return;
+        const componente = await validarComponenteDiretorio(atual);
+        guarda = { raiz, destino: atual, componentes: [...guarda.componentes, componente] };
+        await confirmarGuardaCadeia(guarda);
+    }
+}
+export async function prepararRaizCache(caminho) {
+    const absoluto = path.resolve(caminho);
+    const raizSistema = path.parse(absoluto).root;
+    if (caminhosIguais(absoluto, raizSistema)) {
+        throw new FalhaFilesystemCacheDrift("cache_root_indisponivel");
+    }
+    const componenteRaiz = await validarComponenteDiretorio(raizSistema);
+    const guarda = await garantirCadeiaDiretoriosSegura(raizSistema, componenteRaiz.identidade, absoluto, false);
+    await confirmarGuardaCadeia(guarda);
+    await aplicarPermissaoDiretorio(absoluto);
+    await confirmarGuardaCadeia(guarda);
+    const info = await lstat(absoluto, { bigint: true });
+    const real = await realpath(absoluto);
+    const componenteFinal = guarda.componentes.at(-1);
+    if (!componenteFinal
+        || !mesmaIdentidade(componenteFinal.identidade, identidadeDe(info))
+        || !caminhosIguais(real, absoluto)) {
+        throw new FalhaFilesystemCacheDrift("cache_root_link");
+    }
+    await confirmarGuardaCadeia(guarda);
+    return { real, identidade: identidadeDe(info) };
+}
+export async function garantirSubdiretorioSeguro(raiz, identidadeRaiz, destino) {
+    return garantirCadeiaDiretoriosSegura(raiz, identidadeRaiz, destino, true);
+}
+export function identidadeArquivoValida(caminho, infoCaminho, infoHandle) {
+    return infoCaminho.isFile()
+        && !infoCaminho.isSymbolicLink()
+        && infoHandle.isFile()
+        && infoCaminho.nlink === 1n
+        && infoHandle.nlink === 1n
+        && mesmaIdentidade(identidadeDe(infoCaminho), identidadeDe(infoHandle))
+        && caminho.length > 0;
+}
+//# sourceMappingURL=driftCacheFilesystem.js.map

package/dist/driftCacheModes.d.ts

@@ -0,0 +1,38 @@
+export type ModoCacheDrift = "none" | "cache" | "fresh";
+export type FlagModoCacheDrift = "--cache" | "--drift";
+export type AliasLegadoModoCacheDrift = "off" | "auto" | "refresh";
+export type CodigoErroModoCacheDrift = "flag_duplicada" | "flags_conflitantes" | "valor_ausente" | "valor_invalido" | "flag_nao_permitida_no_comando" | "com_drift_duplicado" | "com_drift_conflitante" | "com_drift_nao_permitido" | "consulta_nao_suportada";
+export type ComandoConsultaDrift = "resumo" | "inspecionar";
+export interface AvisoModoCacheDrift {
+    codigo: "alias_modo_cache_drift_depreciado";
+    flag: FlagModoCacheDrift;
+    valorRecebido: AliasLegadoModoCacheDrift;
+    valorNormalizado: ModoCacheDrift;
+    vigencia: "uma_versao";
+    mensagem: string;
+}
+export interface ResultadoParseModoCacheDrift {
+    modo: ModoCacheDrift | null;
+    flag: FlagModoCacheDrift | null;
+    avisos: readonly AvisoModoCacheDrift[];
+}
+export interface ResolucaoModoCacheDrift {
+    modo: ModoCacheDrift;
+    executar: boolean;
+    avisos: readonly AvisoModoCacheDrift[];
+}
+interface DetalhesErroModoCacheDrift {
+    flag?: FlagModoCacheDrift | "--com-drift";
+    valor?: string;
+}
+export declare class ErroModoCacheDrift extends Error {
+    readonly codigo: CodigoErroModoCacheDrift;
+    readonly name = "ErroModoCacheDrift";
+    readonly flag?: FlagModoCacheDrift | "--com-drift";
+    readonly valor?: string;
+    constructor(codigo: CodigoErroModoCacheDrift, mensagem: string, detalhes?: DetalhesErroModoCacheDrift);
+}
+export declare function parsearModoCacheDrift(args: readonly string[]): ResultadoParseModoCacheDrift;
+export declare function resolverModoCacheComandoDrift(args: readonly string[]): ResolucaoModoCacheDrift;
+export declare function resolverModoCacheConsultaDrift(args: readonly string[], comando: ComandoConsultaDrift): ResolucaoModoCacheDrift;
+export {};

package/dist/driftCacheModes.js

@@ -0,0 +1,147 @@
+// SEMA-GOVERNED: sema.produto.governanca_ia.drift.cache.modos
+// Descrição: normaliza os modos públicos de cache do drift sem efeitos colaterais.
+export class ErroModoCacheDrift extends Error {
+    codigo;
+    name = "ErroModoCacheDrift";
+    flag;
+    valor;
+    constructor(codigo, mensagem, detalhes = {}) {
+        super(mensagem);
+        this.codigo = codigo;
+        this.flag = detalhes.flag;
+        this.valor = detalhes.valor;
+    }
+}
+const FLAGS_MODO_CACHE_DRIFT = ["--cache", "--drift"];
+const MODOS_CACHE_DRIFT = new Set(["none", "cache", "fresh"]);
+const ALIASES_LEGADOS = {
+    off: "none",
+    auto: "cache",
+    refresh: "fresh",
+};
+const COMANDOS_CONSULTA_DRIFT = new Set(["resumo", "inspecionar"]);
+function ehFlagModoCacheDrift(valor) {
+    return FLAGS_MODO_CACHE_DRIFT.includes(valor);
+}
+function ehModoCacheDrift(valor) {
+    return MODOS_CACHE_DRIFT.has(valor);
+}
+function ehAliasLegado(valor) {
+    return Object.prototype.hasOwnProperty.call(ALIASES_LEGADOS, valor);
+}
+function lerOcorrencias(args) {
+    const ocorrencias = [];
+    for (let indice = 0; indice < args.length; indice += 1) {
+        const argumento = args[indice] ?? "";
+        const separador = argumento.indexOf("=");
+        const flagInline = separador >= 0 ? argumento.slice(0, separador) : "";
+        if (ehFlagModoCacheDrift(flagInline)) {
+            const valor = argumento.slice(separador + 1);
+            if (valor.length === 0) {
+                throw new ErroModoCacheDrift("valor_ausente", `A flag ${flagInline} exige um modo: none, cache ou fresh.`, { flag: flagInline });
+            }
+            ocorrencias.push({ flag: flagInline, valor });
+            continue;
+        }
+        if (!ehFlagModoCacheDrift(argumento)) {
+            continue;
+        }
+        const valor = args[indice + 1];
+        if (valor === undefined || valor.length === 0 || valor.startsWith("-")) {
+            throw new ErroModoCacheDrift("valor_ausente", `A flag ${argumento} exige um modo: none, cache ou fresh.`, { flag: argumento });
+        }
+        ocorrencias.push({ flag: argumento, valor });
+        indice += 1;
+    }
+    return ocorrencias;
+}
+function validarOcorrenciaUnica(ocorrencias) {
+    if (ocorrencias.length === 0) {
+        return null;
+    }
+    if (ocorrencias.length === 1) {
+        return ocorrencias[0] ?? null;
+    }
+    const flags = new Set(ocorrencias.map((ocorrencia) => ocorrencia.flag));
+    if (flags.size > 1) {
+        throw new ErroModoCacheDrift("flags_conflitantes", "Use somente uma das flags --cache ou --drift.");
+    }
+    const flag = ocorrencias[0]?.flag;
+    throw new ErroModoCacheDrift("flag_duplicada", `A flag ${flag ?? "de modo de drift"} foi informada mais de uma vez.`, flag === undefined ? {} : { flag });
+}
+function normalizarOcorrencia(ocorrencia) {
+    if (ehModoCacheDrift(ocorrencia.valor)) {
+        return {
+            modo: ocorrencia.valor,
+            flag: ocorrencia.flag,
+            avisos: [],
+        };
+    }
+    if (ehAliasLegado(ocorrencia.valor)) {
+        const valorNormalizado = ALIASES_LEGADOS[ocorrencia.valor];
+        return {
+            modo: valorNormalizado,
+            flag: ocorrencia.flag,
+            avisos: [{
+                    codigo: "alias_modo_cache_drift_depreciado",
+                    flag: ocorrencia.flag,
+                    valorRecebido: ocorrencia.valor,
+                    valorNormalizado,
+                    vigencia: "uma_versao",
+                    mensagem: `${ocorrencia.valor} é um alias temporário; use ${valorNormalizado}.`,
+                }],
+        };
+    }
+    throw new ErroModoCacheDrift("valor_invalido", `Modo inválido para ${ocorrencia.flag}: ${ocorrencia.valor}. Use none, cache ou fresh.`, { flag: ocorrencia.flag, valor: ocorrencia.valor });
+}
+function contarComDrift(args) {
+    return args.reduce((total, argumento) => total + (argumento === "--com-drift" ? 1 : 0), 0);
+}
+function validarComDriftUnico(args) {
+    const ocorrencias = contarComDrift(args);
+    if (ocorrencias > 1) {
+        throw new ErroModoCacheDrift("com_drift_duplicado", "A flag --com-drift foi informada mais de uma vez.", { flag: "--com-drift" });
+    }
+    return ocorrencias === 1;
+}
+export function parsearModoCacheDrift(args) {
+    const ocorrencia = validarOcorrenciaUnica(lerOcorrencias(args));
+    if (ocorrencia === null) {
+        return { modo: null, flag: null, avisos: [] };
+    }
+    return normalizarOcorrencia(ocorrencia);
+}
+export function resolverModoCacheComandoDrift(args) {
+    if (validarComDriftUnico(args)) {
+        throw new ErroModoCacheDrift("com_drift_nao_permitido", "--com-drift só pode ser usada nas consultas resumo e inspecionar.", { flag: "--com-drift" });
+    }
+    const resultado = parsearModoCacheDrift(args);
+    if (resultado.flag === "--drift") {
+        throw new ErroModoCacheDrift("flag_nao_permitida_no_comando", "O comando sema drift usa --cache; --drift pertence às consultas resumo e inspecionar.", { flag: resultado.flag });
+    }
+    return {
+        modo: resultado.modo ?? "fresh",
+        executar: true,
+        avisos: resultado.avisos,
+    };
+}
+export function resolverModoCacheConsultaDrift(args, comando) {
+    if (!COMANDOS_CONSULTA_DRIFT.has(comando)) {
+        throw new ErroModoCacheDrift("consulta_nao_suportada", "O modo de análise de drift em consulta só é válido para resumo e inspecionar.");
+    }
+    const comDrift = validarComDriftUnico(args);
+    const resultado = parsearModoCacheDrift(args);
+    if (resultado.flag === "--cache") {
+        throw new ErroModoCacheDrift("flag_nao_permitida_no_comando", `${comando} usa --drift; --cache pertence ao comando sema drift.`, { flag: resultado.flag });
+    }
+    if (comDrift && resultado.flag !== null) {
+        throw new ErroModoCacheDrift("com_drift_conflitante", `Não combine --com-drift com ${resultado.flag}.`, { flag: resultado.flag });
+    }
+    const modo = comDrift ? "fresh" : (resultado.modo ?? "none");
+    return {
+        modo,
+        executar: modo !== "none",
+        avisos: resultado.avisos,
+    };
+}
+//# sourceMappingURL=driftCacheModes.js.map

package/dist/driftCacheStore.d.ts

@@ -0,0 +1,80 @@
+import { type CodigoErroCasCacheDrift } from "./driftCacheCas.js";
+import { resolverRaizCacheSema, type CodigoErroFilesystemCacheDrift, type OpcoesResolverRaizCacheSema, type OrigemRaizCacheSema, type ResolucaoRaizCacheSema } from "./driftCacheFilesystem.js";
+export { resolverRaizCacheSema };
+export type { OpcoesResolverRaizCacheSema, OrigemRaizCacheSema, ResolucaoRaizCacheSema, };
+export declare const SCHEMA_OBJETO_CACHE_DRIFT: "sema.drift-cache-object/v3";
+export declare const LIMITE_BYTES_OBJETO_CACHE_DRIFT: number;
+export type ValorJsonCacheDrift = null | boolean | number | string | readonly ValorJsonCacheDrift[] | {
+    readonly [chave: string]: ValorJsonCacheDrift;
+};
+export type ValidadorPayloadCacheDrift<T extends ValorJsonCacheDrift> = (valor: unknown) => valor is T;
+export type CodigoErroStoreCacheDrift = CodigoErroFilesystemCacheDrift | CodigoErroCasCacheDrift | "cache_home_invalido" | "cache_root_relativa" | "cache_workspace_invalido" | "cache_chave_invalida" | "cache_objeto_ausente" | "cache_objeto_corrupto" | "cache_objeto_grande" | "cache_objeto_hardlink" | "cache_objeto_conflitante" | "cache_io_indisponivel";
+export type TipoEventoStoreCacheDrift = "cache.store.ready" | "cache.store.unavailable" | "cache.read.hit" | "cache.read.miss" | "cache.read.corrupt" | "cache.write.published" | "cache.write.reused" | "cache.write.error";
+export interface EventoStoreCacheDrift {
+    tipo: TipoEventoStoreCacheDrift;
+    workspaceId?: string;
+    chave?: string;
+    caminhoVirtual?: string;
+    codigo?: CodigoErroStoreCacheDrift;
+}
+export interface MetricasStoreCacheDrift {
+    leituras: number;
+    hits: number;
+    misses: number;
+    corruptos: number;
+    publicacoes: number;
+    reutilizacoes: number;
+    corridasValidadas: number;
+    erros: number;
+}
+export interface OpcoesCriarStoreCacheDrift {
+    baseProjeto: string;
+    raizCache?: string;
+    limiteBytes?: number;
+    observador?: (evento: EventoStoreCacheDrift) => void;
+    ambiente?: Readonly<Record<string, string | undefined>>;
+    diretorioUsuario?: string;
+}
+export type ResultadoLeituraStoreCacheDrift<T> = {
+    estado: "hit";
+    chave: string;
+    valor: T;
+    payloadDigest: string;
+    caminhoVirtual: string;
+} | {
+    estado: "miss";
+    chave: string;
+    codigo: "cache_objeto_ausente";
+    caminhoVirtual: string;
+} | {
+    estado: "corrupto";
+    chave: string;
+    codigo: CodigoErroStoreCacheDrift;
+    caminhoVirtual: string;
+} | {
+    estado: "indisponivel";
+    chave: string;
+    codigo: CodigoErroStoreCacheDrift;
+};
+export type ResultadoPublicacaoStoreCacheDrift = {
+    estado: "publicado" | "existente";
+    chave: string;
+    payloadDigest: string;
+    caminhoVirtual: string;
+} | {
+    estado: "indisponivel" | "erro";
+    chave: string;
+    codigo: CodigoErroStoreCacheDrift;
+};
+export interface StoreCacheDrift {
+    readonly disponivel: boolean;
+    readonly workspaceId: string | null;
+    readonly gitHead: string | null;
+    readonly erroDisponibilidade: CodigoErroStoreCacheDrift | null;
+    ler<T extends ValorJsonCacheDrift>(chave: string, validar?: ValidadorPayloadCacheDrift<T>): Promise<ResultadoLeituraStoreCacheDrift<T>>;
+    publicar<T extends ValorJsonCacheDrift>(chave: string, payload: T, validarExistente?: ValidadorPayloadCacheDrift<T>): Promise<ResultadoPublicacaoStoreCacheDrift>;
+    metricas(): MetricasStoreCacheDrift;
+}
+export declare function serializarJsonCanonicoCacheDrift(valor: unknown): string;
+export declare function digestJsonCanonicoCacheDrift(valor: unknown): string;
+export declare function criarStoreCacheDrift(opcoes: OpcoesCriarStoreCacheDrift): Promise<StoreCacheDrift>;