Contratos versionados: expand antes de contract

examples/contracts/document.schema.json é a versão 2 do contrato de documento. A versão 1, congelada em examples/contracts/document.schema.v1.json, não tem o campo idempotency_key; a versão 2 adiciona esse campo como opcional. Essa é a metade "expand" de uma migração expand/contract: qualquer registro v1 se torna um registro v2 válido apenas preenchendo idempotency_key: null, sem que nenhum produtor de dados v1 precise mudar primeiro. A função migrateDocumentV1toV2 em examples/src/migrations.mjs faz exatamente isso, e examples/compatibility.test.mjs prova três coisas com uma fixture v1 real (examples/fixtures/document-v1.json):

1. A fixture v1 ainda valida contra o schema v1 congelado - congelar o schema não significa apagá-lo.
2. A fixture v1, sem migração, não valida contra o schema v2 (o const de schema_version diverge) - não existe compatibilidade automática só por coincidência de campos.
3. Depois de migrateDocumentV1toV2, o mesmo documento valida contra v2, mantém tenant_id e source_checksum idênticos, e ganha idempotency_key: null sem perder nenhuma informação anterior.

A metade "contract" - remover a tolerância à v1, tornar idempotency_key obrigatório - deliberadamente não está implementada. Contrair antes que todo produtor emita v2 quebraria qualquer chamador que ainda não migrou. Isso fica registrado como trabalho futuro em examples/src/migrations.mjs e no ADR-004, não como pendência escondida.

O ponto pedagógico mais importante aqui é o que compatibility.test.mjs testa como falha esperada: um documento v2 com review_status: "closed" - um valor de enum novo, introduzido sem versionar o schema - é rejeitado pelo validador. Isso é o cenário descrito no prompt como "schema mutável sem migração": alguém ajusta um prompt de extração, ou um handler, para começar a emitir um status novo, sem tocar no contrato. Se o validador aceitasse silenciosamente, o sistema teria uma bifurcação de comportamento não documentada. Rejeitar é o comportamento correto; documentar por que é o trabalho deste capítulo.

As quatro falhas obrigatórias

1. Tenant controlado pela saída do modelo

Sintoma: um extrator (regra ou modelo) processa um documento e a proposta de campos inclui, entre outras coisas, um tenant_id - seja porque o texto mencionava outra organização, seja porque um tool call decidiu "esse documento parece ser da Globex". Se o sistema usa esse campo para decidir onde gravar ou quem pode ver o resultado, a autorização virou uma opinião do modelo.

Causa: confundir "o modelo pode descrever algo sobre tenant" com "o modelo pode decidir tenant". Um LLM que tem permissão de propor uma ação com efeito de autorização é exatamente o risco que a OWASP GenAI Security Project descreve como LLM06:2025, Excessive Agency - um sistema baseado em LLM recebendo grau de autonomia maior do que a tarefa exige (OWASP, LLM Top 10, edição 2025).

Resposta: extraction.mjs aceita um options.modelProposal opcional (pensado para quando um extrator baseado em modelo existir) e, se esse objeto contiver tenant_id ou tenant, o campo é ignorado e registrado em auditoria com o motivo proposal_declared_tenant - nunca mesclado no registro. O teste correspondente injeta uma proposta adversarial com tenant_id: 'globex' enquanto o actorContext real é acme, e confirma que o documento resultante continua com tenant_id: 'acme'.

2. Schema mutável sem migração

Sintoma: um novo campo, um novo valor de enum ou uma mudança de tipo aparece nos dados sem que o schema_version mude. Consumidores antigos e novos discordam silenciosamente sobre o formato.

Causa: tratar o schema como documentação e não como contrato executável - especialmente fácil quando a mudança nasce de uma alteração de prompt ("agora o extrator também retorna confidence") em vez de uma decisão de schema deliberada.

Resposta: todo escritor de documento (ingest.mjs, extraction.mjs) valida contra schema-lite.mjs antes de gravar, e qualquer propriedade fora da lista declarada é rejeitada (additionalProperties: false). compatibility.test.mjs prova isso injetando model_suggested_tenant como uma propriedade extra e confirmando que o validador rejeita - a mesma defesa que impede a falha 1 de entrar pela porta do schema em vez de pela porta do parâmetro.

3. Revisão humana sobrescreve a origem

Sintoma: um revisor corrige um campo errado, e a correção substitui o texto original ou a revisão anterior. Depois de um incidente, não há como saber o que o documento dizia antes da correção, nem quem decidiu o quê.

Causa: tratar "revisão" como edição de um único registro mutável, em vez de como criação de uma nova revisão auditável sobre uma anterior imutável.

Resposta: store.putDocument sempre adiciona ao histórico (docs.get(documentId).push(...)); nunca substitui uma entrada anterior. review.reprocess cria uma nova revisão com revision e extraction_version maiores, mas herda source_checksum do documento original - o texto de origem é gravado uma vez, no ingest, e nunca recalculado. O teste "reprocessamento preserva checksum e revisão anterior" confirma as três propriedades ao mesmo tempo: reprocessed.source_checksum === uploaded.source_checksum, e store.history('acme', 'INV-2001') ainda contém a entrada com review_status: 'rejected' da revisão anterior.

