觀察紀錄與變化解釋

Record 和 Drift Event 回答不同的問題：

Record 是經正規化的觀察事實。
Drift Event 解釋觀察到的變化與 Vision Target 的關係，並引用支持該解釋的 Evidence。

1. 正規化已合併的提取要求

假設某項整合觀察到 GitHub 提取要求 481 已合併。可使用精確的 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 會新增 type: 'record' 和 schema_version: 1，再驗證呼叫端提供的事實。它不會捏造時間戳記、參照或分數。

SDK 也提供 recordFromGitHubPullRequest，處理已驗證且符合 webhook/API 格式的已合併提取要求。該函式會從不可變的 GitHub 身分推導穩定的雜湊 Record ID，且只對應明確的供應商欄位。上方易讀的 REC-001 是為此範例直接指定的。

2. 解釋變化

解釋會指明目標、參照觀察到的 Record，並將該 Record 引用為推理證據：

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

這些關係都是明確的：

vision_target_id 識別比較目標。
references 將解釋連結至 REC-001 與 PRD-001。
reasoning.evidence_refs 將 REC-001 指定為支持解釋的 Evidence，且必須符合 references 中的項目。
actors 表示做出解釋的主體。

createDrift 會新增 Drift 封套類型與協定版本。它會檢查 after 是否等於 before + delta，以及每個證據 ID 是否都出現在 references 中。解釋、影響單位與數值由呼叫端決定；SDK 不會計算 Product Vision 公式。