Uma estrutura de coleta que separa dados fonte de snapshots de execução

✨ Resumo do GPT-5.5

Registro de como, ao migrar para PostgreSQL dados de referência que continuavam mudando entre JSON, CSV e DuckDB, separei evidence fonte, observations, dados de referência, snapshots de execução e artefatos de entrega.

Os dados de referência ficavam instáveis entre JSON, CSV e DuckDB

Ao longo de vários dias, enquanto eu montava o fluxo de coleta, revisão, execução e entrega de dados, vários problemas continuavam aparecendo. Como nunca aprendi nem lidei de verdade com DBs, mudei muitas vezes o modo de armazenar os dados, e cada mudança acabava sendo muito mais do que uma simples troca.

No começo, eu coletava os dados em JSON/CSV e usava DuckDB para visualizá-los. Mas os artefatos dos workers se misturaram com uma estrutura em que o coordenador reconstruía a DB várias vezes, e o que era dado fonte e o que era dado de referência continuava mudando.

Também cheguei a montar um plano para criar a DB em MySQL. Mas o problema não era o MySQL em si, e sim uma estrutura em que vários workers ou scripts atualizavam diretamente os dados de referência. Seguindo assim, era muito provável que problemas de update simultâneo, conflito, ownership e rollback continuassem se repetindo.

Depois disso, avaliei outras alternativas, mas o problema central era o mesmo. Se os limites entre dados coletados, dados de referência, dados de execução e artefatos de entrega são vagos, o mesmo problema acaba voltando.

O principal não era o banco de dados usado, mas a responsabilidade pelas mutações

Migrar para PostgreSQL não resolveria o problema por si só. Antes de decidir qual DB usar, eu precisava definir quem poderia alterar os dados de referência.

Os workers deixam o evidence fonte e as observations em modo append-only. Eles não alteram diretamente os dados de referência. O coordenador revisa o evidence e as observations e só então atualiza os dados e valores de referência. Ao concentrar em um único lugar a responsabilidade de alterar os dados de referência, também dava para rastrear o que precisava ser revertido quando surgia um conflito.

Separei os papéis dentro do PostgreSQL

Então hoje, ao migrar para PostgreSQL, também organizei todo o fluxo que vinha montando havia vários dias. Em vez de tratar tudo como um único bloco de DB, separei os papéis.

• Evidence fonte
  • Armazena as evidências e os valores originais coletados de fontes públicas
  • Valores processados e estados ficam em um histórico separado, sem sobrescrever a fonte
  • Arquivos JSON/CSV podem ser um mirror do evidence, mas não são os dados de referência
• Observation
  • Cada worker envia apenas as observações de seu canal de coleta para um ledger append-only
  • Descoberta e enriquecimento são separados em papéis diferentes
  • Os workers não alteram diretamente os dados de referência
• Dados de referência
  • O coordenador revisa o evidence e as observations
  • Apenas os valores revisados são incorporados aos dados de referência conforme uma estrutura definida
  • As views são usadas como superfícies de cálculo, revisão e exportação
• Snapshot de execução
  • Uma view de coleta não é usada diretamente como base para a execução real
  • Os targets que passam pela deduplicação e pelos quality gates são fixados em um snapshot de um momento específico
  • Resultados de execução e estados de exclusão ou acompanhamento são gerenciados separadamente dos dados de referência
• Artefatos de entrega
  • Arquivos para CSV, Google Sheet, Excel ou vox.ai são gerados a partir dos dados de referência ou do snapshot de execução
  • São artefatos para visualização ou entrega
  • Os artefatos não são modificados novamente como se fossem dados de referência

Agora dá para rastrear do evidence até a execução e a entrega

Assim ficou pronto um fluxo em que dá para rastrear onde o evidence coletado se acumula, o que cada worker deixa, qual valor se torna referência, qual snapshot é usado na execução real e o que vira artefato de entrega.

Claro que a estrutura ainda tem muitas limitações, então haverá muito mais coisa para mexer. Vou continuar testando, recebendo feedback e corrigindo, e provavelmente ainda vai acontecer todo tipo de grande mudança. É assim que o fluxo, a estrutura do harness e minha própria intuição vão evoluir.

Compartilho isso caso a forma como montei este fluxo possa ajudar alguém.