Pipeline architecture

Stages

socotra.yaml  →  Parser  →  StateReader  →  DiffEngine  →  PlanEngine  →  Executor
(YAML)            (Parse)    (Scan FS)        (Detect Drift)  (Order Steps)   (Apply)

Each stage is an independent .NET project. Stages do not call each other directly; they are composed.

• Parser — deserializes YAML into a typed in-memory model.
• StateReader — scans the filesystem for the actual solution, projects, packages, and template files.
• DiffEngine — computes the unordered set of differences between desired and actual state.
• PlanEngine — orders the diff into a safe, dependency-correct execution plan.
• Executor — runs the plan with progress, rollback, and atomic file writes.

The Result monad

All cross-stage data flows as Result<T> — success carries a value, failure carries an error string. This keeps error handling explicit and removes hidden exceptions from the happy path. The built-in result-pattern template exposes the same idea to your generated code.