觀察紀錄與變化解釋

Record 是事實，來自已識別的來源。 Drift Event 是解釋，以明確的 Evidence 為依據，針對 Vision Target 進行比較。 建立 Record 絕不會自動建立 Drift 解釋。

觀察紀錄（Record）

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

呼叫端提供：

• id 和可擴充的 kind
• 日期時間格式的 occurred_at
• source.integration、source.external_id，以及選用的 source.repository
• 人員或代理程式 actors
• 明確的 references
• 包含來源事實且相容於 JSON 的 data 物件

createRecord 只會新增 type: 'record' 和 schema_version: 1，接著驗證完整封套。 它不會產生時間戳記或擷取來源詳細資料。

為了提供穩定的供應商事件身分，SDK 也匯出：

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

它會對有順序的三部分身分進行雜湊，並傳回以 REC- 開頭的 ID。 呼叫端應使用不可變的供應商識別碼，而不是標題。

變化解釋（Drift Event）

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

Drift Event 需要：

• id 和 vision_target_id
• state: 'expected' | 'unexpected'
• 包含 unit、before、delta 和 after 的 impact
• 人員或代理程式 actors
• 明確的 references
• 版本化 reasoning
• 選用的 created_at

影響單位為 percentage_points、ratio 和 score_points。 在浮點精度範圍內，impact.after 必須等於 impact.before + impact.delta。

推理方法為 human、deterministic 和 llm。 每個 reasoning.evidence_refs 項目都必須識別 references 中的一個項目。 LLM 推理還需要非空的證據清單與 model；提供 model_version 時也必須提供 model。 推理封套使用 schema_version: 1。

createDrift 只會新增頂層類型和結構定義版本，再驗證結果。 它不會判斷變更是否符合預期、計算影響、選擇單位、尋找 Evidence 或執行推理引擎。

SDK 刻意不定義 Product Vision 公式。 持久儲存、身分授權與解釋政策屬於另行設計之執行環境的責任。