State-driven workflow

Two states

Socotra reasons about two states at all times: the desired state declared in socotra.yaml, and the actual state observed on the filesystem (projects, solution entries, package references, template files).

The reconciliation cycle

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

The pipeline is unidirectional. Each component is a small, independent module with no circular dependencies, and data flows through the Result<T> monad — success or explicit error, never exceptions across boundaries.

Drift

Drift is any difference between desired and actual state. socotra diff shows raw drift; socotra plan adds ordering and risk classification. Steps are bucketed into three risk levels:

• Low (+ green) — additions: new project, new package, new template application.
• Medium (~ yellow) — modifications: package version bump, target framework change.
• High (− red) — removals: drop a package, remove a project reference, delete a template.

Safety guarantees