Artefatos

Um artefato tem metadados validados, caminho de origem, referências explícitas e nome de recurso. Artefatos Markdown também preservam o texto do corpo.

Locais definidos pelo pacote

A versão 1 do protocolo descobre apenas estes padrões recursivos de origem:

• Vision: research/**/*.md, prd/**/*.md e context/**/*.md
• Loop: triage/**/*.md, design-document/**/*.md, spec/**/*.md e ticket/**/*.md
• Evidence: adr/**/*.md, audit/**/*.md, record/**/*.json e drift/**/*.json

Cada padrão tem como raiz .drifts/<pillar>/. Caminhos de auditoria aninhados, como evidence/audit/runs e evidence/audit/reports, são cobertos pelo padrão de auditoria. Padrões de origem arbitrários não são compatíveis.

Markdown é usado nas nove famílias de documentos. Envelopes Record e Drift Event usam JSON. Durante a descoberta, o metadado type deve corresponder ao diretório de origem.

Análise

parseArtifact(text: string, artifactPath: string): ParsedArtifact

parseArtifact aceita caminhos .md e .json. Ele valida os metadados, deriva o recurso do pilar, como vision.prd, reúne referências explícitas e retorna o caminho original do artefato.

Para Markdown, body é o texto após o delimitador de fechamento do frontmatter. Para Records e Drift Events em JSON, body fica vazio. Extensões não compatíveis, entrada malformada, frontmatter ausente ou um artefato maior que 1 MiB produzem LangDriftError com código ARTIFACT_INVALID.

Descoberta

await discoverArtifacts(root, {
  maxFiles: 1000,
  maxDirectories: 1000
})

Ambos os limites têm valor padrão 1000 e devem ser inteiros positivos seguros. Quem chama a API pode escolher outros limites explicitamente. As leituras de arquivos são limitadas a 1 MiB.

A descoberta:

• visita apenas os locais .drifts declarados pelo pacote
• ordena as entradas dos diretórios antes de processá-las
• ignora entradas iniciadas por ponto e node_modules
• ignora diretórios de artefatos que não existem
• rejeita links simbólicos em vez de segui-los
• rejeita travessia de diretórios, caminhos absolutos, barras invertidas, caracteres de controle, segmentos ocultos e diretórios de dependências

Ela não percorre o repositório inteiro. Os resultados são determinísticos para um sistema de arquivos sem alterações: os locais do pacote têm uma ordem declarada e cada diretório é percorrido em ordem.

O conteúdo local do projeto não deve ser alterado por um processo não confiável durante a inspeção.