@semacode/cli 2.3.1 → 3.0.0

package/dist/distribuicao/skillIntentPolicy.js

@@ -0,0 +1,115 @@
+// SEMA-GOVERNED: sema.produto.distribuicao_global.skill.intencoes
+// Descrição: materializa a matriz de intenção da skill sem executar mutações.
+import { versaoSemanticaValida } from "./versaoSemantica.js";
+export const INTENCOES_SKILL_SEMA = [
+    "INFORMAR",
+    "INSTALAR_GLOBAL",
+    "ATUALIZAR_GLOBAL",
+    "REPARAR_GLOBAL",
+    "ADOTAR_WORKSPACE",
+];
+function versaoGlobalValidada(versao) {
+    if (versao === undefined || versao === "latest") {
+        return { solicitada: "latest", resolverLatest: true };
+    }
+    if (versaoSemanticaValida(versao)) {
+        return { solicitada: versao, resolverLatest: false };
+    }
+    throw new Error("VERSAO_GLOBAL_DEVE_SER_SEMVER_EXATA_OU_LATEST");
+}
+const ACOES_RESOLVER_CLI_INSTALADA = [
+    "provar_cli_path_com_versao_e_skill",
+    "provar_launcher_gerenciado_com_versao_e_skill",
+    "preferir_launcher_gerenciado_se_path_stale_ou_sem_skill",
+];
+const ACOES_PROVAR_AMBAS_CLI = [
+    "provar_cli_path_com_versao_e_skill",
+    "provar_launcher_gerenciado_com_versao_e_skill",
+];
+export function planejarIntencaoSkillSema(entrada) {
+    if (["INSTALAR_GLOBAL", "ATUALIZAR_GLOBAL"].includes(entrada.intencao)) {
+        const versao = versaoGlobalValidada(entrada.versaoSolicitada);
+        const acoesInstalacao = versao.resolverLatest
+            ? [
+                "npm_view_version:@semacode/cli@latest",
+                "validar_semver_exata_resolvida",
+                "npm_install_global:@semacode/cli@SEMVER_EXATA_RESOLVIDA",
+            ]
+            : [`npm_install_global:@semacode/cli@${versao.solicitada}`];
+        return {
+            instalar_pacote_global: true,
+            sincronizar_distribuicao_se_necessario: true,
+            mutar_workspace: false,
+            bloqueado_por_autorizacao_adocao: false,
+            resolver_latest_para_semver_exata: versao.resolverLatest,
+            provar_path_e_launcher_gerenciado: true,
+            exigir_prova_versao: true,
+            exigir_status_final_ready: true,
+            acoes_ordenadas: [
+                ...acoesInstalacao,
+                ...ACOES_RESOLVER_CLI_INSTALADA,
+                "provar_versao_instalada",
+                "consultar_status_distribuicao",
+                "sincronizar_distribuicao_se_necessario",
+                "consultar_status_final_ready",
+            ],
+        };
+    }
+    if (entrada.intencao === "REPARAR_GLOBAL") {
+        const cliDisponivel = entrada.cliDisponivel;
+        return {
+            instalar_pacote_global: false,
+            sincronizar_distribuicao_se_necessario: cliDisponivel,
+            mutar_workspace: false,
+            bloqueado_por_autorizacao_adocao: false,
+            resolver_latest_para_semver_exata: false,
+            provar_path_e_launcher_gerenciado: true,
+            exigir_prova_versao: false,
+            exigir_status_final_ready: cliDisponivel,
+            acoes_ordenadas: cliDisponivel
+                ? [
+                    ...ACOES_RESOLVER_CLI_INSTALADA,
+                    "consultar_status_distribuicao",
+                    "sincronizar_distribuicao_se_necessario",
+                    "consultar_status_final_ready",
+                ]
+                : [
+                    ...ACOES_PROVAR_AMBAS_CLI,
+                    "declarar_cli_indisponivel_apos_path_e_launcher_gerenciado_invalidos",
+                ],
+        };
+    }
+    if (entrada.intencao === "ADOTAR_WORKSPACE") {
+        const autorizado = entrada.adocaoAutorizada;
+        return {
+            instalar_pacote_global: false,
+            sincronizar_distribuicao_se_necessario: false,
+            mutar_workspace: autorizado,
+            bloqueado_por_autorizacao_adocao: !autorizado,
+            resolver_latest_para_semver_exata: false,
+            provar_path_e_launcher_gerenciado: false,
+            exigir_prova_versao: false,
+            exigir_status_final_ready: false,
+            acoes_ordenadas: autorizado
+                ? [
+                    "descobrir_explicar_flow_project_adoption",
+                    "iniciar_template_base",
+                    "sync_codex",
+                    "ler_agents_e_boot",
+                ]
+                : ["pedir_autorizacao_adocao"],
+        };
+    }
+    return {
+        instalar_pacote_global: false,
+        sincronizar_distribuicao_se_necessario: false,
+        mutar_workspace: false,
+        bloqueado_por_autorizacao_adocao: false,
+        resolver_latest_para_semver_exata: false,
+        provar_path_e_launcher_gerenciado: false,
+        exigir_prova_versao: false,
+        exigir_status_final_ready: false,
+        acoes_ordenadas: ["responder_sem_mutar"],
+    };
+}
+//# sourceMappingURL=skillIntentPolicy.js.map

