GBR: ADR-0005 Indexação Semântica Estruturada via AST Chunking (Glance)

• *Status:* Aceito
• *Data:* 2026-05-01

*Contexto:*

Durante a Fase 5 e a Fase 12.3, a CLI (gleambrctl) efetuava a ingestão do código-fonte das bibliotecas iterando sobre o conteúdo dos arquivos como strings genéricas e "fatiando" a cada 1000 caracteres. Esse método, conhecido como "Naive RAG" (RAG Ingênuo), destruía a integridade estrutural do código. Funções ou tipos algébricos eram seccionados transversalmente, e o motor neural BERT perdia a "visão integral" do bloco funcional. Em consultas especializadas, a ausência de sintaxe completa no mesmo "Chunk" causava alucinações críticas (fenômeno da Fossa Semântica e Lost in the Middle), pois o banco vetorial não fornecia os delimitadores reais do código requisitado.

*Decisão:*

1. *Abandono do Fatiamento Léxico:* A técnica de recursive slicing baseada em comprimentos literais de caractere (ex: 1000 bytes) é descontinuada no pipeline de ingestão.
2. **Adoção de AST Chunking (lpil/glance):** Incorporação do parser nativo do compilador Gleam ao orquestrador da CLI. A partir da adoção, o gleambrctl não lê arquivos de texto: ele solicita à biblioteca glance a árvore sintática abstrata completa do documento.
3. *Mapeamento de Fragmentos Cognitivos:* O banco DuckDB passará a receber os chunks alinhados com construtores sintáticos reais: - Funções públicas e privadas (glance.Function). - Declarações de Custom Types (glance.CustomType). - Importações e constantes. - Cada um desses blocos isolados converte-se no seu próprio "Fato Semântico", recebendo o seu próprio cálculo de Embedding via BERT.
4. *Metadados de Injeção Compilada:* O meta_json vinculado ao DuckDB deve extrair ativamente o nome da função e a visibilidade de escopo providenciada pela árvore do glance, e não apenas o "nome do arquivo base".

*Consequências:*

• *Positivas:* Tolerância zero à amputação de assinaturas e lógicas de código no repositório Vetorial. Aumenta substancialmente a probabilidade de acerto analítico da IA Generativa; consolida o passo fundamental de migração para um futuro paradigma de Busca Híbrida (BM25 + Dense Search).
• *Negativas/Riscos:* A indexação local torna-se mais agressiva computacionalmente, pois a criação do banco de dados na máquina do usuário agora envolve passar a String inteira do código do projeto alvo pelo validador e pelo analisador semântico de construção da AST antes de enviá-lo ao motor Rust para cálculo da inferência BERT. Dependência total das atualizações sintáticas lançadas pela equipe da linguagem Gleam no repositório do glance.