candeia 0.0.0-stage → 1.1.1

package/DADOS.md

@@ -0,0 +1,33 @@
+# Licença e fonte dos dados
+
+O código deste repositório está sob a licença MIT (ver `LICENSE`). Os dados não fazem parte do repositório e têm licença própria.
+
+## Fonte
+
+O índice publicado (`manifesto.json` e os arquivos `<UF>/<município>...json.gz`) é derivado do **Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE), Censo Demográfico 2022, do Instituto Brasileiro de Geografia e Estatística (IBGE)**.
+
+O índice é uma transformação do CNEFE feita por `pipeline/`: seleção de colunas, normalização do nome da via, descarte de coordenadas de centróide (NV_GEO_COORD 5 e 6), agrupamento por via e compressão. Nenhum dado de outra fonte é acrescentado. O IBGE não endossa este projeto nem os resultados do geocodificador.
+
+## Licença do índice
+
+O índice é distribuído sob a [Creative Commons Atribuição 4.0 Internacional (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.pt-br). Quem redistribuir o índice, ou uma derivação dele, deve citar as duas fontes:
+
+> Dados: IBGE, Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE), Censo Demográfico 2022. Índice: Candeia (https://github.com/LucasRikelmi/candeia), CC BY 4.0.
+
+Usar o geocodificador para consultar endereços não exige atribuição. A atribuição vale para quem copia ou republica os arquivos do índice.
+
+## Termos de uso do CNEFE (conferido em 2026-11-14)
+
+O que foi encontrado:
+
+- **Não há licença explícita para o CNEFE.** A [página de divulgação dos microdados do CNEFE 2022](https://www.ibge.gov.br/comunicados/40157-ibge-divulga-microdados-do-cadastro-nacional-de-enderecos-para-fins-estatisticos-cnefe-oriundos-do-censo-demografico-2022) não traz termo de uso, licença nem regra de citação. Ela só aponta o termo de uso e a política de privacidade gerais do portal.
+- **A posição do IBGE sobre o conteúdo do portal** é a da resposta oficial do atendimento (protocolo 8171/2009, de 08/01/2009), divulgada na [lista do OpenStreetMap](https://lists.openstreetmap.org/pipermail/imports/2013-July/001981.html). Segundo ela, os conteúdos do portal são de domínio público, e o uso em outras publicações ou portais está condicionado à citação da fonte (IBGE). É com base nessa posição que o OpenStreetMap usa dados do IBGE ([wiki](https://wiki.openstreetmap.org/Pt-br:Tag:source=IBGE)).
+- **Dados pessoais:** o índice não guarda nome de estabelecimento, complemento de unidade (apartamento, sala) nem qualquer campo além de via, tipo, número, quadra/lote, localidade, CEP, coordenada, nível da coordenada e a contagem de pontos repetidos.
+
+Consequência: a licença CC BY 4.0 do índice está em linha com essa posição, porque exige atribuição e a atribuição acima cita o IBGE primeiro.
+
+Limites desta conferência:
+- A resposta de 2009 é anterior ao CNEFE 2022 e não é um termo formal.
+- Ela não é uma análise jurídica.
+
+Se o IBGE publicar termo específico para o CNEFE, ou exigir outra forma de atribuição, o termo do IBGE prevalece sobre este texto.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Rikelmi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# Candeia
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Geocodificação de endereços brasileiros que roda no seu próprio código, sem servidor, sem chave de API e sem custo por consulta.
+
+> **Status: v1.1.1.** O motor, o índice das 27 UFs e o loader funcionam. O índice está publicado em `https://dados.lucasrikelmi.dev/cnefe2022/v1/` (Cloudflare Pages, CC BY 4.0, ver [DADOS.md](DADOS.md)). Instalação pelo npm (ver [Uso](#uso)). Os números de acurácia vêm de um benchmark sintético sobre o próprio CNEFE (132 municípios, 19.800 endereços), descrito em [docs/ARQUITETURA.md](docs/ARQUITETURA.md). Um benchmark de regressão roda no CI a cada PR.
+
+## O problema
+
+Quem precisa transformar um endereço brasileiro em coordenada hoje tem, na prática, duas saídas:
+
+1. **APIs comerciais (Google Maps e similares).** Funcionam bem, mas cobram por consulta, exigem chave e mandam os endereços dos seus clientes para um terceiro.
+2. **Ferramentas de pesquisa baseadas no CNEFE do IBGE.** Gratuitas e offline, mas pensadas para análise em lote por quem programa em R, com download de dados grande e sem suporte a quadra e lote, que é como muito endereço brasileiro realmente se escreve (Goiânia, Distrito Federal, Palmas, loteamentos em geral).
+
+Falta uma opção gratuita que rode dentro de um site ou de um backend comum e entenda o jeito brasileiro de escrever endereço.
+
+## A premissa
+
+O IBGE publica o CNEFE, o cadastro de endereços usado no Censo, com coordenadas. Com ele dá para montar um geocodificador **estático**:
+
+- **Sem servidor.** O código roda no navegador ou no Node de quem usa. Os dados são arquivos estáticos públicos. Nenhuma lógica roda do nosso lado, e o host dos arquivos nunca vê o endereço consultado, só qual município foi baixado.
+- **Dados por município.** Quem consulta Belo Horizonte baixa o arquivo de Belo Horizonte, não o Brasil. O arquivo fica em memória (e no cache HTTP do navegador), e a segunda consulta não usa rede. Quem quiser tudo no próprio ambiente pode espelhar os arquivos do índice (CC BY 4.0) e apontar `base` para lá.
+- **Resposta com qualidade explícita.** Cada resultado traz o nível em que o endereço foi encontrado e uma estimativa de erro em metros, em vez de fingir precisão que não tem.
+- **Endereço do jeito que é digitado.** Abreviações ("R.", "Av.", "Tv."), rodovias com a sigla da UF, quadra e lote no lugar do número de porta, complemento no campo errado.
+
+## Uso
+
+Node 22 ou mais (sem dependências):
+
+```sh
+npm install candeia
+```
+
+No navegador, direto de um CDN:
+
+```js
+import { criarGeocodificador } from "https://cdn.jsdelivr.net/npm/candeia@1.1.1/src/index.js";
+```
+
+```js
+import { criarGeocodificador } from "candeia";
+
+const geo = criarGeocodificador({ base: "https://dados.lucasrikelmi.dev/cnefe2022/v1/" });
+const r = await geo.geocodificar("Rua 8, Qd 21 Lt 4", {
+  municipio: "5208707", // código IBGE
+  bairro: "Setor Central",
+  cep: "74000-000",
+});
+
+// {
+//   status: "verde" | "azul" | "amarelo" | "laranja" | "vermelho",
+//   metodo: "numero" | "quadra_lote" | "lote" | "quadra" | "interpolacao" | "eixo" | "cep" | "cruzamento" | "falha",
+//   coord: { lat, lon },
+//   raio,        // metros: até onde o ponto pode estar (null quando não dá para estimar)
+//   confianca,   // { ate100m, acima1km, amostra }: frações medidas no benchmark para essa cor e raio
+//   viaKey, motivo, ...
+// }
+```
+
+Município pequeno é um arquivo só. Município grande baixa o índice de vias e só a fatia da via pedida: no benchmark, uma consulta fria em São Paulo baixa ~1,3 MB e a seguinte na mesma via não baixa nada. O loader confere o sha256 de cada arquivo contra o manifesto. A página `exemplo/index.html` mostra o uso no navegador. Fora do navegador, passe um `fetch` com `User-Agent` próprio, por exemplo `criarGeocodificador({ base, fetch: (u) => fetch(u, { headers: { "User-Agent": "meu-sistema/1.0" } }) })`: a Cloudflare barra assinaturas genéricas de cliente, como a do Python (ver [docs/PUBLICACAO.md](docs/PUBLICACAO.md)).
+
+Medido no benchmark (cenário com o endereço no índice, variante limpa; rodada 9): 74,5% até 100 m no geral e 92,9% com número de porta; com erro de digitação no nome, 73,7%. Verde acerta até 100 m em 99,8% dos casos. Endereço sem número fica em ~38%, limitado pela extensão da via, e o `raio` diz isso. Rua que não existe na cidade volta vermelho (centro do município) em 83% dos casos; no resto, casa com uma rua de nome parecido, e a cor e o `raio` mostram a incerteza.
+
+Fluxo de uma consulta:
+
+1. **Normalização local.** Tipo da via, nome, número, quadra e lote são extraídos e padronizados.
+2. **Município** pelo código IBGE de 7 dígitos, informado por quem chama.
+3. **Download do arquivo do município** (ou do índice de vias e da fatia da via, nos grandes), ou leitura do que já está em memória.
+4. **Busca por token do nome da via**, para não comparar com todas as ruas da cidade.
+5. **Pontuação do nome** com Jaro-Winkler e Jaccard por tokens. Bairro e CEP desempatam ruas homônimas.
+6. **Refinamento por número, quadra e lote.** Sem número, o motor tenta interpolar entre vizinhos, depois cai para o eixo da via, o CEP e o centro do município. `metodo` diz até onde chegou e `raio` quanto o ponto pode estar longe.
+
+## Dados
+
+- **Fonte:** CNEFE, Censo 2022, IBGE. O IBGE trata o conteúdo do portal como domínio público, com citação obrigatória da fonte. O índice sai sob CC BY 4.0. O que foi conferido e os limites dessa conferência estão em [DADOS.md](DADOS.md).
+- **Formato:** o artefato canônico do pipeline é Parquet sem perda, particionado por UF e município (CSV 18,2 GB → Parquet 3,2 GB no país). O que o cliente baixa é um índice próprio em JSON comprimido com gzip: um arquivo por município (abaixo de 1 MB em 5.425 dos 5.570) e, nos 145 maiores, um índice de vias mais fatias de pontos de até ~0,6 MB. O país inteiro soma ~1 GB; o pior caso de uma consulta (São Paulo capital) baixa ~1,3 MB. Detalhes e medições em `docs/ARQUITETURA.md`.
+- **Pipeline:** os dados nunca entram por pull request. Eles são gerados apenas pelo pipeline do repositório, de forma reproduzível.
+- **Medições:** as análises que definiram as regras (tipos de logradouro, rodovias por UF, tamanho por município, DF) estão em `docs/ARQUITETURA.md` e nos scripts `pipeline/medir_*.py`.
+
+Cada UF escreve endereço de um jeito. Na amostra inicial, o DF tem 96% dos registros com tipo "EDF" e 97% sem número de porta, com o endereço real em quadra, conjunto e lote. O AC tem 57% de CEPs genéricos da cidade e vias rurais como ramal, igarapé e seringal. Um motor que só funciona com "rua + número" não cobre isso.
+
+## Qualidade e honestidade sobre os números
+
+- Um score de similaridade não é probabilidade. A `confianca` devolvida é a fração medida no benchmark para a mesma cor e faixa de raio, validada fora da amostra (metade dos municípios ajusta, a outra mede). Ela não é separada por UF de propósito: a tabela por UF, mesmo encolhida para a nacional, errou mais nos municípios que ficaram fora do ajuste (Brier 0,0959 contra 0,0917 da nacional). A diferença entre municípios da mesma UF é maior que a diferença entre UFs, e a cor e o raio já carregam o que importa.
+- O benchmark sintético sorteia endereços do próprio CNEFE e os suja (abreviações, erros de digitação, campos faltando). Ele é otimista por construção, porque o gabarito vem da mesma base. Ainda não há validação com pontos conferidos em campo.
+- O CNEFE é de 2022. Endereços novos não existem nele.
+- Coordenadas aproximadas servem para mapa, roteirização grosseira, estatística e triagem. Não servem para localizar um portão específico quando o nível devolvido for `logradouro` ou menor.
+
+## Relação com outros projetos
+
+O [geocodebr](https://ipeagit.github.io/geocodebr), do IPEA, também usa o CNEFE, funciona offline e retorna nível de precisão e desvio em metros. É mais maduro e cobre geocodificação reversa e busca por CEP. A proposta do Candeia é outra: rodar em JavaScript (navegador e Node), baixar só o município consultado e tratar quadra e lote.
+
+Comparação nas mesmas 66 mil consultas (≤100 m: fração de respostas a até 100 m do ponto certo; >1 km: fração que errou por mais de 1 km) do benchmark (geocodebr 0.7.0, entrada em campos separados; scripts em `bench/geocodebr/`). Os dois usam o CNEFE 2022 e o gabarito também vem dele, então mede o que cada motor faz com a mesma entrada, não a acurácia no mundo real.
+
+| grupo | ≤100 m Candeia (maior é melhor) | ≤100 m geocodebr (maior é melhor) | >1 km Candeia (menor é melhor) | >1 km geocodebr (menor é melhor) |
+|---|---|---|---|---|
+| endereço limpo | 75,8% | 73,1% | 8,0% | 8,1% |
+| com número de porta | 93,2% | 92,5% | 1,8% | 1,8% |
+| quadra e lote | 91,9% | 58,1% | 1,6% | 2,4% |
+| sem número | 34,0% | 30,1% | 22,9% | 23,4% |
+| sem bairro e CEP | 70,9% | 67,8% | 13,3% | 16,2% |
+| erro de digitação no nome | 74,9% | 74,1% | 7,7% | 7,2% |
+| erro dentro da margem declarada, ou até 100 m (`raio` × `desvio_metros`, limpo) | 91,7% | 93,7% | — | — |
+
+Leitura:
+
+- Com número de porta os dois empatam: a diferença (0,7 ponto) está dentro do ruído de uma amostra desse tamanho. A vantagem do Candeia no "endereço limpo" vem quase toda de quadra e lote e de sem número.
+- A vantagem do Candeia em quadra e lote vem de o geocodebr não ter campo para quadra e lote: ele recebeu só o logradouro. É uma diferença de escopo, não de qualidade do casamento, e são só 627 consultas.
+- Sem bairro e CEP o Candeia erra menos acima de 1 km (13,3% contra 16,2%).
+- Com erro de digitação, a primeira medição deu vantagem ao geocodebr (74,1% contra 72,7%): ele usava o número de porta quando a rua só casava por semelhança, e o Candeia não. Depois da correção (rodada 9) o Candeia passa a 74,9% até 100 m, mas o geocodebr ainda erra menos acima de 1 km (7,2% contra 7,7%).
+- O geocodebr também é mais honesto sobre a própria margem: o erro fica dentro do `desvio_metros` que ele declara em 93,7% dos casos, contra 91,7% do `raio` do Candeia.
+
+Limites desta comparação:
+
+- O gabarito sai do CNEFE, a mesma base dos dois motores. Isso favorece quem reproduz o CNEFE com fidelidade e não diz nada sobre endereço fora dele.
+- As variantes com erro foram geradas pelo benchmark do Candeia, que também escolheu os grupos.
+- O geocodebr recebeu os campos já separados. Na prática, quem usa o geocodebr precisa separar o endereço antes, e o Candeia recebe o texto livre: aqui o geocodebr teve essa ajuda.
+- Não foram medidos tempo, memória nem tamanho de download.
+
+## Roadmap
+
+- [x] Núcleo de normalização e matching em JavaScript, portado do geocodificador do NEXO, com testes de regressão
+- [x] Pipeline de dados (CNEFE → Parquet por município → índice) com manifesto e hash
+- [x] Medição de tamanho por município e escolha do formato de distribuição
+- [x] Suporte a quadra e lote, incluindo o endereço estruturado do DF
+- [x] Interpolação para número de porta inexistente
+- [x] Benchmark sintético e calibração de confiança por cor e raio
+- [x] Índice publicado e loader sob demanda
+- [x] Benchmark de regressão no CI
+- [ ] Validação com pontos conferidos em campo
+- [x] Calibração de confiança por UF: medida e descartada, piora fora da amostra (ver abaixo)
+- [x] Comparação com o geocodebr nos mesmos endereços (ver [Relação com outros projetos](#relação-com-outros-projetos))
+- [x] Pacote no npm
+- [x] Guia de contribuição com casos de teste por UF ([CONTRIBUTING.md](CONTRIBUTING.md))
+
+## Desenvolvimento
+
+```sh
+npm test             # Node >= 22, sem dependências
+node bench/ci.mjs    # benchmark de regressão sobre o índice publicado (~12 MB, ~25 s)
+```
+
+## Contribuindo
+
+A ideia é que contribuir seja barato: o jeito de escrever endereço de cada UF fica em casos de teste legíveis (`test/casos/<UF>.json`, "entrada, resultado esperado"), sem precisar saber JavaScript. Ver [CONTRIBUTING.md](CONTRIBUTING.md). O CI roda um benchmark de regressão em todo pull request e falha se a acurácia cair mais de 1 ponto em qualquer grupo (`bench/ci.mjs`). Mudança intencional atualiza a referência com `node bench/ci.mjs --atualizar`.
+
+## Origem
+
+O motor parte do geocodificador do NEXO, ferramenta de gestão de operações de campo do mesmo autor, hoje restrito a GO. O Candeia o generaliza para as 27 UFs e o separa como biblioteca independente.
+
+## Nome
+
+Candeia é a lamparina de óleo. Na parábola da moeda perdida, a mulher acende a candeia e varre a casa até achar. É isso que o motor faz: procura com a luz que tem e diz até onde conseguiu enxergar.
+
+## Licença
+
+Código: [MIT](LICENSE). Índice de dados: [CC BY 4.0](DADOS.md), derivado do CNEFE 2022 do IBGE, com atribuição obrigatória ao IBGE em redistribuições.

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "candeia",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "Geocodificação de endereços brasileiros a partir do CNEFE (IBGE), sem servidor e sem chave de API.",
+  "keywords": ["geocodificacao", "geocoding", "endereco", "cnefe", "ibge", "brasil", "quadra", "lote"],
+  "type": "module",
+  "exports": "./src/index.js",
+  "files": ["src/", "DADOS.md"],
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "repository": { "type": "git", "url": "git+https://github.com/LucasRikelmi/candeia.git" },
+  "homepage": "https://github.com/LucasRikelmi/candeia#readme",
+  "bugs": "https://github.com/LucasRikelmi/candeia/issues",
+  "author": "Lucas Rikelmi",
+  "license": "MIT",
+  "publishConfig": { "access": "public", "provenance": true }
+}

package/src/calibracao.js

@@ -0,0 +1,18 @@
+// Candeia — probabilidade de acerto por cor e faixa de raio, medida no benchmark
+// (bench/calibrar.mjs gera calibracao_tabela.js). É a calibração do gabarito sintético: o CNEFE
+// contra ele mesmo, com ruído de digitação simulado. Não substitui validação de campo.
+import { CALIBRACAO } from "./calibracao_tabela.js";
+
+export const FAIXAS_RAIO = [0, 50, 100, 250, 500, 1000];
+
+export function faixaRaio(raio) {
+  if (raio == null) return "?";
+  for (const t of FAIXAS_RAIO) if (raio <= t) return `<=${t}`;
+  return ">1000";
+}
+
+// { ate100m, acima1km, amostra } ou null quando a cor não tem célula medida.
+export function confiancaDe(status, raio) {
+  const c = CALIBRACAO[`${status}|${faixaRaio(raio)}`] || CALIBRACAO[status];
+  return c ? { ate100m: c[0], acima1km: c[1], amostra: c[2] } : null;
+}

package/src/calibracao_tabela.js

@@ -0,0 +1,5 @@
+// GERADO por bench/calibrar.mjs — não editar à mão.
+// Fonte: benchmark sintético (119888 respostas, 132 municípios, gabarito = CNEFE 2022).
+// chave "cor|faixa de raio" (ou só "cor") → [P(erro <= 100 m), P(erro > 1 km), n]
+export const CALIBRACAO = { "amarelo": [ 0.598, 0.015, 36994 ], "amarelo|<=0": [ 0.959, 0.019, 537 ], "amarelo|<=100": [ 0.855, 0.011, 5197 ], "amarelo|<=1000": [ 0.392, 0.018, 1139 ], "amarelo|<=250": [ 0.494, 0.013, 12844 ], "amarelo|<=50": [ 0.944, 0.012, 8610 ], "amarelo|<=500": [ 0.262, 0.021, 8667 ], "azul": [ 0.857, 0.024, 509 ], "laranja": [ 0.245, 0.399, 24326 ], "laranja|<=100": [ 0.835, 0.076, 369 ], "laranja|<=1000": [ 0.124, 0.115, 4928 ], "laranja|<=250": [ 0.446, 0.034, 523 ], "laranja|<=50": [ 0.885, 0.077, 312 ], "laranja|<=500": [ 0.211, 0.182, 592 ], "laranja|>1000": [ 0.201, 0.552, 15775 ], "laranja|?": [ 0.66, 0.157, 1651 ], "verde": [ 0.99, 0.004, 57529 ], "verde|<=0": [ 0.988, 0.005, 40244 ], "verde|<=100": [ 0.984, 0.001, 1800 ], "verde|<=50": [ 0.995, 0.002, 15485 ], "vermelho": [ 0, 0.911, 530 ], "vermelho|?": [ 0, 0.911, 530 ] };
+export const CALIBRACAO_VALIDACAO = {"dobra_0":{"cor_e_raio":{"erro_calib_100m":1.32,"erro_calib_1km":0.79,"brier_100m":0.0876,"brier_1km":0.0445},"so_cor":{"erro_calib_100m":1.46,"erro_calib_1km":0.55,"brier_100m":0.1134,"brier_1km":0.0524}},"dobra_1":{"cor_e_raio":{"erro_calib_100m":1.58,"erro_calib_1km":1.02,"brier_100m":0.0958,"brier_1km":0.0508},"so_cor":{"erro_calib_100m":1.5,"erro_calib_1km":0.61,"brier_100m":0.1216,"brier_1km":0.0587}}};

package/src/cnefe.js

@@ -0,0 +1,100 @@
+// Portado do geo_core.js V2.2 do NEXO, sem mudança de comportamento.
+import { normalizeBase, normNum, extensoParaNumeral } from "./normalizar.js";
+
+// ----------------------------------------------------------------------
+// 3) EXTRAÇÃO DE ENTIDADES — LADO ETL (linha bruta do CNEFE)
+//    Recebe um objeto com as colunas reais do CNEFE.
+//
+//    NV_GEO_COORD semântica oficial:
+//      1 = coordenada original da base pública (porta exata)
+//      2 = modificada (aptos empilhados no mesmo número)
+//      3 = estimada (sem coord original ou coord inválida)
+//      4 = face de quadra (~dezenas de metros)
+//      5 = centróide de localidade   → NÃO indexar
+//      6 = centróide de setor de coleta → NÃO indexar
+// ----------------------------------------------------------------------
+
+// #13 — Parser robusto para o bug de duplo ponto nas coordenadas do CNEFE.
+// Exemplos: "-16.113.125" → -16.113125; "-47.948.869" → -47.948869.
+// 4+ pontos = dado irreparável → NaN (será filtrado por isNaN).
+export function parseCnefeLonLat(raw) {
+  const s = String(raw || "").trim().replace(",", ".");
+  const pts = s.split(".");
+  if (pts.length === 1) return parseFloat(s);
+  if (pts.length === 2) return parseFloat(s);
+  if (pts.length === 3) return parseFloat(pts[0] + "." + pts[1] + pts[2]);
+  return NaN; // 4+ pontos: dado inválido
+}
+
+// Extrai quadra e lote dos pares NOM_COMP_ELEMx / VAL_COMP_ELEMx (1–5).
+// ATENÇÃO: NUM_QUADRA do CNEFE é a quadra do SETOR DE COLETA, não do endereço.
+export function extrairCompCnefe(row) {
+  let quadra = null, lote = null;
+  for (let i = 1; i <= 5; i++) {
+    const nome = String(row[`NOM_COMP_ELEM${i}`] || "").toUpperCase().trim();
+    const val  = String(row[`VAL_COMP_ELEM${i}`] || "").trim();
+    if (nome === "QUADRA" && quadra == null) quadra = normNum(val);
+    if (nome === "LOTE"   && lote   == null) lote   = normNum(val);
+  }
+  return { quadra, lote };
+}
+
+// Constrói uma entrada de índice a partir de uma linha do CNEFE.
+// Retorna null se a linha não deve ser indexada.
+export function entradaDeLinhaCnefe(row) {
+  const g = parseInt(row.NV_GEO_COORD, 10);
+
+  // #3 — Descarta centróides de localidade (g=5) e setor de coleta (g=6).
+  // Esses pontos ficam longe do endereço real e causam o sintoma "pino distante".
+  // g=3 (estimada) e g=4 (face de quadra) são mantidos mas com clamp de cor em geocodificar.
+  if (g >= 5) return null;
+
+  const lat = parseCnefeLonLat(row.LATITUDE);
+  const lon = parseCnefeLonLat(row.LONGITUDE);
+  if (isNaN(lat) || isNaN(lon)) return null;
+
+  // Nome da via: extenso → numeral + normalização
+  const viaRaw = normalizeBase(
+    [row.NOM_TITULO_SEGLOGR, row.NOM_SEGLOGR].filter(Boolean).join(" "),
+  );
+  const via = extensoParaNumeral(viaRaw).replace(/\s+/g, " ").trim();
+  if (!via) return null;
+
+  const tipo = normalizeBase(row.NOM_TIPO_SEGLOGR || "");
+
+  const numBruto    = String(row.NUM_ENDERECO || "").trim();
+  const modificador = String(row.DSC_MODIFICADOR || "").toUpperCase().trim();
+  const numero =
+    modificador === "SN" || numBruto === "0" || !numBruto ? null : normNum(numBruto);
+
+  const { quadra, lote } = extrairCompCnefe(row);
+
+  return {
+    codMunicipio: String(row.COD_MUNICIPIO || "").trim(),
+    via,
+    entry: {
+      tp: tipo,
+      n:  numero,
+      q:  quadra,
+      l:  lote,
+      b:  normalizeBase(row.DSC_LOCALIDADE || ""),
+      c:  String(row.CEP || "").replace(/\D/g, ""),
+      la: lat,
+      lo: lon,
+      g,  // NV_GEO_COORD 1–4 (5/6 descartados acima)
+    },
+  };
+}
+
+// Constrói o índice completo a partir de um array de linhas do CNEFE.
+// Filtre COD_UF=52 e COD_MUNICIPIO (jurisdição) antes de chamar.
+export function construirIndiceCnefe(linhasCnefe) {
+  const idx = {};
+  for (const row of linhasCnefe) {
+    const r = entradaDeLinhaCnefe(row);
+    if (!r || !r.via) continue;
+    idx[r.codMunicipio] ??= {};
+    (idx[r.codMunicipio][r.via] ??= []).push(r.entry);
+  }
+  return idx;
+}

package/src/extrair.js

@@ -0,0 +1,254 @@
+// Portado do geo_core.js V2.2 do NEXO; mudanças do Candeia marcadas com "Candeia".
+import { normalizeBase, normNum, ABREV, normalizarPrefixoRodovia, TIPOS_VIA, ehCodigoRodovia, RUIDO_COMPLEMENTO, RE_COMPL_GLUED, _RE_COM_CRUZAMENTO, extensoParaNumeral } from "./normalizar.js";
+
+// ----------------------------------------------------------------------
+// 2) EXTRAÇÃO DE ENTIDADES — LADO RUNTIME (endereço digitado, "sujo")
+// ----------------------------------------------------------------------
+
+// #14 — Regexes de quadra/lote: prefixo de 1 letra (q/l) exige \s+
+// para evitar falso-positivo. Ex.: "nivel5" não é lote 5.
+// Versões com grupo de captura (extração) e sem (limpeza).
+export const _RE_QUADRA_EXT   = /\b(?:quadra\s*|qd\s*|q\s+)0*([0-9]+[a-z]?)\b/g;
+export const _RE_LOTE_EXT     = /\b(?:lote\s*|lt\s*|l\s+)0*([0-9]+[a-z]?(?:-[0-9]+)?)\b/g;
+export const _RE_QUADRA_CLEAN = /\b(?:quadra\s*|qd\s*|q\s+)0*[0-9]+[a-z]?\b/g;
+export const _RE_LOTE_CLEAN   = /\b(?:lote\s*|lt\s*|l\s+)0*[0-9]+[a-z]?(?:-[0-9]+)?\b/g;
+// Km também precisa sair do bloco antes da tokenização da via — sem isso,
+// "GO-222 KM 5,5" (onde a vírgula DECIMAL confunde a detecção da 1ª vírgula
+// do endereço, truncando a base ali) deixava "km 5" vazar para dentro do
+// nome da via extraído (ex.: via="go 222 km 5" em vez de "go 222").
+// Cobre "km 5", "km 5,5", o caso já truncado "km 5" (vírgula virou espaço)
+// e "km-5"/"km -5" (hífen entre "km" e o número, ex.: "RODOVIA GO-040 KM-28").
+export const _RE_KM_CLEAN = /\bkm\.?[\s-]*[0-9]+(?:[.,\s][0-9]+)?\b/gi;
+
+// Helper interno: extrai via normalizada de um bloco de texto já normalizado.
+export function _extrairViaDeBloco(bloco) {
+  let b = bloco
+    .replace(_RE_QUADRA_CLEAN, " ")
+    .replace(_RE_LOTE_CLEAN, " ")
+    .replace(_RE_KM_CLEAN, " ")
+    .replace(/\bs\s*\/?\s*n\b/g, " ")
+    .replace(/\bsem numero\b/g, " ");
+  _RE_QUADRA_CLEAN.lastIndex = 0;
+  _RE_LOTE_CLEAN.lastIndex  = 0;
+  _RE_KM_CLEAN.lastIndex    = 0;
+  let tokens = b.split(/\s+/).filter(Boolean);
+  tokens = tokens.filter((tok, i) => tok !== tokens[i - 1]);
+  let tipo = null;
+  if (tokens.length && (TIPOS_VIA.has(tokens[0]) || ehCodigoRodovia(tokens, 0))) {
+    tipo = tokens[0];
+    tokens = tokens.slice(1);
+  }
+  return { tipo, tokens };
+}
+
+// #19 — O campo bairro às vezes vem preenchido com quadra/lote em vez de nome de
+// bairro de verdade (ex.: "QD 10 LT 05 SALA 2"). Comparar isso com um bairro de verdade
+// nunca vai bater — mas o valor não é lixo, é quadra/lote que foi digitado
+// no campo errado. geocodificar() reaproveita como sinal de desempate
+// quando o próprio endereço não trouxe essa informação (ver uso).
+export function _extrairQLDeBairro(bairroNorm) {
+  let quadra = null, lote = null;
+  bairroNorm.replace(_RE_QUADRA_EXT, (_, n) => { if (quadra == null) quadra = normNum(n); });
+  _RE_QUADRA_EXT.lastIndex = 0;
+  bairroNorm.replace(_RE_LOTE_EXT, (_, n) => { if (lote == null) lote = normNum(n); });
+  _RE_LOTE_EXT.lastIndex = 0;
+  return { quadra, lote };
+}
+
+// Captura {tipo, via, quadra, lote, numero, km} de uma string de endereço livre.
+export function extrairEntidades(enderecoCru) {
+  const cru = String(enderecoCru || "");
+
+  // 1) Número da porta — posição canônica: primeiro token após a 1ª vírgula
+  let numero = null;
+  const idxVirg = cru.indexOf(",");
+  if (idxVirg >= 0) {
+    const pos = cru.slice(idxVirg + 1).trim().split(/[\s,]+/)[0] || "";
+    if (/^\d{1,5}$/.test(pos)) numero = pos.replace(/^0+/, "") || "0";
+  }
+
+  // 1b) Km — endereço rural sem numeração urbana (ex.: "BR 153, KM 540, s/n",
+  // "RODOVIA GO-222 KM 5,5"). Extraído do texto CRU (antes de normalizeBase,
+  // que substituiria a vírgula decimal de "5,5" por espaço e destruiria o
+  // valor). Convenção observada no CNEFE para rodovias: o Km costuma ser
+  // gravado no próprio campo de número de porta — por isso vira fallback de
+  // `numero` logo abaixo, reaproveitando o desempate por número (peso 5 em
+  // geocodificar()) sem precisar de um critério novo no motor de pontuação.
+  let km = null;
+  const mKm = cru.match(/\bkm\.?[\s-]*(\d+(?:[.,]\d+)?)/i);
+  if (mKm) km = mKm[1].replace(",", ".");
+
+  // 2) Base = parte pré-vírgula (ou string inteira se não houver vírgula)
+  let base = normalizeBase(idxVirg >= 0 ? cru.slice(0, idxVirg) : cru);
+  for (const [re, rep] of ABREV) base = base.replace(re, rep);
+  base = normalizarPrefixoRodovia(base);
+  // #16 — Guarda o bloco do cruzamento (ao invés de só descartar) para servir
+  // de via alternativa em geocodificar() quando a via principal não bate em
+  // nada no índice — ver extração de viaCruzamento mais abaixo. "c/" não
+  // exige espaço depois (é comum "C/RUA X" colado, sem
+  // espaço após a barra) — "esq"/"esquina" continuam exigindo os dois
+  // lados por extenso, pra não colidir com outra palavra no meio do nome.
+  let partesCruzamento = base.split(/\s+(?:c\/\s*|esq\s+|esquina\s+)/);
+  // Candeia — "Estrada Esquina Borges" (RS): "esquina" logo depois do tipo é parte do nome
+  // (localidade), não marcador de cruzamento. Sem via antes do marcador, não há cruzamento.
+  const antes = partesCruzamento[0].trim().split(/\s+/).filter(Boolean);
+  if (partesCruzamento.length > 1 && antes.length <= 1 && (!antes.length || TIPOS_VIA.has(antes[0]))) {
+    partesCruzamento = [base];
+  }
+  base = partesCruzamento[0];
+  let blocoCruzamento = partesCruzamento[1] || null;
+
+  // "com" bruto, sem "esq"/"esquina"/"c/" — só entra se o lado direito
+  // começar com um tipo de via reconhecido (ver _RE_COM_CRUZAMENTO acima).
+  if (!blocoCruzamento) {
+    const mCom = base.match(_RE_COM_CRUZAMENTO);
+    if (mCom) {
+      base = mCom[1];
+      blocoCruzamento = mCom[2];
+    }
+  }
+
+  if (blocoCruzamento) {
+    // Sobra de "esquina COM rua X" / "esq C rua X" (duplo marcador) — sem
+    // isso "com"/"c" ficava na frente do bloco e o tipo da via ("rua"/
+    // "avenida"...) nunca era reconhecido por só olhar o 1º token, vazando
+    // pro nome extraído (ex.: viaCruzamento="rua 07" em vez de "07", que
+    // não bate com a chave limpa do CNEFE).
+    const RUIDO_CRUZAMENTO = new Set(["com", "c/", "c", "esq", "esquina"]);
+    let tokensCruz = blocoCruzamento.split(/\s+/).filter(Boolean);
+    while (tokensCruz.length > 1 && RUIDO_CRUZAMENTO.has(tokensCruz[0])) {
+      tokensCruz = tokensCruz.slice(1);
+    }
+    blocoCruzamento = tokensCruz.join(" ");
+  }
+
+  // 3) Quadra e lote — de qualquer ponto da string
+  let full = normalizeBase(cru);
+  for (const [re, rep] of ABREV) full = full.replace(re, rep);
+  full = normalizarPrefixoRodovia(full);
+
+  let quadra = null;
+  full.replace(_RE_QUADRA_EXT, (_, n) => { if (quadra == null) quadra = normNum(n); });
+  _RE_QUADRA_EXT.lastIndex = 0;
+  let lote = null;
+  full.replace(_RE_LOTE_EXT, (_, n) => { if (lote == null) lote = normNum(n); });
+  _RE_LOTE_EXT.lastIndex = 0;
+
+  // #8 — Fallback: "N°10", "N 10", "Nº 10" sem vírgula (forma explícita de número)
+  if (numero == null) {
+    const mN = full.match(/\bn[°o.]?\s*(\d{1,5})\b/);
+    if (mN) {
+      numero = mN[1].replace(/^0+/, "") || "0";
+      // Candeia — tira o "nº 500" do nome da via ("Av. Getulio Vargas nº 500" → via "getulio vargas").
+      // Só com o símbolo º/° escrito: "Avenida N2", "Rua N 113" e "Rua No 7" são nomes de via reais.
+      if (/\bn\s*[º°]\s*\d/i.test(cru)) {
+        const semN = base.replace(/\s+n\s*\d{1,5}\b.*$/, "");
+        const resto = semN.trim().split(/\s+/).filter((t) => !TIPOS_VIA.has(t));
+        if (semN !== base && resto.length) base = semN;
+      }
+    }
+  }
+
+  // Km como fallback de número — só quando não havia número real, nunca
+  // sobrescreve endereço urbano legítimo (ex.: "Rua X, 45" mantém 45).
+  if (numero == null && km != null) {
+    const kmInt = Math.round(parseFloat(km));
+    if (!isNaN(kmInt)) numero = String(kmInt);
+  }
+
+  // 4) Extrai tokens da via a partir da base pré-vírgula
+  let { tipo, tokens } = _extrairViaDeBloco(base);
+
+  // #15 — Fallback: endereço com Q/L antes da vírgula ("QUADRA 5 LOTE 3, RUA 8").
+  // Se a base ficou vazia após limpeza, tenta a parte pós-vírgula como via.
+  if (!tokens.length && idxVirg >= 0) {
+    let altBase = normalizeBase(cru.slice(idxVirg + 1));
+    for (const [re, rep] of ABREV) altBase = altBase.replace(re, rep);
+    altBase = normalizarPrefixoRodovia(altBase);
+    const alt = _extrairViaDeBloco(altBase);
+    if (alt.tokens.length) { tipo = alt.tipo; tokens = alt.tokens; }
+  }
+
+  // Candeia — "esquina" logo depois do tipo é localidade ("Estrada Esquina Borges"), não ruído.
+  const nomeComEsquina = tipo != null && tokens[0] === "esquina";
+  const via0 = tokens
+    .filter((tok) => (nomeComEsquina && tok === "esquina") || (!RUIDO_COMPLEMENTO.has(tok) && !RE_COMPL_GLUED.test(tok)))
+    .join(" ")
+    .trim();
+  const via = extensoParaNumeral(via0);
+
+  // #16 — Via do cruzamento ("Rua X esq Rua Y" → viaCruzamento = "rua y"),
+  // mesmo tratamento (tipo fora, ruído fora, extenso→numeral) da via
+  // principal. null quando o endereço não menciona cruzamento.
+  let viaCruzamento = null;
+  if (blocoCruzamento) {
+    const alt = _extrairViaDeBloco(blocoCruzamento);
+    const viaCruzamento0 = alt.tokens
+      .filter((tok) => !RUIDO_COMPLEMENTO.has(tok) && !RE_COMPL_GLUED.test(tok))
+      .join(" ")
+      .trim();
+    if (viaCruzamento0) viaCruzamento = extensoParaNumeral(viaCruzamento0);
+  }
+
+  // Candeia — número de porta sem vírgula ("Rua Goias 125"). Ambíguo com via que termina em
+  // número ("Avenida T 63", "Rua 15"), então aqui só se propõe a alternativa; geocodificar()
+  // fica com ela apenas se a via sem o número casar melhor no índice.
+  let viaSemNumero = null, numeroSemVirgula = null;
+  if (numero == null && km == null) {
+    const tv = via.split(" ");
+    if (tv.length >= 2 && /^\d{1,5}[a-z]?$/.test(tv[tv.length - 1])) {
+      viaSemNumero = tv.slice(0, -1).join(" ");
+      numeroSemVirgula = normNum(tv[tv.length - 1]);
+    }
+  }
+
+  // Candeia — via "estruturada" (DF, condomínios, conjuntos habitacionais): o CNEFE grava a
+  // quadra/conjunto/bloco no próprio nome do logradouro ("QNN 25 CONJUNTO B", "SQS 308 BLOCO C",
+  // "QUADRA 37"), que a extração acima desmonta (quadra vira campo, bloco vira ruído). Aqui se
+  // propõe a via com essas peças preservadas; geocodificar() só a usa se ela casar exato.
+  const { via: viaEstruturada, lote: loteCasa } = _viaEstruturada(base);
+  if (lote == null && loteCasa != null) lote = loteCasa;
+
+  return { tipo, via, viaCruzamento, quadra, lote, numero, km, viaSemNumero, numeroSemVirgula,
+    viaEstruturada: viaEstruturada && viaEstruturada !== via ? viaEstruturada : null };
+}
+
+const _ABREV_ESTRUTURA = [
+  [/\b(?:conj|cj)\b/g, "conjunto"],
+  [/\b(?:bl|blc)\b/g, "bloco"],
+  [/\b(?:qd|qda)\b/g, "quadra"],
+  [/\b(?:chac|ch)\b/g, "chacara"],
+  [/\bae\b/g, "area especial"],
+  [/\bcond\b/g, "condominio"],
+];
+// Complementos que não fazem parte do logradouro: unidade dentro do lote ou do prédio.
+const _RE_UNIDADE = /\b(?:ap|apto|apartamento|sala|sl|loja|lj|andar|cobertura|kitnet|box)\s*[0-9]+[a-z]?\b/g;
+// Tipos que fazem parte da chave estruturada ("quadra 37", "conjunto 5"); os outros saem do início.
+const _TIPO_ESTRUTURA = new Set(["conjunto", "quadra", "chacara", "setor", "area", "modulo"]);
+// Só propõe a via estruturada quando ela tem peça de estrutura seguida de identificador.
+const _RE_ESTRUTURA = /\b(?:quadra|conjunto|bloco|chacara|area especial|q[a-z]{1,3})\s+[0-9a-z]+\b/;
+
+export function _viaEstruturada(base) {
+  let b = base;
+  for (const [re, rep] of _ABREV_ESTRUTURA) b = b.replace(re, rep);
+  // "casa N" no DF e em conjuntos é o lote; só vira lote quando o endereço não trouxe um.
+  let lote = null;
+  const mCasa = b.match(/\b(?:casa|cs)\s*0*([0-9]+[a-z]?)\b/);
+  if (mCasa) lote = normNum(mCasa[1]);
+  b = b
+    .replace(/\b(?:casa|cs)\s*[0-9]+[a-z]?\b/g, " ")
+    .replace(_RE_UNIDADE, " ")
+    .replace(_RE_LOTE_CLEAN, " ")
+    .replace(_RE_KM_CLEAN, " ")
+    .replace(/\bs\s*\/?\s*n\b/g, " ")
+    .replace(/\bsem numero\b/g, " ");
+  _RE_LOTE_CLEAN.lastIndex = 0;
+  _RE_KM_CLEAN.lastIndex = 0;
+  let tokens = b.split(/\s+/).filter(Boolean);
+  // "EDF" (tipo dos logradouros do DF no CNEFE) e tipos genéricos no início não entram na chave.
+  while (tokens.length > 1 && (tokens[0] === "edf" || (TIPOS_VIA.has(tokens[0]) && !_TIPO_ESTRUTURA.has(tokens[0])))) {
+    tokens = tokens.slice(1);
+  }
+  const v = extensoParaNumeral(tokens.join(" ").trim());
+  return { via: _RE_ESTRUTURA.test(v) ? v : null, lote };
+}