feat: Reference Data Registry (Fase 1) + P1 NCM validated + feasibility studies (Fase 5)

Missão 5:

Fase 1 (Reference Data Registry): migration 0034 adds licence_terms, valid_from/
valid_to, file_size_bytes, raw_file_path, parse_errors, submitted_by/approved_by/
approved_at to the existing `datasets` table (additive only - the 9 pre-existing
dataset kinds keep their current auto-activate behavior in
central/app/datasets/service.py, completely untouched, so this changes nothing
about the currently-running engine). New central/app/reference_registry.py is a
separate, NEW ingestion workflow: register_draft() always lands as DRAFT (never
auto-activates), diff_against_vigente() summarizes a draft against the current
VIGENTE of the same kind for admin review, approve_draft()/reject_draft() are
the only way to promote a DRAFT (refuses non-DRAFT rows and refuses a draft
with recorded parse_errors). New admin screen "Tabelas oficiais"
(/admin/reference-datasets, ADMIN only, CSRF, every decision audited as
REFERENCE_DATASET_APPROVE/REJECT) lists the registry with a diff view and
approve/reject buttons. New CLI (scripts/ingest_reference_dataset.py) downloads
an official source (currently: NCM/Siscomex, no login/captcha), validates
(minimum row count, a known-sample spot check), and registers a DRAFT - --dry-run
never writes anything.

P1 (NCM) validated for real: downloaded the live official Siscomex NCM JSON
(2026-09-28, sha256 8a3bf89a..., 15,156 entries) with an identifiable User-Agent,
one request. Its hash is IDENTICAL to the NCM dataset already ACTIVE in the Hub -
confirms the currently loaded table is already current against the official
source today. Raw file kept out of git (.gitignore:
sources/raw/reference_registry/); manifest (URL, date, hash, size) recorded in
docs/REFERENCE_DATASET_MANIFEST_V1.md, including P2-P6 sources still pending URL
confirmation.

Fase 5 (feasibility studies, no code): docs/VIABILIDADE_CCG_DFE_V1.md - CCG/SEFAZ
GTIN lookup and Distribuição DF-e both require the client's own ICP-Brasil
certificate; recommendation is NOT to implement now (would require either the
Hub holding a client certificate - breaks the project's core security model - or
the Agent making new outbound internet calls, against this mission's fixed
rules). Reading the already-authorized purchase-NFe XML from disk via the Agent
(path already stored in XML_MES) is recommended as the next concrete step
instead: no certificate, no new internet call, opt-in per installation, result
always tagged DECLARADO (never auto-promoted - consensus across purchase
invoices is not fiscal truth). Open Food Facts stays identity-only, unchanged.

21 new tests, all passing. Full suite: 1147 passed, 1 skipped.

No write to any Firebird database anywhere. No Agent code touched.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/REFERENCE_DATASET_MANIFEST_V1.md

