Architecture contracts
Patterns, alternatives and evidence
These patterns connect a decision to its implementation and to a check that can disprove it. Each name links to the detailed section; results describe documented tests, not guarantees for any scene or hardware.
The same policy guides simulation, GPU work and authoring: declare access, centralize derived values and make lifetimes explicit. I prefer a dependency the compiler can check to a rule that requires remembering every consumer.
| Pattern | Where it lives | Alternative avoided | Evidence in the measured scenario |
|---|---|---|---|
| The renderer plans; the backend executes | Render/RenderGraph / RHI/D3D12/DxRenderGraphExecutor | A graph that records commands | 242 plan checks without a device. |
| A single ECS/render handoff | RenderExtractionSystem to RenderScene | Renderer reading the live World | Adding 100,000 entities without a mesh preserves instance counts and upload bytes. |
| Null backend as a build solution | Tessera.NoD3D12.sln | Isolation supported only by #ifdef or text searches | Zero Dx*.obj objects in all four configurations of the solution without D3D12. |
| Generational handles | RHI/Handles.h | A pointer or ComPtr in a component | Nine handle tags; a PSO retired by hot reload causes a skipped draw, without a dangling reference. |
| Declared access and a hazard DAG | SystemDescriptor, AccessAuditor | Locks inside the ECS | Zero mutexes in ECS/; 32 systems: 0.68 µs at 10,000 entities and 0.86 µs at one million. |
| Deferred structural changes | CommandBuffer, PlaybackCommands | Mutating components during iteration | In the test, 1,000 entities produce one archetype transition. |
| Versions for dirty state; hashes for restoration | TransformState, WorldSnapshot | Boolean flags as the sole validity source | In the measured stationary frame, GPU Scene receives 0 upload bytes. |
| One producer per derived value | CanonicalCookedKey, ComputeSceneRect | Recomputing identity or rectangles in each consumer | A shared canonical key; a recomputed key caused a magenta scene in the recorded diagnostic. |
| Composition with explicit contexts | DxFramePassContext | A god class or inheritance-based extension | 85/85 virtual functions preserved across 12 verified module extractions. |
| Defaults preserve behavior | QualitySettings, EffectToggle | Applying a quality profile without a request | Without a flag, the acceptance comparison has 0 differing pixels out of 1,440,000. |
| Provenance and identity inside the data | PROV, IDNT | An external manifest or path-based identity | 102 ms scan versus 316 s recook in the measured project; UUID preserved in IDNT. |
| Instrument before accepting | --*-probe | Trusting a green build alone | A post-build verifier checks runtime DLLs and shaders; probes exercise individual features. |
