參照

參照是明確的協定資料。SDK 不會從文字敘述、標題、分支名稱或供應商 URL 推斷參照。

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

type 與 id 構成協定身分。 path 可將本機參照限制到一個產出物路徑。 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。
• 沒有路徑且符合選用第三個引數的參照，也標記為 external。此清單是呼叫端已知身分的明確登錄表。
• 其他情況會產生 REFERENCE_NOT_FOUND 問題。
• 已解析本機參照之間的循環會產生 REFERENCE_CYCLE 問題。

問題會透過 resolution.issues 傳回；缺少參照和循環不會拋出例外。 重複的本機 (type, id) 身分會造成歧義，因此會拋出代碼為 ARTIFACT_INVALID 的 LangDriftError。

參照路徑會接受與產出物相同的安全路徑檢查。 路徑不會觸發遠端查詢，已知參照清單也不會查詢或證明後端資料存在。 解析僅在本機進行，必須視為傳輸前的獨立檢查關卡。