test: fixed three-level/two-region nested shear preset (nested_shear_n128)

Test-only opt-in. New shear_nested.py: fixed parent-frame rectangles
(L0->L1 (16,16,60,112),(68,24,112,120); L1->L2 (44,44,108,212),
(148,60,212,228)), exact leaves/hops/work/nu/tau, depth-3 + 4N-finest
generalization of the shear assessment (same summaries/screens/budgets),
bounded final macro snapshot writer/reader (packed ACTIVE leaves + rho/u,
metadata, sha256, 8 MiB cap; no populations/restart/time series).
run_case: --diagnostic nested_shear_n128 (U128, U512, constant/projected
R128 depth 3), --final-snapshot only for projected depth 3, shear_nested.py
path+hash pin. assess_shear_wave: assess_nested contract and CLI.
shear_wave.py and oracle.py byte-identical; old guards/defaults unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/validation/taylor_green/run_case.py

@@ -21,6 +21,8 @@ INITIALIZATION = "physical FP64 equilibrium G at actual cell centers; rho=1+3p"
 SHEAR_WAVE_SHA256 = "81d5c8ee60864372887cddf9239580c82fb6750d956038f1e3ee9de61aa4e877"
 SCALED_DIAGNOSTIC = "scaled_n256"
 SCALED_SHEAR = "scaled_shear_n256"  # mutually exclusive with scaled_n256 (one flow each)
+NESTED_SHEAR = "nested_shear_n128"  # fixed three-level/two-region shear preset
+SHEAR_NESTED_SHA256 = "fa6cfe87fb4df8c6d732c637c885276833c81973b950c7724d734f8fc350bcb0"
 
 
 def flow_functions(flow="taylor_green"):
@@ -109,7 +111,14 @@ def verify_source(repo, revision, flow="taylor_green"):
     if result["source_tree_sha256"] != SOURCE_SHA256:
         raise RuntimeError("Wrong numerical source fingerprint")
     result["build_capture_sha256"] = BUILD_CAPTURE_SHA256
