Bản ghi và sai lệch

Bản ghi (Record) và sự kiện sai lệch (Drift Event) trả lời những câu hỏi khác nhau:

• Record là một sự kiện thực tế đã quan sát và chuẩn hóa.
• Drift Event diễn giải biến động quan sát được so với mục tiêu định hướng (Vision Target) và dẫn bằng chứng (Evidence) hỗ trợ diễn giải đó.

1. Chuẩn hóa một pull request đã hợp nhất

Giả sử một tích hợp đã quan sát pull request 481 của GitHub ở trạng thái đã hợp nhất. Có thể tạo sự kiện chuẩn hóa với cấu trúc RecordEvent chính xác:

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 thêm type: 'record' và schema_version: 1, rồi kiểm tra các dữ kiện do bên gọi cung cấp. Nó không tự tạo dấu thời gian, tham chiếu hay điểm số.

SDK cũng cung cấp recordFromGitHubPullRequest cho pull request đã hợp nhất và kiểm tra theo cấu trúc webhook/API. Hàm hỗ trợ này suy ra ID Record băm ổn định từ định danh GitHub bất biến và chỉ ánh xạ các trường tường minh của nhà cung cấp. ID dễ đọc REC-001 ở trên được cung cấp trực tiếp cho ví dụ này.

2. Diễn giải biến động

Diễn giải nêu mục tiêu, tham chiếu Record quan sát được và dùng Record đó làm bằng chứng cho lập luận:

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
  }
})

Các quan hệ là tường minh:

• vision_target_id xác định mục tiêu so sánh.
• references liên kết diễn giải với REC-001 và PRD-001.
• reasoning.evidence_refs xác định REC-001 là bằng chứng hỗ trợ và phải khớp một mục trong references.
• actors ghi nhận chủ thể thực hiện diễn giải.

createDrift thêm kiểu vỏ bọc Drift và phiên bản giao thức. Nó kiểm tra after bằng before + delta và mọi ID bằng chứng đều xuất hiện trong references. Bên gọi chịu trách nhiệm về diễn giải, đơn vị và giá trị tác động; SDK không tính công thức Product Vision.