package/dist/distribuicao/tipos.d.ts

@@ -0,0 +1,50 @@
+export declare const ESTADOS_DISTRIBUICAO_GLOBAL: readonly ["READY", "MISSING", "STALE", "BROKEN_TARGET", "PERMISSION_DENIED"];
+export type EstadoDistribuicaoGlobal = typeof ESTADOS_DISTRIBUICAO_GLOBAL[number];
+export interface OpcoesAmbienteDistribuicaoGlobal {
+    /** Plataforma usada para escolher o formato do launcher. */
+    plataforma?: NodeJS.Platform;
+    /** Home explícita. A implementação nunca consulta outro diretório quando este valor é informado. */
+    diretorioUsuario?: string;
+    /** Executável absoluto do Node que será embutido no launcher. */
+    executavelNode?: string;
+    /** Raiz absoluta do pacote @semacode/cli instalado. */
+    raizPacote?: string;
+}
+export type CodigoDiagnosticoDistribuicaoGlobal = "AMBIENTE_INVALIDO" | "CAMINHO_FORA_DA_HOME" | "COMPONENTE_NAO_DIRETORIO" | "CONTEUDO_NAO_GERENCIADO" | "DESTINO_ALTERADO" | "DESTINO_AUSENTE" | "DESTINO_DESATUALIZADO" | "DESTINO_PRONTO" | "ERRO_PERMISSAO" | "EXECUTAVEL_NODE_INVALIDO" | "LIMPEZA_PENDENTE" | "LOCK_PERDIDO" | "LOCK_TIMEOUT" | "PACOTE_INVALIDO" | "PERMISSAO_EXECUCAO_INVALIDA" | "RECIBO_INVALIDO" | "ROLLBACK_FALHOU" | "SYMLINK_OU_JUNCTION" | "TARGET_CLI_INVALIDO";
+export interface ResultadoLauncherGlobal {
+    estado: EstadoDistribuicaoGlobal;
+    alterado: boolean;
+    destino_simbolico: "$HOME/.sema/bin/sema" | "$HOME/.sema/bin/sema.cmd";
+    codigo: CodigoDiagnosticoDistribuicaoGlobal;
+    node_absoluto: boolean;
+    entrypoint_absoluto: boolean;
+    recibo_valido: boolean;
+    independente_path: boolean;
+    fallback_simbolico: "$HOME/.sema/bin/sema-managed.ps1" | null;
+}
+export type IdentificadorDestinoSkillGlobal = "agents" | "claude";
+export interface ResultadoDestinoSkillGlobal {
+    id: IdentificadorDestinoSkillGlobal;
+    estado: EstadoDistribuicaoGlobal;
+    alterado: boolean;
+    destino_simbolico: "$HOME/.agents/skills/sema" | "$HOME/.claude/skills/sema";
+    codigo: CodigoDiagnosticoDistribuicaoGlobal;
+}
+export interface ResultadoSkillGlobal {
+    estado: EstadoDistribuicaoGlobal;
+    alterado: boolean;
+    origem_simbolica: "$PACKAGE_ROOT/skills/sema";
+    destino_agents: EstadoDistribuicaoGlobal;
+    destino_claude: EstadoDistribuicaoGlobal | "NOT_DETECTED";
+    espelho_claude_detectado: boolean;
+    ownership_valido: boolean;
+    digest_alinhado: boolean;
+    cache_plugin_intocado: true;
+    destinos: ResultadoDestinoSkillGlobal[];
+}
+export interface ResultadoDistribuicaoGlobal {
+    estado: EstadoDistribuicaoGlobal;
+    alterado: boolean;
+    launcher: ResultadoLauncherGlobal;
+    skill: ResultadoSkillGlobal;
+}

package/dist/distribuicao/tipos.js

