#!/usr/bin/env python3 """Freeze the V8 single-factor voxel-resolution protocol (TRAIN72, CPU only).""" from __future__ import annotations import argparse import datetime import importlib.metadata import shutil import subprocess import sys from dataclasses import asdict from pathlib import Path import numpy as np import torch from mcss.mechanism_pilot.geometry_carrier_experiment import read, validate_split from mcss.mechanism_pilot.readout_reanalysis import ( PRIMARY_REFERENCE, READOUTS, REFERENCES, reference_values, ) from mcss.mechanism_pilot.rgbd_evidence_carrier import LOG_SIGMA0 from mcss.mechanism_pilot.rgbd_resolution_carrier import ( BOUNDS_RULE, EXPERIMENT, PRIMARY_PAIR, VARIANT_SPECS, carrier_config, make_carrier, parameter_hash, ) from mcss.mechanism_pilot.small_training import sha, write_json V2 = Path("outputs/EXP-3D-GEOMETRY-AWARE-CARRIER-V2") V3 = Path("outputs/EXP-3D-DENSE-EVIDENCE-CARRIER-V3") V4 = Path("outputs/EXP-3D-PLANE-SWEEP-CARRIER-V4") V5 = Path("outputs/EXP-3D-RGBD-EVIDENCE-CARRIER-V5") V6 = Path("outputs/EXP-3D-RGBD-TRAIN-SCALE-V6") V7 = Path("outputs/EXP-3D-RGBD-DEPTH-BOUNDS-V7") PLAN = "PLAN_BEFORE_V7_RESULTS.md" PLAN_SHA256 = "a228ed812c28181db994b8d535e25cb6b390ff6f0ddd80a739c816b519c33232" BOUNDS_TEXT = { "FROZEN": "context-camera rays cast to the frozen TRAIN prior", "CONTEXT_DEPTH": "hull of the measured context depth and context cameras, anchor " "frame, frozen x1.1 padding, >=1 m", }[BOUNDS_RULE] COUNTS = {"C0": 5150, "C1": 5150, "C2": 5150} SEEDS = [20260928, 20260929, 20260930] THREADS = {"OMP_NUM_THREADS": "1", "OPENBLAS_NUM_THREADS": "1", "MKL_NUM_THREADS": "1"} def seal_previous(root): """Hash every earlier experiment artifact so finalization can prove nothing changed.""" files = {} for base in (Path("outputs"), Path("docs/experiments")): for path in sorted(base.rglob("*")): if path.is_file() and EXPERIMENT not in path.parts: files[str(path)] = {"sha256": sha(path), "bytes": path.stat().st_size} write_json( root / "audit/previous_experiment_seal.json", {"created_utc": datetime.datetime.now(datetime.UTC).isoformat(), "files": files}, ) return len(files) def prepare(root): root = Path(root).resolve() if root.name != EXPERIMENT: raise PermissionError("Exact V8 experiment directory required") if (root / "preregistration.json").exists(): raise FileExistsError("No re-freezing") if not (root / "PROTOCOL.md").is_file(): raise PermissionError("Frozen V8 protocol text required before freezing") for earlier in (V2, V3, V4, V5, V6, V7): if read(earlier / "integrity.json")["status"] != "PASS": raise PermissionError(f"{earlier.name} must be finalized before V8 freezes") if sha(root / PLAN) != PLAN_SHA256: raise PermissionError("The pre-V7 plan fixing the bounds rule must be intact") gain = float(read(V7 / "static_results.json")["surface_gain"]["mean"]) if BOUNDS_RULE != ("CONTEXT_DEPTH" if gain > 0 else "FROZEN"): raise PermissionError("Bounds rule must follow the pre-V7 plan (V7 BOUNDS_GAIN sign)") prior = read(V2 / "train_depth_prior.json") near, far = prior["near_m"], prior["far_m"] manifest = read(V6 / "scene_split.json") v5_scenes = read(V5 / "scene_split.json")["scenes"] train24 = sorted(r["scene_id"] for r in v5_scenes if r["split"] == "TRAIN") train72 = sorted(r["scene_id"] for r in manifest["scenes"] if r["split"] == "TRAIN") validate_split(manifest) counts = {s: sum(r["split"] == s for r in manifest["scenes"]) for s in ("TRAIN", "DEV")} if counts != {"TRAIN": 72, "DEV": 8} or len(train24) != 24: raise PermissionError(f"Unexpected V2 cohort: {counts}") write_json(root / "scene_split.json", manifest) # Geometry-free constants from TRAIN supervision targets only (primary-query GT). train_depths, train_files = [], {} for record in sorted( (r for r in manifest["scenes"] if r["scene_id"] in train24), key=lambda r: r["scene_id"] ): frames = {f["frame_id"]: f for f in record["frames"]} for fid in record["roles"]["primary_query"]: path = Path(frames[fid]["depth"]) train_files[str(path)] = sha(path) train_depths.append(np.load(path).squeeze().astype(np.float32)) reference = reference_values(train_depths) write_json( root / "frame_role_lock.json", { "roles": {r["scene_id"]: r["roles"] for r in manifest["scenes"]}, "manifest_sha256": sha(root / "scene_split.json"), "source": "V2 locked cohort, frame roles and GT-free bounds rule reused unchanged", "v2_scene_split_sha256": sha(V2 / "scene_split.json"), "dev_reused_from_v2": True, "selection_uses_model_outputs": False, "no_frame_or_bounds_search_after_training": True, }, ) for name in ("train_depth_prior.json", "data_provenance.json"): shutil.copyfile(V2 / name, root / name) hashes = { seed: {v: parameter_hash(make_carrier(v, seed, "cpu", near, far)) for v in VARIANT_SPECS} for seed in SEEDS } if any(len(set(per_seed.values())) != 1 for per_seed in hashes.values()): raise AssertionError("Variants must share identical shared parameters per seed") counts_by_variant = { v: sum(p.numel() for p in make_carrier(v, SEEDS[0], "cpu", near, far).parameters()) for v in VARIANT_SPECS } if counts_by_variant != COUNTS: raise AssertionError(f"Parameter counts changed: {counts_by_variant}") write_json( root / "architecture_contract.json", { "variants": { v: {**spec, "config": asdict(carrier_config(v))} for v, spec in VARIANT_SPECS.items() }, "parameter_count": COUNTS, "shared_parameter_hash_by_seed": {str(s): h["C0"] for s, h in hashes.items()}, "only_difference_C0_C1": "C1 differs from C0 only by the voxel grid, 32^3 instead " "of 16^3, with one dense evidence candidate per voxel; the 5150 shared parameters " "and their per-seed draw, the V5 C1 model and loss, TRAIN72, 6000 steps and the " f"bounds rule ({BOUNDS_RULE}: {BOUNDS_TEXT}) are identical, in training and in " "evaluation. The depth-likelihood scale follows each grid's own mean voxel edge " "(the V5 definition); the surface-loss band keeps the frozen 16-grid spacing.", "C2_difference_from_C1": "24^3 grid (13824 candidates); dose-response, secondary, " "never a gate", "depth_bypass": { "log_sigma_init": LOG_SIGMA0, "sampling": "nearest pixel of the full-resolution measured ray-distance map", "placement": "after the >=2-view support gate: one measured view suffices", "inputs": "context RGB, measured context depth, context cameras; no query", }, "anchor_control": "anchor RGB + anchor depth, the same full-role bounds as the " "variant's A/B state; a single view never reaches the >=2-view lifting support, " "so an anchor state carries the single-view depth bypass and learned priors only", "state": "query-independent; all DEV states sealed before query load; " ">=2 queries/state", "test_time_input": "RGB+DEPTH+CAMERA for every variant", "test_time_depth_used": True, "new_backbone_or_learned_matching": False, }, ) config = { "experiment": EXPERIMENT, "variants": list(VARIANT_SPECS), "variant_specs": VARIANT_SPECS, "primary_method": "C1", "primary_pair": list(PRIMARY_PAIR), "primary_contrast": "RESOLUTION_GAIN = AbsRel(C0 16^3) - AbsRel(C1 32^3)", "secondary_contrast": "GRID24_GAP = AbsRel(C2 24^3) - AbsRel(C1 32^3); descriptive " "only (dose-response)", "bounds_rule": BOUNDS_RULE, "bounds_rule_basis": f"{PLAN} (sha256 {PLAN_SHA256}), written before any V7 " "result: the V7 C1 rule if the V7 BOUNDS_GAIN point estimate is >0, else the " "frozen rule", "train_sets": {"TRAIN24": train24, "TRAIN72": train72}, "device": "cpu", "seeds": SEEDS, "steps": 6000, "checkpoint_steps": [100, 200, 300, 500, 750, 1000, 1500, 2000, 3000, 4000, 5000, 6000], "checkpoint_rationale": "identical to V6/V7", "learning_rate": 0.001, "optimizer": "Adam", "weight_decay": 0, "lr_schedule": "constant", "gradient_clip": 1.0, "batch_scenes": 1, "batch_rays": 1024, "precision": "FP32", "num_threads": 1, "thread_environment": THREADS, "cpu_affinity": list(range(8, 24)), "augmentation": "none", "image_size": [128, 160], "train_targets": "TRAIN primary_query2 RGB+ray-distance depth; never carrier input", "context_input": "context RGB + measured context ray distance + cameras (RGB-D " "track); query depth never enters construction", "context_roles": "independent A/B states, equal loss weights", "sampling": "seeded scene permutation cycled; primary query slot cycles per scene visit; " "uniform with-replacement rays, identical indices for A/B and all variants", "initialize": "from scratch; identical per-seed shared parameters for all variants; " "the depth bypass starts at zero without consuming the RNG", "parallel_workers": 3, "execution": "seeds sequential; the C0/C1/C2 runs of one seed concurrently on " "CPU cores 8-23 (identical contention); no GPU is used or queried (GPU paused by " "the user); min_free_gpu_mib is unused", "min_free_gpu_mib": 3072, "infrastructure_retries": 2, "infrastructure_failure_policy": "a signal-terminated run, or a run whose log shows a " "fixed CUDA resource-allocation signature, is moved to audit/failed_attempts with an " "incident record and rerun from scratch with identical variant/seed/config, at most " "infrastructure_retries times per run counted across runner invocations; archived " "checkpoints and DEV curves are never used; any other Python error is never retried; " "a failed C0/C1 run stops the experiment", "checkpoint_selection": "independent per variant/seed using the frozen V2 DEV rule; " "never best seed", "seed_handling": "all seeds equally weighted within scene; each seed reported", "statistics": "frozen V2 estimator (geometry_carrier_statistics); its SURFACE_* fields " "denote the primary C0-C1 contrast, i.e. RESOLUTION in V8", "dev_reuse": "the 8 DEV scenes were evaluated in V2-V7; V8 is a DEV mechanism " "diagnostic of the voxel resolution, not a qualification round; FRESH-V1 and " "FRESH-V2 are not used", "fresh_qualification_included": False, "writer_updates": False, "dynamic_ttt_run": False, } write_json(root / "training_contract.json", config) write_json( root / "loss_contract.json", { "C0": "V2 C1 loss: mean_A_B[RGB Charbonnier(eps=.001) + masked depth AbsRel] + " ".1 mean_A_B surface loss", "C1": "identical to C0", "C2": "identical to C0", "authority": "mcss.mechanism_pilot.rgbd_resolution_carrier.training_loss: the frozen " "V2 C1 loss (mcss.mechanism_pilot.geometry_carrier.training_loss) accepting a " "registered g^3 state; identical at 16^3; the surface band keeps the frozen " "16-grid spacing for every grid", "v2_loss_contract_sha256": sha(V2 / "loss_contract.json"), "lambda_surface": 0.1, "regularization": 0, "training_track": "RGB-D track: context depth is carrier input for every variant; " "TRAIN query depth is supervision only", }, ) shutil.copyfile(V2 / "checkpoint_selection_lock.json", root / "checkpoint_selection_lock.json") write_json( root / "decision_rules.json", { "bootstrap": { "unit": "physical scene", "draws": 10000, "seed": 20260928, "ci": "percentile95", }, "RESOLUTION_STATUS": "frozen V2 primary-contrast gate applied to C0-C1: gain>0; " "CIlo>0; " ">=.75 nonworse; all LOSO>0; positive top1 share<=.5; C1 wrong-scene and shuffle " "damage CIlo>0; C0/C1 common-mask opacity gate; state audits PASS", "SCENE_SPECIFICITY_STATUS": "C1 wrong-scene damage CIlo>0 and C1 spatial-shuffle " "damage CIlo>0 -> SUPPORTED, otherwise NOT_ESTABLISHED", "STATIC_DEV_STATUS": "frozen V2 static gate for C1", "GRID24_GAP": "AbsRel(C2)-AbsRel(C1), descriptive with CI, never a gate", "GEOMETRY_FREE_REFERENCE": { "values": reference, "train_files_sha256": train_files, "references": list(REFERENCES), "primary_reference": PRIMARY_REFERENCE, "readouts": list(READOUTS), "bootstrap": {"unit": "scene", "draws": 10000, "seed": 20260928}, "labels": "ABOVE (frozen V2 evidence rule) / BELOW (mirror) / " "NOT_DISTINGUISHABLE per carrier, readout and metric", "role": "descriptive; never a gate; computed after all states are sealed", }, "TRAIN_FIT": "last-100-step TRAIN depth AbsRel per variant, descriptive", "interpretation": { "A": "RESOLUTION_STATUS=SUPPORTED and C1 RAW AbsRel ABOVE " "REF_TRAIN_ABSREL_OPTIMAL on ALL DEV scenes; next: FRESH-V2 qualification", "B": "RESOLUTION_GAIN CIlo>0, or C1 ABOVE the reference on all scenes or on " "the no-hit-excluded scenes, not A", "C": "otherwise", }, "fresh_qualification_included": False, "final_static_status": "NOT_ESTABLISHED", "dynamic_ttt_next_stage_allowed": False, }, ) write_json( root / "audit/environment.json", { "python": sys.version, "torch": torch.__version__, "cuda": torch.version.cuda, "gpu": torch.cuda.get_device_name() if torch.cuda.is_available() else None, "gpu_shared": True, "packages": {d.metadata["Name"]: d.version for d in importlib.metadata.distributions()}, "commit": subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip(), }, ) sealed = seal_previous(root) data_hashes = {} for r in manifest["scenes"]: for f in r["frames"]: for kind in ("rgb", "depth"): data_hashes[str(Path(f[kind]))] = sha(Path(f[kind])) write_json(root / "audit/data_hashes.json", data_hashes) names = ( "scene_split.json", "frame_role_lock.json", "training_contract.json", "architecture_contract.json", "loss_contract.json", "checkpoint_selection_lock.json", "decision_rules.json", "train_depth_prior.json", "data_provenance.json", "PROTOCOL.md", PLAN, "audit/data_hashes.json", "audit/previous_experiment_seal.json", ) source_paths = sorted(Path("src/mcss").rglob("*.py")) source_paths += sorted(Path("scripts").glob("*rgbd_resolution*.py")) write_json( root / "preregistration.json", { "status": "FROZEN_BEFORE_FORMAL_TRAINING", "experiment": EXPERIMENT, "primary_method": "C1", "input_sha256": {str((root / n).resolve()): sha(root / n) for n in names}, "source_sha256": {str(p.resolve()): sha(p) for p in source_paths}, "data_sha256": data_hashes, "fresh_status": "NOT_INCLUDED_DEV_MECHANISM_ROUND", "formal_training_started": False, "qualification_opened": False, }, ) print("FROZEN", counts, "previous_files_sealed", sealed) if __name__ == "__main__": p = argparse.ArgumentParser() p.add_argument("--root", required=True) a = p.parse_args() prepare(a.root)