@@ -0,0 +1,30 @@
+# Manifesto de datasets oficiais baixados — Missão 5
+
+Arquivos brutos não vão para o git (`.gitignore`: `sources/raw/reference_registry/`). Este
+manifesto registra o que foi baixado, de onde, quando e com qual hash — suficiente para
+reproduzir o download e conferir integridade, sem guardar o arquivo em si no repositório.
+
+| Dataset | Fonte oficial | URL | Data | SHA-256 | Tamanho | Linhas | Observação |
+|---|---|---|---|---|---|---|---|
+| P1 — NCM vigente | Siscomex (Governo Federal, sem login/captcha) | `https://portalunico.siscomex.gov.br/classif/api/publico/nomenclatura/download/json` | 2026-09-28 | `8a3bf89a5b89fc3c3391b0a2c3a30cd261b17726a406dd481f39b37d4fb3b51e` | 3.149.367 bytes | 15.156 | **Hash idêntico** ao dataset NCM já ativo no Hub — confirma que a tabela já carregada está em dia com a fonte oficial hoje. Registrado no Reference Data Registry (`datasets.id=52` no Hub de desenvolvimento local), reconhecido como já existente (nenhum DRAFT novo foi necessário). |
+
+## Próximos datasets (P2–P6, Fase 2) — pendentes de confirmação de URL/formato antes de baixar
+
+Por prioridade da missão, ainda não confirmados/baixados nesta passada:
+
+- **P2** Domínios da NF-e (CFOP, CST ICMS, CSOSN, CST PIS/COFINS, CST IPI, unidades) — já parcialmente
+  cobertos por `sources/raw/bootstrap_v1/` (CFOP, tabelas MOC) em missões anteriores; confirmar se
+  há uma fonte oficial atualizável programaticamente (Portal Único / SPED) versus os arquivos
+  operator-supplied já carregados.
+- **P3** TIPI — já carregada (`sources/raw/bootstrap_v1/1 TIPI 2022...xlsx`, ACTIVE); confirmar se
+  existe endpoint oficial para verificar vigência sem depender de upload manual.
+- **P4** CEST × NCM (Confaz) — já carregada via bootstrap; buscar fonte Confaz oficial navegável
+  por API/CSV para atualização automática futura.
+- **P5** EFD-Contribuições (SPED) — parcialmente coberta (`SPED_PISCOFINS_TABLES_V3.json` já usado
+  pelo motor); confirmar quais das tabelas 4.3.10–4.3.17 têm fonte oficial baixável hoje.
+- **P6** ICMS-ST BA — já parcialmente coberta (`decreto_2012_13780_ricms_anexo_1...pdf`, PDF, parser
+  determinístico ainda não fechado — ver `docs/DUPLICATE_KEY_MMMODAS_V1.md`/histórico do projeto).
+
+Cada um exige confirmação individual de URL/formato/vigência antes de qualquer download, conforme
+a regra fixa desta missão — não foi feito nesta passada por prudência de tempo, não por
+impossibilidade técnica.

docs/VIABILIDADE_CCG_DFE_V1.md

