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.