Correctness contracts

Blockflow’s checks make execution geometry reviewable, but they cannot discover an algorithm’s undeclared dependency by inspecting its arithmetic. Correctness comes from a chain of explicit contracts: the operation tells the truth, the plan provisions it, the graph orders its producers, and the executor publishes only valid owned outputs.

flowchart TB
  A["Operation: true dependencies and types"] --> B["Plan: sufficient source geometry"]
  B --> C["Graph: producers cover each read"]
  C --> D["Executor: wait, compute and commit valid output"]
  D --> E["Independent numerical and seam tests"]
Figure 1: Each layer checks a different claim. A later layer cannot repair a missing algorithm requirement.

Dependency declarations are scientific claims

BlockOp::reach and BlockOp::reach_spec state what the algorithm needs beyond an output position. They must be derived from the kernel and its parameters, independently of the halo selected by the plan. If an implementation reads three neighbors but declares one, a plan that faithfully supplies one can still produce a complete, plausible, wrong image.

The geometry check can detect a granted halo narrower than the declared reach. It cannot detect a declaration that understates the real kernel. That last claim needs a mathematical derivation and numerical tests. A finite Gaussian support, derivative radius, interpolation footprint or convolution support should be calculated from the exact implementation, including rounding and truncation.

Additional operands must be declared with SourceInput or represented by an explicit source leaf. Fetching an unplanned image from inside a kernel would hide producer dependencies, buffer lifetimes and resource costs from the plan. Dtype acceptance and production likewise belong in the contract: successful allocation does not prove that a kernel implements integer labels or floating intensity with the requested semantics.

Valid output is a geometric property

BlockGeometry distinguishes a core, read region and valid output. A kernel may calculate its entire supplied buffer, but only the region with satisfied dependencies may be committed. Across a phase, those valid outputs must cover the intended domain exactly. boxes_tile_exactly checks the partition rather than trusting that a caller’s nominal block size implies complete coverage.

Internal block edges are not true image boundaries. A clamped derivative can be well defined at the outer face of an image and still be wrong if it clamps at every tile seam. The operation’s Anchor preserves where the buffer lies in the global domain so the same boundary policy can apply consistently.

Mapped source geometry needs equivalent care. A consumer on a different grid must wait for every producer region covering its actual source footprint. TaskGraph checks those dependencies per image; producer block indices need not match consumer block indices.

Order, global state and fixed points

A reduction must see every contribution it promises to use. FragmentOp::barrier is a binding ordering property, while SchedulePriority only ranks already ready tasks. Substituting phase-major preference for a barrier can produce an answer that depends on which worker happened to finish first.

Coverage distinguishes a complete stream containing empty block contributions from one in which required contributions were never written. SeamFold makes order-independence claims explicit. Floating-point accumulation can change with partition and traversal even when an algebraic sum looks associative; use an accumulator and contract suited to the required reproducibility.

IterativeOp adds a temporal contract. Every substage reads a consistent previous state, and the next state becomes visible only after its blocks finish. A fixed iteration count is not a proof of a fixed point. The executor’s SubstageLimit guards runaway work and returns failure when the operation has not converged. The iteration page explains which operations use that route and why tile-local convergence is insufficient.

Safe shortcuts need stronger declarations

A uniform block can be skipped only when every relevant operation declares the correct BlockOp::constant_maps_to result over the supplied read extent. A zero core with nonzero halo is not necessarily a uniform input to a stencil. Likewise, missing metadata is not a proof that an object region is empty.

FragmentOp::prepare can avoid pixel work using declared summaries, but its completed output must still satisfy pixel and fragment coverage. A shortcut is part of the algorithm’s contract, not a scheduler guess based on values that were never read.

Slicing is another independent promise. A kernel with bounded reach may still carry scan state and be unsafe to cut inside one block. IterativeOp::stationary permits dirty-block skipping only when repeated unchanged operand windows produce unchanged results regardless of substage index. A false declaration of safe slicing or stationarity can preserve plausible output shapes while changing values.

Tests should target the possible wrong answers

Use an independent resident or mathematical oracle on a small enough fixture. Then vary block shape, seam placement, worker count and legal scheduling policy. Include true edges, anisotropic dimensions, extra inputs and invalid samples. An identity transform or all-zero image alone can let a broken halo pass vacuously; include features deliberately crossing seams.

For a radius-two filter followed by a radius-one filter, test both the correctly composed radius-three dependency and an intentionally insufficient grant. For a fixed point, include a propagation corridor crossing several blocks and an oscillating rule that must reach the guard. For branch and fragment reductions, change traversal order as well as block boundaries.

Bitwise identity is a strong and appropriate requirement when arithmetic order is unchanged. When a solver or reduction intentionally changes floating-point order, use an independently justified tolerance or task-specific metric and state the convention. Performance measurements are useful only after those output controls pass, and Rust measurements use release builds.