Payloads e transporte

Envelope

interface PayloadEnvelope {
  schema_version: 1
  account_id: string
  project_id: string
  resource: string
  resource_id: string
  source: PayloadSource
  references: ArtifactRef[]
  payload: JsonObject
}

account_id e project_id vêm do projeto validado. Eles roteiam e contextualizam um payload; não são credenciais nem autorizam acesso. resource é o pilar e o tipo, como vision.prd, e resource_id é o ID do artefato ou evento.

Para um artefato Markdown, payload é { metadata, body }. Payloads Record e Drift Event são seus envelopes JSON validados. references são as referências explícitas derivadas da entrada validada.

Proveniência da origem

PayloadSource.kind é um destes valores:

markdown — exige um path relativo seguro
json — exige um path relativo seguro
integration — exige integration e external_id

Artefatos analisados inferem markdown ou json a partir do caminho. Um Record direto infere sua origem de integração. Um Drift Event direto não tem campo de origem, então quem chama a API deve fornecer a proveniência explicitamente.

createPayload(
  project: Project,
  input: ParsedArtifact | RecordEvent | DriftEvent,
  source?: PayloadSource
): PayloadEnvelope

Objetos de origem rejeitam campos adicionais e combinações inválidas. A proveniência de arquivos usa as mesmas restrições de sintaxe de caminhos relativos dos artefatos locais.

Transporte injetado

interface PayloadTransport {
  send(
    payload: PayloadEnvelope,
    context: { authorization: string }
  ): Promise<{ correlationId?: string }>
}

sendPayload valida e constrói o envelope, resolve uma credencial e chama essa interface fornecida por quem chama a API. Ele não escolhe um endpoint nem uma topologia de protocolo.

As credenciais usam uma referência env:NAME. resolveCredential lê o valor em tempo de execução e rejeita valores ausentes ou que contenham quebra de linha ou byte nulo. A credencial é passada separadamente no contexto de transporte e nunca é incluída no envelope do payload.

await sendPayload(project, input, transport, {
  credentialRef: 'env:LANGDRIFT_TOKEN',
  source
})

O SDK não fornece cliente HTTP, persistência, processamento em lote, fila em segundo plano, novas tentativas automáticas ou envio automático. Não coloque segredos em corpos Markdown e dados de Record, pois esses campos são conteúdo do payload.

Erros de transporte

Um adaptador injetado pode lançar TransportError(status). sendPayload mapeia:

401 ou 403 para REMOTE_UNAUTHORIZED
outros status 4xx para REMOTE_REJECTED
todas as outras falhas de transporte para MCP_UNAVAILABLE

Eles se tornam valores LangDriftError. Corpos brutos de respostas remotas, rastreamentos de pilha e credenciais não são encaminhados. Dados de transporte indisponível não ficam em fila local; qualquer nova tentativa é explícita.