Compile zero padding ahead of a convolution as a sampling phase, validated live

CONTRIBUTING.md

@@ -81,7 +81,9 @@ tag `research-archive-2026-10-12` ([history](docs/history/README.md)).
      `NOT_LIVE` for "Fixed — offline only". Name settings by the parameters of the block, its
      cost functions or its constants builder (the record's `sources`), and add the block to
      [`tests/test_x02b_validated_settings.py`](tests/test_x02b_validated_settings.py)'s
-     allowance tables only with a reason;
+     allowance tables only with a reason. A new setting on an existing block enters that
+     block's record at its default value, the one value its evidence ran, until a live run
+     varies it; a call at any other value is then reported outside the record;
    - `per_setting`, where a radius or chip-edge dependence depends on a setting
      (`window_resize`, `patch_embed`).
 4. **Add offline tests.** Build the block's graph against the offline signatures and

docs/api.md

@@ -54,7 +54,27 @@ full window (9), as PyTorch's zero padding does; `False` divides by the number o
 in-bounds pixels.
 
 Convolution uses odd same-padded kernels, stride 1/2, dilation 1 and zero padding
-mode. Groups=1 retains the existing `conv2d` block. Groups greater than one route
+mode. A convolution is an `nn.Conv2d` module or `F.conv2d` (`torch.conv2d`) whose weight
+and bias are the model's own parameters or buffers, read only by that call. Zero padding
+directly ahead of it, as `nn.ZeroPad2d`, `nn.ConstantPad2d` with value 0 or `F.pad` with
+a static four-integer pad, mode `"constant"` and value 0 or None, adds to the
+convolution's own padding; an `nn.Identity` directly ahead of `F.conv2d` is absorbed too.
+On each axis the total padding before the input must be `kernel // 2 - phase` with
+`0 <= phase < stride`, and PyTorch's output count at the input size must be
+`ceil((n - phase) / stride)`. Phase 0 is the same-padded convolution and compiles to its
+existing graph; a nonzero phase (for example `(0, 1, 0, 1)` ahead of a 3 × 3 stride-2
+convolution) runs the same block, sampling input pixel `stride * i + phase`
+(the blocks' keyword-only `phase`, an integer or a `(phase_y, phase_x)` pair). A
+nonzero phase is validated live on small fixtures at stride 2: an ordinary 3 × 3
+convolution at phase 1, and depthwise 3 × 3 at phases 1 and `(1, 0)` and 5 × 5 at
+phase 1; other kernels and phases are not validated. Refused: padding computed from a
+tensor's shape, negative pads, other `F.pad` lengths, nonzero values, reflection,
+replication and circular padding, a padding node with any other use, a total padding
+whose phase is outside `[0, stride)` or whose output count is not
+`ceil((n - phase) / stride)` (an unpadded stride-1 convolution, for example), and
+functional weights that are computed or shared. An unpadded 3 × 3 stride-2 convolution
+on an odd-sized map is the phase-1 form and compiles; on an even-sized map it is
+refused. Groups=1 retains the existing `conv2d` block. Groups greater than one route
 to `grouped_conv2d`, including depthwise convolutions and channel multipliers;
 groups must divide both channel counts. The grouped block is validated live for
 depthwise 3 x 3 at strides 1/2 with optional bias, depthwise 5 x 5 at stride 1, and

docs/building-blocks.md

@@ -132,8 +132,8 @@ their own.
 | [`eval_dropout`](../tensor_ee/blocks/raster/activations.py) | R → R | pointwise | `float32_operands` | no | Ready | [evidence/t02-operators.json](evidence/t02-operators.json); [evidence/t05-primary.json](evidence/t05-primary.json) |
 | [`common_score_mask`](../tensor_ee/blocks/raster/activations.py) | R → R | pointwise | `float32_operands` | no | Ready | [evidence/t03-outputs.json](evidence/t03-outputs.json) |
 | [`softmax`](../tensor_ee/blocks/raster/activations.py) | R → R | pointwise | `float32_operands` | no | Ready | [evidence/t03-outputs.json](evidence/t03-outputs.json); [evidence/t05-primary.json](evidence/t05-primary.json) |
-| [`grouped_conv2d`](../tensor_ee/blocks/raster/conv.py) | R → R | k×k, radius 2 | `float32_operands` | no | Ready — depthwise 3×3 stride 1 or 2, 5×5 stride 1; 3×3 stride 1 with 2 channels per group or channel multiplier 2 | [evidence/raster-grouped-conv-offline.json](evidence/raster-grouped-conv-offline.json); [evidence/live-fixtures/20261029T125301Z-grouped_conv.json](evidence/live-fixtures/20261029T125301Z-grouped_conv.json) |
-| [`conv2d`](../tensor_ee/blocks/raster/conv.py) | R → R | k×k, radius 3 | `float32_operands` | no | Ready | [cnn/results/parity.json](history/cnn/results/parity.json); [cnn/results/primitives_float32.json](history/cnn/results/primitives_float32.json); [cnn/results/resnet_primitives.json](history/cnn/results/resnet_primitives.json); [cnn/results/resnet18_full64_float32_policy.json](history/cnn/results/resnet18_full64_float32_policy.json); [cnn/results/segwater_js_parity_1x1.json](history/cnn/results/segwater_js_parity_1x1.json); [cnn/results/tiled_resnet18_2x2_parity.json](history/cnn/results/tiled_resnet18_2x2_parity.json) |
+| [`grouped_conv2d`](../tensor_ee/blocks/raster/conv.py) | R → R | k×k, radius 3 | `float32_operands` | no | Ready — depthwise 3×3 stride 1 or 2, 5×5 stride 1 or 2; 3×3 stride 1 with 2 channels per group or channel multiplier 2 | [evidence/raster-grouped-conv-offline.json](evidence/raster-grouped-conv-offline.json); [evidence/live-fixtures/20261029T125301Z-grouped_conv.json](evidence/live-fixtures/20261029T125301Z-grouped_conv.json); [evidence/raster-padded-conv-offline.json](evidence/raster-padded-conv-offline.json); [evidence/live-fixtures/20261112T185127Z-padded_conv.json](evidence/live-fixtures/20261112T185127Z-padded_conv.json) |
+| [`conv2d`](../tensor_ee/blocks/raster/conv.py) | R → R | k×k, radius 3 | `float32_operands` | no | Ready | [cnn/results/parity.json](history/cnn/results/parity.json); [cnn/results/primitives_float32.json](history/cnn/results/primitives_float32.json); [cnn/results/resnet_primitives.json](history/cnn/results/resnet_primitives.json); [cnn/results/resnet18_full64_float32_policy.json](history/cnn/results/resnet18_full64_float32_policy.json); [cnn/results/segwater_js_parity_1x1.json](history/cnn/results/segwater_js_parity_1x1.json); [cnn/results/tiled_resnet18_2x2_parity.json](history/cnn/results/tiled_resnet18_2x2_parity.json); [evidence/raster-padded-conv-offline.json](evidence/raster-padded-conv-offline.json); [evidence/live-fixtures/20261112T185127Z-padded_conv.json](evidence/live-fixtures/20261112T185127Z-padded_conv.json) |
 | [`concatenate`](../tensor_ee/blocks/raster/merge.py) | R → R | pointwise | `float32_operands` | no | Ready | [cnn/results/parity.json](history/cnn/results/parity.json); [cnn/results/resnet18_full64_float32_policy.json](history/cnn/results/resnet18_full64_float32_policy.json); [cnn/results/segwater_js_parity_1x1.json](history/cnn/results/segwater_js_parity_1x1.json) |
 | [`residual_add`](../tensor_ee/blocks/raster/merge.py) | R → R | pointwise | `float32_operands` | no | Ready | [cnn/results/resnet_primitives.json](history/cnn/results/resnet_primitives.json); [cnn/results/resnet18_full64_float32_policy.json](history/cnn/results/resnet18_full64_float32_policy.json); [cnn/results/segwater_js_parity_1x1.json](history/cnn/results/segwater_js_parity_1x1.json) |
 | [`multiply`](../tensor_ee/blocks/raster/merge.py) | R → R | pointwise | `float32_operands` | no | Ready — same grid on a 5 × 7 map; one-pixel gate on 5 × 7 and 12 × 20 maps | [evidence/raster-global-pool-multiply-offline.json](evidence/raster-global-pool-multiply-offline.json); [evidence/live-fixtures/20261112T151417Z-global_pool_multiply.json](evidence/live-fixtures/20261112T151417Z-global_pool_multiply.json) |
@@ -450,7 +450,7 @@ generated list cannot drift from the code.
 | Core | [`tensor_ee.core.precision`](../tensor_ee/core/precision.py) | Precision policies, and how float32 values enter an Earth Engine graph. | `validate_policy`, `exact_scalar`, `encode_float32`, `constant_value` |
 | Core | [`tensor_ee.core.tensor`](../tensor_ee/core/tensor.py) | Tensor carriers: R (`Raster`) and W (`WindowTensor`), plus `Feature`. | `band_names`, `ServerArray`, `Raster`, `WindowTensor`, `Feature`, `same_grid` |
 | Layouts | [`tensor_ee.layouts.boundaries`](../tensor_ee/layouts/boundaries.py) | Stage boundaries: how saved images enter a stage's graph and how its outputs leave it. | `grid_view`, `pin_boundary`, `saved_image`, `boundary_windows`, `boundary_raster`, `relabel_to_windows`, `relabel_from_windows` |
-| Layouts | [`tensor_ee.layouts.raster`](../tensor_ee/layouts/raster.py) | R-layout converters: pinning, zero extension, stride sampling, embedded fixtures. | `project`, `finish`, `zero_extended`, `stride_sample`, `from_image`, `stride_sample_phase`, `embedded_raster` |
+| Layouts | [`tensor_ee.layouts.raster`](../tensor_ee/layouts/raster.py) | R-layout converters: pinning, zero extension, stride sampling, embedded fixtures. | `project`, `finish`, `zero_extended`, `phase_pair`, `canonical_phase`, `stride_sample`, `sample_grids`, `from_image`, `stride_sample_phase`, `embedded_raster` |
 | Layouts | [`tensor_ee.layouts.shift`](../tensor_ee/layouts/shift.py) | W-layout translation, Swin's cyclic shift, periodic extension and domain masks. | `timm_shift`, `projection`, `translate`, `materialize`, `cyclic_neighbor`, `roll_axis`, `roll_windows`, `shift_windows`, `unshift_windows`, `periodic_extension`, `domain_mask` |
 | Layouts | [`tensor_ee.layouts.window`](../tensor_ee/layouts/window.py) | R <-> W converters, halos and im2col. | `as_row`, `flatten_row`, `stride_samples`, `stack_tokens`, `to_windows`, `from_dense`, `depth_to_space`, `to_dense`, `zeros`, `reshape`, `zero_outside`, `check_crop`, `same_crop`, `neighbours`, `halo`, `taps`, `im2col` |
 | Weights | [`tensor_ee.weights.assets`](../tensor_ee/weights/assets.py) | The FeatureCollection weight-asset format and its provider. | `ConvolutionWeights`, `convolution_weights`, `feature_records`, `FeatureCollectionWeightProvider` |