Produto / Engine
O engine que executa estrutura
O Orvienm lê uma especificação declarativa, verifica-a, determina exatamente quais caminhos estão faltando, aplica-os e então confere o resultado contra o que foi declarado.
Visão geral
O engine opera acima do sistema de arquivos. Ele não o observa continuamente e não é dono de tudo o que há dentro dele. Recebe uma especificação que descreve a estrutura que um workspace deveria ter e reconcilia o workspace em direção a essa estrutura por meio de uma sequência de etapas explícitas.
Cada etapa é separável. A validação pode rodar sem planejamento, e um plano pode ser produzido e lido sem que nada seja aplicado.
Ciclo de execução
Cada etapa tem uma única responsabilidade, e nenhuma etapa é pulada no caminho até o sistema de arquivos.
- 01
Define
Declare a estrutura que o sistema deve ter.
- 02
Validate
Confira a especificação antes que qualquer coisa seja executada.
- 03
Plan
Mostre as mudanças estruturais que um apply faria.
- 04
Apply
Execute o plano, criando o que está faltando.
- 05
Verify
Compare o workspace com a estrutura esperada.
Saída do plano
Um plano compara a estrutura declarada com o que está em disco e imprime a diferença. Ele não altera nada. Diretórios que já correspondem são reportados como keep e permanecem intactos.
Um diretório presente no workspace mas ausente da especificação — aqui build/ — é reportado como undeclared. O apply não o cria nem o remove. O plano não nomeia nenhuma operação que o engine não vá executar.
.orvienm.yaml
version: 1
structure:
name: platform
directories:
- core
- data
- docsPlano
$ orvienm plan .orvienm.yaml
Orvienm Plan
────────────────────
= keep core/
= keep data/
= keep docs/
? undeclared build/
Plan Summary
────────────────────
Create: 0
Keep: 3
Undeclared: 1A sintaxe completa dos comandos, as opções e os fluxos estão na Referência da CLI.
Mutação conservadora
O engine cria o que a especificação declara e está faltando. Ele não apaga um caminho apenas porque a especificação não o menciona.
Isso importa porque um workspace raramente pertence a um único sistema. Saídas de build, diretórios temporários locais e arquivos de outras ferramentas convivem com a estrutura que o Orvienm governa. Tratar “ausente da especificação” como “não deveria existir” tornaria o engine inseguro para apontar a um workspace real.
Portanto, itens extras inesperados são preservados. O que o engine não governa, ele deixa em paz.
Verify e convergência
Aplicar uma estrutura uma vez não diz nada sobre ela continuar valendo. O verify compara o workspace com a estrutura que a especificação declara e aponta onde os dois divergem.
Um workspace convergiu quando a verificação não encontra diferença entre a estrutura declarada e o estado em disco. Onde houver diferença, essa diferença é desvio — relatado, não reparado silenciosamente. O que fazer a respeito é uma decisão de governança.
Por que isso se sustenta
Determinismo
A mesma especificação sobre o mesmo estado produz o mesmo plano, em qualquer máquina e em qualquer ambiente.
Previsibilidade
Nada é aplicado sem ter sido mostrado antes. O plano é a descrição do trabalho, não uma estimativa dele.
Segurança
O engine cria o que está faltando e não toca no que não governa. Nada é removido por não ter sido declarado.