-    if flow == "shear_wave":
+    if flow == "shear_nested":
+        import shear_nested
+        module = harness / "shear_nested.py"
+        if (Path(shear_nested.__file__).resolve() != module
+                or hashlib.sha256(module.read_bytes()).hexdigest() != SHEAR_NESTED_SHA256):
+            raise RuntimeError("Wrong shear_nested module checkout or content")
+        result["shear_nested_sha256"] = SHEAR_NESTED_SHA256
+    if flow in ("shear_wave", "shear_nested"):
         import shear_wave
         module = harness / "shear_wave.py"
         if (Path(shear_wave.__file__).resolve() != module
@@ -182,21 +191,35 @@ def main():
     p.add_argument("--depth", type=int, choices=[1, 2, 3], required=True)
     p.add_argument("--output", type=Path, required=True)
     p.add_argument("--explosion", choices=["constant", "projected_linear"], default="constant")
-    p.add_argument("--diagnostic", choices=[SCALED_DIAGNOSTIC, SCALED_SHEAR],
+    p.add_argument("--diagnostic", choices=[SCALED_DIAGNOSTIC, SCALED_SHEAR, NESTED_SHEAR],
                    help="explicit four-case N256/fine512 same-placement diagnostic "
-                        "(scaled_n256: Taylor-Green; scaled_shear_n256: shear wave)")
+                        "(scaled_n256: Taylor-Green; scaled_shear_n256: shear wave) or the "
+                        "fixed three-level/two-region shear preset (nested_shear_n128)")
+    p.add_argument("--final-snapshot", action="store_true",
+                   help="nested_shear_n128 projected depth-3 only: final macro snapshot")
     p.add_argument("--early-pressure", action="store_true",
                    help="also save 65 scalar pressure samples at t*=k*.001875, k=0..64")
     p.add_argument("--flow", choices=["taylor_green", "shear_wave"], default="taylor_green")
     args = p.parse_args()
-    if args.flow == "shear_wave" and (args.re != 100 or args.depth == 3 or args.early_pressure):
+    nested = args.diagnostic == NESTED_SHEAR
+    if args.flow == "shear_wave" and (args.re != 100 or (args.depth == 3 and not nested)
+                                      or args.early_pressure):
         p.error("shear_wave requires --re 100, depth 1 or 2 and no --early-pressure")
+    if args.final_snapshot and not (nested and args.depth == 3
+                                    and args.explosion == "projected_linear"):
+        p.error("--final-snapshot requires nested_shear_n128 projected depth 3")
     initial, metrics, limits, initialization = flow_functions(args.flow)
     if args.output.exists():
         p.error("Output already exists; choose a new path to retain prior evidence")
-    if args.explosion != "constant" and args.depth != 2:
+    if args.explosion != "constant" and args.depth != 2 and not nested:
         p.error("projected_linear requires depth 2")
-    if args.diagnostic:
+    if nested:
+        import shear_nested
+        if args.flow != "shear_wave":
+            p.error(f"--diagnostic {NESTED_SHEAR} requires --flow shear_wave")
+        if (args.re, args.n, args.depth, args.explosion) not in shear_nested.CASES:
+            p.error("nested_shear_n128 requires one of its four Re100 cases")
+    elif args.diagnostic:
         cases = {(256, 1, "constant"), (512, 1, "constant"),
                  (256, 2, "constant"), (256, 2, "projected_linear")}
         flow = "shear_wave" if args.diagnostic == SCALED_SHEAR else "taylor_green"
@@ -209,13 +232,13 @@ def main():
         if args.diagnostic == SCALED_SHEAR and (args.n, args.depth, args.explosion) not in cases:
             p.error("scaled_shear_n256 requires one of its four Re100 cases")
     elif args.n == 512:
-        p.error("N512 requires --diagnostic scaled_n256 or scaled_shear_n256")
+        p.error("N512 requires --diagnostic scaled_n256, scaled_shear_n256 or nested_shear_n128")
     selected = os.environ.get("CUDA_VISIBLE_DEVICES", "")
     if not args.dry_run and (not args.run_gpu or not selected or "," in selected or selected == "-1"):
         p.error("--run-gpu and exactly one explicit CUDA_VISIBLE_DEVICES are required")
     repo = args.repo.resolve()
     sys.path[:0] = [str(repo / "src"), str(repo)]
-    source = verify_source(repo, args.expected_revision, args.flow)
+    source = verify_source(repo, args.expected_revision, "shear_nested" if nested else args.flow)
     runtime = runtime_source(repo)
     if args.dry_run:
         print(json.dumps(dict(source=source, runtime_source=runtime, dry_run=True,
@@ -229,7 +252,12 @@ def main():
     from CelerisLab.lbm.hierarchy import build_hierarchy, leaf_partition
 
     cfg = config(args.n, args.re)
-    refinements = [] if args.depth == 1 else rectangles(args.n, args.depth)
+    if args.depth == 1:
+        refinements = []
+    elif nested:
+        refinements = [list(level) for level in shear_nested.REFINEMENTS]
+    else:
+        refinements = rectangles(args.n, args.depth)
     h = build_hierarchy(cfg, refinements)
     np.testing.assert_array_equal(leaf_partition(h), np.ones((args.n, args.n)))
     masks = [k == ACTIVE for k in h.kinds]
@@ -317,6 +345,13 @@ def main():
                     initial_mass = row["mass"]
                 if step in main_steps:
                     report["rows"].append(row)
+                if args.final_snapshot and step == main_steps[-1]:
+                    # Optional macro-only snapshot; scalar receipt stays authoritative.
+                    report["final_snapshot"] = shear_nested.write_snapshot(
+                        args.output.with_name(args.output.stem + ".final_macro.npz"),
+                        run.download(), masks,
+                        shear_nested.snapshot_meta(step, cfg.viscosity, args.explosion,
+                                                   source.get("revision")))
                 if step in early_steps:
                     trace = report["early_pressure"]
                     trace["rows"].append({key: row[key] for key in ("step", "tstar", "pressure_l2")})