@@ -0,0 +1,10 @@
+// SEMA-GOVERNED: sema.produto.distribuicao_global
+// Descrição: define o contrato público e injetável da distribuição local global da CLI e da skill Sema.
+export const ESTADOS_DISTRIBUICAO_GLOBAL = [
+    "READY",
+    "MISSING",
+    "STALE",
+    "BROKEN_TARGET",
+    "PERMISSION_DENIED",
+];
+//# sourceMappingURL=tipos.js.map

package/dist/distribuicao/versaoSemantica.d.ts

@@ -0,0 +1,3 @@
+export declare function versaoSemanticaValida(valor: unknown): valor is string;
+/** Retorna -1, 0 ou 1. Build metadata não participa da precedência SemVer. */
+export declare function compararVersoesSemanticas(a: string, b: string): -1 | 0 | 1;

package/dist/distribuicao/versaoSemantica.js

@@ -0,0 +1,62 @@
+// SEMA-GOVERNED: sema.produto.distribuicao_global
+// Descrição: valida versões SemVer de pacotes e recibos sem rede ou dependência externa.
+const PADRAO_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/u;
+function analisar(valor) {
+    if (valor.length > 256)
+        return null;
+    const match = valor.match(PADRAO_SEMVER);
+    if (!match)
+        return null;
+    return {
+        major: BigInt(match[1] ?? "0"),
+        minor: BigInt(match[2] ?? "0"),
+        patch: BigInt(match[3] ?? "0"),
+        prerelease: match[4]?.split(".") ?? null,
+    };
+}
+export function versaoSemanticaValida(valor) {
+    return typeof valor === "string" && analisar(valor) !== null;
+}
+function compararIdentificador(a, b) {
+    const numericoA = /^\d+$/u.test(a);
+    const numericoB = /^\d+$/u.test(b);
+    if (numericoA && numericoB) {
+        const inteiroA = BigInt(a);
+        const inteiroB = BigInt(b);
+        return inteiroA === inteiroB ? 0 : inteiroA > inteiroB ? 1 : -1;
+    }
+    if (numericoA !== numericoB)
+        return numericoA ? -1 : 1;
+    return a === b ? 0 : a > b ? 1 : -1;
+}
+/** Retorna -1, 0 ou 1. Build metadata não participa da precedência SemVer. */
+export function compararVersoesSemanticas(a, b) {
+    const versaoA = analisar(a);
+    const versaoB = analisar(b);
+    if (!versaoA || !versaoB)
+        throw new Error("VERSAO_SEMANTICA_INVALIDA");
+    for (const chave of ["major", "minor", "patch"]) {
+        if (versaoA[chave] !== versaoB[chave])
+            return versaoA[chave] > versaoB[chave] ? 1 : -1;
+    }
+    if (versaoA.prerelease === null || versaoB.prerelease === null) {
+        if (versaoA.prerelease === versaoB.prerelease)
+            return 0;
+        return versaoA.prerelease === null ? 1 : -1;
+    }
+    const limite = Math.max(versaoA.prerelease.length, versaoB.prerelease.length);
+    for (let indice = 0; indice < limite; indice += 1) {
+        const itemA = versaoA.prerelease[indice];
+        const itemB = versaoB.prerelease[indice];
+        if (itemA === undefined || itemB === undefined) {
+            if (itemA === itemB)
+                return 0;
+            return itemA === undefined ? -1 : 1;
+        }
+        const comparacao = compararIdentificador(itemA, itemB);
+        if (comparacao !== 0)
+            return comparacao;
+    }
+    return 0;
+}
+//# sourceMappingURL=versaoSemantica.js.map

package/dist/drift.part01.d.ts

@@ -1,8 +1,8 @@
 import type { EngineBanco, NivelConfiancaSemantica, NivelRiscoSemantico, TipoRecursoPersistencia } from "@sema/nucleo";
 import type { ContextoProjetoCarregado } from "./projeto.js";
-import type { PoliticaCacheDrift } from "./driftCache.js";
-import type { MetricasCacheIncrementalDrift } from "./driftCacheIncremental.js";
 import type { MetricasCatalogoDrift, ObservadorOperacaoDrift } from "./driftCatalogo.js";
