Background

Context that doesn't belong in any single subsystem page: design decisions, pitfalls, and historical migrations whose influence is still visible in the code.

This section is curated, not exhaustive. For the chronological story of the codebase, see lore.

Pages

• Design decisions — the load-bearing choices: the graph engine, the plug-in protocol, the HCL2 type system, why state and plans are versioned files, why providers are out of process.
• Pitfalls — places where the obvious change is the wrong one. Marks, deferred actions, the difference between configuration and state addresses, parallelism in the walker.
• Migration context — why internal/legacy/ exists, why two plug-in protocol versions coexist, why the cloud and remote backends are mostly the same code.