O que se espera que um producer de OSIRIS JSON faca
Os producers de OSIRIS JSON sao o ponto em que o padrao se torna real.
As diretrizes para producers e a documentacao do SDK de producers deixam isso explicito. Um producer nao e apenas um parser que por acaso emite JSON. E o limite em que inventarios proprietarios sao traduzidos para um snapshot de OSIRIS deterministico, portavel e seguro em que outras ferramentas possam confiar.
Um producer e um tradutor somente leitura
O primeiro ponto importante nas diretrizes para producers e o que um producer nao e.
Ele nao provisiona infraestrutura. Nao modifica dispositivos. Nao inventa dados ausentes. Nao reinterpreta a especificacao. O trabalho de um producer e mais estreito e mais rigoroso: descobrir o que existe, normalizar isso em OSIRIS, remover dados inseguros ou irrelevantes e emitir um snapshot que possa ser validado pela toolchain canonica de OSIRIS.
Isso parece obvio, mas e a linha certa a ser tracada. No momento em que producers comecam a se comportar como planos de controle, ou comecam a embutir ideias personalizadas sobre o que OSIRIS significa, a interoperabilidade se rompe.
O fluxo de trabalho do producer e deliberado
A documentacao descreve o ciclo de vida do producer em quatro etapas: discovery, normalization, redaction e emission.
Essa sequencia importa porque cada etapa tem uma responsabilidade diferente:
- discovery coleta dados do vendor ou da plataforma
- normalization os mapeia para estruturas padrao de OSIRIS
- redaction remove segredos, PII e ruido inutil
- emission serializa o documento e o valida antes da publicacao
As diretrizes tambem abrem espaco para a realidade. Inventarios parciais sao aceitaveis. Falhas individuais de discovery normalmente devem ser registradas e ignoradas, em vez de derrubar toda a exportacao. Mas essa flexibilidade para na fronteira de seguranca: se segredos forem detectados, espera-se que o producer falhe de forma segura.
Determinismo e uma funcionalidade, nao acabamento
Um dos temas mais fortes em ambos os documentos e o determinismo.
Espera-se que IDs de recursos, conexoes e grupos sejam estaveis entre execucoes. A documentacao para producers insiste fortemente contra aleatoriedade, ordenacao instavel e nomes ad hoc. A razao e direta: se o mesmo ambiente produzir uma saida diferente toda vez, diff, correlacao e automacao posterior se tornam nao confiaveis.
O SDK reforca isso com ajudas concretas:
- geracao deterministica de IDs a partir de chaves canonicas
- tratamento de colisoes em duas fases por meio de um
IDRegistry - um
DocumentBuilderque gerencia$schema,version, metadados do generator e uma saida topologica ordenada - helpers de teste que verificam determinismo byte a byte e consistencia de golden files
Este e um dos sinais mais claros de que OSIRIS esta sendo projetado para tooling de longa duracao, nao para exportacoes pontuais.
Seguranca e responsabilidade do producer
As diretrizes para producers sao igualmente firmes sobre redaction.
Documentos OSIRIS nao devem conter credenciais, tokens, chaves privadas nem strings de conexao com segredos embutidos. Espera-se que producers procurem padroes comuns antes da emission, decomponham valores inseguros em vez de copia-los por inteiro e escolham um modo de falha explicito.
O padrao recomendado e fail-closed. Existe um modo log-and-redact de ativacao explicita, mas mesmo ali as regras continuam rigorosas: nunca registrar o proprio valor secreto, sempre marcar o documento como redigido e nunca permitir que a redaction aconteca silenciosamente.
Essa e a postura correta. Producers ficam mais proximos dos sistemas-fonte brutos, e isso faz deles o lugar mais perigoso para agir com descuido.
O SDK esta ali para remover a deriva
O SDK de producers em Go nao e apresentado como infraestrutura magica. Ele e apresentado como uma forma de interromper a deriva dos producers.
Ele padroniza o contrato Collect(ctx), fornece contexto de execucao compartilhado, factories de recursos e relacionamentos, helpers de normalizacao, builders deterministas e um harness de testes. Tão importante quanto isso, ele se recusa a se tornar um segundo validador. O SDK nao controla os diagnosticos V-* e nao importa @osirisjson/core como biblioteca. Producers validam a saida chamando a CLI canonica como uma etapa externa.
Essa separacao e arquitetonicamente solida. Ela mantem a logica de mapeamento nos producers e a logica de validacao no motor compartilhado de OSIRIS.
Confianca vem dos testes
A mensagem final na documentacao para producers e que a saida de um producer precisa ser reproduzivel e revisavel.
Golden files sao tratados como a principal defesa contra regressao. O fluxo de trabalho esperado e simples: simular a entrada do vendor, gerar o documento OSIRIS, compará-lo com o golden file e, em seguida, validar esse artefato com a CLI canonica sob o perfil strict. O harness de testes do SDK adiciona helpers para esse fluxo e para reexecucoes deterministicas com relogios e fixtures fixos.
Isso importa porque a qualidade de um producer nao se resume a saber se a exportacao “funciona uma vez”. Trata-se de saber se a mesma entrada continua produzindo uma saida confiavel a medida que o ecossistema evolui.
Ler a documentacao de producers
As diretrizes para producers estao disponiveis na secao de arquitetura da documentacao: