0009 — Espelho fiel: identidade nativa, origem externa prefixada

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-15 · Decidido em: 2026-07-15

Contexto

Um incidente (loop §6, feedback de um repo de app) revelou uma brecha no padrão da casa: a integração PIED (shape 3 — vertical que grava o estado-desejado, §8) promoveu chaves do vocabulário do parceiro (codigo_alt, x_ped) a identidade de 1ª classe na tabela-espelho do X-Adm. A §Fronteiras já normatizava o prefixo de tabela (<dominio>_, <app>_ = de quem é o dado), mas nada regia a identidade de coluna dentro da tabela-espelho — então "cópia fiel do X-Adm" não tinha guarda no nível onde o desvio acontece.

O risco não é cosmético: uma vez que um join ou uma chave de negócio passa a depender de x_ped, o espelho fica acoplado ao vocabulário de um terceiro — quando o parceiro muda o campo, ou uma segunda fonte entra com outro nome, o modelo do X-Adm quebra ou diverge por fonte.

Decisão

A tabela-espelho modela a entidade do X-Adm, não a do parceiro. A fidelidade é por coluna:

• Identidade em coluna nativa. Chave de negócio e critério de join vivem sempre em coluna nativa do X-Adm, conferida contra a spec de entidades do ERP — não se inventa identidade a partir do que a fonte externa mandou.
• Origem externa prefixada, só rastreabilidade. Campo que só existe no vocabulário da fonte entra prefixado pela origem (<origem>_<campo>, ex. pied_x_ped) e serve só como transporte/rastreabilidade — o consumidor o lê para auditar, nunca para casar registros. A coluna sincroniza como o resto da tabela (a tabela é sem prefixo), mas não é chave nem join.

A norma entra como piso na constituição §8 (ao lado de owner-writes), com o detalhe operável e a tabela de coluna na §Fronteiras e o eco server-side em Java/Micronaut §Banco.

Alternativas consideradas

• Deixar como convenção do vertical PIED (só no repo do app): o desvio se repete em cada novo shape-3/parceiro. Preterido: é invariante cross-cutting do espelho, não detalhe de um cliente.
• Manter o exemplo pied_* literal na norma: deixaria a próxima integração reinventar o prefixo. Preterido em favor da convenção genérica <origem>_, consistente com os prefixos de tabela (<dominio>_/<app>_) já existentes.

Consequências

• Próxima coluna nova no espelho tem regra clara: identidade → nativa (contra a spec de entidades); campo do parceiro → <origem>_, rastreabilidade.
• Adoção oportunista (§1.6): o espelho PIED existente migra a chave para coluna nativa quando o repo do app tocar o schema; a coluna do parceiro permanece como <origem>_ de auditoria.
• Sem guarda de gate offline (diferente da 0008): a fidelidade depende da spec de entidades do ERP, que o central não conhece — o enforcement é revisão de PR no repo do vertical, não o valida-frontmatter.