Product / Engine
The engine that executes structure
Orvienm reads a declarative specification, checks it, works out exactly which paths are missing, applies them, and then verifies the result against what was declared.
Overview
The engine operates above the filesystem. It does not watch it, and it does not own everything inside it. It is given a specification describing the structure a workspace should have, and it reconciles the workspace toward that structure through a sequence of explicit stages.
Every stage is separable. Validation can run without planning, and a plan can be produced and read without applying anything.
Execution lifecycle
Each stage has a single responsibility, and no stage is skipped on the way to the filesystem.
- 01
Define
Declare the structure the system should have.
- 02
Validate
Check the specification before anything is executed.
- 03
Plan
Show the structural changes an apply would make.
- 04
Apply
Execute the plan, creating what is missing.
- 05
Verify
Compare the workspace against the expected structure.
Plan output
A plan compares the declared structure against what is on disk and prints the difference. It changes nothing. Directories that already match are reported as keep and left untouched.
A directory present in the workspace but absent from the specification — here build/ — is reported as undeclared. Apply neither creates nor removes it. The plan names no operation the engine will not perform.
.orvienm.yaml
version: 1
structure:
name: platform
directories:
- core
- data
- docsPlan
$ orvienm plan .orvienm.yaml
Orvienm Plan
────────────────────
= keep core/
= keep data/
= keep docs/
? undeclared build/
Plan Summary
────────────────────
Create: 0
Keep: 3
Undeclared: 1Full command syntax, options and workflows are in the CLI Reference.
Conservative mutation
The engine creates what the specification declares and is missing. It does not delete a path merely because the specification does not mention it.
This matters because a workspace is rarely owned by one system. Build output, local scratch directories and files belonging to other tools sit alongside the structure Orvienm governs. Treating “absent from the specification” as “should not exist” would make the engine unsafe to point at a real workspace.
So unexpected extras are preserved. What the engine does not own, it leaves alone.
Verify and convergence
Applying a structure once says nothing about whether it still holds. Verify compares the workspace against the structure the specification declares and reports where the two disagree.
A workspace has converged when verification finds no difference between the declared structure and the state on disk. Where they differ, that difference is drift — reported, not silently repaired. What to do about it is a governance decision.
Why it holds
Determinism
The same specification against the same state produces the same plan, on any machine and in any environment.
Predictability
Nothing is applied that was not shown first. The plan is the description of the work, not an estimate of it.
Safety
The engine creates what is missing and leaves what it does not own untouched. Nothing is removed because it was not declared.