観測記録と変化の解釈

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

順序を持つ 3 要素の識別情報をハッシュ化し、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 の計算式を未定義にしています。永続化、識別情報の認可、解釈ポリシーは、別途設計するランタイムの責務です。