+import type { CoberturaEscopoDrift, EstrategiaEscopoDrift } from "./driftEscopo.js";
+import type { AvisoModoCacheDrift, ModoCacheDrift } from "./driftCacheModes.js";
 export type OrigemCodigoDrift = "ts" | "js" | "py" | "dart" | "lua" | "cs" | "java" | "go" | "rust" | "cpp" | "php";
 export type OrigemSimboloDrift = OrigemCodigoDrift | "sql";
 export interface SimboloResolvido {
@@ -34,11 +34,12 @@ export interface OpcoesDriftLegado {
     escopo?: EscopoDriftReal;
     ignorarWorktrees?: boolean;
     ignorarConsumidoresLaterais?: boolean;
-    cache?: PoliticaCacheDrift;
-    observador?: ObservadorOperacaoDrift;
+    modoCache?: ModoCacheDrift;
+    avisosModoCache?: readonly AvisoModoCacheDrift[];
+    observador?: ObservadorOperacaoDrift | undefined;
 }
 export interface DiagnosticoDrift {
-    tipo: "impl_quebrado" | "task_sem_impl" | "rota_divergente" | "recurso_divergente" | "vinculo_quebrado" | "seguranca_frouxa" | "pontuacao_semantica_insuficiente" | "contrato_monolitico" | "codigo_monolitico" | "codigo_governado_sem_cabecalho" | "escopo_estreito_sem_vinculos";
+    tipo: "impl_quebrado" | "task_sem_impl" | "rota_divergente" | "recurso_divergente" | "vinculo_quebrado" | "seguranca_frouxa" | "pontuacao_semantica_insuficiente" | "contrato_monolitico" | "codigo_monolitico" | "codigo_governado_sem_cabecalho" | "escopo_estreito_sem_vinculos" | "escopo_estreito_ambiguo";
     modulo: string;
     task?: string;
     route?: string;
@@ -164,28 +165,30 @@ export interface ConfiguracaoEscopoDriftAplicada {
     ignorarWorktrees: boolean;
     ignorarConsumidoresLaterais: boolean;
     termosEscopo: string[];
-    estrategia?: "arquivos_vinculados" | "projeto";
-    cobertura?: "completa" | "parcial";
+    estrategia?: EstrategiaEscopoDrift;
+    cobertura?: CoberturaEscopoDrift;
     arquivosPlanejados?: string[];
     arquivosDeclarados?: string[];
     arquivosInferidos?: string[];
     arquivosAusentes?: string[];
     bloqueios?: string[];
-    cache?: {
-        politica: PoliticaCacheDrift;
-        origem: "cache" | "calculado" | "nao_aplicavel";
-        chave?: string;
-        incremental?: MetricasCacheIncrementalDrift;
-        fasesMs?: {
-            planejamento: number;
-            catalogacao: number;
-            dependencias: number;
-            assinaturas: number;
-            indexacao: number;
-            total: number;
-        };
-    };
     catalogo?: MetricasCatalogoDrift;
+    cache?: EstadoCacheDriftAplicado;
+}
+export interface MetricasCacheDriftAplicado {
+    hits: number;
+    misses: number;
+    corruptos: number;
+    gravacoes: number;
+    errosGravacao: number;
+}
+export interface EstadoCacheDriftAplicado {
+    modo: ModoCacheDrift;
+    origem: "cache" | "calculado" | "indisponivel" | "nao_aplicavel";
+    schema: string;
+    workspaceId?: string;
+    metricas: MetricasCacheDriftAplicado;
+    avisos: readonly AvisoModoCacheDrift[];
 }
 export interface RegistroImpactoSemanticoArquivo {
     arquivo: string;
@@ -278,10 +281,9 @@ export declare function obterDiretoriosIgnoradosAtivos(): Set<string>;
 export declare function definirDiretoriosIgnoradosAtivos(diretorios: Set<string>): void;
 export declare function normalizarFragmentoArquivo(valor: string): string;
 export declare function normalizarEscopoDrift(valor?: string): EscopoDriftReal;
-export type OpcoesDriftLegadoResolvidas = Required<Omit<OpcoesDriftLegado, "observador">> & {
-    observador?: ObservadorOperacaoDrift;
+export declare function resolverOpcoesDrift(opcoes?: OpcoesDriftLegado): Omit<Required<OpcoesDriftLegado>, "observador"> & {
+    observador: ObservadorOperacaoDrift | undefined;
 };
-export declare function resolverOpcoesDrift(opcoes?: OpcoesDriftLegado): OpcoesDriftLegadoResolvidas;
 export declare function resolverDiretoriosIgnoradosAtivos(opcoes?: OpcoesDriftLegado): Set<string>;
 export declare function quebrarTermosEscopo(valor: string): string[];
 export declare function quebrarTermosModuloEscopo(nomeModulo: string): string[];

package/dist/drift.part01.js

@@ -91,7 +91,8 @@ export function resolverOpcoesDrift(opcoes) {
         escopo: normalizarEscopoDrift(opcoes?.escopo),
         ignorarWorktrees: opcoes?.ignorarWorktrees !== false,
         ignorarConsumidoresLaterais: opcoes?.ignorarConsumidoresLaterais !== false,
-        cache: opcoes?.cache === "refresh" || opcoes?.cache === "off" ? opcoes.cache : "auto",
+        modoCache: opcoes?.modoCache ?? "none",
+        avisosModoCache: opcoes?.avisosModoCache ?? [],
         observador: opcoes?.observador,
     };
 }

package/dist/drift.part04.d.ts

@@ -1,8 +1,17 @@
 import ts from "typescript";
 import type { IrModulo, IrSuperficie, IrTask, IrVinculo, NivelConfiancaSemantica, NivelRiscoSemantico } from "@sema/nucleo";
 import { ResultadoDrift, SimboloResolvido } from "./drift.part01.js";
+import type { OrigemCodigoDrift } from "./drift.part01.js";
 import { type PoliticaPontuacaoSemantica } from "./driftScore.js";
-import type { CatalogoDrift } from "./driftCatalogo.js";
+export type EventoLeituraCompartilhadaDrift = "extractor.run" | "ast.create";
+export interface AdaptadorLeituraCompartilhadaDrift {
+    listarPorRaiz(raiz: string, extensoes: readonly string[]): readonly string[] | Promise<readonly string[]>;
+    lerTexto(arquivo: string): Promise<string>;
+    emitir?(tipo: EventoLeituraCompartilhadaDrift, arquivo?: string): void;
+}
+export declare function chaveCaminhoCanonicoDrift(caminho: string): string;
+export declare function deduplicarRaizesSobrepostasDrift(diretorios: readonly string[]): string[];
+export declare function encontrarCandidatosFisicosImplementacaoDrift(simbolos: readonly SimboloResolvido[], origem: OrigemCodigoDrift, caminhoDeclarado: string): SimboloResolvido[];
 export declare function resolverArquivoOuSimboloAncora(vinculos: IrVinculo[], simbolos: SimboloResolvido[], mapaImpl: Map<string, SimboloResolvido>, arquivos: string[]): {
     arquivo?: string;
     simbolo?: string;
@@ -38,9 +47,9 @@ export declare function lerDecorator(node: ts.Node, nomes: string[]): {
     argumentos: ts.NodeArray<ts.Expression>;
 } | undefined;
 export declare function juntarCaminhoHttp(base: string | undefined, sufixo: string | undefined): string;
-export declare function listarArquivosRecursivos(diretorio: string, extensoes: string[], catalogo?: CatalogoDrift): Promise<string[]>;
+export declare function listarArquivosRecursivos(diretorio: string, extensoes: string[], adaptadorLeitura?: AdaptadorLeituraCompartilhadaDrift): Promise<string[]>;
 export declare const EXTENSOES_ARQUIVOS_RASTREAVEIS_DRIFT: string[];
-export declare function indexarArquivosRastreaveis(diretorios: string[], catalogo?: CatalogoDrift): Promise<string[]>;
+export declare function indexarArquivosRastreaveis(diretorios: string[], adaptadorLeitura?: AdaptadorLeituraCompartilhadaDrift): Promise<string[]>;
 export declare function caminhosSimbolicos(baseDiretorio: string, arquivo: string): string[];
 export declare function registrarSimboloTypeScript(simbolos: Map<string, SimboloResolvido>, basesSimbolicas: string[], arquivo: string, nome: string, nomeClasse?: string, origem?: "ts" | "js"): void;
 export declare function desembrulharExpressaoTypeScript(expr: ts.Expression): ts.Expression;

package/dist/drift.part04.js

@@ -1,11 +1,71 @@
-// SEMA-GOVERNED: sema.governanca_ia_contexto
-// Descricao: CLI particionada; consulte contratos/sema/governanca_ia_contexto.sema antes de editar.
+// SEMA-GOVERNED: sema.produto.governanca_ia.drift
+// Descricao: compartilha primitivas de indexacao e leitura do drift entre linguagens.
+import { AsyncLocalStorage } from "node:async_hooks";
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import ts from "typescript";
 import { diretoriosIgnoradosAtivos } from "./drift.part01.js";
 import { escolherArquivoPorVinculo, escolherSimboloPorVinculo } from "./drift.part03.js";
 import { avaliarPontuacaoSemantica, resolverPoliticaPontuacaoSemantica } from "./driftScore.js";
+export function chaveCaminhoCanonicoDrift(caminho) {
+    const resolvido = path.resolve(caminho);
+    return process.platform === "win32" ? resolvido.toLowerCase() : resolvido;
+}
+function caminhoEstaDentroDaRaizDrift(raiz, candidato) {
+    const relativo = path.relative(path.resolve(raiz), path.resolve(candidato));
+    return relativo === "" || (!relativo.startsWith("..") && !path.isAbsolute(relativo));
+}
+const contextoRaizesSobrepostasDrift = new AsyncLocalStorage();
+export function deduplicarRaizesSobrepostasDrift(diretorios) {
+    const unicas = new Map();
+    for (const diretorio of diretorios) {
+        const chave = chaveCaminhoCanonicoDrift(diretorio);
+        if (!unicas.has(chave)) {
+            unicas.set(chave, diretorio);
+        }
+    }
+    const candidatas = [...unicas.values()];
+    const raizesFisicas = candidatas.filter((candidata, indice) => !candidatas.some((outra, outroIndice) => indice !== outroIndice
+        && chaveCaminhoCanonicoDrift(candidata) !== chaveCaminhoCanonicoDrift(outra)
+        && caminhoEstaDentroDaRaizDrift(outra, candidata)));
+    const aliasesPorRaiz = new Map();
+    for (const raizFisica of raizesFisicas) {
+        aliasesPorRaiz.set(chaveCaminhoCanonicoDrift(raizFisica), candidatas.filter((candidata) => chaveCaminhoCanonicoDrift(candidata) !== chaveCaminhoCanonicoDrift(raizFisica)
+            && caminhoEstaDentroDaRaizDrift(raizFisica, candidata)));
+    }
+    contextoRaizesSobrepostasDrift.enterWith(aliasesPorRaiz);
+    return raizesFisicas;
+}
+export function encontrarCandidatosFisicosImplementacaoDrift(simbolos, origem, caminhoDeclarado) {
+    const caminhoNormalizado = caminhoDeclarado.trim().toLowerCase();
+    if (!caminhoNormalizado) {
+        return [];
+    }
+    const mesmaFamilia = (candidato) => candidato.origem === origem
+        || ((origem === "ts" || origem === "js") && (candidato.origem === "ts" || candidato.origem === "js"));
+    const porArquivo = new Map();
+    for (const candidato of simbolos) {
+        const caminhoCandidato = candidato.caminho.toLowerCase();
+        if (!mesmaFamilia(candidato)
+            || (caminhoCandidato !== caminhoNormalizado && !caminhoCandidato.endsWith(`.${caminhoNormalizado}`))) {
+            continue;
+        }
+        const chaveArquivo = chaveCaminhoCanonicoDrift(candidato.arquivo);
+        const anterior = porArquivo.get(chaveArquivo);
+        const candidatoExato = caminhoCandidato === caminhoNormalizado;
+        const anteriorExato = anterior?.caminho.toLowerCase() === caminhoNormalizado;
+        if (!anterior
+            || (candidatoExato && !anteriorExato)
+            || (candidatoExato === anteriorExato
+                && (candidato.caminho.length < anterior.caminho.length
+                    || (candidato.caminho.length === anterior.caminho.length
+                        && candidato.caminho.localeCompare(anterior.caminho, "pt-BR") < 0)))) {
+            porArquivo.set(chaveArquivo, candidato);
+        }
+    }
+    return [...porArquivo.values()].sort((a, b) => a.arquivo.localeCompare(b.arquivo, "pt-BR")
+        || a.caminho.localeCompare(b.caminho, "pt-BR"));
+}
 export function resolverArquivoOuSimboloAncora(vinculos, simbolos, mapaImpl, arquivos) {
     for (const vinculo of vinculos) {
         if (vinculo.simbolo) {
@@ -258,9 +318,11 @@ export function juntarCaminhoHttp(base, sufixo) {
     const caminho = `/${partes.join("/")}`.replace(/\/+/g, "/");
     return caminho === "//" ? "/" : caminho;
 }
-export async function listarArquivosRecursivos(diretorio, extensoes, catalogo) {
-    if (catalogo) {
-        return catalogo.listarPorRaiz(diretorio, extensoes);
+export async function listarArquivosRecursivos(diretorio, extensoes, adaptadorLeitura) {
+    if (adaptadorLeitura) {
+        const arquivos = await adaptadorLeitura.listarPorRaiz(diretorio, extensoes);
+        return [...new Map(arquivos.map((arquivo) => [chaveCaminhoCanonicoDrift(arquivo), arquivo])).values()]
+            .sort((a, b) => a.localeCompare(b, "pt-BR"));
     }
     let entradas;
     try {
@@ -294,16 +356,19 @@ export const EXTENSOES_ARQUIVOS_RASTREAVEIS_DRIFT = [
     ".yml", ".yaml", ".toml", ".xml", ".html", ".htm", ".css",
     ".Caddyfile", ".caddyfile",
 ];
-export async function indexarArquivosRastreaveis(diretorios, catalogo) {
-    const arquivos = new Set();
-    for (const diretorio of diretorios) {
-        for (const arquivo of await listarArquivosRecursivos(diretorio, EXTENSOES_ARQUIVOS_RASTREAVEIS_DRIFT, catalogo)) {
-            arquivos.add(arquivo);
+export async function indexarArquivosRastreaveis(diretorios, adaptadorLeitura) {
+    const arquivos = new Map();
+    for (const diretorio of deduplicarRaizesSobrepostasDrift(diretorios)) {
+        for (const arquivo of await listarArquivosRecursivos(diretorio, EXTENSOES_ARQUIVOS_RASTREAVEIS_DRIFT, adaptadorLeitura)) {
+            const chave = chaveCaminhoCanonicoDrift(arquivo);
+            if (!arquivos.has(chave)) {
+                arquivos.set(chave, arquivo);
+            }
         }
     }
-    return [...arquivos].sort((a, b) => a.localeCompare(b, "pt-BR"));
+    return [...arquivos.values()].sort((a, b) => a.localeCompare(b, "pt-BR"));
 }
-export function caminhosSimbolicos(baseDiretorio, arquivo) {
+function caminhosSimbolicosParaBaseDrift(baseDiretorio, arquivo) {
     const relativo = path.relative(baseDiretorio, arquivo).replace(/\.[^.]+$/, "");
     const semPrefixo = relativo
         .split(path.sep)
@@ -312,13 +377,19 @@ export function caminhosSimbolicos(baseDiretorio, arquivo) {
         .join(".");
     const prefixo = paraIdentificadorModulo(path.basename(baseDiretorio));
     const comPrefixo = prefixo ? [prefixo, semPrefixo].filter(Boolean).join(".") : semPrefixo;
+    const aliasesBase = [semPrefixo, comPrefixo].filter(Boolean);
     const aliasesIndex = path.basename(relativo) === "index"
-        ? [
-            semPrefixo.replace(/(?:^|\.)index$/, ""),
-            comPrefixo.replace(/(?:^|\.)index$/, ""),
-        ]
+        ? aliasesBase.map((alias) => alias.replace(/(?:^|\.)index$/, ""))
         : [];
-    return [...new Set([semPrefixo, comPrefixo, ...aliasesIndex].filter(Boolean))];
+    return [...new Set([...aliasesBase, ...aliasesIndex].filter(Boolean))];
+}
+export function caminhosSimbolicos(baseDiretorio, arquivo) {
+    const aliasesConfigurados = contextoRaizesSobrepostasDrift.getStore()
+        ?.get(chaveCaminhoCanonicoDrift(baseDiretorio))
+        ?.filter((raiz) => caminhoEstaDentroDaRaizDrift(raiz, arquivo))
+        ?? [];
+    return [...new Set([baseDiretorio, ...aliasesConfigurados]
+            .flatMap((base) => caminhosSimbolicosParaBaseDrift(base, arquivo)))];
 }
 export function registrarSimboloTypeScript(simbolos, basesSimbolicas, arquivo, nome, nomeClasse, origem = "ts") {
     for (const baseSimbolica of basesSimbolicas) {

package/dist/drift.part05.d.ts

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import { RegistroConsumerSurfaceDrift, SimboloResolvido } from "./drift.part01.js";
-import type { CatalogoDrift } from "./driftCatalogo.js";
+import { type AdaptadorLeituraCompartilhadaDrift } from "./drift.part04.js";
 export declare function registrarMetodoTypeScriptProtoOuObjeto(simbolos: Map<string, SimboloResolvido>, basesSimbolicas: string[], arquivo: string, nomeMetodo: string, nomeClasse?: string, origem?: "ts" | "js"): void;
 export declare function registrarMetodosObjectAssignTypeScript(simbolos: Map<string, SimboloResolvido>, basesSimbolicas: string[], arquivo: string, objeto: ts.ObjectLiteralExpression, sourceFile: ts.SourceFile, nomeClasse?: string, origem?: "ts" | "js"): void;
 export declare function registrarAtribuicaoPrototypeTypeScript(simbolos: Map<string, SimboloResolvido>, basesSimbolicas: string[], arquivo: string, sourceFile: ts.SourceFile, esquerda: ts.Expression, direita: ts.Expression, origem?: "ts" | "js"): void;
@@ -44,5 +44,5 @@ export declare function extrairRotasReactViteConsumer(relacaoArquivo: string, co
 export declare function normalizarRotaDeclaradaFlutter(caminhoCru: string): string;
 export declare function extrairRotasFlutterConsumer(relacaoArquivo: string, codigo: string): RotaFlutterConsumerDrift[];
 export declare function extrairRotasAngularConsumerDiretas(relacaoArquivo: string, codigo: string, prefixo?: string): RotaAngularConsumerDrift[];
-export declare function extrairRotasAngularConsumer(diretorioBase: string, relacaoArquivo: string, prefixo?: string, visitados?: Set<string>, catalogo?: CatalogoDrift): Promise<RotaAngularConsumerDrift[]>;
+export declare function extrairRotasAngularConsumer(diretorioBase: string, relacaoArquivo: string, prefixo?: string, visitados?: Set<string>, adaptadorLeitura?: AdaptadorLeituraCompartilhadaDrift): Promise<RotaAngularConsumerDrift[]>;
 export declare function simboloEhBridgeConsumer(caminho: string, arquivo: string): boolean;

package/dist/drift.part05.js

@@ -1,9 +1,9 @@
-// SEMA-GOVERNED: sema.governanca_ia_contexto
-// Descricao: CLI particionada; consulte contratos/sema/governanca_ia_contexto.sema antes de editar.
+// SEMA-GOVERNED: sema.produto.governanca_ia.drift
+// Descricao: extrai rotas e superficies consumidoras dentro do escopo fisico planejado.
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import ts from "typescript";
-import { desembrulharExpressaoTypeScript, extrairNomePropriedadeTypeScript, registrarSimboloTypeScript } from "./drift.part04.js";
+import { desembrulharExpressaoTypeScript, extrairNomePropriedadeTypeScript, registrarSimboloTypeScript, } from "./drift.part04.js";
 export function registrarMetodoTypeScriptProtoOuObjeto(simbolos, basesSimbolicas, arquivo, nomeMetodo, nomeClasse, origem = "ts") {
     if (!nomeMetodo) {
         return;
@@ -318,7 +318,7 @@ export function extrairRotasAngularConsumerDiretas(relacaoArquivo, codigo, prefi
     }
     return rotas;
 }
-export async function extrairRotasAngularConsumer(diretorioBase, relacaoArquivo, prefixo = "/", visitados = new Set(), catalogo) {
+export async function extrairRotasAngularConsumer(diretorioBase, relacaoArquivo, prefixo = "/", visitados = new Set(), adaptadorLeitura) {
     const relacaoNormalizada = normalizarRelacaoConsumer(relacaoArquivo);
     if (visitados.has(relacaoNormalizada)) {
         return [];
@@ -327,7 +327,9 @@ export async function extrairRotasAngularConsumer(diretorioBase, relacaoArquivo,
     let codigo = "";
     try {
         const arquivo = path.join(diretorioBase, relacaoNormalizada);
-        codigo = catalogo ? await catalogo.lerTexto(arquivo) : await readFile(arquivo, "utf8");
+        codigo = adaptadorLeitura
+            ? await adaptadorLeitura.lerTexto(arquivo)
+            : await readFile(arquivo, "utf8");
     }
     catch {
         return [];
@@ -338,7 +340,7 @@ export async function extrairRotasAngularConsumer(diretorioBase, relacaoArquivo,
         if (!rota.arquivoRotasFilhas) {
             continue;
         }
-        filhas.push(...await extrairRotasAngularConsumer(diretorioBase, rota.arquivoRotasFilhas, rota.rota, visitados, catalogo));
+        filhas.push(...await extrairRotasAngularConsumer(diretorioBase, rota.arquivoRotasFilhas, rota.rota, visitados, adaptadorLeitura));
     }
     return [...rotas, ...filhas];
 }

package/dist/drift.part06.d.ts

@@ -1,9 +1,9 @@
 import type { FonteLegado } from "./tipos.js";
 import { ConsumerFramework, RecursoResolvido, RegistroConsumerBridgeDrift, RegistroConsumerSurfaceDrift, RotaResolvida, SimboloResolvido } from "./drift.part01.js";
-import type { CatalogoDrift } from "./driftCatalogo.js";
+import { type AdaptadorLeituraCompartilhadaDrift } from "./drift.part04.js";
 export declare function inferirConsumerFrameworkPrincipal(fontesLegado: FonteLegado[], consumerSurfaces: RegistroConsumerSurfaceDrift[], consumerBridges: RegistroConsumerBridgeDrift[]): ConsumerFramework | null;
 export declare function extrairColecoesFirebase(arquivo: string, codigo: string): RecursoResolvido[];
-export declare function indexarTypeScript(diretorios: string[], catalogo?: CatalogoDrift): Promise<{
+export declare function indexarTypeScript(diretorios: string[], adaptadorLeitura?: AdaptadorLeituraCompartilhadaDrift): Promise<{
     simbolos: SimboloResolvido[];
     rotas: RotaResolvida[];
     recursos: RecursoResolvido[];