Referência da especificação

Uma especificação do Orvienm é um arquivo YAML que declara uma estrutura: um nome e os diretórios que devem existir sob ele. O formato é deliberadamente pequeno e fechado — quatro chaves de raiz, duas delas opcionais — e só cresce à medida que o engine implementa mais.

Esta página documenta o que o engine aceita hoje. Para o que cada comando faz com uma especificação, veja a Referência da CLI.

version: 1

structure:
  name: platform
  directories:
    - core
    - data

Aplicar isso cria platform/ contendo core/ data/, relativo ao diretório em que o comando roda.

version: 1

style: enterprise        # optional: enterprise | technical | hybrid

structure:
  name: platform         # required — the directory the engine creates
  directories:           # required — non-empty list of strings
    - core
    - data
    - docs

policy:                  # optional
  forbid:
    - secrets

A raiz precisa ser um mapping YAML. Exatamente quatro chaves são reconhecidas.

• version — obrigatória. Declara o formato contra o qual o arquivo foi escrito. O valor é registrado no fingerprint e no lock file, mas não passa por verificação de faixa.
• structure — obrigatória. Um mapping; veja abaixo.
• style — opcional. Veja abaixo.
• policy — opcional. Veja abaixo.

O conjunto de chaves de raiz é fechado. Qualquer outra chave é erro de validação: Unknown field at root level: 'x'. É por isso que chaves herdadas de rascunhos antigos ou de outras ferramentas — relationships entre elas — falham em vez de serem ignoradas.

• structure.name — obrigatória. Nomeia o diretório que o engine cria e inspeciona. É resolvido em relação ao diretório de trabalho, então rodar um comando de dentro desse diretório criaria uma segunda raiz aninhada.
• structure.directories — obrigatória. Uma lista de strings, que não pode ser vazia. Cada entrada é um diretório sob a raiz. Uma entrada pode conter barras, e nesse caso os diretórios intermediários também são criados.

Opcional. Aceita enterprise, technical hybrid; qualquer outro valor é erro de validação. Quando omitido, é tratado como enterprise.

O style não muda o que o engine cria, mas participa do fingerprint — alterá-lo muda a identidade da especificação e, portanto, conta como desvio.

Opcional. Apenas uma regra está implementada: policy.forbid, uma lista de nomes.

policy:
  forbid:
    - secrets

O comando orvienm policy lê essa lista e reporta qualquer um desses nomes encontrado dentro da estrutura declarada, em qualquer profundidade, com o caminho relativo à raiz da estrutura. Nada é bloqueado ou removido. Por padrão o comando sai com 0 mesmo quando encontra uma violação, de modo que adicionar um bloco policy não pode tornar vermelho um pipeline verde; orvienm policy --strict sai com 2 diante de uma violação, quando você quiser que ele sirva de portão. O policy não faz parte da validação, e nenhum outro comando o consulta.

Cada entrada em structure.directories é verificada individualmente após a normalização. Todos os casos abaixo são erros de validação.

• Um valor que não seja string, ou uma string vazia ou só com espaços.
• Um caminho absoluto — /data C:\data. Uma especificação não pode alcançar fora do workspace.
• Um caminho contendo ... Travessia é rejeitada pelo mesmo motivo.
• Qualquer um dos caracteres < > : " \ | ? *. Barras são permitidas.
• Duas entradas que normalizam para o mesmo caminho — a e ./a colidem.

A ordem das entradas é irrelevante. O fingerprint ordena a lista, então reordenar diretórios produz a mesma identidade.

Como barras são permitidas, uma entrada como core/products valida e aplica corretamente — o engine cria os diretórios intermediários.

Todo comando raciocina sobre o mesmo conjunto expandido. Um caminho declarado contribui com ele próprio e com cada um de seus ancestrais, então o plan reporta keep para todos eles depois de um apply bem-sucedido, o verify confere todos eles, e o doctor não trata um diretório intermediário criado pelo engine como não declarado.

A ordem das entradas nunca importa: o fingerprint ordena a lista, e a expansão junta os ancestrais compartilhados por irmãos.

Os comandos plan, apply, graph policy aceitam um argumento de arquivo opcional. Quando ele é omitido, usam o primeiro destes encontrado no diretório de trabalho:

.orvienm.yaml
orvienm.yaml
orvienm.yml

Os comandos validate, verify, status, doctor fingerprint exigem o argumento de arquivo explicitamente e falham sem ele.

Em um apply bem-sucedido, o engine escreve .orv.lock no diretório de trabalho.

{
    "orvienm_version": "0.3.0",
    "generated_at": "2026-08-27T04:12:51.638274Z",
    "fingerprint": "810ce0ae93772eb7ed941e811c7f66ab4bcf9e8eef1c2b2d8b676246cda5963f",
    "structure_name": "platform",
    "schema_version": 1,
    "style": "enterprise"
}

O campo fingerprint é um SHA-256 sobre um manifesto canônico construído a partir de exatamente quatro entradas: version, style, structure.name e a lista ordenada de diretórios. Comentários, ordem das chaves e espaçamento não o afetam.

Desvio significa que o fingerprint da especificação atual difere do que está registrado no lock — ou seja, a especificação mudou, não o sistema de arquivos. Quando isso acontece, o apply se recusa a rodar e sai com 3. Apague .orv.lock para aceitar a nova especificação e aplique de novo. Como o desvio é comparado no nível do fingerprint, e não campo a campo, apagar o lock aceita todas as mudanças do arquivo de uma vez.

Um apply bem-sucedido registra a especificação sobre a qual o workspace agora se apoia, tenha ele criado a estrutura ou encontrado tudo já conforme. Um apply que falha não registra nada, e um apply bloqueado deixa o lock existente intacto, de modo que a evidência de desvio nunca é sobrescrita antes de ser reconhecida.

O lock é o único estado persistido pelo engine: não há diretório de estado, repositório de snapshots nem histórico de execuções na CLI.

Estes aparecem em material antigo e em ferramentas próximas. Nenhum deles é aceito pelo validador atual, e usá-los produz erro em vez de ser ignorado.

• Mappings YAML aninhados como sintaxe de estrutura — diretórios são uma lista plana de caminhos.
• _requires, referências e declarações de dependência.
• relationships e arestas declarativas de grafo.
• Apêndices, perfis além dos valores de style, e OSL.
• Detecção de ciclos, convenções de nomenclatura e regras de restrição.
• Severidades de aviso — todo achado de validação é um erro.

Quando uma especificação falha, veja a Solução de problemas.