@@ -0,0 +1,85 @@
+# Estudos de viabilidade (Missão 5, Fase 5) — decisão recomendada, sem código
+
+## 5.1 — CCG/SEFAZ (consulta de GTIN com certificado) e Distribuição DF-e (XML de compras)
+
+### O que cada serviço exige
+
+- **CCG (Consulta Cadastro de Contribuintes)/consulta de GTIN via SEFAZ**: exige certificado
+  digital ICP-Brasil **do cliente** (e-CNPJ ou e-CPF do contador/contribuinte) para autenticar a
+  chamada ao webservice estadual/nacional. Não existe uma chave "genérica" do GTI para isso — cada
+  cliente autenticaria com o certificado dele.
+- **Distribuição DF-e** (`NFeDistribuicaoDFe`): mesmo requisito de certificado ICP-Brasil do
+  destinatário (o CNPJ que recebeu a nota), usado para baixar XMLs de compra que o Fisco já sabe
+  que aquele CNPJ recebeu — não depende do fornecedor ter enviado nada manualmente.
+
+### Risco de segurança da chave privada
+
+O desenho atual do projeto é deliberado e documentado (`docs/rtc_auto_apply.md`): **o Hub nunca
+tem acesso a nada local do cliente** (sem chave, sem certificado, sem execução remota). Um
+certificado ICP-Brasil é, na prática, mais sensível que uma senha — normalmente um arquivo `.pfx`
+protegido por senha, ou um token/smartcard físico. Usar isso a partir do Hub (nuvem, fora do
+controle do cliente) exigiria:
+- Ou o cliente **enviar o certificado para o Hub** (nunca deveria acontecer — quebra o modelo de
+  confiança do projeto inteiro, e um vazamento do Hub comprometeria a identidade fiscal de todos
+  os clientes que fizeram isso);
+- Ou o **Agent local** (que já roda na máquina do cliente) fazer a consulta usando o certificado
+  já instalado ali, e devolver ao Hub só o resultado relevante (NCM/GTIN do fornecedor, nunca o
+  XML completo nem o certificado). Isso é tecnicamente viável e é o único desenho que não quebra
+  "o Hub nunca acessa nada local do cliente" — mas ainda é uma consulta à internet **feita pelo
+  Agent**, o que hoje é proibido por regra fixa desta missão ("Só o Hub acessa a internet externa.
+  O Agent não recebe nenhuma chamada externa nova"). Ou seja: **incompatível com o desenho atual
+  sem uma decisão explícita de abrir uma exceção para o Agent**.
+
+### Opt-in por cliente
+
+Mesmo que se decida abrir essa exceção no futuro, o consentimento tem que ser **por instalação**,
+nunca automático — cada cliente tem que decidir explicitamente confiar sua chave/certificado a essa
+finalidade, com escopo claro (o que é consultado, quando, o que é armazenado).
+
+### Esforço estimado (ordem de grandeza, não um cronograma)
+
+- Alto: implica mexer no modelo de segurança do Agent (hoje só lê Firebird local e fala com o Hub),
+  criar um fluxo de configuração de certificado por cliente, tratar renovação/expiração de
+  certificado, e novo tipo de erro/retentativa (SEFAZ indisponível, certificado vencido, etc.).
+  Não é um parser a mais — é uma superfície de segurança nova.
+
+### Decisão recomendada
+
+**Não implementar agora.** O ganho (GTIN/NCM do fornecedor mais confiável) não justifica o
+aumento de superfície de risco e a mudança de desenho ("só o Hub acessa a internet") sem uma
+necessidade concreta e urgente de algum cliente. Reavaliar se/quando um cliente pedir
+explicitamente e aceitar o modelo "o Agent consulta, o Hub nunca vê o certificado".
+
+## 5.2 — XML de NF-e de compra já armazenado nos bancos (evidência declarada)
+
+Como já mapeado (`docs/PISCOFINS_TRANSMITTED_SOURCE_V1.md`), o SGV **não guarda o XML em si** no
+Firebird — só o caminho do arquivo no disco local (`XML_MES.CAMINHO_XML`). Isso muda o desenho
+possível:
+
+- **Viável, com opt-in por cliente**: o Agent (que já roda na máquina, já lê Firebird local) pode
+  ler o arquivo XML autorizado **do disco** (caminho já registrado no banco) — isso não é uma
+  chamada à internet, é leitura de arquivo local, compatível com "o Agent não recebe chamada
+  externa nova" desde que o Hub não peça isso via internet, só o Agent decida ler o que já está
+  no disco dele mesmo.
+- O Agent extrairia **apenas** NCM/CEST/EAN do fornecedor (campos declarados na nota de compra,
+  identificados como DECLARADO — nunca VERIFICADO), agregados, sem dado pessoal (nunca nome do
+  fornecedor, CNPJ, endereço, valores) — um novo "tier" de evidência na KB, mais forte que uma
+  simples observação de cadastro, mas ainda não uma fonte oficial de classificação fiscal:
+  **consenso entre notas de compra não é verdade fiscal** (o fornecedor pode errar o NCM tanto
+  quanto o cliente).
+- Esforço: médio — parser de XML de NF-e (schema já público/estável), sem certificado nem
+  internet nova; o risco real é performance (muitos arquivos por cliente) e tratamento de arquivo
+  ausente/corrompido (comum em bases antigas).
+
+### Decisão recomendada
+
+**Viável como próxima etapa concreta**, com opt-in explícito por instalação (o Agent só lê os XMLs
+se o cliente autorizar), e resultado tratado sempre como evidência DECLARADA (nunca promovida
+automaticamente a VERIFIED_KB). Recomendo priorizar isso sobre CCG/Distribuição DF-e — mesmo
+ganho de evidência, risco de segurança muito menor (sem certificado, sem chamada externa nova).
+
+## 5.3 — Open Food Facts
+
+Confirmado: continua útil **só como identidade de produto** (nome/marca/unidade a partir do GTIN),
+nunca como fonte de classificação fiscal (NCM/CEST/CST) — a base não tem esse dado e não deveria
+ser tratada como se tivesse. Nenhuma mudança de uso recomendada.