@semacode/cli 2.3.1 → 3.0.0

package/dist/drift.part14.js

@@ -1,6 +1,5 @@
 // SEMA-GOVERNED: sema.governanca_ia_contexto
 // Descricao: analisa modulos selecionados no drift; consulte contratos/sema/governanca_ia_contexto.sema antes de editar.
-import { existsSync } from "node:fs";
 import path from "node:path";
 import { escolherArquivoPorVinculo, escolherSimboloPorVinculo } from "./drift.part03.js";
 import { calcularRiscoOperacional, encontrarAncoraSuperficie } from "./drift.part04.js";
@@ -8,16 +7,29 @@ import { resolverPersistenciaLocalPorTask } from "./drift.part08.js";
 import { escolherRotasEsperadas, normalizarCaminhoRota, ordenarCandidatos, sugerirCandidatosParaImpl, sugerirCandidatosParaTaskSemImpl } from "./drift.part09.js";
 import { coletarVinculosIr, extrairRecursosEsperados, resolverRecursoEsperado } from "./drift.part10.js";
 function escolherArquivoDeclarado(contexto, arquivosConhecidos, valor) {
-    const resolucaoIndexada = escolherArquivoPorVinculo(arquivosConhecidos, valor);
-    if (resolucaoIndexada.status !== "nao_encontrado") {
-        return resolucaoIndexada;
+    if (!caminhoEstaDentroDoWorkspace(contexto.baseProjeto, valor)) {
+        return { confianca: "baixa", status: "nao_encontrado" };
     }
-    const caminhoExplicito = path.resolve(contexto.baseProjeto, valor);
-    if (existsSync(caminhoExplicito)) {
-        return { arquivo: caminhoExplicito, confianca: "alta", status: "resolvido" };
+    const resolucaoIndexada = escolherArquivoPorVinculo(arquivosConhecidos, valor);
+    if (resolucaoIndexada.arquivo
+        && !caminhoEstaDentroDoWorkspace(contexto.baseProjeto, resolucaoIndexada.arquivo)) {
+        return { confianca: "baixa", status: "nao_encontrado" };
     }
     return resolucaoIndexada;
 }
+function caminhoEstaDentroDoWorkspace(baseProjeto, valor) {
+    const relativo = path.relative(path.resolve(baseProjeto), path.resolve(baseProjeto, valor));
+    return relativo === "" || (relativo !== ".."
+        && !relativo.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relativo));
+}
+function redigirCaminhoDeclaradoExterno(baseProjeto, valor) {
+    if (caminhoEstaDentroDoWorkspace(baseProjeto, valor)) {
+        return valor;
+    }
+    const nome = path.basename(path.normalize(valor)) || "arquivo";
+    return `[fora_do_workspace]/${nome}`;
+}
 export function analisarModulosSelecionadosDrift(estado) {
     const { contexto, mapaImpl, todosSimbolos, mapaRecursos, todosRecursos, todasRotasIndexadas, todosArquivosConhecidos, implsValidos, implsQuebrados, vinculosValidos, vinculosQuebrados, rotasDivergentes, recursosValidos, recursosDivergentes, diagnosticos, tasksResumo, taskPorChave, guardrailsPorTask, resumoVinculosPorTask, arquivosAncoraHerdadosPorTask, } = estado;
     for (const item of contexto.modulosSelecionados) {
@@ -307,6 +319,7 @@ export function analisarModulosSelecionadosDrift(estado) {
                 registro.simbolo = resolucaoSimbolo.simbolo?.simbolo;
             }
             else if (arquivoDeclarado) {
+                registro.valor = redigirCaminhoDeclaradoExterno(contexto.baseProjeto, registro.valor);
                 const resolucaoArquivo = escolherArquivoDeclarado(contexto, todosArquivosConhecidos, arquivoDeclarado);
                 registro.status = resolucaoArquivo.status;
                 registro.confianca = resolucaoArquivo.confianca;
@@ -341,6 +354,7 @@ export function analisarModulosSelecionadosDrift(estado) {
                 }
             }
             else {
+                registro.valor = redigirCaminhoDeclaradoExterno(contexto.baseProjeto, registro.valor);
                 const resolucaoArquivo = escolherArquivoDeclarado(contexto, todosArquivosConhecidos, itemVinculo.vinculo.valor);
                 registro.status = resolucaoArquivo.status;
                 registro.confianca = resolucaoArquivo.confianca;

package/dist/driftCacheCas.d.ts

@@ -0,0 +1,43 @@
+import { type FileHandle } from "node:fs/promises";
+import { type EstadoEntradaCache, type GuardaCadeiaCache, type IdentidadeFilesystem } from "./driftCacheFilesystem.js";
+export type CodigoErroCasCacheDrift = "cache_objeto_corrupto" | "cache_objeto_grande" | "cache_objeto_hardlink" | "cache_objeto_conflitante" | "cache_io_indisponivel";
+export interface LockPublicacaoCache {
+    caminho: string;
+    handle: FileHandle;
+    identidade: IdentidadeFilesystem;
+    guarda: GuardaCadeiaCache;
+    token: string;
+    contendido: boolean;
+}
+export declare class FalhaCasCacheDrift extends Error {
+    readonly codigo: CodigoErroCasCacheDrift;
+    constructor(codigo: CodigoErroCasCacheDrift);
+}
+export interface OpcoesAdquirirLockPublicacao {
+    chave: string;
+    pasta: string;
+    guardaInicial: GuardaCadeiaCache;
+    raiz: string;
+    identidadeRaiz: IdentidadeFilesystem;
+}
+export interface OpcoesPublicarObjetoExclusivo {
+    temporario: string;
+    destino: string;
+    guarda: GuardaCadeiaCache;
+    identidadeTemporario: IdentidadeFilesystem;
+    estadoDestinoSubstituivel: EstadoEntradaCache | null;
+}
+export type ResultadoPublicacaoObjetoExclusivo = {
+    estado: "publicado";
+} | {
+    estado: "existente";
+} | {
+    estado: "conflito";
+};
+export declare function capturarEstadoEntradaGuardado(caminho: string, guarda: GuardaCadeiaCache): Promise<EstadoEntradaCache | null>;
+export declare function removerArquivoGuardadoSeMesmo(caminho: string, identidade: IdentidadeFilesystem, guarda: GuardaCadeiaCache, permitirHardlink?: boolean): Promise<boolean>;
+export declare function publicarObjetoExclusivo(opcoes: OpcoesPublicarObjetoExclusivo): Promise<ResultadoPublicacaoObjetoExclusivo>;
+export declare function adquirirLockPublicacao(opcoes: OpcoesAdquirirLockPublicacao): Promise<LockPublicacaoCache>;
+export declare function confirmarLockPublicacao(lock: LockPublicacaoCache): Promise<void>;
+export declare function liberarLockPublicacao(lock: LockPublicacaoCache): Promise<void>;
+export declare function limparTemporariosOrfaos(chave: string, pasta: string, guarda: GuardaCadeiaCache): Promise<void>;

package/dist/driftCacheCas.js

@@ -0,0 +1,351 @@
+// SEMA-GOVERNED: sema.produto.governanca_ia.drift.cache.store
+// Descrição: serializa publicadores concorrentes por chave e recupera locks/temporários sem substituir vencedor válido.
+import { constants } from "node:fs";
+import { link, lstat, open, readdir, unlink, } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { setTimeout as esperar } from "node:timers/promises";
+import { aplicarPermissaoArquivo, capturarGuardaCadeia, confirmarGuardaCadeia, erroEhAusencia, estadoEntrada, identidadeArquivoValida, identidadeDe, lerHandleLimitado, lstatOuNull, mesmaIdentidade, mesmoEstadoEntrada, } from "./driftCacheFilesystem.js";
+export class FalhaCasCacheDrift extends Error {
+    codigo;
+    constructor(codigo) {
+        super(codigo);
+        this.codigo = codigo;
+        this.name = "FalhaCasCacheDrift";
+    }
+}
+const SCHEMA_LOCK_CACHE_DRIFT = "sema.drift-cache-lock/v1";
+const TENTATIVAS_LOCK_CACHE_DRIFT = 200;
+const INTERVALO_LOCK_CACHE_DRIFT_MS = 10;
+const TTL_LOCK_CACHE_DRIFT_MS = 30_000;
+const TOKENS_LOCK_ATIVOS = new Set();
+const PROCESSO_INICIADO_EM_CACHE_DRIFT = performance.timeOrigin;
+function processoEstaAtivo(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (erro) {
+        const codigo = erro.code ?? "";
+        return !["ESRCH", "EINVAL"].includes(codigo);
+    }
+}
+function registroObjeto(valor) {
+    return typeof valor === "object" && valor !== null && !Array.isArray(valor);
+}
+function registroLockCache(valor) {
+    if (!registroObjeto(valor))
+        return false;
+    return valor.schema === SCHEMA_LOCK_CACHE_DRIFT
+        && Number.isSafeInteger(valor.pid)
+        && Number(valor.pid) > 0
+        && typeof valor.processoIniciadoEm === "number"
+        && Number.isFinite(valor.processoIniciadoEm)
+        && valor.processoIniciadoEm > 0
+        && typeof valor.token === "string"
+        && /^[a-f0-9-]{36}$/u.test(valor.token)
+        && typeof valor.criadoEm === "number"
+        && Number.isFinite(valor.criadoEm);
+}
+export async function capturarEstadoEntradaGuardado(caminho, guarda) {
+    await confirmarGuardaCadeia(guarda);
+    const info = await lstatOuNull(caminho);
+    await confirmarGuardaCadeia(guarda);
+    return info ? estadoEntrada(info) : null;
+}
+async function vincularExclusivo(origem, destino, guarda) {
+    await confirmarGuardaCadeia(guarda);
+    try {
+        await link(origem, destino);
+    }
+    catch (erro) {
+        const codigo = erro.code ?? "";
+        if (!["EEXIST", "EPERM"].includes(codigo))
+            throw erro;
+        await confirmarGuardaCadeia(guarda);
+        if (await lstatOuNull(destino))
+            return "existente";
+        throw erro;
+    }
+    await confirmarGuardaCadeia(guarda);
+    return "vinculado";
+}
+export async function removerArquivoGuardadoSeMesmo(caminho, identidade, guarda, permitirHardlink = false) {
+    try {
+        await confirmarGuardaCadeia(guarda);
+        const info = await lstat(caminho, { bigint: true });
+        if (info.isFile()
+            && !info.isSymbolicLink()
+            && (permitirHardlink || info.nlink === 1n)
+            && mesmaIdentidade(identidade, identidadeDe(info))) {
+            await confirmarGuardaCadeia(guarda);
+            await unlink(caminho);
+            await confirmarGuardaCadeia(guarda);
+            return true;
+        }
+    }
+    catch (erro) {
+        if (erroEhAusencia(erro))
+            return true;
+        // Limpeza é best effort; nunca seguimos um caminho cuja cadeia mudou.
+    }
+    return false;
+}
+export async function publicarObjetoExclusivo(opcoes) {
+    const identidadeSubstituida = opcoes.estadoDestinoSubstituivel
+        ? {
+            dev: opcoes.estadoDestinoSubstituivel.dev,
+            ino: opcoes.estadoDestinoSubstituivel.ino,
+        }
+        : null;
+    let quarentena = null;
+    let destinoCriado = false;
+    try {
+        await confirmarGuardaCadeia(opcoes.guarda);
+        const infoTemporario = await lstat(opcoes.temporario, { bigint: true });
+        if (!infoTemporario.isFile()
+            || infoTemporario.isSymbolicLink()
+            || infoTemporario.nlink !== 1n
+            || !mesmaIdentidade(opcoes.identidadeTemporario, identidadeDe(infoTemporario))) {
+            throw new FalhaCasCacheDrift("cache_objeto_hardlink");
+        }
+        if (opcoes.estadoDestinoSubstituivel) {
+            if (opcoes.estadoDestinoSubstituivel.tipo !== "arquivo" || !identidadeSubstituida) {
+                return { estado: "conflito" };
+            }
+            const atual = await capturarEstadoEntradaGuardado(opcoes.destino, opcoes.guarda);
+            if (!mesmoEstadoEntrada(opcoes.estadoDestinoSubstituivel, atual)) {
+                return { estado: "conflito" };
+            }
+            const digest = path.basename(opcoes.destino, ".json");
+            const caminhoQuarentena = path.join(path.dirname(opcoes.destino), `.${digest}.${randomUUID()}.replaced`);
+            if (await vincularExclusivo(opcoes.destino, caminhoQuarentena, opcoes.guarda) !== "vinculado") {
+                return { estado: "conflito" };
+            }
+            const [infoQuarentena, infoDestino] = await Promise.all([
+                lstat(caminhoQuarentena, { bigint: true }),
+                lstat(opcoes.destino, { bigint: true }),
+            ]);
+            quarentena = { caminho: caminhoQuarentena, identidade: identidadeDe(infoQuarentena) };
+            if (!infoQuarentena.isFile()
+                || infoQuarentena.isSymbolicLink()
+                || !mesmaIdentidade(identidadeSubstituida, identidadeDe(infoQuarentena))
+                || !mesmaIdentidade(identidadeSubstituida, identidadeDe(infoDestino))) {
+                return { estado: "conflito" };
+            }
+            const removido = await removerArquivoGuardadoSeMesmo(opcoes.destino, identidadeSubstituida, opcoes.guarda, true);
+            if (!removido)
+                return { estado: "conflito" };
+        }
+        const vinculo = await vincularExclusivo(opcoes.temporario, opcoes.destino, opcoes.guarda);
+        if (vinculo === "existente")
+            return { estado: "existente" };
+        destinoCriado = true;
+        const [infoDestino, infoTemporarioVinculado] = await Promise.all([
+            lstat(opcoes.destino, { bigint: true }),
+            lstat(opcoes.temporario, { bigint: true }),
+        ]);
+        if (!infoDestino.isFile()
+            || infoDestino.isSymbolicLink()
+            || infoDestino.nlink !== 2n
+            || infoTemporarioVinculado.nlink !== 2n
+            || !mesmaIdentidade(opcoes.identidadeTemporario, identidadeDe(infoDestino))
+            || !mesmaIdentidade(opcoes.identidadeTemporario, identidadeDe(infoTemporarioVinculado))) {
+            throw new FalhaCasCacheDrift("cache_objeto_conflitante");
+        }
+        const temporarioRemovido = await removerArquivoGuardadoSeMesmo(opcoes.temporario, opcoes.identidadeTemporario, opcoes.guarda, true);
+        if (!temporarioRemovido)
+            throw new FalhaCasCacheDrift("cache_objeto_conflitante");
+        const infoFinal = await lstat(opcoes.destino, { bigint: true });
+        if (!infoFinal.isFile()
+            || infoFinal.isSymbolicLink()
+            || infoFinal.nlink !== 1n
+            || !mesmaIdentidade(opcoes.identidadeTemporario, identidadeDe(infoFinal))) {
+            throw new FalhaCasCacheDrift("cache_objeto_conflitante");
+        }
+        destinoCriado = false;
+        return { estado: "publicado" };
+    }
+    catch (erro) {
+        if (destinoCriado) {
+            await removerArquivoGuardadoSeMesmo(opcoes.destino, opcoes.identidadeTemporario, opcoes.guarda, true);
+        }
+        throw erro;
+    }
+    finally {
+        if (quarentena) {
+            await removerArquivoGuardadoSeMesmo(quarentena.caminho, quarentena.identidade, opcoes.guarda, true);
+        }
+    }
+}
+async function lerLockSeguro(caminho, guarda) {
+    await confirmarGuardaCadeia(guarda);
+    const infoAntes = await lstatOuNull(caminho);
+    if (!infoAntes)
+        return null;
+    if (!infoAntes.isFile() || infoAntes.isSymbolicLink()) {
+        throw new FalhaCasCacheDrift("cache_objeto_corrupto");
+    }
+    if (infoAntes.nlink !== 1n)
+        throw new FalhaCasCacheDrift("cache_objeto_hardlink");
+    if (infoAntes.size > 4096n)
+        throw new FalhaCasCacheDrift("cache_objeto_grande");
+    let handle;
+    try {
+        handle = await open(caminho, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    }
+    catch (erro) {
+        if (erroEhAusencia(erro))
+            return null;
+        throw erro;
+    }
+    try {
+        await confirmarGuardaCadeia(guarda);
+        const infoHandle = await handle.stat({ bigint: true });
+        if (!identidadeArquivoValida(caminho, infoAntes, infoHandle)) {
+            const atual = await lstatOuNull(caminho);
+            if (!atual
+                || !mesmaIdentidade(identidadeDe(infoAntes), identidadeDe(atual)))
+                return null;
+            throw new FalhaCasCacheDrift("cache_objeto_corrupto");
+        }
+        const bytes = await lerHandleLimitado(handle, 4096);
+        const infoHandleFinal = await handle.stat({ bigint: true });
+        const infoFinal = await lstatOuNull(caminho);
+        await confirmarGuardaCadeia(guarda);
+        if (!infoFinal
+            || !mesmaIdentidade(identidadeDe(infoAntes), identidadeDe(infoFinal)))
+            return null;
+        if (bytes.byteLength > 4096
+            || !identidadeArquivoValida(caminho, infoFinal, infoHandleFinal)) {
+            throw new FalhaCasCacheDrift("cache_objeto_corrupto");
+        }
+        let valor = null;
+        try {
+            valor = JSON.parse(bytes.toString("utf8"));
+        }
+        catch {
+            // Lock incompleto só pode ser removido após a janela de segurança.
+        }
+        return { info: infoFinal, valor };
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+async function removerLockOrfao(caminho, guarda) {
+    const leitura = await lerLockSeguro(caminho, guarda);
+    if (!leitura)
+        return true;
+    const lock = registroLockCache(leitura.valor) ? leitura.valor : null;
+    const idadeMs = Math.max(0, Date.now() - Number(leitura.info.mtimeMs));
+    const pertenceInstanciaAtual = lock?.pid === process.pid
+        && lock.processoIniciadoEm === PROCESSO_INICIADO_EM_CACHE_DRIFT;
+    const orfao = lock
+        ? (!TOKENS_LOCK_ATIVOS.has(lock.token)
+            && !pertenceInstanciaAtual
+            && (!processoEstaAtivo(lock.pid) || idadeMs >= TTL_LOCK_CACHE_DRIFT_MS))
+        : idadeMs >= TTL_LOCK_CACHE_DRIFT_MS;
+    if (!orfao)
+        return false;
+    await removerArquivoGuardadoSeMesmo(caminho, identidadeDe(leitura.info), guarda);
+    return await lstatOuNull(caminho) === null;
+}
+export async function adquirirLockPublicacao(opcoes) {
+    const caminho = path.join(opcoes.pasta, `.${opcoes.chave.slice("sha256:".length)}.lock`);
+    const token = randomUUID();
+    let contendido = false;
+    let guarda = opcoes.guardaInicial;
+    for (let tentativa = 0; tentativa < TENTATIVAS_LOCK_CACHE_DRIFT; tentativa += 1) {
+        let handle;
+        let identidade;
+        try {
+            await confirmarGuardaCadeia(guarda);
+            handle = await open(caminho, "wx", 0o600);
+            await confirmarGuardaCadeia(guarda);
+            const [infoHandle, infoCaminho] = await Promise.all([
+                handle.stat({ bigint: true }),
+                lstat(caminho, { bigint: true }),
+            ]);
+            if (!identidadeArquivoValida(caminho, infoCaminho, infoHandle)) {
+                throw new FalhaCasCacheDrift("cache_objeto_hardlink");
+            }
+            identidade = identidadeDe(infoHandle);
+            await aplicarPermissaoArquivo(handle);
+            await confirmarGuardaCadeia(guarda);
+            await handle.writeFile(JSON.stringify({
+                schema: SCHEMA_LOCK_CACHE_DRIFT,
+                pid: process.pid,
+                processoIniciadoEm: PROCESSO_INICIADO_EM_CACHE_DRIFT,
+                token,
+                criadoEm: Date.now(),
+            }), "utf8");
+            await handle.sync();
+            const [infoHandleFinal, infoCaminhoFinal] = await Promise.all([
+                handle.stat({ bigint: true }),
+                lstat(caminho, { bigint: true }),
+            ]);
+            if (!identidadeArquivoValida(caminho, infoCaminhoFinal, infoHandleFinal)
+                || !mesmaIdentidade(identidade, identidadeDe(infoHandleFinal))) {
+                throw new FalhaCasCacheDrift("cache_objeto_corrupto");
+            }
+            await confirmarGuardaCadeia(guarda);
+            TOKENS_LOCK_ATIVOS.add(token);
+            return { caminho, handle, identidade, guarda, token, contendido };
+        }
+        catch (erro) {
+            await handle?.close().catch(() => undefined);
+            if (identidade)
+                await removerArquivoGuardadoSeMesmo(caminho, identidade, guarda);
+            if (erro.code !== "EEXIST")
+                throw erro;
+            contendido = true;
+            guarda = await capturarGuardaCadeia(opcoes.raiz, opcoes.identidadeRaiz, opcoes.pasta);
+            const removido = await removerLockOrfao(caminho, guarda);
+            if (!removido)
+                await esperar(INTERVALO_LOCK_CACHE_DRIFT_MS);
+        }
+    }
+    throw new FalhaCasCacheDrift("cache_io_indisponivel");
+}
+export async function confirmarLockPublicacao(lock) {
+    await confirmarGuardaCadeia(lock.guarda);
+    const [infoHandle, infoCaminho] = await Promise.all([
+        lock.handle.stat({ bigint: true }),
+        lstat(lock.caminho, { bigint: true }),
+    ]);
+    if (!identidadeArquivoValida(lock.caminho, infoCaminho, infoHandle)
+        || !mesmaIdentidade(lock.identidade, identidadeDe(infoHandle))) {
+        throw new FalhaCasCacheDrift("cache_objeto_conflitante");
+    }
+    await confirmarGuardaCadeia(lock.guarda);
+}
+export async function liberarLockPublicacao(lock) {
+    await lock.handle.close().catch(() => undefined);
+    try {
+        await removerArquivoGuardadoSeMesmo(lock.caminho, lock.identidade, lock.guarda);
+    }
+    finally {
+        TOKENS_LOCK_ATIVOS.delete(lock.token);
+    }
+}
+export async function limparTemporariosOrfaos(chave, pasta, guarda) {
+    const digest = chave.slice("sha256:".length);
+    const padrao = new RegExp(`^\\.${digest}\\.[a-f0-9-]{36}\\.(?:tmp|replaced)$`, "u");
+    await confirmarGuardaCadeia(guarda);
+    const entradas = await readdir(pasta, { withFileTypes: true });
+    await confirmarGuardaCadeia(guarda);
+    for (const entrada of entradas) {
+        if (entrada.isSymbolicLink() || !padrao.test(entrada.name))
+            continue;
+        const caminho = path.join(pasta, entrada.name);
+        const info = await lstatOuNull(caminho);
+        if (info?.isFile() && !info.isSymbolicLink()) {
+            await removerArquivoGuardadoSeMesmo(caminho, identidadeDe(info), guarda, true);
+        }
+    }
+}
+//# sourceMappingURL=driftCacheCas.js.map

package/dist/driftCacheFilesystem.d.ts

@@ -0,0 +1,64 @@
+import { type BigIntStats } from "node:fs";
+import { type FileHandle } from "node:fs/promises";
+export type CodigoErroFilesystemCacheDrift = "cache_root_sobrepoe_workspace" | "cache_root_link" | "cache_root_hardlink" | "cache_root_nao_diretorio" | "cache_root_indisponivel";
+export type OrigemRaizCacheSema = "explicita" | "localappdata" | "windows_fallback" | "macos_cache" | "xdg_cache" | "unix_fallback";
+export interface OpcoesResolverRaizCacheSema {
+    plataforma?: NodeJS.Platform;
+    ambiente?: Readonly<Record<string, string | undefined>>;
+    diretorioUsuario?: string;
+    raizCache?: string;
+}
+export type ResolucaoRaizCacheSema = {
+    disponivel: true;
+    raiz: string;
+    origem: OrigemRaizCacheSema;
+} | {
+    disponivel: false;
+    codigo: "cache_home_invalido" | "cache_root_relativa";
+};
+export interface IdentidadeFilesystem {
+    dev: bigint;
+    ino: bigint;
+}
+export interface ComponenteGuardadoCache {
+    caminho: string;
+    identidade: IdentidadeFilesystem;
+}
+export interface GuardaCadeiaCache {
+    raiz: string;
+    destino: string;
+    componentes: readonly ComponenteGuardadoCache[];
+}
+export interface EstadoEntradaCache {
+    dev: bigint;
+    ino: bigint;
+    size: bigint;
+    mtimeNs: bigint;
+    ctimeNs: bigint;
+    nlink: bigint;
+    tipo: "arquivo" | "diretorio" | "link" | "outro";
+}
+export declare class FalhaFilesystemCacheDrift extends Error {
+    readonly codigo: CodigoErroFilesystemCacheDrift;
+    constructor(codigo: CodigoErroFilesystemCacheDrift);
+}
+export declare function resolverRaizCacheSema(opcoes?: OpcoesResolverRaizCacheSema): ResolucaoRaizCacheSema;
+export declare function caminhoContido(base: string, alvo: string): boolean;
+export declare function caminhosSobrepostos(a: string, b: string): boolean;
+export declare function identidadeDe(info: BigIntStats): IdentidadeFilesystem;
+export declare function mesmaIdentidade(a: IdentidadeFilesystem, b: IdentidadeFilesystem): boolean;
+export declare function erroEhAusencia(erro: unknown): boolean;
+export declare function lstatOuNull(caminho: string): Promise<BigIntStats | null>;
+export declare function estadoEntrada(info: BigIntStats): EstadoEntradaCache;
+export declare function mesmoEstadoEntrada(a: EstadoEntradaCache | null, b: EstadoEntradaCache | null): boolean;
+export declare function capturarGuardaCadeia(raiz: string, identidadeRaiz: IdentidadeFilesystem, destino: string): Promise<GuardaCadeiaCache>;
+export declare function confirmarGuardaCadeia(guarda: GuardaCadeiaCache): Promise<void>;
+export declare function aplicarPermissaoArquivo(handle: FileHandle): Promise<void>;
+export declare function lerHandleLimitado(handle: FileHandle, limiteBytes: number): Promise<Buffer>;
+export declare function validarComponentesExistentesSemLink(alvo: string): Promise<void>;
+export declare function prepararRaizCache(caminho: string): Promise<{
+    real: string;
+    identidade: IdentidadeFilesystem;
+}>;
+export declare function garantirSubdiretorioSeguro(raiz: string, identidadeRaiz: IdentidadeFilesystem, destino: string): Promise<GuardaCadeiaCache>;
+export declare function identidadeArquivoValida(caminho: string, infoCaminho: BigIntStats, infoHandle: BigIntStats): boolean;