参照

参照は明示的なプロトコルデータです。 SDK は文章、見出し、ブランチ名、プロバイダー URL から参照を推測しません。

interface ArtifactRef {
  type: string
  id: string
  path?: string
  integration?: string
  external_id?: string
}

type と id がプロトコルの識別情報を構成します。 path は、ローカル参照を 1 つの成果物パスに限定できます。 integration と external_id は外部識別情報の組であり、両方を指定するか、どちらも省略します。

文書メタデータには、references、supersedes、superseded_by、および research、specs、vision_targets などの型付き関係配列を指定できます。 external: { integration, id } フィールドは、文書自身のプロバイダー識別情報を外部参照として登録します。 Drift Event は vision_target_id も参照します。

参照の集合を解決する

const resolution = await resolveReferences(
  root,
  artifacts,
  [{ type: 'vision-target', id: 'VT-001' }]
)

解決処理は、正確な (type, id) の組でローカル成果物にインデックスを付けます。

一致するローカル識別情報は resolved です。参照が path を含む場合、そのパスは対象成果物のパスと一致する必要があります。
integration と external_id を持つ参照は external です。
任意の第 3 引数と一致し、パスを持たない参照も external です。このリストは、呼び出し側がすでに把握している識別情報の明示的な登録簿です。
それ以外は REFERENCE_NOT_FOUND の問題になります。
解決済みローカル参照の循環は、REFERENCE_CYCLE の問題になります。

問題は resolution.issues に返されます。参照の欠落や循環は例外を送出しません。ローカルの (type, id) 識別情報が重複すると曖昧になるため、コード ARTIFACT_INVALID の LangDriftError を送出します。

参照パスには、成果物と同じ安全なパスのチェックを適用します。パスがリモート検索を引き起こすことはなく、既知の参照リストもバックエンドデータを照会したり、その存在を証明したりしません。解決はローカル限定であり、転送前の独立した確認段階として扱う必要があります。