Referências

Referências são dados explícitos do protocolo. O SDK não as infere a partir de prosa, títulos, nomes de branches ou URLs de provedores.

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

type e id formam a identidade do protocolo. path pode restringir uma referência local a um caminho de artefato. integration e external_id são um par inseparável para uma identidade externa.

Os metadados de documentos podem fornecer references, supersedes, superseded_by e listas de relações tipadas, como research, specs ou vision_targets. O campo external: { integration, id } registra a identidade do próprio documento no provedor como referência externa. Drift Events também referenciam seu vision_target_id.

Resolva um conjunto

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

A resolução indexa artefatos locais pelo par exato (type, id).

• Uma identidade local correspondente recebe resolved. Se a referência incluir path, ele deve ser igual ao caminho do artefato de destino.
• Uma referência com integration e external_id recebe external.
• Uma referência sem caminho que corresponda ao terceiro argumento opcional também recebe external. Essa lista é um registro explícito de identidades já conhecidas por quem chama a API.
• Qualquer outro caso produz um problema REFERENCE_NOT_FOUND.
• Ciclos entre referências locais resolvidas produzem problemas REFERENCE_CYCLE.

Os problemas são retornados em resolution.issues; referências ausentes e ciclos não lançam exceções. Identidades locais (type, id) duplicadas são ambíguas e lançam LangDriftError com código ARTIFACT_INVALID.

Os caminhos de referências passam pelas mesmas verificações de segurança dos artefatos. Um caminho não provoca consulta remota, e a lista de referências conhecidas não consulta nem comprova a existência de dados no backend. A resolução é exclusivamente local e deve ser tratada como uma etapa separada antes do transporte.