Registros e desvios

Um registro (Record) é um fato de uma origem identificada. Um evento de desvio (Drift Event) é uma interpretação em relação a um alvo de direção (Vision Target), sustentada por evidências (Evidence) explícitas. Criar um Record nunca cria uma interpretação de desvio automaticamente.

Registros

function createRecord(
  input: Omit<RecordEvent, 'type' | 'schema_version'>
): RecordEvent

Quem chama a API fornece:

• id e kind extensível
• occurred_at como data e hora
• source.integration, source.external_id e, opcionalmente, source.repository
• actors humanos ou agentes
• references explícitas
• um objeto data compatível com JSON contendo fatos da origem

createRecord adiciona apenas type: 'record' e schema_version: 1 e valida o envelope completo. Ele não gera uma data nem busca detalhes da origem.

Para identidades estáveis de eventos de provedores, o SDK também exporta:

recordId(integration: string, sourceId: string, eventId: string): string

A função calcula o hash da identidade ordenada de três partes e retorna um ID com prefixo REC-. Use identificadores imutáveis dos provedores, não títulos.

Eventos de desvio

function createDrift(
  input: Omit<DriftEvent, 'type' | 'schema_version'>
): DriftEvent

Um Drift Event exige:

• id e vision_target_id
• state: 'expected' | 'unexpected'
• impact com unit, before, delta e after
• actors humanos ou agentes
• references explícitas
• reasoning versionado
• created_at opcional

As unidades de impacto são percentage_points, ratio e score_points. impact.after deve ser igual a impact.before + impact.delta dentro da precisão de ponto flutuante.

Os métodos de raciocínio são human, deterministic e llm. Cada entrada em reasoning.evidence_refs deve identificar um item em references. O raciocínio LLM também exige uma lista de evidências não vazia e model; model_version, quando presente, também exige model. O envelope de raciocínio usa schema_version: 1.

createDrift adiciona apenas o tipo e a versão do esquema no nível superior e valida o resultado. Ele não decide se uma mudança é esperada, calcula impacto, escolhe unidades, encontra evidências nem executa um mecanismo de raciocínio.

O SDK deixa deliberadamente a fórmula de Product Vision indefinida. Persistência, autorização de identidades e política de interpretação pertencem a um ambiente de execução projetado separadamente.