Solução de problemas

Comece pelo code do erro. LangDriftError.issues contém caminhos JSON Pointer para falhas de validação. SetupError.files e .fields identificam conflitos de configuração e entradas ausentes.

Carregamento do projeto

`PROJECT_NOT_FOUND`

Nenhuma raiz .git foi encontrada na busca pelos diretórios pais, ou .drifts/project.json está ausente. Informe explicitamente a raiz existente desejada ou execute a configuração local nela.

`PROJECT_INVALID`

O arquivo do projeto é um JSON malformado ou não corresponde ao esquema de projeto. Revise-o manualmente. A configuração preserva o conteúdo conflitante e não o substitui.

`SCHEMA_UNSUPPORTED`

Um evento, artefato, projeto ou envelope de raciocínio declara uma versão de esquema diferente de 1. Esta versão candidata não oferece migração. Não altere o número sem revisar os dados em relação ao esquema da versão 1.

Artefatos e referências

`ARTIFACT_INVALID`

As causas atuais incluem:

JSON malformado ou frontmatter langdrift ausente/inválido
uso não compatível de .md / .json ou divergência entre tipo e diretório
campos desconhecidos ou outra divergência de esquema
arquivo ou corpo com mais de 1 MiB
limites de descoberta inválidos ou limites de arquivos/diretórios excedidos
identidades locais (type, id) duplicadas
impacto Drift inconsistente ou proveniência de evidências ausente
uma amostra inválida de pull request integrado do GitHub

Leia os caminhos de campos em issues. O analisador não infere identidades ausentes a partir de títulos ou nomes de arquivo.

`PATH_OUTSIDE_ROOT`

O caminho é absoluto, sobe para diretórios pais, contém um segmento ou caractere proibido ou alcança um link simbólico. Use um caminho relativo normal na árvore .drifts do projeto. A descoberta nunca segue links simbólicos.

Problemas de referências

REFERENCE_NOT_FOUND e REFERENCE_CYCLE são retornados em resolveReferences(...).issues; não são lançados como exceções. Registre uma identidade externa explicitamente conhecida, corrija o tipo/ID/caminho exato ou remova o ciclo local antes do transporte.

Credenciais e transporte

`CREDENTIAL_MISSING`

A referência não está no formato env:NAME, ou o valor de ambiente está ausente ou contém quebra de linha ou byte nulo. Passe apenas uma referência e forneça o valor ao ambiente de execução.

`REMOTE_UNAUTHORIZED`

O transporte injetado informou 401 ou 403. Os valores de roteamento account_id e project_id não concedem autorização; revise a credencial de execução e a política do destino.

`REMOTE_REJECTED`

O transporte injetado informou outro status 4xx. Revise o envelope validado e o contrato do destino.

`MCP_UNAVAILABLE`

O transporte falhou sem uma resposta 4xx classificada. Nada fica em fila local. Só tente novamente após verificar o adaptador fornecido por quem chama a API.

Configuração

ROOT_INVALID — --root não aponta para um diretório existente.
SETUP_ARGUMENT_MISSING — forneça ID de projeto, ID de conta e nome em uma execução não interativa.
SETUP_ARGUMENT_INVALID — revise as opções aceitas, opções booleanas conflitantes e o par ID numérico de instalação do GitHub e owner/repository.
SETUP_CONFLICT — inspecione o status e o motivo de cada arquivo. A verificação prévia não gravou nada.
SETUP_PATH_CONFLICT — um caminho gerenciado é um link simbólico ou tem um pai que não é diretório.
SETUP_CONCURRENT_CHANGE — um destino mudou após a verificação prévia e foi preservado.
SETUP_WRITE_FAILED — uma falha de E/S interrompeu a criação. Arquivos criados antes podem permanecer; inspecione e execute novamente.

.drifts/execution é um conflito deliberado porque esta versão usa Loop e não migra estruturas legadas.

Para diagnósticos seguros na aplicação, reportError(error, logger) emite o código, uma mensagem genérica e os problemas de validação. Ele omite corpos e rastreamentos de pilha de exceções desconhecidas.