ADR-0005: Branch (definition) early, Scenario (state) deferred

Status

Accepted

Date

2026-06-24

Context

The pack treats Branch and Scenario as Universe-level overlays, but they differ wildly in cost:

Branch = a definition/schema/code/policy overlay. Git-for-the-ontology. Tractable, and needed early because the engineering process (RFC → … → migration) and the Value Types model (ADR-0007) both assume schema changes can be tested off-main before merge.
Scenario = a hypothetical operational-state overlay across potentially millions of entities. This requires copy-on-write delta storage plus a read-time merge of base + overlay under every RealityContext — taxing every read path. It is one of the hardest things to build well.

The first proof lifecycle (plan → build package → survey → evidence → approve as-built → reconcile → writeback → close) needs no scenario. Scenarios appear only as fiber-cut-sector-44 — a SmartOps blast-radius simulation, a later module.

Decision

Split them.

Branch (definition overlay) is in scope from the kernel skeleton — required for safe schema evolution.
Scenario (operational-state overlay) is deferred past the first proof lifecycle. Its mechanism (copy-on-write delta tables merged at read-time) may be validated in isolation (POC 9), but it must not gate the operational loop and must not tax the operational read paths in the proof.

Alternatives Considered

Both first-class from day one

Full branch + scenario overlay engine in the skeleton; every read resolves branch/scenario.

Rejected: biggest moat if it lands, but it makes every read path more expensive from the start and is far too much for a 2–3 person proof.

Branch only, drop Scenario entirely

Use a cloned sandbox Universe for what-ifs instead of overlays.

Viable later fallback. Not chosen now because scenario-as-overlay is a likely SmartOps differentiator; we defer, not delete.

Neither in the kernel

Plain migrations + cloned Universe for what-ifs.

Rejected: schema evolution genuinely benefits from definition branches given our RFC→migration process and Value Type versioning.

Consequences

The skeleton implements definition branching; the operational read path stays free of scenario-merge cost.
When scenarios arrive, they must prove they don’t regress operational read p95 — the deferral is also a performance guardrail.
Interacts with ADR-0007: branches are where Value Type version changes are tested before merge.