4. Monólito chamado "modular" apesar de dependências circulares

Sintoma: o time descreve o sistema como "arquitetura modular" porque o código está em arquivos separados com nomes de domínio (ingest.js, review.js...), mas extraction importa uma função de review para "avisar que terminou", e review importa algo de extraction para "reprocessar automaticamente". Nenhum dos dois pode ser entendido, testado ou substituído isoladamente, porque carregar um carrega o outro.

Causa: adicionar uma chamada direta entre módulos de domínio na primeira vez que "seria conveniente" um chamar o outro, sem checar se isso fecha um ciclo no grafo de dependências.

Resposta: este capítulo resolveu o mesmo problema de coordenação - extração precisa avançar o estado, revisão precisa reprocessar de volta para extração - sem um ciclo, extraindo a tabela de transições para state.mjs, um módulo-folha que ambos importam. Nem extraction.mjs nem review.mjs precisam saber que o outro existe. A verificação de que isso é verdade não é uma alegação de design; é o grep estático reproduzido acima, que qualquer leitor pode rodar de novo.

O que os testes provam e o que não provam

Os 16 testes locais (node --test examples/*.test.mjs, ver verification.md para saída completa) cobrem: caminho positivo completo (ingest → extract → approve); o incidente sintético do início, com dois tenants usando o mesmo document_id; leitura, extração e aprovação/rejeição cross-tenant negadas e auditadas; injeção de tenant_id forjado em uma proposta de extração; rejeição de approved -> extracted sem novo versionamento (o exercício básico); preservação de checksum e revisão anterior no reprocessamento; conflito de checksum ao reingerir o mesmo document_id com conteúdo diferente; validação da fixture v1 contra o próprio schema v1; falha esperada ao validar v1 direto contra v2; migração v1→v2 sem perda; rejeição de um schema_version v2 já migrado sendo migrado de novo; aceitação de idempotency_key explícito; e as duas falhas de schema descritas acima (enum não versionado, propriedade desconhecida).

O que isso não prova: nenhuma linha de PostgreSQL foi executada nesta sessão. store.mjs particiona corretamente dentro de um único processo Node com uma única instância de Map - isso não é o mesmo que provar que uma política de row-level security segura uma tabela compartilhada sob conexões concorrentes, com um pool de conexões que pode, por engano, rodar como dono da tabela. A seção seguinte e o exercício avançado detalham exatamente o que faltaria. Também não medimos qualidade de extração: parseInvoiceText é a mesma classe de parser por regra do capítulo 1, testado aqui só por comportamento de contrato (produz um registro válido? registra proveniência?), não por acurácia contra uma distribuição real de faturas.

Custo, segurança e reversibilidade

A AWS Well-Architected Framework enquadra isso como perguntas, não como checklist de certificação: que decisão de segurança este desenho assume, e o que ela custa para operar? Neste capítulo, a resposta é registrada em ADR-004: manter tenancy pooled (uma partição lógica por tenant_id, não um schema ou banco por tenant) e aplicar isolamento no código da aplicação, adiando a prova em infraestrutura compartilhada.

Isso tem um custo de reversibilidade explícito. Migrar um tenant específico para um schema ou banco dedicado, mais tarde, é um problema de extração e recarga de dados - não um redesenho, porque tenant_id já é uma chave de primeira classe desde o início. O caminho inverso - juntar tenants que já divergiram em silos separados - é mais difícil. Isso favorece adiar a decisão de silo até haver um gatilho real: um piloto consentido com exigência contratual de residência de dados, ou uma medição de carga (não feita ainda) mostrando que um tenant degrada a latência de outro em uma tabela compartilhada.

Sobre segurança especificamente de banco de dados, a documentação de Row Security Policies do PostgreSQL - reaberta nesta sessão, refletindo a versão "current" (PostgreSQL 18 no momento do acesso) - registra três detalhes que mudam o que "prova de isolamento" significa na prática: ENABLE ROW LEVEL SECURITY precisa ser ligado por tabela, ou a política simplesmente não roda; superusuários e o dono da tabela ignoram RLS por padrão, então um pool de conexões que rodasse como dono passaria qualquer teste cross-tenant sem provar nada; e checagens de integridade referencial (chave única, chave estrangeira) ignoram RLS por design, o que a própria documentação chama de canal secundário potencial de vazamento de informação. Nenhuma dessas condições foi testada aqui - elas estão documentadas em ADR-004 como o que falta antes de qualquer afirmação de isolamento em produção.

Checklist antes de avançar

• O tenant_id de toda operação vem de um contexto autenticado pelo chamador, nunca de um campo dentro do documento ou de uma proposta de modelo.
• Uma leitura, escrita ou transição cross-tenant retorna o mesmo resultado de um recurso inexistente - sem vazar existência.
• Toda transição de estado passa por uma tabela única, testável isoladamente, que nenhum módulo de domínio reimplementa por conta própria.
• Reprocessar um documento sempre cria uma nova revisão com checksum de origem preservado; nunca sobrescreve a revisão anterior.
• Um schema tem versão explícita; mudar seu formato sem mudar a versão é tratado como bug, não como flexibilidade.
• O grafo de imports entre módulos de domínio é acíclico - e isso é verificado, não presumido.
• Toda decisão de tenancy (pooled vs. silo) está registrada como ADR com gatilho de revisão explícito, não como escolha implícita da primeira implementação.

Exercícios

Básico. Critério verificável: chamar review.reprocess(store, auditLog, reviewer, 'INV-2001', { nextRevision: revisãoAtual, reason: '...' }) a partir do estado approved, usando a mesma revision atual (sem incrementar), deve lançar TransitionError com a mensagem contendo "new revision", e o log de auditoria deve conter uma entrada com result: 'denied' e reason: 'missing_versioning'. Solução comentada: isso já está implementado e testado em examples/tenancy.test.mjs, no teste "basic exercise: approved -> extracted is rejected without a new revision/extraction_version" - a checagem vive em assertReprocessVersioning (examples/src/state.mjs), chamada por review.reprocess antes de qualquer escrita no store.

Intermediário. Critério verificável: adicionar um schema v2 do contrato de documento sem invalidar a fixture v1 existente. Solução comentada: já resolvido por examples/contracts/document.schema.v1.json (congelado) + examples/contracts/document.schema.json (v2, com idempotency_key opcional) + migrateDocumentV1toV2 em examples/src/migrations.mjs. O teste "intermediate exercise" em examples/compatibility.test.mjs roda exatamente essa migração sobre examples/fixtures/document-v1.json e confirma que nada se perde. Trecho demonstrativo (não é um comando novo, é o já executado nesta sessão): node --test examples/compatibility.test.mjs.

Avançado. Critério verificável: escrever um teste que tenta ler, por document_id conhecido, um documento de outro tenant, e descrever - sem implementar - os requisitos adicionais para provar a mesma propriedade em PostgreSQL real. Solução comentada: o teste já existe ('cross-tenant read of a known document_id returns nothing, same as a nonexistent id', em examples/tenancy.test.mjs) e prova a propriedade dentro de um processo Node com uma única instância de Map. Os requisitos adicionais, descritos em examples/adrs/004-tenancy.md e não executados nesta sessão, são: (1) ALTER TABLE ... ENABLE ROW LEVEL SECURITY explicitamente ativado na tabela; (2) uma política USING (tenant_id = current_setting('app.tenant_id')::text) - trecho demonstrativo, não executado:

-- Demonstrativo. Não executado nesta sessão; requer Postgres real e role dedicada.
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON documents
  USING (tenant_id = current_setting('app.tenant_id')::text);

(3) uma role de teste que não seja dona da tabela e não tenha BYPASSRLS, porque o dono e o superusuário ignoram RLS por padrão; (4) duas transações separadas com SET LOCAL app.tenant_id = '...' diferentes, testando SELECT/UPDATE/DELETE cross-tenant e esperando zero linhas ou erro de permissão; (5) atenção ao canal secundário documentado pelo próprio Postgres: violações de chave única/estrangeira ignoram RLS e podem, em tese, revelar que uma linha existe em outra partição.

Glossário curto

• Tenancy pooled: várias organizações compartilham as mesmas tabelas/estruturas, distinguidas por uma coluna/chave de tenant.
• Tenancy silo: cada organização tem seu próprio schema ou banco de dados.
• Expand/contract: padrão de migração de schema em duas fases - primeiro adiciona campos de forma compatível com versões antigas (expand), depois remove a tolerância à versão antiga só quando todo produtor já migrou (contract).
• RLS (row-level security): mecanismo do PostgreSQL que filtra linhas visíveis/graváveis por política, avaliado por linha, e que não se aplica a superusuários ou donos de tabela por padrão.
• Excessive agency: item LLM06:2025 da OWASP GenAI Security Project - um sistema baseado em LLM com grau de autonomia maior do que a tarefa exige, especialmente perigoso quando essa autonomia pode afetar autorização.

Ponte para o capítulo 3

Este capítulo prova isolamento e contrato dentro de um único processo Node. O que fica pendente, explicitamente, para a continuação da série: uma integração real com um banco transacional (a ADR-004 já lista os requisitos de RLS que precisam ser satisfeitos, não apenas declarados); uma política de retenção e redação de PII mais completa do que o redactFields atual, que hoje só mascara o comprimento de strings; e o primeiro ponto em que um extrator baseado em modelo real - não a regra de parseInvoiceText - entra no sistema sem herdar nenhuma autoridade sobre tenant ou transição de estado. Nenhum desses três itens está implementado aqui; estão registrados como o próximo experimento, não como resultado.