Detailed design records
The design section explains the current model in topic order. Repository design records preserve the investigations, measurements and revisions behind it. They are useful for understanding why an interface exists, but several retain superseded proposals before later sections describe what was actually built.
Start with the current path
For an application, read the practical guide and the current operation/source contract first. For example, PlanBuilder, BlockOp, FragmentOp and execute_phases define today’s assembly and execution interfaces. Then use the records to understand a tradeoff or limitation in that implementation.
| Subject | Record and useful question |
|---|---|
| Practical pipeline map | GUIDE.md: which API implements this pattern? |
| Operation contracts and branching | Writing an op: what must a branch or combine declare? |
| Storage, progress and execution | Executing a run: how do storage and observation attach to execution? |
| Synchronization and reduction | Barriers: why separate waiting for evidence from fetching pixels? |
| Within-block parallelism | Intra-block threading: when does extra slicing pay for its halo work? |
| Cache/prefetch investigation | Cache and prefetch: what must a claimed cache benefit measure? |
| Distributed placement | Distributed locality: how does placement affect repeated fetches? |
| Simulation versus execution | Simulator fidelity: which cost must reflect actual allocations and work? |
| Metadata-first work | Task preparation: when can a task complete without pixel reads? |
| Physical sampling | Point sampling: how are source workspaces and read budgets declared? |
Read status and later corrections together
The barrier record begins with a dependency/read coupling that motivated new contracts, then records the implementation and corrections. Reading only its opening would incorrectly describe the old limitation as the current design. Similarly, the cache investigation’s opening and a present storage adapter can refer to different stages of integration. A design record is evidence of that sequence; it should not be flattened into a timeless feature list.
A performance figure also retains its measurement conditions. The intra-block record reports machine load and arithmetic amplification because a thread-count ratio without those conditions can misidentify the bottleneck. Carry that scope when using its result to explain a design choice.
Use a record to answer a focused question
For a new operation, first specify the owned output, numerical boundary policy, required source windows and live workspace. Decide whether its state is an image, a small shared calibration or a larger global structure. Then choose an interface that expresses those facts. An existing record can explain why a seemingly simpler alternative failed, such as using pixel halos to force a global synchronization or treating a changed visit order as storage fusion.
When the record and current source disagree, inspect the implementation and its tests before copying a claim into user documentation. Keep the website focused on the resulting behavior, and link the historical argument here for readers who need its measurements and rejected alternatives.