small fixes 2026-08-17 (4): shipped S2 pyramid opt-out, deliberate shardmap re-pin driver

src/zagg/configs/sentinel2_l2a.yaml

@@ -38,6 +38,14 @@ output:
   # int64 microseconds cannot state and a toc word can. Output-defining: a
   # store born on toc is a different product from a legacy-axis one.
   time_encoding: toc
+  # Overview family OFF, declared rather than left absent (issue #459): an
+  # absent key means the every-2-orders default is ON (`get_pyramid` -> {}), so
+  # every raster run dispatches a rollup sweep whose overview family generates
+  # nothing -- raster fields have no fold law (issue #399 ruled option (b), a
+  # raster column writer, and it is unimplemented; raster leaves stay
+  # column-less by construction, PR #416 phase 5). Mirrors the benchmark leg's
+  # opt-out in tests/data/benchmark/configs/s2_neon_o9.yaml (issue #201).
+  pyramid: false
   grid:
     type: healpix
     parent_order: 11

tests/data/benchmark/README.md

@@ -179,6 +179,20 @@ places the panel.
    print(bench_metrics.select_densest_shard(sm))   # -> (shard_key, n_granules)
    ```
 
+   > **Re-pinning a map that already exists** is one command:
+   > `tools/repin_benchmark_shardmaps.py` (issue #444) rebuilds through the
+   > drift check's own recipe, selects the pin (nested rule included), prunes
+   > the ring maps, and writes the map plus its `targets.json`
+   > `shard_key`/`n_granules`. It re-pins **deliberately** — the drift check
+   > stays the accident detector — so run it only when a convention or grammar
+   > change makes the committed words wrong. `--check` rebuilds and reports the
+   > differences without writing. The entry's `note` is prose: restate it by
+   > hand in the same commit.
+   >
+   > ```bash
+   > uv run python tools/repin_benchmark_shardmaps.py --check healpix_o9_88s
+   > ```
+
    > **The committed maps span two granule-record schemas.** The five
    > `sm_healpix_*.json` maps were last rebuilt after issue #246, so their
    > granule records carry `time_start`/`time_end` (and their `metadata` a

tests/test_benchmark_shardmap.py

@@ -61,13 +61,13 @@ def resolve_aoi_temporal_cmr(sm_meta: dict) -> tuple[dict, dict, dict]:
     )
 
 
-pytestmark = [
-    pytest.mark.slow,
-    pytest.mark.skipif(
-        os.environ.get("ZAGG_BENCHMARK_DRIFT") != "1",
-        reason="set ZAGG_BENCHMARK_DRIFT=1 to run the CMR shard-map drift check",
-    ),
-]
+#: The network gate is the drift check's own, not the module's (it was
+#: module-level while the drift check was the only test here): the issue #444
+#: re-pin-driver tests below rebuild from the committed catalogs and need no CMR.
+needs_cmr = pytest.mark.skipif(
+    os.environ.get("ZAGG_BENCHMARK_DRIFT") != "1",
+    reason="set ZAGG_BENCHMARK_DRIFT=1 to run the CMR shard-map drift check",
+)
 
 
 def _containing_shard(parent_grid, shard_key: int) -> int:
@@ -101,6 +101,8 @@ def _config_for_shardmap(sm_key: str) -> Path:
     raise AssertionError(f"no target references shardmap '{sm_key}'")
 
 
+@pytest.mark.slow
+@needs_cmr
 @pytest.mark.parametrize("sm_key", list(MANIFEST["shardmaps"]))
 def test_pinned_shardmap_no_drift(sm_key):
     from zagg.catalog import load_polygon, polygon_to_bbox
@@ -170,3 +172,92 @@ def test_pinned_shardmap_no_drift(sm_key):
         f"{sm_key}: densest granule count drifted {pinned_n} -> {n} "
         f"(rebuilt densest shard {key}). Re-pin the shard map + targets.json."
     )
+
+
+# -- the deliberate re-pin driver (issue #444) --------------------------------
+#
+# ``tools/repin_benchmark_shardmaps.py`` is the counterpart of the drift check
+# above: the guard detects an accidental move, the driver makes a deliberate
+# one. It imports the guard's recipe helpers, so these tests pin the parts the
+# guard does not exercise -- the pruning, the pin write-back, and the claim the
+# driver exists to support: that it reproduces the PR #441 artifacts from the
+# committed catalogs.
+
+OFFLINE_PINS = [k for k, v in MANIFEST["shardmaps"].items() if v.get("catalog_parquet")]
+
+
+def _driver():
+    """The re-pin driver, imported from ``tools/`` (not an installed module)."""
+    sys.path.insert(0, str(REPO / "tools"))
+    import repin_benchmark_shardmaps
+
+    return repin_benchmark_shardmaps
+
+
+def _without_volatile(text: str, volatile) -> str:
+    """A written map's text minus the metadata lines a rebuild legitimately moves."""
+    return "".join(
+        line
+        for line in text.splitlines(keepends=True)
+        if not any(f'"{k}"' in line for k in volatile)
+    )
+
+
+@pytest.mark.slow
+@pytest.mark.parametrize("sm_key", OFFLINE_PINS)
+def test_offline_pin_reproduces_committed_map(sm_key, tmp_path):
+    """The driver reproduces the PR #441 artifacts from the committed catalogs.
+
+    The acceptance test issue #444 asks for, and the reason it can only cover
+    the ``catalog_parquet`` (88S ring) entries: the NEON trio rebuilds from CMR
+    by design -- an ATL03 footprint quad blankets the whole NEON box, so a local
+    full-catalog snapshot over-includes (``tests/data/benchmark/README.md``).
+
+    Byte-for-byte over the whole written manifest -- every granule record,
+    ``shard_keys``, ``grid_signature``, and the metadata the build derives --
+    except the two keys a faithful rebuild still moves, which are asserted
+    separately below.
+    """
+    driver = _driver()
+    mapped, key, n = driver.repin(sm_key)
+    sm_meta = MANIFEST["shardmaps"][sm_key]
+    assert (key, n) == (sm_meta["shard_key"], sm_meta["n_granules"])
+
+    written = tmp_path / "rebuilt.json"
+    mapped.to_json(str(written))
+    assert _without_volatile(written.read_text(), driver.VOLATILE_META) == _without_volatile(
+        (BENCH / sm_meta["path"]).read_text(), driver.VOLATILE_META
+    )
+
+    from zagg.config import load_config
+    from zagg.grids import from_config
+
+    # The one live divergence, and why it is not a pin move: PR #447 made the
+    # unpinned HEALPix ``swath`` cover order the SHARD order, where the
+    # committed maps recorded the chunk order they were built at. The
+    # assignment is unchanged -- which is what the byte comparison above just
+    # showed, over the same catalog.
+    grid = from_config(load_config(str(_config_for_shardmap(sm_key))))
+    assert mapped.metadata["mortie_order"] == grid.parent_order
+
+
+def test_repin_updates_only_the_pin_literals_in_targets():
+    # The write-back is surgical because targets.json is hand-formatted (compact
+    # inline ``worker`` objects survive a re-pin); the entry's prose ``note`` is
+    # the re-pinner's to restate, not the driver's to rewrite.
+    driver = _driver()
+    text = (BENCH / "targets.json").read_text()
+    out = driver.update_targets(text, "healpix_o9", 4242, 7)
+
+    entry = json.loads(out)["shardmaps"]["healpix_o9"]
+    assert (entry["shard_key"], entry["n_granules"]) == (4242, 7)
+    assert entry["note"] == MANIFEST["shardmaps"]["healpix_o9"]["note"]
+    changed = [(a, b) for a, b in zip(text.splitlines(), out.splitlines(), strict=True) if a != b]
+    assert len(changed) == 2, changed
+
+
+def test_repin_refuses_an_unknown_shardmap(capsys):
+    driver = _driver()
+    with pytest.raises(SystemExit):
+        driver.main(["--check", "healpix_o42"])
+    assert "unknown shard map(s) ['healpix_o42']" in capsys.readouterr().err

tests/test_raster_runner.py

@@ -966,6 +966,19 @@ def test_sentinel2_l2a_config_loads_and_validates(self):
         assert cfg.data_source["bands"]["scl"]["dtype"] == "uint8"
         assert cfg.output["grid"]["child_order"] == 19
 
+    def test_sentinel2_l2a_config_declares_the_overview_family_off(self):
+        # Issue #459: an ABSENT output.pyramid resolves to the every-2-orders
+        # default schedule (``get_pyramid`` -> ``{}``), so a raster run
+        # dispatches an overview family that generates nothing -- raster leaves
+        # are column-less by construction (issue #399 option (b), unimplemented).
+        # The shipped template declares the opt-out rather than inheriting the
+        # default, and ``None`` is the "family OFF" resolution.
+        from zagg.config import get_pyramid
+
+        cfg = default_config("sentinel2_l2a")
+        assert cfg.output["pyramid"] is False
+        assert get_pyramid(cfg) is None
+
 
 class TestRasterHiveLocalBackend:
     """Local raster hive runs (issue #247 phase 3): manifest, leaves, coverage."""