Registros e desvios

Um registro (Record) e um evento de desvio (Drift Event) respondem a perguntas diferentes:

• Um Record é um fato observado e normalizado.
• Um Drift Event interpreta uma mudança observada em relação a um alvo de direção (Vision Target) e cita as evidências (Evidence) que sustentam essa interpretação.

1. Normalize um pull request integrado

Suponha que uma integração tenha observado o pull request 481 do GitHub já integrado. O evento normalizado pode ser criado com o formato exato de RecordEvent:

import { createRecord } from '@langdrift/sdk'
 
const record = createRecord({
  id: 'REC-001',
  kind: 'github.pull_request.merged',
  occurred_at: '2026-09-19T18:00:00Z',
  source: {
    integration: 'github',
    repository: 'example/product',
    external_id: '9001'
  },
  actors: [{ type: 'human', external_id: 'github:12345' }],
  references: [
    { type: 'prd', id: 'PRD-001' },
    { type: 'vision-target', id: 'VT-001' }
  ],
  data: {
    number: 481,
    title: 'Add Product Vision summary',
    state: 'closed',
    author: { type: 'human', external_id: 'github:12345' },
    created_at: '2026-09-18T10:00:00Z',
    updated_at: '2026-09-19T18:00:00Z',
    merged_at: '2026-09-19T18:00:00Z',
    head: { ref: 'product-vision-summary', sha: 'abc123' },
    base: { ref: 'main', sha: 'def456' },
    labels: ['product-vision']
  }
})

createRecord adiciona type: 'record' e schema_version: 1 e valida os fatos fornecidos por quem chama a API. Ele não inventa datas, referências ou pontuações.

O SDK também fornece recordFromGitHubPullRequest para um pull request integrado e validado no formato de webhook/API. Essa função deriva um ID de Record estável por hash a partir da identidade imutável do GitHub e mapeia apenas campos explícitos do provedor. O ID legível REC-001 acima é fornecido diretamente para este exemplo.

2. Interprete a mudança

A interpretação identifica seu alvo, referencia o Record observado e cita esse Record como evidência do raciocínio:

import { createDrift } from '@langdrift/sdk'
 
const drift = createDrift({
  id: 'DRIFT-001',
  vision_target_id: 'VT-001',
  state: 'expected',
  impact: {
    unit: 'score_points',
    before: 10,
    delta: 2,
    after: 12
  },
  actors: [{ type: 'human', id: 'user_42' }],
  references: [
    { type: 'record', id: record.id },
    { type: 'prd', id: 'PRD-001' }
  ],
  reasoning: {
    method: 'human',
    evidence_refs: [record.id],
    schema_version: 1
  }
})

As relações são explícitas:

• vision_target_id identifica o alvo de comparação.
• references vincula a interpretação a REC-001 e PRD-001.
• reasoning.evidence_refs identifica REC-001 como evidência de apoio e deve corresponder a uma entrada em references.
• actors atribui a autoria da interpretação.

createDrift adiciona o tipo do envelope Drift e a versão do protocolo. Ele verifica se after é igual a before + delta e se cada ID de evidência aparece em references. Quem chama a API é responsável pela interpretação, unidade e valores de impacto; o SDK não calcula uma fórmula de Product Vision.