観測記録と変化の解釈

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 は、検証済みの webhook/API 形式のマージされたプルリクエストを扱う recordFromGitHubPullRequest も提供します。この関数は、変更されない 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 の計算式を計算しません。