Publish frozen reproduction executor image source

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/fig2.png filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1.7
+# Linux/amd64 descriptor resolved from the official Python registry on 2026-07-28.
+ARG BASE_IMAGE=python:3.12-slim@sha256:cab2dbf575e971934a81e4622f5aba17aa7929719bd7e31033a3a83b97fd0464
+FROM ${BASE_IMAGE}
+
+ARG SCIENCE_SPEC_SHA256=c0ded12138cb7c15a15966294ed9bdb87d3a66d2373a7d90050578dbb973c6fd
+LABEL org.opencontainers.image.title="neutral-sheaf-admm-reproduction"
+LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.revision="1e2b5d648361802234348b0b1a7fb3a222128e7d"
+LABEL reproduction.science-spec-sha256="${SCIENCE_SPEC_SHA256}"
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    JAX_DEFAULT_MATMUL_PRECISION=highest \
+    TRACE_MODE=none \
+    TRACKIO_LOGBOOK_AUTONOTE=0
+
+WORKDIR /repro
+COPY pyproject.toml uv.lock LICENSE SCIENCE-SPEC.yaml ./
+RUN test "$(sha256sum SCIENCE-SPEC.yaml | cut -d' ' -f1)" = "${SCIENCE_SPEC_SHA256}" \
+    && python -m pip install --no-cache-dir uv==0.11.9 \
+    && uv sync --frozen --no-dev
+COPY configs ./configs
+COPY src ./src
+COPY scripts ./scripts
+ENV PATH="/repro/.venv/bin:${PATH}" PYTHONPATH="/repro/src"
+EXPOSE 7860
+CMD ["python", "-m", "http.server", "7860"]

LICENSE

@@ -0,0 +1,161 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or merely
+link (or bind by name) to the interfaces of, the Work and Derivative Works
+thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the purposes
+of this definition, "submitted" means any form of electronic, verbal, or
+written communication sent to the Licensor or its representatives, including
+but not limited to communication on electronic mailing lists, source code
+control systems, and issue tracking systems that are managed by, or on behalf
+of, the Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise designated
+in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable patent license to make,
+have made, use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable by such
+Contributor that are necessarily infringed by their Contribution(s) alone or
+by combination of their Contribution(s) with the Work to which such
+Contribution(s) was submitted. If You institute patent litigation against any
+entity (including a cross-claim or counterclaim in a lawsuit) alleging that the
+Work or a Contribution incorporated within the Work constitutes direct or
+contributory patent infringement, then any patent licenses granted to You
+under this License for that Work shall terminate as of the date such
+litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of
+the following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

README.md

@@ -1,10 +1,115 @@
 ---
-title: Sheaf Admm Icml2026 Executor
-emoji: 🌖
+title: Sheaf-ADMM ICML 2026 Reproduction Executor
+emoji: 🧩
 colorFrom: indigo
 colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
+license: apache-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Sheaf-ADMM
+
+![Sheaf-ADMM overview](assets/fig2.png)
+
+Official JAX/Flax implementation of **Learning Multi-Agent Coordination via
+Sheaf-ADMM** (ICML 2026).
+
+[![arXiv](https://img.shields.io/badge/arXiv-2605.31005-b31b1b?style=flat-square)](https://arxiv.org/abs/2605.31005)
+[![Blog](https://img.shields.io/badge/Blog-Sakana%20AI-1f6feb?style=flat-square)](https://pub.sakana.ai/sheaf-admm/)
+
+Sheaf-ADMM decomposes an input into overlapping local views, each processed by an
+agent that solves a small convex subproblem parameterized by a neural encoder.
+Agents coordinate through the Alternating Direction Method of Multipliers (ADMM),
+with the inter-agent constraints specified by a *cellular sheaf* — which aspects
+of neighboring solutions must agree. The optimization is unrolled for a fixed
+number of iterations, so the whole pipeline is differentiable and every component
+is trained end-to-end.
+
+## Installation
+
+This repository is intended to be run from a source checkout. Install
+[uv](https://docs.astral.sh/uv/getting-started/installation/), then run:
+
+```bash
+uv sync
+```
+
+For CUDA experiments, install a JAX build matching your driver:
+
+```bash
+uv pip install -U "jax[cuda12]"
+```
+
+## Data
+
+```bash
+uv run python -m sheaf_admm.data.build_maze \
+  --height 19 \
+  --width 19 \
+  --train-size 10000 \
+  --test-size 1000 \
+  --min-path-length 18 \
+  --ood-sizes \
+  --output-dir datasets/maze_std3_19px_10k
+
+uv run python -m sheaf_admm.data.build_mnist \
+  --output-dir datasets/mnist
+
+uv run python -m sheaf_admm.data.build_sudoku \
+  --output-dir datasets/sudoku_easy
+```
+
+The MNIST and Sudoku builders download their source datasets on first run.
+
+## Training
+
+Each task has a Sheaf-ADMM model and a recurrent-MPNN baseline:
+
+```bash
+# Maze
+uv run python scripts/train.py +experiment=maze_sheaf
+uv run python scripts/train.py +experiment=maze_mpnn
+
+# MNIST
+uv run python scripts/train.py +experiment=mnist_sheaf
+uv run python scripts/train.py +experiment=mnist_mpnn
+
+# Sudoku
+uv run python scripts/train.py +experiment=sudoku_sheaf
+uv run python scripts/train.py +experiment=sudoku_sheaf_lora
+uv run python scripts/train.py +experiment=sudoku_mpnn
+```
+
+Set `training.seed=42`, `123`, or `456` for the paper seeds. Set
+`wandb.mode=online` to enable Weights & Biases logging. Checkpoints and
+`history.json` are written to Hydra's run directory under `outputs/`.
+
+## Visualization
+
+The visualization script expects a Sheaf-ADMM checkpoint:
+
+```bash
+uv run python -m scripts.visualize \
+  --checkpoint outputs/<date>/<time>/checkpoint.pkl \
+  --out-dir /tmp/sheaf_admm_viz
+```
+
+## Checks
+
+```bash
+uv run python -m ruff check .
+uv run python -m pytest -q
+```
+
+## Citation
+
+```bibtex
+@inproceedings{sheafadmm2026,
+  title     = {Learning Multi-Agent Coordination via Sheaf-ADMM},
+  author    = {Seely, Jeffrey and Cupia{\l}, Bart{\l}omiej and Jones, Llion},
+  booktitle = {International Conference on Machine Learning (ICML)},
+  year      = {2026},
+}
+```

SCIENCE-SPEC.yaml

@@ -0,0 +1,1653 @@
+{
+  "authorities": {
+    "approved_protocol_sha256": "f4904e05e8abd051281926abec6774c6fe39b84160367f0bfde806b0669e0c2b",
+    "base_image": "python:3.12-slim@sha256:cab2dbf575e971934a81e4622f5aba17aa7929719bd7e31033a3a83b97fd0464",
+    "canonical_claims_sha256": "26ca2fa3697061cb71a91a0f687ab5ce99e908b7b50c009ee2efcc645695d489",
+    "challenge_dataset_revision": "81166abbeb76e5f79ff87e51061b5a0306507203",
+    "challenge_space_revision": "5bbcad2e9a7e8a7479f3563ac1fc6c768d4bb050",
+    "deadline_utc": "2026-08-03T11:59:00Z",
+    "dependency_lock_sha256": "e9dd209b20905a9a553c30ab1bab0259d2c665ee7805942744d9c5f198610bd7",
+    "execution_bucket": "Mindcraft/sheaf-admm-icml2026-runs",
+    "execution_image_space": "Mindcraft/sheaf-admm-icml2026-executor",
+    "input_bucket": "Mindcraft/sheaf-admm-icml2026-inputs",
+    "paper_sha256": "95d6de2011cdeaf4eeba6c7cc320146a530183da7f045457227cab3165b83a70",
+    "poster_commit": "e503c399b5427ca6cb712ccb080a758e9c19cf23",
+    "space_id": "Mindcraft/repro-learning-multi-agent-coordination-via-sheaf-admm",
+    "sudoku_dataset_revision": "4d5aa527a9fb9aacca0b0d5b8b77d569fa9afcaa",
+    "trace_mode": "none",
+    "trackio_logbook_autonote": 0,
+    "trackio_version": "0.33.0",
+    "trackio_wheel_sha256": "277340507ac46c02c06900c1d680129bdb528223c8110b0b6bc9326bb9f0891d",
+    "upstream_commit": "1e2b5d648361802234348b0b1a7fb3a222128e7d"
+  },
+  "budget_limits": {
+    "billing_quantum": "ceil(rate*1e6*ceil(seconds/60)/60)",
+    "gpu_retry_reserve_micro_usd": 10000000,
+    "minimum_unspent_balance_micro_usd": 10000000,
+    "normal_cap_micro_usd": 75000000
+  },
+  "data_rules": {
+    "c5": {
+      "K": 100,
+      "exact_figure6_protocol": "unreleased",
+      "examples_per_size": 1000,
+      "generator_seed_formula": "21005000+n",
+      "min_path_length_formula": "3*(n-1)/2",
+      "n19_replacements": true,
+      "overlap_rejection": "canonical wall/start/goal/path against training",
+      "realized_minimum": [
+        27,
+        33,
+        39,
+        45,
+        51,
+        57
+      ],
+      "sizes": [
+        19,
+        23,
+        27,
+        31,
+        35,
+        39
+      ],
+      "test_augmentation": false
+    },
+    "maze": {
+      "builder": "released_deterministic_DFS",
+      "height": 19,
+      "min_path_length": 18,
+      "ood_sizes": true,
+      "test_size": 1000,
+      "train_size": 10000,
+      "width": 19
+    },
+    "mnist": {
+      "agent_count": 81,
+      "clean": true,
+      "drop_agents": 24,
+      "drop_effect": [
+        "zero_3x3_pixels",
+        "remove_incident_sheaf_edges",
+        "exclude_removed_agents_from_vote"
+      ],
+      "drop_fraction_label": "30%",
+      "mask_derivation": [
+        "dataset_revision",
+        "example_id",
+        "condition",
+        "master_seed"
+      ],
+      "master_seed": 21005300,
+      "padding_pixels": 16,
+      "tier": "B_target_informed_nonconfirmatory"
+    },
+    "sudoku": {
+      "revision": "4d5aa527a9fb9aacca0b0d5b8b77d569fa9afcaa",
+      "source": "Ritvik19/Sudoku-Dataset",
+      "test_rows": [
+        50000,
+        52000
+      ],
+      "test_split": "test_hard",
+      "train_augmentation": "eight_way",
+      "train_rows": [
+        0,
+        50000
+      ]
+    }
+  },
+  "evaluators": {
+    "C5-EVAL-2X-GENERALIZATION-A": {
+      "physical_jobs": 1,
+      "shard": "deterministic_lpt_A"
+    },
+    "C5-EVAL-2X-GENERALIZATION-B": {
+      "physical_jobs": 1,
+      "shard": "deterministic_lpt_B"
+    },
+    "MAZE-EVAL-C2-C4B": {
+      "physical_jobs": 1,
+      "units": [
+        "imported_default_3",
+        "mpnn84_3",
+        "quadratic_3"
+      ]
+    },
+    "MNIST-EVAL-C3": {
+      "conditions": [
+        "clean",
+        "pad16",
+        "drop30"
+      ],
+      "physical_jobs": 1,
+      "units": [
+        "imported_sheaf_3",
+        "cnn_3"
+      ]
+    },
+    "SUD-EVAL-C1-C4A": {
+      "physical_jobs": 1,
+      "units": [
+        "imported_sheaf_3",
+        "mpnn225_3",
+        "identity_3"
+      ]
+    }
+  },
+  "failure_classes": [
+    "INVALID_INPUT",
+    "INCOMPLETE_OUTPUT",
+    "HASH_MISMATCH",
+    "CONFIG_MISMATCH",
+    "CAPABILITY_VIOLATION",
+    "READINESS_TIMEOUT",
+    "HEARTBEAT_TIMEOUT",
+    "INFRASTRUCTURE",
+    "CODE_PARITY",
+    "DATA_ASSERTION",
+    "BUDGET_GATE",
+    "DEADLINE_GATE",
+    "PRIVACY_FINDING",
+    "AMBIGUOUS_SUBMISSION"
+  ],
+  "fixture_rules": {
+    "disjoint_from_final_generators": true,
+    "id_prefix": "smoke-",
+    "maze_seed_formula": "91005200+n",
+    "mnist_seed": 91005301,
+    "purpose": [
+      "compile",
+      "memory",
+      "timing",
+      "serialization",
+      "one_step_gradient"
+    ],
+    "sudoku_seed": 91005101,
+    "verdict_metrics_forbidden": true
+  },
+  "format": 1,
+  "hardware_routes": {
+    "maze_c5": {
+      "fallback": {
+        "flavor": "l40sx1",
+        "usd_per_hour": "1.80"
+      },
+      "primary": {
+        "flavor": "l4x1",
+        "usd_per_hour": "0.80"
+      }
+    },
+    "mnist": {
+      "fallback": {
+        "flavor": "l40sx1",
+        "usd_per_hour": "1.80"
+      },
+      "primary": {
+        "flavor": "l4x1",
+        "usd_per_hour": "0.80"
+      }
+    },
+    "sudoku": {
+      "fallback": {
+        "flavor": "h200",
+        "usd_per_hour": "5.00"
+      },
+      "primary": {
+        "flavor": "a100-large",
+        "usd_per_hour": "2.50"
+      }
+    }
+  },
+  "imports": [
+    {
+      "checkpoint_sha256": "4444ca900b84911f778ade7fb4c682853308fac6008748ff644f5193122951b8",
+      "config_sha256": "831675683b8ca586616be95d7377a2ed1da776a04cc9457b5b4f855c5598e74a",
+      "ema_decay": 0.999,
+      "final_epoch": 19,
+      "neutral_alias": "mnist-sheaf-seed-42",
+      "seed": 42,
+      "task": "mnist"
+    },
+    {
+      "checkpoint_sha256": "34b693aac81e1ab880324726eb6db80e35e0683f3c997a2d082acd5c9393a5f6",
+      "config_sha256": "c1f902d7509c5a2dbd0130757b55607b51016e2a9039392da4b09b79c694c978",
+      "ema_decay": 0.999,
+      "final_epoch": 19,
+      "neutral_alias": "mnist-sheaf-seed-123",
+      "seed": 123,
+      "task": "mnist"
+    },
+    {
+      "checkpoint_sha256": "f35206c24e79df75878e330ff01ff489ec29f82ae11eb3de04f401e2e4d2a3e5",
+      "config_sha256": "3a3c11e55551b9b820696abb7cf28ea94d4295e022c5da9525adfb802ee77d17",
+      "ema_decay": 0.999,
+      "final_epoch": 19,
+      "neutral_alias": "mnist-sheaf-seed-456",
+      "seed": 456,
+      "task": "mnist"
+    },
+    {
+      "checkpoint_sha256": "7a8295f5af4f52c2ec5963fa35e7e3906ebce5ea433551bfc9017e4a9825de9c",
+      "config_sha256": "6e93a94469a1cec98dd2dc3ff9df91ce613ad99d18a5cae0388b8a42a610595a",
+      "ema_decay": 0.999,
+      "final_epoch": 49,
+      "neutral_alias": "maze-sheaf-seed-42",
+      "seed": 42,
+      "task": "maze"
+    },
+    {
+      "checkpoint_sha256": "bd1369916039e3984911951217c7ae083efe6696f06f6cec9f2f5c009187a6f5",
+      "config_sha256": "8621e9687a39a5f28e5178561c4a6da9dbff09595dbc1340e1e97710c8af82d5",
+      "ema_decay": 0.999,
+      "final_epoch": 49,
+      "neutral_alias": "maze-sheaf-seed-123",
+      "seed": 123,
+      "task": "maze"
+    },
+    {
+      "checkpoint_sha256": "a61191e0a3ec14aa245acc4b566dc7dd6caafba69365f9aa347dc2f906e95f38",
+      "config_sha256": "0566b34b360220bcc8e32cea6236884a9b7a693c68ca1cdc56861ab95ec7da13",
+      "ema_decay": 0.999,
+      "final_epoch": 49,
+      "neutral_alias": "maze-sheaf-seed-456",
+      "seed": 456,
+      "task": "maze"
+    },
+    {
+      "checkpoint_sha256": "53fb0f4c287bb419247956a3ab4492acb42cde6a3c3335ed1c18694c705d163e",
+      "config_sha256": "66ac9154bb1a15483211e0e8458cea4250181fdabc864c1748f89561535621fb",
+      "ema_decay": 0.999,
+      "final_epoch": 9,
+      "neutral_alias": "sudoku-sheaf-seed-42",
+      "seed": 42,
+      "task": "sudoku"
+    },
+    {
+      "checkpoint_sha256": "a16e792b46aeca8ca6dc9d9323217328ecf43e0ce32022870c5626186997511f",
+      "config_sha256": "f080a4055a676a5094204fc78de5e2f57c07dd2f67af8c55cf7615dcb818d47d",
+      "ema_decay": 0.999,
+      "final_epoch": 9,
+      "neutral_alias": "sudoku-sheaf-seed-123",
+      "seed": 123,
+      "task": "sudoku"
+    },
+    {
+      "checkpoint_sha256": "7a6937eedf75f553965c21b5dda5c4da8164489125159f6fc8465e9159b2b3af",
+      "config_sha256": "1649e4d4e047bcceefb9b13ebee6fa830eeac668445714457a2ed258563a9625",
+      "ema_decay": 0.999,
+      "final_epoch": 9,
+      "neutral_alias": "sudoku-sheaf-seed-456",
+      "seed": 456,
+      "task": "sudoku"
+    }
+  ],
+  "lifecycle": {
+    "CPU_CANARY": {
+      "science_freeze_sha256": "NOT_APPLICABLE",
+      "science_spec_sha256": "NOT_APPLICABLE"
+    },
+    "CPU_IMPORT": {
+      "science_freeze_sha256": "NOT_APPLICABLE",
+      "science_spec_sha256": "EXACT"
+    },
+    "GPU_SMOKE": {
+      "science_freeze_sha256": "NOT_APPLICABLE",
+      "science_spec_sha256": "EXACT"
+    },
+    "SCIENTIFIC_EVAL": {
+      "control_mount": "/repro-control read-only",
+      "science_freeze_sha256": "EXACT",
+      "science_spec_sha256": "EXACT"
+    },
+    "SCIENTIFIC_TRAIN": {
+      "control_mount": "/repro-control read-only",
+      "science_freeze_sha256": "EXACT",
+      "science_spec_sha256": "EXACT"
+    }
+  },
+  "metrics": {
+    "c1": "Sudoku exact puzzle accuracy and parameter count",
+    "c2": "Maze exact puzzle accuracy and per-vertex latent dimension ratio",
+    "c3": "MNIST classification accuracy by condition",
+    "c4": "Sudoku exact puzzle accuracy and Maze exact puzzle accuracy",
+    "c5": "Maze exact puzzle accuracy by size",
+    "replication_unit": "training_seed",
+    "report": [
+      "every_seed",
+      "mean",
+      "sample_standard_deviation",
+      "student_t_interval",
+      "paper_value",
+      "unrounded_delta"
+    ],
+    "same_seed_comparisons": "paired",
+    "t_critical": {
+      "90_df2": 2.919985580355516,
+      "95_df2": 4.302652729911275
+    }
+  },
+  "outcomes": {},
+  "protocol_status": "frozen_pre_mutation",
+  "reducers": {
+    "c1": {
+      "negative": "Sheaf_mean<85 or MPNN_mean>20 or U95(paired_gap)<=60",
+      "parameter_match": "relative_count_mismatch<=0.05",
+      "support": "Sheaf_mean>=85 and MPNN_mean<=20 and L95(paired_gap)>60"
+    },
+    "c2": {
+      "negative": "either mean<90 or interval wholly beyond equivalence bounds",
+      "ratio": "84/10=8.4x per-vertex latent dimension",
+      "support": "both means>=95 and paired_90_interval within [-2,2]"
+    },
+    "c3": {
+      "adequacy": "each mean>=98.5 and each seed>=98.0",
+      "negative": "either upper interval<=threshold",
+      "required_suffix": "DROPOUT_SEMANTICS_TARGET_SELECTED",
+      "support": "L95(pad_gap)>20 and L95(drop_gap)>10"
+    },
+    "c4_maze": {
+      "falsifies_collapse": "default_mean>=90 and quadratic_mean>=90 and U95(default-quadratic)<20",
+      "required_suffix": "PROMPT_MISSTATES_PAPER_TABLE",
+      "supports_direction": "default_mean>=90 and quadratic_mean<=60 and L95(default-quadratic)>20"
+    },
+    "c4_sudoku": {
+      "negative": "learned_mean<85 or identity_mean>15 or U95(gap)<=60",
+      "support": "learned_mean>=85 and identity_mean<=15 and L95(gap)>60"
+    },
+    "c5": {
+      "negative": "any mean<95",
+      "required_suffix": "INCONCLUSIVE_EXACT_DENSE_FIGURE6_CONFIG_UNRELEASED",
+      "support": "all six three-seed means>=95"
+    },
+    "precedence": [
+      "invalid_or_incomplete",
+      "supported_or_negative",
+      "ambiguous_or_inconclusive"
+    ]
+  },
+  "registered_configs": {
+    "C1-SUD-MPNN225-123": {
+      "canonical_sha256": "703fe3f833c3b2910a92783710faee4893ddb333d008b4784288171e78fa56f5",
+      "config": {
+        "data": {
+          "dir": "/data/train/sudoku_easy",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "comm_norm_type": "layernorm",
+          "d_e": 32,
+          "d_v": 225,
+          "dec_hidden_dims": [
+            256
+          ],
+          "decoder_arch": "sudoku",
+          "enc_d_model": 128,
+          "enc_num_blocks": 2,
+          "encoder_arch": "sudoku",
+          "mpnn_aggregation": "max",
+          "mpnn_edge_type_mode": "slot",
+          "mpnn_graph_readout": "per_node",
+          "mpnn_message_dim": 32,
+          "num_classes": 10,
+          "num_directions": 9
+        },
+        "model_type": "mpnn",
+        "task": "sudoku",
+        "task_cfg": {},
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 10,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0017,
+          "mpnn_eval_rounds": 50,
+          "mpnn_train_rounds": 20,
+          "seed": 123,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 1,
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C1-SUD-MPNN225-123.json"
+    },
+    "C1-SUD-MPNN225-42": {
+      "canonical_sha256": "a0a0fad0c015647c5b03f31542c7f01fd2648ad04c19360b82d6dc3e060e3af2",
+      "config": {
+        "data": {
+          "dir": "/data/train/sudoku_easy",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "comm_norm_type": "layernorm",
+          "d_e": 32,
+          "d_v": 225,
+          "dec_hidden_dims": [
+            256
+          ],
+          "decoder_arch": "sudoku",
+          "enc_d_model": 128,
+          "enc_num_blocks": 2,
+          "encoder_arch": "sudoku",
+          "mpnn_aggregation": "max",
+          "mpnn_edge_type_mode": "slot",
+          "mpnn_graph_readout": "per_node",
+          "mpnn_message_dim": 32,
+          "num_classes": 10,
+          "num_directions": 9
+        },
+        "model_type": "mpnn",
+        "task": "sudoku",
+        "task_cfg": {},
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 10,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0017,
+          "mpnn_eval_rounds": 50,
+          "mpnn_train_rounds": 20,
+          "seed": 42,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 1,
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C1-SUD-MPNN225-42.json"
+    },
+    "C1-SUD-MPNN225-456": {
+      "canonical_sha256": "b1e99a06aafa6fa0255a8c4c4141b5e7da37a72f21e0388fe10ab45528454a44",
+      "config": {
+        "data": {
+          "dir": "/data/train/sudoku_easy",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "comm_norm_type": "layernorm",
+          "d_e": 32,
+          "d_v": 225,
+          "dec_hidden_dims": [
+            256
+          ],
+          "decoder_arch": "sudoku",
+          "enc_d_model": 128,
+          "enc_num_blocks": 2,
+          "encoder_arch": "sudoku",
+          "mpnn_aggregation": "max",
+          "mpnn_edge_type_mode": "slot",
+          "mpnn_graph_readout": "per_node",
+          "mpnn_message_dim": 32,
+          "num_classes": 10,
+          "num_directions": 9
+        },
+        "model_type": "mpnn",
+        "task": "sudoku",
+        "task_cfg": {},
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 10,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0017,
+          "mpnn_eval_rounds": 50,
+          "mpnn_train_rounds": 20,
+          "seed": 456,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 1,
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C1-SUD-MPNN225-456.json"
+    },
+    "C2-MAZE-MPNN84-123": {
+      "canonical_sha256": "545effae66a4ab9a6c802d32eaa28b06bf664a3618cac556aadd42a39285b40b",
+      "config": {
+        "data": {
+          "dir": "/data/train/maze_std3_19px_10k",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "comm_norm_type": "layernorm",
+          "d_e": 42,
+          "d_v": 84,
+          "dec_hidden_dim": 256,
+          "decoder_arch": "mlp_concat_v2",
+          "enc_hidden_dim": 256,
+          "encoder_arch": "mlp_v2",
+          "mpnn_aggregation": "max",
+          "mpnn_edge_type_mode": "spatial",
+          "mpnn_graph_readout": "per_node",
+          "mpnn_message_dim": 42,
+          "num_classes": 6,
+          "num_directions": 8
+        },
+        "model_type": "mpnn",
+        "task": "maze",
+        "task_cfg": {
+          "connectivity": 8,
+          "num_classes": 6,
+          "patch_size": 3,
+          "stride": 2
+        },
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 50,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0003,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 123,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 5,
+          "warmup_steps": 200,
+          "weight_decay": 1e-06
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C2-MAZE-MPNN84-123.json"
+    },
+    "C2-MAZE-MPNN84-42": {
+      "canonical_sha256": "f826d5b2c392645ceabd97ed219310e4c8dd8278dce3c935b893ef6ec67c598d",
+      "config": {
+        "data": {
+          "dir": "/data/train/maze_std3_19px_10k",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "comm_norm_type": "layernorm",
+          "d_e": 42,
+          "d_v": 84,
+          "dec_hidden_dim": 256,
+          "decoder_arch": "mlp_concat_v2",
+          "enc_hidden_dim": 256,
+          "encoder_arch": "mlp_v2",
+          "mpnn_aggregation": "max",
+          "mpnn_edge_type_mode": "spatial",
+          "mpnn_graph_readout": "per_node",
+          "mpnn_message_dim": 42,
+          "num_classes": 6,
+          "num_directions": 8
+        },
+        "model_type": "mpnn",
+        "task": "maze",
+        "task_cfg": {
+          "connectivity": 8,
+          "num_classes": 6,
+          "patch_size": 3,
+          "stride": 2
+        },
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 50,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0003,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 42,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 5,
+          "warmup_steps": 200,
+          "weight_decay": 1e-06
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C2-MAZE-MPNN84-42.json"
+    },
+    "C2-MAZE-MPNN84-456": {
+      "canonical_sha256": "2fb6db8a94a03033c21b698aeb700ebf2013abf803e4d34e23a778e3a5ab8d09",
+      "config": {
+        "data": {
+          "dir": "/data/train/maze_std3_19px_10k",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "comm_norm_type": "layernorm",
+          "d_e": 42,
+          "d_v": 84,
+          "dec_hidden_dim": 256,
+          "decoder_arch": "mlp_concat_v2",
+          "enc_hidden_dim": 256,
+          "encoder_arch": "mlp_v2",
+          "mpnn_aggregation": "max",
+          "mpnn_edge_type_mode": "spatial",
+          "mpnn_graph_readout": "per_node",
+          "mpnn_message_dim": 42,
+          "num_classes": 6,
+          "num_directions": 8
+        },
+        "model_type": "mpnn",
+        "task": "maze",
+        "task_cfg": {
+          "connectivity": 8,
+          "num_classes": 6,
+          "patch_size": 3,
+          "stride": 2
+        },
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 50,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0003,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 456,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 5,
+          "warmup_steps": 200,
+          "weight_decay": 1e-06
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C2-MAZE-MPNN84-456.json"
+    },
+    "C3-MNIST-CNN-123": {
+      "canonical_sha256": "528044762e54a8f02036c84c34836a857518c98b5aef2fec60d5352b04d89ef8",
+      "config": {
+        "data": {
+          "augmentation": false,
+          "dir": "/data/train/mnist",
+          "examples": 60000,
+          "input_range": [
+            0,
+            1
+          ],
+          "loader": "image",
+          "normalization": false,
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "layout": "NHWC/HWIO/NHWC",
+          "parameter_count": 65642,
+          "post_pool_sizes": [
+            14,
+            30
+          ],
+          "pre_pool_sizes": [
+            28,
+            60
+          ]
+        },
+        "model_type": "mnist_cnn_repro",
+        "task": "mnist",
+        "task_cfg": {},
+        "training": {
+          "batch_size": 128,
+          "betas": [
+            0.9,
+            0.999
+          ],
+          "ema_decay": 0.999,
+          "epoch_permutation": "fold_in(PRNGKey(seed),epoch)",
+          "epochs": 20,
+          "epsilon": 1e-08,
+          "final_batch": "pad_to_128_mask_normalize",
+          "grad_clip": 1.0,
+          "lr": 0.001,
+          "schedule": "linear_to_task_lr_then_constant",
+          "seed": 123,
+          "selection": "fixed_final_epoch",
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "mode": "disabled"
+        }
+      },
+      "file": "control/registered-configs/C3-MNIST-CNN-123.json"
+    },
+    "C3-MNIST-CNN-42": {
+      "canonical_sha256": "442cbeddd56b3eba9dc239e84403285d135bca4868d58a315fe67fcd97b1f4f6",
+      "config": {
+        "data": {
+          "augmentation": false,
+          "dir": "/data/train/mnist",
+          "examples": 60000,
+          "input_range": [
+            0,
+            1
+          ],
+          "loader": "image",
+          "normalization": false,
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "layout": "NHWC/HWIO/NHWC",
+          "parameter_count": 65642,
+          "post_pool_sizes": [
+            14,
+            30
+          ],
+          "pre_pool_sizes": [
+            28,
+            60
+          ]
+        },
+        "model_type": "mnist_cnn_repro",
+        "task": "mnist",
+        "task_cfg": {},
+        "training": {
+          "batch_size": 128,
+          "betas": [
+            0.9,
+            0.999
+          ],
+          "ema_decay": 0.999,
+          "epoch_permutation": "fold_in(PRNGKey(seed),epoch)",
+          "epochs": 20,
+          "epsilon": 1e-08,
+          "final_batch": "pad_to_128_mask_normalize",
+          "grad_clip": 1.0,
+          "lr": 0.001,
+          "schedule": "linear_to_task_lr_then_constant",
+          "seed": 42,
+          "selection": "fixed_final_epoch",
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "mode": "disabled"
+        }
+      },
+      "file": "control/registered-configs/C3-MNIST-CNN-42.json"
+    },
+    "C3-MNIST-CNN-456": {
+      "canonical_sha256": "2ba04eca4a4bec45d8cadb2c2363efe34b0ab731698ac12948f82c5ef288a099",
+      "config": {
+        "data": {
+          "augmentation": false,
+          "dir": "/data/train/mnist",
+          "examples": 60000,
+          "input_range": [
+            0,
+            1
+          ],
+          "loader": "image",
+          "normalization": false,
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "layout": "NHWC/HWIO/NHWC",
+          "parameter_count": 65642,
+          "post_pool_sizes": [
+            14,
+            30
+          ],
+          "pre_pool_sizes": [
+            28,
+            60
+          ]
+        },
+        "model_type": "mnist_cnn_repro",
+        "task": "mnist",
+        "task_cfg": {},
+        "training": {
+          "batch_size": 128,
+          "betas": [
+            0.9,
+            0.999
+          ],
+          "ema_decay": 0.999,
+          "epoch_permutation": "fold_in(PRNGKey(seed),epoch)",
+          "epochs": 20,
+          "epsilon": 1e-08,
+          "final_batch": "pad_to_128_mask_normalize",
+          "grad_clip": 1.0,
+          "lr": 0.001,
+          "schedule": "linear_to_task_lr_then_constant",
+          "seed": 456,
+          "selection": "fixed_final_epoch",
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "mode": "disabled"
+        }
+      },
+      "file": "control/registered-configs/C3-MNIST-CNN-456.json"
+    },
+    "C4-MAZE-QUADRATIC-123": {
+      "canonical_sha256": "5f7b04835bc32b012a5e2d5e12e2b1512c3c95343ac7d8ac97a77a46178f723e",
+      "config": {
+        "data": {
+          "dir": "/data/train/maze_std3_19px_10k",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "cg_iters": 5,
+          "comm_norm_type": "layernorm",
+          "d_e": 5,
+          "d_v": 10,
+          "dec_hidden_dim": 256,
+          "decoder_arch": "mlp_concat_v2",
+          "enc_hidden_dim": 256,
+          "encoder_arch": "mlp_v2",
+          "gamma": 5.0,
+          "lora_init_style": "standard",
+          "lora_rank": 4,
+          "num_classes": 6,
+          "num_directions": 8,
+          "objective_mode": "quadratic",
+          "rho_init": 0.25,
+          "rm_init": "orthonormal",
+          "rm_mode": "context",
+          "rm_sharing": "directional",
+          "tikhonov_eps": 1e-05,
+          "x_solver": "diagonal_prox",
+          "z_mode": "prox",
+          "z_solver": "unrolled_cg"
+        },
+        "model_type": "sheaf",
+        "task": "maze",
+        "task_cfg": {
+          "connectivity": 8,
+          "num_classes": 6,
+          "patch_size": 3,
+          "stride": 2
+        },
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 50,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0003,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 123,
+          "train_iters_dist": "uniform",
+          "train_iters_min": 15,
+          "val_interval": 5,
+          "warmup_steps": 200,
+          "weight_decay": 1e-06
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C4-MAZE-QUADRATIC-123.json"
+    },
+    "C4-MAZE-QUADRATIC-42": {
+      "canonical_sha256": "87eb0690dbe06c6c70044866181311c9f2c0f7f724e75063464c501c3ef533db",
+      "config": {
+        "data": {
+          "dir": "/data/train/maze_std3_19px_10k",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "cg_iters": 5,
+          "comm_norm_type": "layernorm",
+          "d_e": 5,
+          "d_v": 10,
+          "dec_hidden_dim": 256,
+          "decoder_arch": "mlp_concat_v2",
+          "enc_hidden_dim": 256,
+          "encoder_arch": "mlp_v2",
+          "gamma": 5.0,
+          "lora_init_style": "standard",
+          "lora_rank": 4,
+          "num_classes": 6,
+          "num_directions": 8,
+          "objective_mode": "quadratic",
+          "rho_init": 0.25,
+          "rm_init": "orthonormal",
+          "rm_mode": "context",
+          "rm_sharing": "directional",
+          "tikhonov_eps": 1e-05,
+          "x_solver": "diagonal_prox",
+          "z_mode": "prox",
+          "z_solver": "unrolled_cg"
+        },
+        "model_type": "sheaf",
+        "task": "maze",
+        "task_cfg": {
+          "connectivity": 8,
+          "num_classes": 6,
+          "patch_size": 3,
+          "stride": 2
+        },
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 50,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0003,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 42,
+          "train_iters_dist": "uniform",
+          "train_iters_min": 15,
+          "val_interval": 5,
+          "warmup_steps": 200,
+          "weight_decay": 1e-06
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C4-MAZE-QUADRATIC-42.json"
+    },
+    "C4-MAZE-QUADRATIC-456": {
+      "canonical_sha256": "14a74656730c7fcc84be1e1cbda241310e68a92cc34f714820b7a5f32f18997e",
+      "config": {
+        "data": {
+          "dir": "/data/train/maze_std3_19px_10k",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "cg_iters": 5,
+          "comm_norm_type": "layernorm",
+          "d_e": 5,
+          "d_v": 10,
+          "dec_hidden_dim": 256,
+          "decoder_arch": "mlp_concat_v2",
+          "enc_hidden_dim": 256,
+          "encoder_arch": "mlp_v2",
+          "gamma": 5.0,
+          "lora_init_style": "standard",
+          "lora_rank": 4,
+          "num_classes": 6,
+          "num_directions": 8,
+          "objective_mode": "quadratic",
+          "rho_init": 0.25,
+          "rm_init": "orthonormal",
+          "rm_mode": "context",
+          "rm_sharing": "directional",
+          "tikhonov_eps": 1e-05,
+          "x_solver": "diagonal_prox",
+          "z_mode": "prox",
+          "z_solver": "unrolled_cg"
+        },
+        "model_type": "sheaf",
+        "task": "maze",
+        "task_cfg": {
+          "connectivity": 8,
+          "num_classes": 6,
+          "patch_size": 3,
+          "stride": 2
+        },
+        "training": {
+          "K_eval": 100,
+          "K_train": 40,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 50,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 4,
+          "lr": 0.0003,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 456,
+          "train_iters_dist": "uniform",
+          "train_iters_min": 15,
+          "val_interval": 5,
+          "warmup_steps": 200,
+          "weight_decay": 1e-06
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C4-MAZE-QUADRATIC-456.json"
+    },
+    "C4-SUD-IDENTITY-123": {
+      "canonical_sha256": "3bbb5dec4ca83cbab0379208b94d19b570eb97e2e411259208734c7467ef06ef",
+      "config": {
+        "data": {
+          "dir": "/data/train/sudoku_easy",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "cg_iters": 5,
+          "comm_norm_type": "layernorm",
+          "d_e": 32,
+          "d_v": 288,
+          "dec_hidden_dims": [
+            256
+          ],
+          "decoder_arch": "sudoku",
+          "enc_d_model": 128,
+          "enc_num_blocks": 2,
+          "encoder_arch": "sudoku",
+          "gamma": 2.0,
+          "num_classes": 10,
+          "num_directions": 9,
+          "objective_mode": "non_negative",
+          "rho_init": 0.25,
+          "rm_constant": true,
+          "rm_init": "identity",
+          "rm_mode": "fixed",
+          "rm_sharing": "sudoku",
+          "x_solver": "diagonal_prox",
+          "z_mode": "prox",
+          "z_solver": "unrolled_cg"
+        },
+        "model_type": "sheaf",
+        "task": "sudoku",
+        "task_cfg": {},
+        "training": {
+          "K_eval": 50,
+          "K_train": 20,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 10,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 2,
+          "lr": 0.0017,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 123,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 1,
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C4-SUD-IDENTITY-123.json"
+    },
+    "C4-SUD-IDENTITY-42": {
+      "canonical_sha256": "d6af26f0bfbcb23770bcd838ee12b937401c2dcc060dff601ff32de262e70f85",
+      "config": {
+        "data": {
+          "dir": "/data/train/sudoku_easy",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "cg_iters": 5,
+          "comm_norm_type": "layernorm",
+          "d_e": 32,
+          "d_v": 288,
+          "dec_hidden_dims": [
+            256
+          ],
+          "decoder_arch": "sudoku",
+          "enc_d_model": 128,
+          "enc_num_blocks": 2,
+          "encoder_arch": "sudoku",
+          "gamma": 2.0,
+          "num_classes": 10,
+          "num_directions": 9,
+          "objective_mode": "non_negative",
+          "rho_init": 0.25,
+          "rm_constant": true,
+          "rm_init": "identity",
+          "rm_mode": "fixed",
+          "rm_sharing": "sudoku",
+          "x_solver": "diagonal_prox",
+          "z_mode": "prox",
+          "z_solver": "unrolled_cg"
+        },
+        "model_type": "sheaf",
+        "task": "sudoku",
+        "task_cfg": {},
+        "training": {
+          "K_eval": 50,
+          "K_train": 20,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 10,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 2,
+          "lr": 0.0017,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 42,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 1,
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C4-SUD-IDENTITY-42.json"
+    },
+    "C4-SUD-IDENTITY-456": {
+      "canonical_sha256": "265179cbf9101405f1b04175bc3d247a719ceb8a415d11b84345a240365cbd49",
+      "config": {
+        "data": {
+          "dir": "/data/train/sudoku_easy",
+          "loader": "puzzle",
+          "train_split": "train",
+          "val_splits": []
+        },
+        "dtype": "float32",
+        "model": {
+          "cg_iters": 5,
+          "comm_norm_type": "layernorm",
+          "d_e": 32,
+          "d_v": 288,
+          "dec_hidden_dims": [
+            256
+          ],
+          "decoder_arch": "sudoku",
+          "enc_d_model": 128,
+          "enc_num_blocks": 2,
+          "encoder_arch": "sudoku",
+          "gamma": 2.0,
+          "num_classes": 10,
+          "num_directions": 9,
+          "objective_mode": "non_negative",
+          "rho_init": 0.25,
+          "rm_constant": true,
+          "rm_init": "identity",
+          "rm_mode": "fixed",
+          "rm_sharing": "sudoku",
+          "x_solver": "diagonal_prox",
+          "z_mode": "prox",
+          "z_solver": "unrolled_cg"
+        },
+        "model_type": "sheaf",
+        "task": "sudoku",
+        "task_cfg": {},
+        "training": {
+          "K_eval": 50,
+          "K_train": 20,
+          "batch_size": 128,
+          "ema_decay": 0.999,
+          "epochs": 10,
+          "exit_on_nan": true,
+          "grad_clip": 1.0,
+          "loss_window": 2,
+          "lr": 0.0017,
+          "mpnn_eval_rounds": 100,
+          "mpnn_train_rounds": 40,
+          "seed": 456,
+          "train_iters_dist": "fixed",
+          "train_iters_min": 15,
+          "val_interval": 1,
+          "warmup_steps": 200,
+          "weight_decay": 1e-07
+        },
+        "wandb": {
+          "entity": null,
+          "group": null,
+          "mode": "disabled",
+          "name": null,
+          "project": "sheaf-admm",
+          "tags": []
+        }
+      },
+      "file": "control/registered-configs/C4-SUD-IDENTITY-456.json"
+    }
+  },
+  "run_identities": [
+    "C1-SUD-MPNN225-42",
+    "C1-SUD-MPNN225-123",
+    "C1-SUD-MPNN225-456",
+    "C2-MAZE-MPNN84-42",
+    "C2-MAZE-MPNN84-123",
+    "C2-MAZE-MPNN84-456",
+    "C3-MNIST-CNN-42",
+    "C3-MNIST-CNN-123",
+    "C3-MNIST-CNN-456",
+    "C4-SUD-IDENTITY-42",
+    "C4-SUD-IDENTITY-123",
+    "C4-SUD-IDENTITY-456",
+    "C4-MAZE-QUADRATIC-42",
+    "C4-MAZE-QUADRATIC-123",
+    "C4-MAZE-QUADRATIC-456"
+  ],
+  "submission_limits": {
+    "all_returned_ids_max": 29,
+    "cpu_retry_ids": 1,
+    "cpu_returned_ids_max": 3,
+    "gpu_retry_ids": 3,
+    "gpu_returned_ids_max": 26,
+    "primary_cpu_ids": 2,
+    "primary_gpu_ids": 23,
+    "target_scientific_concurrency": 6
+  },
+  "title": "Learning Multi-Agent Coordination via Sheaf-ADMM",
+  "training_common": {
+    "batch_size": 128,
+    "dtype": "float32",
+    "early_stopping": false,
+    "ema_decay": 0.999,
+    "evaluation_parameters": "EMA",
+    "global_grad_clip": 1.0,
+    "jax_default_matmul_precision": "highest",
+    "optimizer": "AdamW",
+    "schedule": "linear_to_task_lr_then_constant",
+    "selection": "fixed_final_epoch",
+    "training_mount_content": [
+      "registered_task_train_split"
+    ],
+    "validation_selection": false,
+    "validation_splits": [],
+    "warmup_steps": 200
+  },
+  "training_families": {
+    "C1-SUD-MPNN225": {
+      "base": "sudoku_mpnn",
+      "data": {
+        "dir": "datasets/sudoku_easy",
+        "loader": "puzzle",
+        "train_split": "train",
+        "val_splits": []
+      },
+      "model": {
+        "comm_norm_type": "layernorm",
+        "d_e": 32,
+        "d_v": 225,
+        "dec_hidden_dims": [
+          256
+        ],
+        "decoder_arch": "sudoku",
+        "enc_d_model": 128,
+        "enc_num_blocks": 2,
+        "encoder_arch": "sudoku",
+        "mpnn_aggregation": "max",
+        "mpnn_edge_type_mode": "slot",
+        "mpnn_graph_readout": "per_node",
+        "mpnn_message_dim": 32,
+        "num_classes": 10,
+        "num_directions": 9
+      },
+      "model_type": "mpnn",
+      "paper_row_reconstruction": true,
+      "seeds": [
+        42,
+        123,
+        456
+      ],
+      "task": "sudoku",
+      "task_cfg": {},
+      "training": {
+        "epochs": 10,
+        "lr": 0.0017,
+        "mpnn_eval_rounds": 50,
+        "mpnn_train_rounds": 20,
+        "weight_decay": 1e-07
+      }
+    },
+    "C2-MAZE-MPNN84": {
+      "base": "maze_mpnn",
+      "data": {
+        "dir": "datasets/maze_std3_19px_10k",
+        "loader": "puzzle",
+        "train_split": "train",
+        "val_splits": []
+      },
+      "model": {
+        "comm_norm_type": "layernorm",
+        "d_e": 42,
+        "d_v": 84,
+        "dec_hidden_dim": 256,
+        "decoder_arch": "mlp_concat_v2",
+        "enc_hidden_dim": 256,
+        "encoder_arch": "mlp_v2",
+        "mpnn_aggregation": "max",
+        "mpnn_edge_type_mode": "spatial",
+        "mpnn_graph_readout": "per_node",
+        "mpnn_message_dim": 42,
+        "num_classes": 6,
+        "num_directions": 8
+      },
+      "model_type": "mpnn",
+      "seeds": [
+        42,
+        123,
+        456
+      ],
+      "task": "maze",
+      "task_cfg": {
+        "connectivity": 8,
+        "num_classes": 6,
+        "patch_size": 3,
+        "stride": 2
+      },
+      "training": {
+        "epochs": 50,
+        "lr": 0.0003,
+        "mpnn_eval_rounds": 100,
+        "mpnn_train_rounds": 40,
+        "train_round_distribution": "fixed",
+        "weight_decay": 1e-06
+      }
+    },
+    "C3-MNIST-CNN": {
+      "data": {
+        "augmentation": false,
+        "input_range": [
+          0,
+          1
+        ],
+        "normalization": false,
+        "val_splits": []
+      },
+      "model": {
+        "bias_init": "zeros",
+        "kernel_init": "glorot_uniform",
+        "layers": [
+          "conv3x3-1-32-same-relu",
+          "conv3x3-32-32-same-relu",
+          "maxpool2x2-stride2-valid",
+          "conv3x3-32-64-same-relu",
+          "conv3x3-64-64-same-relu",
+          "global-spatial-mean",
+          "dense64-10"
+        ],
+        "layout": "NHWC/HWIO/NHWC",
+        "parameter_count": 65642,
+        "post_pool_sizes": [
+          14,
+          30
+        ],
+        "pre_pool_sizes": [
+          28,
+          60
+        ]
+      },
+      "model_type": "mnist_cnn_repro",
+      "seeds": [
+        42,
+        123,
+        456
+      ],
+      "task": "mnist",
+      "training": {
+        "betas": [
+          0.9,
+          0.999
+        ],
+        "epoch_permutation": "fold_in(PRNGKey(seed),epoch)",
+        "epochs": 20,
+        "epsilon": 1e-08,
+        "examples": 60000,
+        "final_batch": "pad_to_128_mask_normalize",
+        "kernel_only_weight_decay": 1e-07,
+        "loss": "mean_sparse_categorical_cross_entropy",
+        "lr": 0.001
+      }
+    },
+    "C4-MAZE-QUADRATIC": {
+      "base": "maze_sheaf",
+      "data": {
+        "dir": "datasets/maze_std3_19px_10k",
+        "loader": "puzzle",
+        "train_split": "train",
+        "val_splits": []
+      },
+      "forbidden_heads": [
+        "l1",
+        "lower_bound",
+        "upper_bound"
+      ],
+      "heads": [
+        "positive_q_diag",
+        "q"
+      ],
+      "model": {
+        "cg_iters": 5,
+        "comm_norm_type": "layernorm",
+        "d_e": 5,
+        "d_v": 10,
+        "dec_hidden_dim": 256,
+        "decoder_arch": "mlp_concat_v2",
+        "enc_hidden_dim": 256,
+        "encoder_arch": "mlp_v2",
+        "gamma": 5,
+        "lora_init_style": "standard",
+        "lora_rank": 4,
+        "num_classes": 6,
+        "num_directions": 8,
+        "objective_mode": "quadratic",
+        "rho_init": 0.25,
+        "rm_init": "orthonormal",
+        "rm_mode": "context",
+        "rm_sharing": "directional",
+        "tikhonov_eps": 1e-05,
+        "x_solver": "diagonal_prox",
+        "z_mode": "prox",
+        "z_solver": "unrolled_cg"
+      },
+      "model_type": "sheaf",
+      "overrides": {
+        "data.val_splits": [],
+        "model.objective_mode": "quadratic"
+      },
+      "seeds": [
+        42,
+        123,
+        456
+      ],
+      "task": "maze",
+      "task_cfg": {
+        "connectivity": 8,
+        "num_classes": 6,
+        "patch_size": 3,
+        "stride": 2
+      },
+      "training": {
+        "K_eval": 100,
+        "K_train": 40,
+        "epochs": 50,
+        "loss_window": 4,
+        "lr": 0.0003,
+        "train_K_distribution": "uniform_inclusive_15_40",
+        "train_iters_min": 15,
+        "weight_decay": 1e-06
+      }
+    },
+    "C4-SUD-IDENTITY": {
+      "base": "sudoku_sheaf",
+      "constant_map": "F=[I_32,0,...,0] for every slot and endpoint",
+      "data": {
+        "dir": "datasets/sudoku_easy",
+        "loader": "puzzle",
+        "train_split": "train",
+        "val_splits": []
+      },
+      "model": {
+        "cg_iters": 5,
+        "comm_norm_type": "layernorm",
+        "d_e": 32,
+        "d_v": 288,
+        "dec_hidden_dims": [
+          256
+        ],
+        "decoder_arch": "sudoku",
+        "enc_d_model": 128,
+        "enc_num_blocks": 2,
+        "encoder_arch": "sudoku",
+        "gamma": 2.0,
+        "num_classes": 10,
+        "num_directions": 9,
+        "objective_mode": "non_negative",
+        "rho_init": 0.25,
+        "rm_constant": true,
+        "rm_init": "identity",
+        "rm_mode": "fixed",
+        "rm_sharing": "sudoku",
+        "x_solver": "diagonal_prox",
+        "z_mode": "prox",
+        "z_solver": "unrolled_cg"
+      },
+      "model_type": "sheaf",
+      "overrides": {
+        "data.val_splits": [],
+        "model.rm_constant": true,
+        "model.rm_init": "identity"
+      },
+      "pairing_requirement": "control and intervention common leaves and counters bit-identical before replacement",
+      "parameter_tree_requirement": "no restriction-map leaf",
+      "seeds": [
+        42,
+        123,
+        456
+      ],
+      "task": "sudoku",
+      "task_cfg": {},
+      "training": {
+        "K_eval": 50,
+        "K_train": 20,
+        "epochs": 10,
+        "loss_window": 2,
+        "lr": 0.0017,
+        "train_iters_dist": "fixed",
+        "weight_decay": 1e-07
+      }
+    }
+  }
+}

configs/config.yaml

@@ -0,0 +1,52 @@
+# Base config. Shared optimization settings live here (the paper's shared HPs);
+# per-task architecture + solver settings come from configs/experiment/*.yaml,
+# selected with `+experiment=<name>`.
+defaults:
+  - _self_
+
+task: maze            # maze | mnist | sudoku  (selects the task hook)
+model_type: sheaf     # sheaf | mpnn
+dtype: float32        # registered reproduction runs forbid mixed precision
+
+wandb:
+  project: sheaf-admm
+  entity: null        # null -> your default wandb entity
+  name: null          # null -> wandb auto-name
+  group: null         # e.g. group seeds of one experiment together
+  tags: []
+  mode: disabled      # online | offline | disabled
+
+training:
+  seed: 42            # paper sweeps seeds {42, 123, 456}
+  lr: 3.0e-4
+  weight_decay: 1.0e-6
+  epochs: 50
+  batch_size: 128
+  warmup_steps: 200   # linear warmup -> constant LR
+  grad_clip: 1.0      # global-norm clip
+  ema_decay: 0.999    # EMA of params, used at eval
+  exit_on_nan: true
+  val_interval: 5
+
+  # ADMM horizon (Sheaf): K_train iterations at train, K_eval at eval.
+  K_train: 40
+  K_eval: 100
+  loss_window: 4              # average CE over the final w iterates
+  train_iters_dist: fixed     # fixed | uniform (Maze resamples K ~ U[train_iters_min, K_train])
+  train_iters_min: 15
+
+  # MPNN baseline message-passing rounds (the K analog for the recurrent MPNN).
+  mpnn_train_rounds: 40
+  mpnn_eval_rounds: 100
+
+data:
+  dir: ???            # set per experiment
+  train_split: train
+  val_splits: [test]
+  loader: puzzle      # puzzle (maze/sudoku) | image (mnist)
+
+# kwargs forwarded to the task hook (sheaf_admm.training.make_task)
+task_cfg: {}
+
+# sheaf_admm.models.ModelConfig fields (set per experiment)
+model: {}

configs/experiment/maze_mpnn.yaml

@@ -0,0 +1,40 @@
+# @package _global_
+# Table 1 baseline: recurrent-MPNN, parameter-matched (d_v=84, ~182K), max aggregation.
+# (CM variant: set model.d_v=10, model.d_e=5, model.mpnn_message_dim=5 -> ~49K.)
+task: maze
+model_type: mpnn
+
+training:
+  lr: 3.0e-4
+  weight_decay: 1.0e-6
+  epochs: 50
+  mpnn_train_rounds: 40
+  mpnn_eval_rounds: 100
+  val_interval: 5
+
+data:
+  dir: datasets/maze_std3_19px_10k
+  train_split: train
+  val_splits: [test, test_ood_2x, test_ood_2xW, test_ood_4x, test_ood_4xW]
+  loader: puzzle
+
+task_cfg:
+  patch_size: 3
+  stride: 2
+  connectivity: 8
+  num_classes: 6
+
+model:
+  num_classes: 6
+  d_v: 84
+  d_e: 42
+  encoder_arch: mlp_v2
+  enc_hidden_dim: 256
+  comm_norm_type: layernorm
+  decoder_arch: mlp_concat_v2
+  dec_hidden_dim: 256
+  mpnn_message_dim: 42
+  mpnn_aggregation: max          # the strongest aggregation in the sweep
+  mpnn_edge_type_mode: spatial   # 8 grid directions
+  num_directions: 8
+  mpnn_graph_readout: per_node

configs/experiment/maze_sheaf.yaml

@@ -0,0 +1,51 @@
+# @package _global_
+# Table 1 anchor: Sheaf-ADMM maze (d_v=10, ~182K params -> 99.9 / 98.1 / 4.5).
+task: maze
+model_type: sheaf
+
+training:
+  lr: 3.0e-4
+  weight_decay: 1.0e-6
+  epochs: 50
+  K_train: 40
+  K_eval: 100
+  loss_window: 4
+  train_iters_dist: uniform   # K ~ U[15, 40] per step
+  train_iters_min: 15
+  val_interval: 5
+
+data:
+  dir: datasets/maze_std3_19px_10k
+  train_split: train
+  val_splits: [test, test_ood_2x, test_ood_2xW, test_ood_4x, test_ood_4xW]
+  loader: puzzle
+
+task_cfg:
+  patch_size: 3
+  stride: 2
+  connectivity: 8
+  num_classes: 6
+
+model:
+  num_classes: 6
+  d_v: 10
+  d_e: 5
+  encoder_arch: mlp_v2
+  enc_hidden_dim: 256
+  comm_norm_type: layernorm
+  objective_mode: l1box_diag        # closed-form L1 + box x-update
+  x_solver: diagonal_prox
+  z_solver: unrolled_cg
+  z_mode: prox                      # soft consensus
+  gamma: 5.0
+  cg_iters: 5
+  tikhonov_eps: 1.0e-5
+  rm_sharing: directional           # one base map per grid direction (8-way, see num_directions)
+  rm_init: orthonormal
+  rm_mode: context                  # LoRA-modulated restriction maps
+  lora_rank: 4
+  lora_init_style: standard
+  num_directions: 8
+  rho_init: 0.25
+  decoder_arch: mlp_concat_v2
+  dec_hidden_dim: 256

configs/experiment/mnist_mpnn.yaml

@@ -0,0 +1,39 @@
+# @package _global_
+# MNIST recurrent-MPNN baseline (graph-level mean-pool readout).
+task: mnist
+model_type: mpnn
+
+training:
+  lr: 1.0e-3
+  weight_decay: 1.0e-7
+  epochs: 20
+  mpnn_train_rounds: 20
+  mpnn_eval_rounds: 50
+  val_interval: 5
+
+data:
+  dir: datasets/mnist
+  train_split: train
+  val_splits: [test]
+  loader: image
+
+task_cfg:
+  patch_size: 3
+  stride: 3
+  connectivity: 8
+  num_classes: 10
+
+model:
+  num_classes: 10
+  d_v: 32
+  d_e: 24
+  encoder_arch: mlp
+  enc_hidden_dim: 256
+  comm_norm_type: layernorm
+  decoder_arch: classification
+  dec_hidden_dims: [128]
+  mpnn_message_dim: 24
+  mpnn_aggregation: mean
+  mpnn_edge_type_mode: spatial
+  num_directions: 8
+  mpnn_graph_readout: graph

configs/experiment/mnist_sheaf.yaml

@@ -0,0 +1,52 @@
+# @package _global_
+# MNIST classification (clean ~98.5%): 28x28 image, non-overlapping 3x3 patches
+# (stride 3 -> 81 agents). Global (shared) restriction map, hard consensus (Fz=0).
+task: mnist
+model_type: sheaf
+
+training:
+  lr: 1.0e-3
+  weight_decay: 1.0e-7
+  epochs: 20
+  K_train: 20
+  K_eval: 100
+  loss_window: 2
+  train_iters_dist: fixed
+  val_interval: 5
+
+data:
+  dir: datasets/mnist
+  train_split: train
+  val_splits: [test]
+  loader: image
+
+task_cfg:
+  patch_size: 3
+  stride: 3          # paper Table 4 stride
+  connectivity: 8
+  num_classes: 10
+
+model:
+  num_classes: 10
+  d_v: 32
+  d_e: 24
+  encoder_arch: mlp
+  enc_hidden_dim: 256
+  comm_norm_type: layernorm
+  objective_mode: lasso
+  l1_weight: 0.006337180166370117
+  x_solver: diagonal_prox
+  z_solver: unrolled_cg
+  z_mode: project          # hard consensus (Fz = 0)
+  cg_iters: 5
+  tikhonov_eps: 1.0e-5
+  rm_sharing: global       # one shared restriction map
+  rm_init: orthonormal
+  rm_mode: context
+  lora_rank: 8
+  lora_init_style: legacy
+  num_directions: 8
+  rho_init: 0.12
+  decoder_arch: classification
+  dec_linear_head: true
+  dec_readout_mode: x_only

configs/experiment/sudoku_mpnn.yaml

@@ -0,0 +1,36 @@
+# @package _global_
+# Recurrent-MPNN Sudoku baseline.
+task: sudoku
+model_type: mpnn
+
+training:
+  lr: 3.0e-4
+  weight_decay: 1.0e-7
+  epochs: 5
+  mpnn_train_rounds: 20
+  mpnn_eval_rounds: 50
+  val_interval: 1
+
+data:
+  dir: datasets/sudoku_easy
+  train_split: train
+  val_splits: [test_hard]
+  loader: puzzle
+
+task_cfg: {}
+
+model:
+  num_classes: 10
+  d_v: 504
+  d_e: 32
+  encoder_arch: sudoku
+  enc_d_model: 128
+  enc_num_blocks: 2
+  comm_norm_type: layernorm
+  decoder_arch: sudoku
+  dec_hidden_dims: [256]
+  mpnn_message_dim: 32
+  mpnn_aggregation: max
+  mpnn_edge_type_mode: slot       # 9 shared-cell slots
+  num_directions: 9
+  mpnn_graph_readout: per_node

configs/experiment/sudoku_sheaf.yaml

@@ -0,0 +1,44 @@
+# @package _global_
+# Sheaf-ADMM Sudoku with fixed restriction maps.
+task: sudoku
+model_type: sheaf
+
+training:
+  lr: 1.7e-3
+  weight_decay: 1.0e-7
+  epochs: 10
+  K_train: 20
+  K_eval: 50
+  loss_window: 2
+  train_iters_dist: fixed
+  val_interval: 1
+
+data:
+  dir: datasets/sudoku_easy
+  train_split: train
+  val_splits: [test_hard]
+  loader: puzzle
+
+task_cfg: {}   # 27 row/col/box agents are derived from the multigraph
+
+model:
+  num_classes: 10
+  d_v: 288               # 9 cells x 32-dim blocks
+  d_e: 32
+  encoder_arch: sudoku
+  enc_d_model: 128
+  enc_num_blocks: 2
+  comm_norm_type: layernorm
+  objective_mode: non_negative      # closed-form x = max((rho(z-y)-q)/(D+rho), 0)
+  x_solver: diagonal_prox
+  z_solver: unrolled_cg
+  z_mode: prox
+  gamma: 2.0
+  cg_iters: 5
+  rm_sharing: sudoku                # 9 base maps = selectors onto 9 disjoint 32-d blocks
+  rm_init: soft_slice
+  rm_mode: fixed
+  num_directions: 9
+  rho_init: 0.25
+  decoder_arch: sudoku
+  dec_hidden_dims: [256]

configs/experiment/sudoku_sheaf_lora.yaml

@@ -0,0 +1,46 @@
+# @package _global_
+# Sheaf-ADMM Sudoku with LoRA-modulated restriction maps.
+task: sudoku
+model_type: sheaf
+
+training:
+  lr: 1.7e-3
+  weight_decay: 1.0e-7
+  epochs: 10
+  K_train: 20
+  K_eval: 50
+  loss_window: 2
+  train_iters_dist: fixed
+  val_interval: 1
+
+data:
+  dir: datasets/sudoku_easy
+  train_split: train
+  val_splits: [test_hard]
+  loader: puzzle
+
+task_cfg: {}
+
+model:
+  num_classes: 10
+  d_v: 288
+  d_e: 32
+  encoder_arch: sudoku
+  enc_d_model: 128
+  enc_num_blocks: 2
+  comm_norm_type: layernorm
+  objective_mode: non_negative
+  x_solver: diagonal_prox
+  z_solver: unrolled_cg
+  z_mode: prox
+  gamma: 2.0
+  cg_iters: 5
+  rm_sharing: sudoku
+  rm_init: soft_slice
+  rm_mode: context          # LoRA modulation on
+  lora_rank: 4
+  lora_init_style: standard
+  num_directions: 9
+  rho_init: 0.25
+  decoder_arch: sudoku
+  dec_hidden_dims: [256]

pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "sheaf-admm"
+version = "0.1.0"
+description = "Learning multi-agent coordination via sheaf-constrained ADMM (JAX/Flax reference implementation)."
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Jeffrey Seely" },
+    { name = "Bartłomiej Cupiał" },
+    { name = "Llion Jones" },
+]
+dependencies = [
+    "jax==0.10.1; sys_platform != 'linux'",
+    "jax[cuda12]==0.10.1; sys_platform == 'linux'",
+    "flax==0.12.7",
+    "optax==0.2.8",
+    "numpy==2.4.6",
+    "hydra-core==1.3.2",
+    "omegaconf==2.3.0",
+    # dataset construction — required to build MNIST / Sudoku / maze locally
+    "ml-datasets==0.2.1",
+    "datasets==4.8.5",
+    "huggingface-hub==1.17.0",
+    # figures / artifacts
+    "matplotlib==3.10.9",
+    "pillow==12.2.0",
+    # experiment tracking
+    "wandb==0.27.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sheaf_admm"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/assets",
+    "/configs",
+    "/scripts",
+    "/src",
+    "/tests",
+    "/LICENSE",
+    "/README.md",
+    "/pyproject.toml",
+    "/uv.lock",
+]
+
+[dependency-groups]
+dev = [
+    "pytest==9.0.3",
+    "ruff==0.15.15",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: end-to-end tests that train a tiny model (deselect with -m 'not slow')",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+# Keep math unicode (ρ, σ, γ, η, λ) — they read better than ASCII in this codebase.
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E741", "RUF002", "RUF003", "B008"]

scripts/aggregate_attempts.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Accept a complete attempt or verify the complete accepted identity set."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.aggregation import accept_attempt, load_complete_units
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--registry", type=Path, required=True)
+    sub = parser.add_subparsers(dest="action", required=True)
+    accept = sub.add_parser("accept")
+    accept.add_argument("--logical-id", required=True)
+    accept.add_argument("--attempt-id", required=True)
+    accept.add_argument("--prefix", type=Path, required=True)
+    verify = sub.add_parser("verify")
+    verify.add_argument("--required-json", type=Path, required=True)
+    args = parser.parse_args()
+    if args.action == "accept":
+        row = accept_attempt(
+            args.registry,
+            logical_id=args.logical_id,
+            attempt_id=args.attempt_id,
+            prefix=args.prefix,
+        )
+        print(json.dumps(row, sort_keys=True))
+    else:
+        required = set(json.loads(args.required_json.read_text()))
+        print(json.dumps(load_complete_units(args.registry, required), sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/build_preupload_privacy.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Assemble the exact multi-scope PRE_UPLOAD_PRIVACY receipt, failing incomplete."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.hashing import atomic_write_json, compact_json_bytes, sha256_bytes, sha256_file
+from repro_control.privacy import SCANNER_VERSION, scan_paths
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--checkout", type=Path, required=True)
+    parser.add_argument("--package-manifest", type=Path, required=True)
+    parser.add_argument("--image-contract", type=Path, required=True)
+    parser.add_argument("--intended-remote-map", type=Path, required=True)
+    parser.add_argument("--output", type=Path, default=Path("PRE_UPLOAD_PRIVACY.json"))
+    args = parser.parse_args()
+    checkout = args.checkout.resolve()
+    tracked = subprocess.run(
+        ["git", "ls-files", "-z"],
+        cwd=checkout,
+        check=True,
+        capture_output=True,
+    ).stdout.split(b"\0")
+    tracked_paths = [checkout / raw.decode() for raw in tracked if raw]
+    source = scan_paths(
+        tracked_paths,
+        relative_to=checkout,
+        intended_remote_map=json.loads(args.intended_remote_map.read_text()),
+    )
+    object_lines = subprocess.run(
+        ["git", "rev-list", "--objects", "--all"],
+        cwd=checkout,
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout.splitlines()
+    git_objects = sorted(line.split()[0] for line in object_lines if line)
+    trackio = checkout / ".trackio"
+    trackio_scan = (
+        scan_paths([trackio], relative_to=checkout, intended_remote_map={})
+        if trackio.is_dir()
+        else None
+    )
+    image = json.loads(args.image_contract.read_text())
+    package_manifest = json.loads(args.package_manifest.read_text())
+    blockers = []
+    if trackio_scan is None:
+        blockers.append(".trackio scaffold does not exist")
+    if not image.get("resolved_and_read_back"):
+        blockers.append("immutable image config/history/layers are unresolved")
+    if source["findings"]:
+        blockers.append("source privacy findings exist")
+    if trackio_scan and trackio_scan["findings"]:
+        blockers.append(".trackio privacy findings exist")
+    receipt = {
+        "format": 1,
+        "scanner_version": SCANNER_VERSION,
+        "rules": source["rules"],
+        "source": source,
+        "git_object_ids": git_objects,
+        "git_object_set_sha256": sha256_bytes(compact_json_bytes(git_objects)),
+        "trackio": trackio_scan,
+        "image_contract_sha256": sha256_file(args.image_contract),
+        "image": image,
+        "private_input_manifest_sha256": sha256_file(args.package_manifest),
+        "private_input_payload_root_sha256": package_manifest["payload_root_sha256"],
+        "intended_remote_map_sha256": sha256_file(args.intended_remote_map),
+        "complete": not blockers,
+        "blockers": blockers,
+        "exit_code": 0 if not blockers else 2,
+    }
+    atomic_write_json(args.output, receipt)
+    print(json.dumps({"complete": receipt["complete"], "blockers": blockers}))
+    return receipt["exit_code"]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/build_registered_data.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Build sealed MNIST mask banks or registered C5 long-path shards."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.data import (
+    build_mnist_mask_bank,
+    generate_c5_size,
+    write_mnist_mask_bank,
+)
+from repro_control.hashing import atomic_write_json
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="command", required=True)
+    masks = sub.add_parser("mnist-masks")
+    masks.add_argument("--dataset-revision", required=True)
+    masks.add_argument("--example-ids-json", type=Path, required=True)
+    masks.add_argument("--output", type=Path, required=True)
+    c5 = sub.add_parser("c5")
+    c5.add_argument("--size", type=int, required=True)
+    c5.add_argument("--training-identities-json", type=Path, required=True)
+    c5.add_argument("--examples", type=int, default=1000)
+    c5.add_argument("--output-npz", type=Path, required=True)
+    c5.add_argument("--output-manifest", type=Path, required=True)
+    args = parser.parse_args()
+    if args.command == "mnist-masks":
+        ids = json.loads(args.example_ids_json.read_text())
+        bank = build_mnist_mask_bank(args.dataset_revision, ids)
+        write_mnist_mask_bank(args.output, bank)
+        print(bank["bank_sha256"])
+        return 0
+    import numpy as np
+
+    identities = frozenset(json.loads(args.training_identities_json.read_text()))
+    arrays, manifest = generate_c5_size(
+        args.size,
+        training_identities=identities,
+        examples=args.examples,
+    )
+    args.output_npz.parent.mkdir(parents=True, exist_ok=True)
+    np.savez_compressed(args.output_npz, **arrays)
+    atomic_write_json(args.output_manifest, manifest)
+    print(manifest["identity_root_sha256"])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/evaluate_repro.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Run one fused verdict evaluator and seal its complete result units."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.archives import safe_extract_tar_gz
+from repro_control.artifacts import finalize_attempt, verify_read_back
+from repro_control.hashing import atomic_write_json, sha256_file
+from repro_control.heartbeat import heartbeat, marker
+from repro_control.runtime import (
+    assert_evaluation_isolated,
+    configure_scientific_runtime,
+    load_job_manifest,
+    require_control_freeze,
+    verify_science_spec,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--science-spec", type=Path, required=True)
+    parser.add_argument("--job-manifest", type=Path, required=True)
+    parser.add_argument("--control-dir", type=Path, required=True)
+    parser.add_argument("--freeze-sha256", required=True)
+    parser.add_argument("--unit-manifest", type=Path)
+    parser.add_argument("--output-dir", type=Path)
+    parser.add_argument("--eval-archive", type=Path)
+    parser.add_argument("--eval-destination", type=Path, default=Path("/data/eval"))
+    parser.add_argument("--imports-archive", type=Path)
+    parser.add_argument("--imports-destination", type=Path, default=Path("/imports"))
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+    spec = verify_science_spec(args.science_spec)
+    manifest = load_job_manifest(args.job_manifest, freeze_sha256=args.freeze_sha256)
+    assert_evaluation_isolated(manifest)
+    if manifest["logical_id"] not in spec["evaluators"]:
+        raise SystemExit("unregistered evaluator logical identity")
+    require_control_freeze(
+        args.control_dir,
+        args.freeze_sha256,
+        manifest["science_spec_sha256"],
+    )
+    configure_scientific_runtime()
+    if args.dry_run:
+        print(
+            json.dumps(
+                {
+                    "contract_verified": True,
+                    "logical_id": manifest["logical_id"],
+                    "outcomes": {},
+                }
+            )
+        )
+        return 0
+    if args.unit_manifest is None or args.output_dir is None:
+        raise SystemExit("--unit-manifest and --output-dir are required for execution")
+    if sha256_file(args.unit_manifest) != manifest["hashes"]["config"]:
+        raise SystemExit("evaluator unit manifest hash mismatch")
+    args.output_dir.mkdir(parents=True, exist_ok=False)
+    if args.eval_archive:
+        safe_extract_tar_gz(args.eval_archive, args.eval_destination)
+    if args.imports_archive:
+        safe_extract_tar_gz(args.imports_archive, args.imports_destination)
+    marker("GPU_READY", manifest["logical_id"])
+    from repro_control.evaluation import evaluate_units
+
+    with heartbeat(f"SCIENTIFIC_EVAL:{manifest['logical_id']}"):
+        evaluate_units(args.unit_manifest, args.output_dir / "results.json")
+    atomic_write_json(
+        args.output_dir / "evaluation-receipt.json",
+        {
+            "format": 1,
+            "logical_id": manifest["logical_id"],
+            "attempt_id": manifest["attempt_id"],
+            "unit_manifest_sha256": sha256_file(args.unit_manifest),
+            "results_sha256": sha256_file(args.output_dir / "results.json"),
+            "outcomes": {},
+        },
+    )
+    finalize_attempt(
+        args.output_dir,
+        logical_id=manifest["logical_id"],
+        attempt_id=manifest["attempt_id"],
+        expected_outputs=manifest["expected_outputs"],
+    )
+    verify_read_back(
+        args.output_dir,
+        logical_id=manifest["logical_id"],
+        attempt_id=manifest["attempt_id"],
+    )
+    marker("DONE", f"{manifest['logical_id']} {manifest['attempt_id']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/freeze_science_spec.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Materialize exact registered configs and propagate the immutable science-spec hash."""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.configs import config_sha256, registered_config_for
+from repro_control.hashing import atomic_write_json, sha256_file
+
+SUDOKU_REVISION = "4d5aa527a9fb9aacca0b0d5b8b77d569fa9afcaa"
+TRACKIO_WHEEL_SHA256 = "277340507ac46c02c06900c1d680129bdb528223c8110b0b6bc9326bb9f0891d"
+BASE_IMAGE = (
+    "python:3.12-slim@"
+    "sha256:cab2dbf575e971934a81e4622f5aba17aa7929719bd7e31033a3a83b97fd0464"
+)
+IMAGE_SPACE_ID = "Mindcraft/sheaf-admm-icml2026-executor"
+
+
+def _replace_spec_hash(path: Path, old: str, new: str) -> None:
+    text = path.read_text()
+    if old not in text:
+        raise RuntimeError(f"old science-spec hash not present in {path}")
+    path.write_text(text.replace(old, new))
+
+
+def main() -> int:
+    root = Path(__file__).resolve().parents[1]
+    spec_path = root / "SCIENCE-SPEC.yaml"
+    old_hash = sha256_file(spec_path)
+    spec = json.loads(spec_path.read_text())
+    if spec.get("outcomes") != {} or len(spec.get("run_identities", [])) != 15:
+        raise RuntimeError("science spec is not in the pre-outcome fifteen-run state")
+    spec["authorities"].update(
+        {
+            "sudoku_dataset_revision": SUDOKU_REVISION,
+            "dependency_lock_sha256": sha256_file(root / "uv.lock"),
+            "trackio_wheel_sha256": TRACKIO_WHEEL_SHA256,
+            "base_image": BASE_IMAGE,
+            "execution_image_space": IMAGE_SPACE_ID,
+        }
+    )
+    spec["data_rules"]["sudoku"]["revision"] = SUDOKU_REVISION
+    registered = {}
+    config_root = root / "control" / "registered-configs"
+    for logical_id in spec["run_identities"]:
+        config = registered_config_for(root, logical_id)
+        digest = config_sha256(config)
+        atomic_write_json(config_root / f"{logical_id}.json", config)
+        if sha256_file(config_root / f"{logical_id}.json") == digest:
+            raise RuntimeError("file-byte hash must remain distinct from canonical config hash")
+        registered[logical_id] = {
+            "canonical_sha256": digest,
+            "file": f"control/registered-configs/{logical_id}.json",
+            "config": config,
+        }
+    spec["registered_configs"] = registered
+    atomic_write_json(spec_path, spec)
+    new_hash = sha256_file(spec_path)
+    if new_hash == old_hash:
+        raise RuntimeError("science spec did not change")
+
+    constants_path = root / "src" / "repro_control" / "constants.py"
+    constants = constants_path.read_text()
+    constants = re.sub(
+        r'SCIENCE_SPEC_SHA256 = "[0-9a-f]{64}"',
+        f'SCIENCE_SPEC_SHA256 = "{new_hash}"',
+        constants,
+        count=1,
+    )
+    constants_path.write_text(constants)
+    _replace_spec_hash(root / "Dockerfile", old_hash, new_hash)
+
+    image_contract_path = root / "IMAGE-SOURCE-CONTRACT.json"
+    image_contract = json.loads(image_contract_path.read_text())
+    image_contract.update(
+        base_image_digest=BASE_IMAGE.rsplit("@", 1)[1],
+        science_spec_sha256=new_hash,
+    )
+    atomic_write_json(image_contract_path, image_contract)
+
+    freeze_path = root / "control" / "SCIENCE-FREEZE.template.yaml"
+    freeze = json.loads(freeze_path.read_text())
+    freeze["science_spec_sha256"] = new_hash
+    atomic_write_json(freeze_path, freeze)
+
+    inventory_path = root / "PUBLICATION-INVENTORY.json"
+    inventory = json.loads(inventory_path.read_text())
+    image_rows = [
+        row for row in inventory["entries"] if row["asset_or_surface_type"] == "execution_image"
+    ]
+    if len(image_rows) != 1:
+        raise RuntimeError("publication inventory must have exactly one execution image row")
+    image_rows[0]["full_url_or_expected_repo"] = (
+        f"https://huggingface.co/spaces/{IMAGE_SPACE_ID}"
+    )
+    atomic_write_json(inventory_path, inventory)
+
+    status_path = root / "LOCAL-IMPLEMENTATION-STATUS.md"
+    if status_path.exists() and old_hash in status_path.read_text():
+        _replace_spec_hash(status_path, old_hash, new_hash)
+    print(
+        json.dumps(
+            {
+                "old_science_spec_sha256": old_hash,
+                "science_spec_sha256": new_hash,
+                "registered_config_count": len(registered),
+                "sudoku_revision": SUDOKU_REVISION,
+            },
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/import_data.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""Build and seal the private train/eval/import input archives on an HF CPU Job."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.archives import create_deterministic_tar_gz
+from repro_control.artifacts import finalize_attempt, verify_read_back
+from repro_control.checkpoints import load_neutral_checkpoint
+from repro_control.data import (
+    C5_SIZES,
+    build_mnist_mask_bank,
+    canonical_maze_identity,
+    generate_c5_size,
+    validate_smoke_fixture_registry,
+    write_mnist_mask_bank,
+    write_puzzle_split,
+)
+from repro_control.hashing import (
+    atomic_write_json,
+    canonical_root,
+    file_entry,
+    sha256_file,
+)
+from repro_control.heartbeat import heartbeat, marker
+from repro_control.runtime import load_job_manifest, verify_science_spec
+
+
+def _verify_handoff(handoff: Path, *, verify_checkpoints: bool) -> list[dict]:
+    package_manifest = json.loads((handoff / "PACKAGE-MANIFEST.json").read_text())
+    for row in package_manifest["entries"]:
+        path = handoff / row["path"]
+        if path.stat().st_size != row["bytes"] or sha256_file(path) != row["sha256"]:
+            raise SystemExit(f"handoff mismatch: {row['path']}")
+    imports = json.loads((handoff / "IMPORTS.json").read_text())
+    if len(imports) != 9:
+        raise SystemExit("IMPORTS.json must contain exactly nine rows")
+    validate_smoke_fixture_registry(handoff / "SMOKE-FIXTURES.json")
+    if verify_checkpoints:
+        for row in imports:
+            load_neutral_checkpoint(
+                handoff / "checkpoints" / row["neutral_alias"] / "checkpoint.pkl",
+                handoff / "configs" / f"{row['neutral_alias']}.json",
+                row,
+            )
+    return imports
+
+
+def _tree_manifest(root: Path) -> dict:
+    entries = [
+        file_entry(path, relative_to=root)
+        for path in sorted(root.rglob("*"))
+        if path.is_file()
+    ]
+    return {"format": 1, "entries": entries, "root_sha256": canonical_root(entries)}
+
+
+def _copy_split(source_dataset: Path, split: str, target_dataset: Path) -> None:
+    target_dataset.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(source_dataset / split, target_dataset / split)
+    for name in ("metadata.json", "config.json"):
+        source = source_dataset / name
+        if source.is_file():
+            shutil.copy2(source, target_dataset / name)
+
+
+def _maze_training_identities(dataset_root: Path) -> frozenset[str]:
+    import numpy as np
+
+    inputs = np.load(dataset_root / "train/all__inputs.npy", mmap_mode="r")
+    labels = np.load(dataset_root / "train/all__labels.npy", mmap_mode="r")
+    return frozenset(
+        canonical_maze_identity(input_row, label_row)
+        for input_row, label_row in zip(inputs, labels, strict=True)
+    )
+
+
+def _build_registered_inputs(
+    handoff: Path,
+    workspace: Path,
+    *,
+    sudoku_revision: str,
+) -> dict:
+    from sheaf_admm.data.build_maze import MazeConfig
+    from sheaf_admm.data.build_maze import build as build_maze
+    from sheaf_admm.data.build_mnist import MNISTConfig
+    from sheaf_admm.data.build_mnist import build as build_mnist
+    from sheaf_admm.data.build_sudoku import SudokuConfig
+    from sheaf_admm.data.build_sudoku import build as build_sudoku
+
+    build_root = workspace / "build"
+    maze_root = build_root / "maze_std3_19px_10k"
+    mnist_root = build_root / "mnist"
+    sudoku_root = build_root / "sudoku_easy"
+
+    marker("HEARTBEAT", "CPU_IMPORT:build-maze")
+    build_maze(
+        MazeConfig(
+            height=19,
+            width=19,
+            train_size=10_000,
+            test_size=1_000,
+            min_path_length=18,
+            train_augment=True,
+            test_augment=False,
+            seed=0,
+            output_dir=maze_root,
+        ),
+        ood_sizes=False,
+    )
+    marker("HEARTBEAT", "CPU_IMPORT:build-mnist")
+    build_mnist(
+        MNISTConfig(
+            padding=0,
+            seed=0,
+            normalize=True,
+            gen_robustness=False,
+            output_dir=mnist_root,
+        )
+    )
+    marker("HEARTBEAT", "CPU_IMPORT:build-sudoku")
+    build_sudoku(
+        SudokuConfig(
+            dataset_revision=sudoku_revision,
+            seed=0,
+            train_size=50_000,
+            test_size=2_000,
+            difficulty_max=2.0,
+            train_augment=True,
+            test_augment=False,
+            output_dir=sudoku_root,
+        )
+    )
+
+    train_root = workspace / "train"
+    eval_root = workspace / "eval"
+    imports_root = workspace / "imports"
+    _copy_split(maze_root, "train", train_root / "maze_std3_19px_10k")
+    _copy_split(mnist_root, "train", train_root / "mnist")
+    _copy_split(sudoku_root, "train", train_root / "sudoku_easy")
+    _copy_split(maze_root, "test", eval_root / "maze_std3_19px_10k")
+    _copy_split(mnist_root, "test", eval_root / "mnist")
+    _copy_split(sudoku_root, "test_hard", eval_root / "sudoku_easy")
+
+    test_count = 10_000
+    mask_bank = build_mnist_mask_bank(
+        f"ml-datasets-0.2.1:{sha256_file(mnist_root / 'test/images.npy')}",
+        range(test_count),
+    )
+    write_mnist_mask_bank(eval_root / "mnist/drop30-mask-bank.json", mask_bank)
+
+    marker("HEARTBEAT", "CPU_IMPORT:build-c5")
+    training_identities = _maze_training_identities(maze_root)
+    c5_receipts = {}
+    for size in C5_SIZES:
+        arrays, c5_manifest = generate_c5_size(
+            size,
+            training_identities=training_identities,
+            examples=1000,
+        )
+        c5_root = eval_root / "c5" / f"{size}x{size}"
+        write_puzzle_split(
+            c5_root,
+            "test",
+            arrays["inputs"],
+            arrays["labels"],
+            height=size,
+            width=size,
+        )
+        atomic_write_json(c5_root / "generation-manifest.json", c5_manifest)
+        c5_receipts[str(size)] = c5_manifest
+
+    shutil.copytree(handoff / "checkpoints", imports_root / "checkpoints")
+    shutil.copytree(handoff / "configs", imports_root / "configs")
+    shutil.copy2(handoff / "IMPORTS.json", imports_root / "IMPORTS.json")
+    shutil.copy2(handoff / "RIGHTS.json", imports_root / "RIGHTS.json")
+    manifests = {
+        "train": _tree_manifest(train_root),
+        "eval": _tree_manifest(eval_root),
+        "imports": _tree_manifest(imports_root),
+    }
+    for name, value in manifests.items():
+        atomic_write_json(workspace / f"{name}-tree-manifest.json", value)
+    return {
+        "tree_manifests": manifests,
+        "mnist_mask_bank_sha256": mask_bank["bank_sha256"],
+        "maze_training_identity_count": len(training_identities),
+        "c5": c5_receipts,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--science-spec", type=Path, required=True)
+    parser.add_argument("--job-manifest", type=Path, required=True)
+    parser.add_argument("--handoff", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    parser.add_argument("--sudoku-revision", required=True)
+    parser.add_argument("--verify-checkpoints", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+    spec = verify_science_spec(args.science_spec)
+    manifest = load_job_manifest(args.job_manifest)
+    if manifest["job_class"] != "CPU_IMPORT":
+        raise SystemExit("CPU import entrypoint requires a CPU_IMPORT manifest")
+    imports = _verify_handoff(args.handoff, verify_checkpoints=args.verify_checkpoints)
+    if args.dry_run:
+        print(
+            json.dumps(
+                {
+                    "contract_verified": True,
+                    "verified_import_rows": len(imports),
+                    "outcomes": {},
+                }
+            )
+        )
+        return 0
+    if args.sudoku_revision != spec["data_rules"]["sudoku"]["revision"]:
+        raise SystemExit("Sudoku revision differs from the frozen science spec")
+    args.output_dir.mkdir(parents=True, exist_ok=False)
+    marker("CPU_READY", "CPU_IMPORT")
+    with (
+        heartbeat("CPU_IMPORT"),
+        tempfile.TemporaryDirectory(prefix="sheaf-import-") as temporary,
+    ):
+        workspace = Path(temporary)
+        build_receipt = _build_registered_inputs(
+            args.handoff,
+            workspace,
+            sudoku_revision=args.sudoku_revision,
+        )
+        archive_hashes = {}
+        for name in ("train", "eval", "imports"):
+            archive = args.output_dir / f"{name}-data.tar.gz"
+            archive_hashes[name] = create_deterministic_tar_gz(workspace / name, archive)
+            shutil.copy2(
+                workspace / f"{name}-tree-manifest.json",
+                args.output_dir / f"{name}-tree-manifest.json",
+            )
+    receipt = {
+        "format": 1,
+        "logical_id": manifest["logical_id"],
+        "attempt_id": manifest["attempt_id"],
+        "verified_import_rows": len(imports),
+        "sudoku_revision": args.sudoku_revision,
+        "archives": archive_hashes,
+        "build": build_receipt,
+        "outcomes": {},
+    }
+    atomic_write_json(args.output_dir / "import-receipt.json", receipt)
+    finalize_attempt(
+        args.output_dir,
+        logical_id=manifest["logical_id"],
+        attempt_id=manifest["attempt_id"],
+        expected_outputs=manifest["expected_outputs"],
+    )
+    verify_read_back(
+        args.output_dir,
+        logical_id=manifest["logical_id"],
+        attempt_id=manifest["attempt_id"],
+    )
+    marker("DONE", f"{manifest['logical_id']} {manifest['attempt_id']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/launch_job.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Prepare, submit, reconcile, poll, or cancel one durable direct HF Job attempt."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.hf_provider import HFJobsProvider
+from repro_control.launcher import (
+    AmbiguousSubmission,
+    BudgetSnapshot,
+    DirectLauncher,
+    LaunchError,
+    LauncherState,
+)
+
+
+def _launcher(args) -> DirectLauncher:
+    provider = HFJobsProvider(namespace=args.namespace) if args.action != "prepare" else None
+    return DirectLauncher(
+        args.state,
+        provider=provider,
+        enable_submit=args.enable_submit,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--state", type=Path, required=True)
+    parser.add_argument("--namespace", default="Mindcraft")
+    parser.add_argument(
+        "--enable-submit",
+        action="store_true",
+        help="Required for submit/cancel; omitted by default to keep the CLI non-mutating.",
+    )
+    sub = parser.add_subparsers(dest="action", required=True)
+    prepare = sub.add_parser("prepare")
+    prepare.add_argument("--request", type=Path, required=True)
+    prepare.add_argument("--budget-snapshot", type=Path, required=True)
+    prepare.add_argument("--guarded-critical-path-seconds", type=int, required=True)
+    submit = sub.add_parser("submit")
+    submit.add_argument("--attempt-id", required=True)
+    reconcile = sub.add_parser("reconcile")
+    reconcile.add_argument("--attempt-id", required=True)
+    poll = sub.add_parser("poll")
+    poll.add_argument("--attempt-id", required=True)
+    cancel = sub.add_parser("cancel")
+    cancel.add_argument("--attempt-id", required=True)
+    sub.add_parser("show")
+    args = parser.parse_args()
+    launcher = _launcher(args)
+    try:
+        if args.action == "prepare":
+            request = json.loads(args.request.read_text())
+            budget = BudgetSnapshot(**json.loads(args.budget_snapshot.read_text()))
+            row = launcher.prepare(
+                request,
+                budget=budget,
+                now=datetime.now(UTC),
+                guarded_critical_path_seconds=args.guarded_critical_path_seconds,
+            )
+        elif args.action == "submit":
+            if not args.enable_submit:
+                raise LaunchError("submit requires --enable-submit")
+            row = launcher.submit_prepared(args.attempt_id)
+        elif args.action == "reconcile":
+            row = launcher.reconcile_ambiguous(args.attempt_id)
+        elif args.action == "poll":
+            row = launcher.poll(args.attempt_id, now=datetime.now(UTC))
+        elif args.action == "cancel":
+            if not args.enable_submit:
+                raise LaunchError("cancel requires --enable-submit")
+            launcher.cancel(args.attempt_id)
+            row = next(
+                item
+                for item in LauncherState.load(args.state).attempts
+                if item["attempt_id"] == args.attempt_id
+            )
+        else:
+            print(
+                json.dumps(
+                    {
+                        "format": 1,
+                        "attempts": LauncherState.load(args.state).attempts,
+                    },
+                    sort_keys=True,
+                )
+            )
+            return 0
+    except AmbiguousSubmission as exc:
+        print(str(exc), file=sys.stderr)
+        return 3
+    except (LaunchError, ValueError, KeyError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    print(json.dumps(row, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/reduce_results.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Apply one exhaustive registered reducer to accepted complete numeric inputs."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.reducers import (
+    reduce_c1,
+    reduce_c2,
+    reduce_c3,
+    reduce_c4_maze,
+    reduce_c4_sudoku,
+    reduce_c5,
+)
+from repro_control.hashing import atomic_write_json
+
+
+def plain(value):
+    if dataclasses.is_dataclass(value):
+        return {field.name: plain(getattr(value, field.name)) for field in dataclasses.fields(value)}
+    if isinstance(value, dict):
+        return {str(key): plain(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [plain(item) for item in value]
+    return value
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--claim", choices=("c1", "c2", "c3", "c4-sudoku", "c4-maze", "c5"), required=True)
+    parser.add_argument("--input", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    value = json.loads(args.input.read_text())
+    reducers = {
+        "c1": reduce_c1,
+        "c2": reduce_c2,
+        "c3": reduce_c3,
+        "c4-sudoku": reduce_c4_sudoku,
+        "c4-maze": reduce_c4_maze,
+        "c5": reduce_c5,
+    }
+    result = reducers[args.claim](**value)
+    atomic_write_json(args.output, plain(result))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/replace_scaffold_cells.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Replace the two official pinned scaffold cells in place."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.scaffold import replace_scaffold_file
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--scaffold-export",
+        type=Path,
+        required=True,
+        help="Official Executive-summary page.md or a synthetic JSON export",
+    )
+    parser.add_argument("--summary", type=Path, required=True)
+    parser.add_argument("--poster", type=Path, required=True)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    replace_scaffold_file(
+        args.scaffold_export,
+        summary_path=args.summary,
+        poster_path=args.poster,
+        output_path=args.output,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/scan_privacy.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Write a deterministic privacy receipt for explicitly selected local roots."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.privacy import scan_paths, write_receipt
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--checkout", type=Path, required=True)
+    parser.add_argument("--root", type=Path, action="append", required=True)
+    parser.add_argument("--intended-remote-map", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    mapping = json.loads(args.intended_remote_map.read_text())
+    receipt = scan_paths(args.root, relative_to=args.checkout, intended_remote_map=mapping)
+    write_receipt(args.output, receipt, require_clean=False)
+    print(json.dumps({"exit_code": receipt["exit_code"], "findings": len(receipt["findings"])}))
+    return receipt["exit_code"]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/smoke_repro.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Run a real, verdict-isolated admission workload and seal its receipt."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.artifacts import finalize_attempt, verify_read_back
+from repro_control.hashing import atomic_write_json
+from repro_control.heartbeat import heartbeat, marker
+from repro_control.runtime import assert_smoke_isolated, load_job_manifest, verify_science_spec
+from repro_control.smoke_runtime import (
+    fixture_hashes,
+    orchestrate_family,
+    run_c5_probe_child,
+    run_family_child,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--science-spec", type=Path)
+    parser.add_argument("--job-manifest", type=Path)
+    parser.add_argument("--family", choices=("sudoku", "maze-c5", "mnist"))
+    parser.add_argument("--project-root", type=Path, default=Path(__file__).resolve().parents[1])
+    parser.add_argument("--handoff", type=Path)
+    parser.add_argument("--output-dir", type=Path)
+    parser.add_argument("--steps-warmup", type=int, default=5)
+    parser.add_argument("--steps-measured", type=int, default=20)
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--allow-cpu-preflight", action="store_true")
+    parser.add_argument("--internal-family-child", choices=("sudoku", "maze-c5", "mnist"))
+    parser.add_argument("--internal-c5-probe-child", action="store_true")
+    parser.add_argument("--size", type=int)
+    parser.add_argument("--batch-size", type=int)
+    parser.add_argument("--timing", action="store_true")
+    args = parser.parse_args()
+
+    if args.internal_family_child:
+        value = run_family_child(
+            args.project_root,
+            args.handoff,
+            args.internal_family_child,
+            warmup_steps=args.steps_warmup,
+            measured_steps=args.steps_measured,
+            allow_cpu=args.allow_cpu_preflight,
+        )
+        print(json.dumps(value))
+        return 0
+    if args.internal_c5_probe_child:
+        value = run_c5_probe_child(
+            args.handoff,
+            size=args.size,
+            batch_size=args.batch_size,
+            timing=args.timing,
+            allow_cpu=args.allow_cpu_preflight,
+        )
+        print(json.dumps(value))
+        return 0
+
+    if not all((args.science_spec, args.job_manifest, args.family, args.handoff)):
+        parser.error("top-level smoke requires spec, manifest, family, and handoff")
+    verify_science_spec(args.science_spec)
+    manifest = load_job_manifest(args.job_manifest)
+    assert_smoke_isolated(manifest)
+    if (args.steps_warmup, args.steps_measured) != (5, 20):
+        raise SystemExit("registered smoke requires 5 warm-up and 20 measured steps")
+    if args.dry_run:
+        print(
+            json.dumps(
+                {
+                    "contract_verified": True,
+                    "family": args.family,
+                    "verdict_metrics_emitted": False,
+                    "outcomes": {},
+                }
+            )
+        )
+        return 0
+    if args.output_dir is None:
+        raise SystemExit("--output-dir is required for execution")
+    args.output_dir.mkdir(parents=True, exist_ok=False)
+    marker("CPU_PREFLIGHT_READY" if args.allow_cpu_preflight else "GPU_READY", args.family)
+    with heartbeat(f"GPU_SMOKE:{args.family}"):
+        result = orchestrate_family(
+            Path(__file__).resolve(),
+            args.project_root,
+            args.handoff,
+            args.family,
+            warmup_steps=args.steps_warmup,
+            measured_steps=args.steps_measured,
+            allow_cpu=args.allow_cpu_preflight,
+        )
+    receipt = {
+        "format": 1,
+        "logical_id": manifest["logical_id"],
+        "attempt_id": manifest["attempt_id"],
+        "family": args.family,
+        "fixture_hashes": fixture_hashes(args.handoff),
+        "warmup_steps": 5,
+        "measured_steps": 20,
+        "result": result,
+        "verdict_metrics_emitted": False,
+        "outcomes": {},
+    }
+    atomic_write_json(args.output_dir / "smoke-receipt.json", receipt)
+    finalize_attempt(
+        args.output_dir,
+        logical_id=manifest["logical_id"],
+        attempt_id=manifest["attempt_id"],
+        expected_outputs=manifest["expected_outputs"],
+    )
+    verify_read_back(
+        args.output_dir,
+        logical_id=manifest["logical_id"],
+        attempt_id=manifest["attempt_id"],
+    )
+    marker("DONE", f"{manifest['logical_id']} {manifest['attempt_id']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/train.py

@@ -0,0 +1,261 @@
+"""Hydra training entrypoint for Sheaf-ADMM (and the MPNN baseline).
+
+One entrypoint for every task (maze / mnist / sudoku) and both model families
+(``model_type=sheaf|mpnn``); the task and HPs come entirely from config.
+
+    python scripts/train.py +experiment=maze_sheaf
+    python scripts/train.py +experiment=sudoku_sheaf training.seed=123
+    python scripts/train.py +experiment=mnist_sheaf
+
+Runs do not log by default. Set ``wandb.mode=online`` to enable Weights & Biases.
+Importing ``sheaf_admm`` pins ``float32`` matmul precision to ``highest`` (the
+paper setting) before any compilation.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import hydra
+import jax
+import numpy as np
+import wandb
+from hydra.core.hydra_config import HydraConfig
+from omegaconf import DictConfig, OmegaConf
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT / "src") not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT / "src"))
+
+import sheaf_admm as _sheaf_admm  # noqa: F401,E402  (sets matmul precision on import)
+from repro_control.checkpoints import save_checkpoint_atomic  # noqa: E402
+from repro_control.configs import (  # noqa: E402
+    config_sha256,
+    load_json_config,
+    verify_before_optimizer,
+)
+from repro_control.hashing import atomic_write_json  # noqa: E402
+from repro_control.interventions import assert_common_bit_identical  # noqa: E402
+from sheaf_admm.data import ImageDataset, PuzzleDataset  # noqa: E402
+from sheaf_admm.models import model_config_from_dict  # noqa: E402
+from sheaf_admm.training import (  # noqa: E402
+    build_model,
+    create_train_state,
+    evaluate,
+    make_task,
+    make_train_step,
+    sample_k,
+)
+
+
+def _puzzle_batch(batch):
+    out = {"inputs": np.asarray(batch["inputs"]), "labels": np.asarray(batch["labels"])}
+    for key in ("height", "width"):
+        if key in batch:
+            out[key] = batch[key]
+    return out
+
+
+def _train_batches(cfg: DictConfig, epoch: int):
+    """Yield ``{inputs/images, labels}`` batches for one training epoch."""
+    d = cfg.data
+    if d.loader == "puzzle":
+        ds = PuzzleDataset(d.dir, d.train_split)
+        for _set, batch in ds.iter_train_batches(
+            cfg.training.batch_size, seed=cfg.training.seed + epoch
+        ):
+            yield _puzzle_batch(batch)
+    else:  # image
+        ds = ImageDataset(d.dir, d.train_split)
+        for batch in ds.iter_batches(
+            cfg.training.batch_size, shuffle=True, seed=cfg.training.seed + epoch
+        ):
+            yield {"images": np.asarray(batch["images"]), "labels": np.asarray(batch["labels"])}
+
+
+def _val_batches(cfg: DictConfig, split: str):
+    d = cfg.data
+    if d.loader == "puzzle":
+        ds = PuzzleDataset(d.dir, split)
+        for _set, batch in ds.iter_test_batches(cfg.training.batch_size):
+            yield _puzzle_batch(batch)
+    else:
+        ds = ImageDataset(d.dir, split)
+        for batch in ds.iter_batches(cfg.training.batch_size, shuffle=False):
+            yield {"images": np.asarray(batch["images"]), "labels": np.asarray(batch["labels"])}
+
+
+@hydra.main(config_path="../configs", config_name="config", version_base=None)
+def main(cfg: DictConfig) -> None:
+    sys.stdout.reconfigure(line_buffering=True)  # flush per line so sbatch log-tailing works live
+    expected_path = os.environ.get("REPRO_EXPECTED_CONFIG_PATH", "")
+    expected_sha256 = os.environ.get("REPRO_EXPECTED_CONFIG_SHA256", "")
+    if bool(expected_path) != bool(expected_sha256):
+        raise RuntimeError("both registered config environment variables are required together")
+    if expected_path:
+        resolved = OmegaConf.to_container(cfg, resolve=True)
+        expected = load_json_config(Path(expected_path))
+        verify_before_optimizer(resolved, expected, expected_sha256=expected_sha256)
+        if config_sha256(expected) != expected_sha256:
+            raise RuntimeError("registered config file hash mismatch")
+        print(f"CONFIG_VERIFIED {expected_sha256}", flush=True)
+    print(OmegaConf.to_yaml(cfg))
+    t = cfg.training
+    run = wandb.init(
+        project=cfg.wandb.project,
+        entity=cfg.wandb.entity,
+        name=cfg.wandb.name,
+        group=cfg.wandb.group,
+        tags=list(cfg.wandb.tags),
+        mode=cfg.wandb.mode,
+        config=OmegaConf.to_container(cfg, resolve=True),
+    )
+
+    task = make_task(cfg.task, **OmegaConf.to_container(cfg.task_cfg, resolve=True))
+    model_cfg = model_config_from_dict(OmegaConf.to_container(cfg.model, resolve=True))
+    model = build_model(model_cfg, cfg.model_type)
+    graph_readout = model_cfg.mpnn_graph_readout
+
+    sample_fwd, _, _ = task.prepare(next(_train_batches(cfg, 0)))
+    state = create_train_state(
+        model,
+        sample_fwd,
+        model_type=cfg.model_type,
+        lr=t.lr,
+        weight_decay=t.weight_decay,
+        warmup_steps=t.warmup_steps,
+        grad_clip=t.grad_clip,
+        ema_decay=t.ema_decay,
+        k_init=t.K_train,
+        loss_window=t.loss_window,
+        seed=cfg.training.seed,
+    )
+    if cfg.model_type == "sheaf" and bool(cfg.model.get("rm_constant", False)):
+        control_model_config = OmegaConf.to_container(cfg.model, resolve=True)
+        control_model_config["rm_init"] = "soft_slice"
+        control_model_config["rm_constant"] = False
+        control_model = build_model(model_config_from_dict(control_model_config), "sheaf")
+        control_state = create_train_state(
+            control_model,
+            sample_fwd,
+            model_type="sheaf",
+            lr=t.lr,
+            weight_decay=t.weight_decay,
+            warmup_steps=t.warmup_steps,
+            grad_clip=t.grad_clip,
+            ema_decay=t.ema_decay,
+            k_init=t.K_train,
+            loss_window=t.loss_window,
+            seed=cfg.training.seed,
+        )
+        counters = {"step": 0, "training_seed": int(cfg.training.seed)}
+        assert_common_bit_identical(
+            control_state.params,
+            state.params,
+            control_state.opt_state,
+            state.opt_state,
+            counters,
+            counters,
+        )
+        parity_path = Path(HydraConfig.get().runtime.output_dir) / "identity-parity.json"
+        atomic_write_json(
+            parity_path,
+            {
+                "format": 1,
+                "common_parameter_leaves_bit_identical": True,
+                "common_optimizer_leaves_bit_identical": True,
+                "counters_bit_identical": True,
+                "identity_parameter_tree_has_restriction_map": False,
+                "checked_before_first_optimizer_step": True,
+                "outcomes": {},
+            },
+        )
+        print("IDENTITY_COMMON_PARITY_VERIFIED", flush=True)
+    run.summary["params"] = sum(x.size for x in jax.tree_util.tree_leaves(state.params))
+    print(f"[init] model_type={cfg.model_type} params={run.summary['params']:,}")
+
+    train_step = make_train_step(task, cfg.model_type, graph_readout)
+    rng = jax.random.PRNGKey(cfg.training.seed)
+    rng_np = np.random.default_rng(cfg.training.seed)
+    history: list[dict] = []
+    best: dict[str, float] = {}
+    step = 0
+
+    for epoch in range(t.epochs):
+        for batch in _train_batches(cfg, epoch):
+            fwd, targets, _ = task.prepare(batch)
+            rng, sub = jax.random.split(rng)
+            k = (
+                sample_k(rng_np, t.train_iters_dist, t.train_iters_min, t.K_train)
+                if cfg.model_type == "sheaf"
+                else t.mpnn_train_rounds
+            )
+            state, loss = train_step(state, fwd, targets, sub, n_iter=k, loss_window=t.loss_window)
+            step += 1
+            loss = float(loss)
+            run.log({"train/loss": loss, "train/k": k, "epoch": epoch}, step=step)
+            if t.exit_on_nan and not np.isfinite(loss):
+                print(f"[epoch {epoch}] non-finite loss — stopping (exit_on_nan).")
+                run.finish(exit_code=1)
+                return
+
+        if epoch % t.val_interval == 0 or epoch == t.epochs - 1:
+            k_eval = t.K_eval if cfg.model_type == "sheaf" else t.mpnn_eval_rounds
+            row = {"epoch": epoch, "loss": loss}
+            for split in cfg.data.val_splits:
+                m = evaluate(
+                    state,
+                    task,
+                    _val_batches(cfg, split),
+                    model_type=cfg.model_type,
+                    graph_readout=graph_readout,
+                    k_eval=k_eval,
+                )
+                row[split] = m
+                run.log({f"val/{split}/{kk}": vv for kk, vv in m.items()}, step=step)
+                for kk, vv in m.items():  # track best-so-far in the run summary
+                    key = f"best/{split}/{kk}"
+                    best[key] = max(best.get(key, vv), vv)
+                print(
+                    f"[epoch {epoch}] loss={loss:.4f}  {split}: "
+                    + "  ".join(f"{kk}={vv * 100:.2f}%" for kk, vv in m.items())
+                )
+            history.append(row)
+            run.summary.update(best)
+        out = Path(HydraConfig.get().runtime.output_dir)
+        save_checkpoint_atomic(
+            out / "checkpoint.partial.pkl",
+            {
+                "params": jax.device_get(state.params),
+                "ema_params": jax.device_get(state.ema_params),
+                "optimizer_state": jax.device_get(state.opt_state),
+                "config": OmegaConf.to_container(cfg, resolve=True),
+                "next_epoch": epoch + 1,
+                "step": step,
+                "jax_rng": np.asarray(jax.device_get(rng)),
+                "numpy_rng_state": rng_np.bit_generator.state,
+            },
+        )
+        atomic_write_json(out / "history.partial.json", history)
+
+    out = Path(HydraConfig.get().runtime.output_dir)
+    save_checkpoint_atomic(
+        out / "checkpoint.pkl",
+        {
+            "params": jax.device_get(state.params),
+            "ema_params": jax.device_get(state.ema_params),
+            "optimizer_state": jax.device_get(state.opt_state),
+            "config": OmegaConf.to_container(cfg, resolve=True),
+            "seed": int(cfg.training.seed),
+            "final_epoch": int(t.epochs) - 1,
+        },
+    )
+    atomic_write_json(out / "history.json", history)
+    print(f"[done] saved checkpoint + history to {out}")
+    run.finish()
+
+
+if __name__ == "__main__":
+    main()

scripts/train_repro.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""Scientific training contract gate for one registered isolated seed."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pickle
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from repro_control.archives import safe_extract_tar_gz
+from repro_control.artifacts import finalize_attempt, verify_read_back
+from repro_control.configs import (
+    config_sha256,
+    load_json_config,
+    registered_config_for,
+    verify_before_optimizer,
+)
+from repro_control.hashing import atomic_write_json, sha256_file
+from repro_control.heartbeat import heartbeat, marker
+from repro_control.interventions import contains_restriction_map
+from repro_control.runtime import (
+    configure_scientific_runtime,
+    load_job_manifest,
+    require_control_freeze,
+    require_jax_platform,
+    verify_science_spec,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--science-spec", type=Path, required=True)
+    parser.add_argument("--job-manifest", type=Path, required=True)
+    parser.add_argument("--control-dir", type=Path, required=True)
+    parser.add_argument("--freeze-sha256", required=True)
+    parser.add_argument("--data-dir", type=Path)
+    parser.add_argument("--train-archive", type=Path)
+    parser.add_argument("--output-dir", type=Path)
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+    spec = verify_science_spec(args.science_spec)
+    manifest = load_job_manifest(args.job_manifest, freeze_sha256=args.freeze_sha256)
+    if manifest["job_class"] != "SCIENTIFIC_TRAIN":
+        raise SystemExit("training entrypoint requires SCIENTIFIC_TRAIN")
+    if manifest["logical_id"] not in spec["run_identities"]:
+        raise SystemExit("unregistered training logical identity")
+    require_control_freeze(args.control_dir, args.freeze_sha256, manifest["science_spec_sha256"])
+    configure_scientific_runtime()
+    if args.dry_run:
+        print(
+            json.dumps(
+                {
+                    "contract_verified": True,
+                    "logical_id": manifest["logical_id"],
+                    "outcomes": {},
+                }
+            )
+        )
+        return 0
+    if args.data_dir is None or args.output_dir is None:
+        raise SystemExit("--data-dir and --output-dir are required for execution")
+    if args.train_archive:
+        safe_extract_tar_gz(args.train_archive, args.data_dir)
+    require_jax_platform("gpu")
+    marker("GPU_READY", manifest["logical_id"])
+    logical_id = manifest["logical_id"]
+    seed = manifest["seed"]
+    expected_path = args.control_dir / "registered-configs" / f"{logical_id}.json"
+    expected = load_json_config(expected_path)
+    expected_sha256 = config_sha256(expected)
+    if expected_sha256 != manifest["hashes"]["config"]:
+        raise SystemExit("registered config hash differs from the Job manifest")
+    independently_composed = registered_config_for(
+        Path(__file__).resolve().parents[1],
+        logical_id,
+        data_root=str(args.data_dir),
+    )
+    verify_before_optimizer(
+        independently_composed,
+        expected,
+        expected_sha256=expected_sha256,
+    )
+    args.output_dir.mkdir(parents=True, exist_ok=False)
+    with heartbeat(f"SCIENTIFIC_TRAIN:{logical_id}"):
+        if logical_id.startswith("C3-MNIST-CNN-"):
+            from repro_control.cnn_training import train_fixed_cnn
+
+            train_fixed_cnn(
+                Path(expected["data"]["dir"]),
+                args.output_dir,
+                seed=seed,
+                registered_config=expected,
+                registered_config_sha256=expected_sha256,
+            )
+        else:
+            root = Path(__file__).resolve().parents[1]
+            if logical_id.startswith("C1-SUD-MPNN225-"):
+                experiment = "sudoku_mpnn"
+                overrides = [
+                    "model.d_v=225",
+                    "training.lr=1.7e-3",
+                    "training.epochs=10",
+                ]
+            elif logical_id.startswith("C2-MAZE-MPNN84-"):
+                experiment = "maze_mpnn"
+                overrides = []
+            elif logical_id.startswith("C4-SUD-IDENTITY-"):
+                experiment = "sudoku_sheaf"
+                overrides = ["model.rm_init=identity", "+model.rm_constant=true"]
+            elif logical_id.startswith("C4-MAZE-QUADRATIC-"):
+                experiment = "maze_sheaf"
+                overrides = ["model.objective_mode=quadratic"]
+            else:
+                raise SystemExit("no registered training backend")
+            command = [
+                sys.executable,
+                str(root / "scripts" / "train.py"),
+                f"+experiment={experiment}",
+                f"training.seed={seed}",
+                f"data.dir={expected['data']['dir']}",
+                "data.val_splits=[]",
+                "wandb.mode=disabled",
+                f"hydra.run.dir={args.output_dir}",
+                *overrides,
+            ]
+            env = os.environ.copy()
+            env.update(
+                REPRO_EXPECTED_CONFIG_PATH=str(expected_path),
+                REPRO_EXPECTED_CONFIG_SHA256=expected_sha256,
+            )
+            subprocess.run(command, check=True, env=env)
+
+    checkpoint_path = args.output_dir / "checkpoint.pkl"
+    with checkpoint_path.open("rb") as handle:
+        checkpoint = pickle.load(handle)
+        if handle.read(1):
+            raise SystemExit("checkpoint contains trailing bytes")
+    if checkpoint.get("ema_params") is None:
+        raise SystemExit("training checkpoint lacks EMA parameters")
+    import jax
+
+    parameter_count = sum(
+        int(leaf.size) for leaf in jax.tree_util.tree_leaves(checkpoint["params"])
+    )
+    identity_parity = None
+    if logical_id.startswith("C4-SUD-IDENTITY-"):
+        parity_path = args.output_dir / "identity-parity.json"
+        if not parity_path.is_file():
+            raise SystemExit("identity training lacks the pre-step parity receipt")
+        identity_parity = json.loads(parity_path.read_text())
+        if not all(
+            identity_parity.get(name) is True
+            for name in (
+                "common_parameter_leaves_bit_identical",
+                "common_optimizer_leaves_bit_identical",
+                "counters_bit_identical",
+                "checked_before_first_optimizer_step",
+            )
+        ):
+            raise SystemExit("identity pre-step parity receipt is not affirmative")
+        if contains_restriction_map(checkpoint["params"]):
+            raise SystemExit("identity checkpoint unexpectedly contains restriction-map parameters")
+    receipt = {
+        "format": 1,
+        "logical_id": logical_id,
+        "attempt_id": manifest["attempt_id"],
+        "seed": seed,
+        "registered_config_sha256": expected_sha256,
+        "checkpoint_sha256": sha256_file(checkpoint_path),
+        "history_sha256": sha256_file(args.output_dir / "history.json"),
+        "parameter_count": parameter_count,
+        "ema": True,
+        "fixed_final_epoch": int(expected["training"]["epochs"]) - 1,
+        "identity_common_parity": identity_parity,
+        "outcomes": {},
+    }
+    atomic_write_json(args.output_dir / "training-receipt.json", receipt)
+    finalize_attempt(
+        args.output_dir,
+        logical_id=logical_id,
+        attempt_id=manifest["attempt_id"],
+        expected_outputs=manifest["expected_outputs"],
+    )
+    verify_read_back(
+        args.output_dir,
+        logical_id=logical_id,
+        attempt_id=manifest["attempt_id"],
+    )
+    marker("DONE", f"{logical_id} {manifest['attempt_id']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/visualize.py

@@ -0,0 +1,153 @@
+"""Emit the paper's analysis artifacts from a trained Sheaf-ADMM checkpoint.
+
+Loads a ``checkpoint.pkl`` written by ``scripts/train.py`` (a dict with
+``params`` / ``ema_params`` / ``config``), rebuilds the model + task from the
+embedded config, pulls one validation batch, and writes the three artifacts:
+
+* ``prediction_evolution.pdf`` — global prediction vs ADMM count ``k``;
+* ``coordination_dynamics.pdf`` — primal/dual residual heatmaps + curves;
+* ``xz_trajectories.pdf`` — per-agent x-vs-z 2-D trajectories.
+
+    python -m scripts.visualize --checkpoint outputs/.../checkpoint.pkl --out-dir /tmp/viz
+
+The ``--task`` / ``--data-dir`` flags override what the checkpoint config says
+(useful for visualizing on an OOD split). Evaluation uses the EMA parameters by
+default (``--params ema``), matching how the trainer reports metrics.
+Only Sheaf-ADMM checkpoints are supported; MPNN baselines do not expose an ADMM
+trajectory.
+"""
+
+from __future__ import annotations
+
+import argparse
+import pickle
+import sys
+from pathlib import Path
+
+import numpy as np
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT / "src") not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT / "src"))
+
+import sheaf_admm as _sheaf_admm  # noqa: F401,E402  (sets matmul precision on import)
+from sheaf_admm.data import ImageDataset, PuzzleDataset  # noqa: E402
+from sheaf_admm.models import model_config_from_dict  # noqa: E402
+from sheaf_admm.training import build_model, make_task  # noqa: E402
+from sheaf_admm.viz import (  # noqa: E402
+    plot_coordination_dynamics,
+    plot_prediction_evolution,
+    plot_xz_trajectories,
+    run_trajectory,
+)
+
+# Default per-task ADMM counts for the prediction-evolution panels.
+DEFAULT_KS = {"maze": (1, 3, 5, 10, 30), "sudoku": (1, 3, 5, 10, 20), "mnist": (1, 3, 5, 10, 30)}
+
+
+def _first_batch(cfg: dict, task_name: str, data_dir: str, split: str):
+    loader = cfg["data"].get("loader", "puzzle" if task_name in ("maze", "sudoku") else "image")
+    if loader == "puzzle":
+        ds = PuzzleDataset(data_dir, split)
+        for _set, b in ds.iter_test_batches(batch_size=8):
+            batch = {"inputs": np.asarray(b["inputs"]), "labels": np.asarray(b["labels"])}
+            for key in ("height", "width"):
+                if key in b:
+                    batch[key] = b[key]
+            return batch
+    ds = ImageDataset(data_dir, split)
+    for b in ds.iter_batches(batch_size=8, shuffle=False):
+        return {"images": np.asarray(b["images"]), "labels": np.asarray(b["labels"])}
+    raise RuntimeError("no batch available from the dataset")
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--checkpoint", required=True, help="path to checkpoint.pkl")
+    p.add_argument("--out-dir", required=True, help="directory for the artifact files")
+    p.add_argument("--task", default=None, help="override task (maze|sudoku|mnist)")
+    p.add_argument("--data-dir", default=None, help="override dataset directory")
+    p.add_argument("--split", default=None, help="dataset split (default: first val split)")
+    p.add_argument("--params", choices=("ema", "raw"), default="ema", help="which weights to use")
+    p.add_argument(
+        "--num-iters", type=int, default=30, help="ADMM steps for the trajectory artifacts"
+    )
+    p.add_argument("--batch-index", type=int, default=0, help="example index within the batch")
+    p.add_argument(
+        "--ks", type=int, nargs="+", default=None, help="ADMM counts for prediction evolution"
+    )
+    args = p.parse_args()
+
+    with open(args.checkpoint, "rb") as f:
+        ckpt = pickle.load(f)
+    cfg = ckpt["config"]
+    if cfg.get("model_type") != "sheaf":
+        raise ValueError(
+            "scripts.visualize supports Sheaf-ADMM checkpoints only "
+            f"(got model_type={cfg.get('model_type')!r})."
+        )
+    params = ckpt.get("ema_params") if args.params == "ema" else ckpt["params"]
+    if params is None:
+        params = ckpt["params"]
+
+    task_name = args.task or cfg["task"]
+    data_dir = args.data_dir or cfg["data"]["dir"]
+    split = args.split or cfg["data"]["val_splits"][0]
+    ks = tuple(args.ks) if args.ks else DEFAULT_KS[task_name]
+
+    task = make_task(task_name, **cfg.get("task_cfg", {}))
+    model_cfg = model_config_from_dict(cfg["model"])
+    model = build_model(model_cfg, cfg["model_type"])
+
+    batch = _first_batch(cfg, task_name, data_dir, split)
+    fwd, targets, aux = task.prepare(batch)
+
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    written = []
+    written.append(
+        plot_prediction_evolution(
+            model,
+            params,
+            task,
+            fwd,
+            targets,
+            aux,
+            ks,
+            str(out_dir / "prediction_evolution.pdf"),
+            batch_index=args.batch_index,
+            title=f"{task_name}: prediction vs k",
+        )
+    )
+
+    centers = aux.get("centers")
+    traj = run_trajectory(
+        model,
+        params,
+        fwd,
+        num_iters=args.num_iters,
+        batch_index=args.batch_index,
+        centers=centers,
+    )
+    written.append(
+        plot_coordination_dynamics(
+            traj,
+            str(out_dir / "coordination_dynamics.pdf"),
+            title=f"{task_name}: coordination dynamics (rho={traj.rho:.3g})",
+        )
+    )
+    written.append(
+        plot_xz_trajectories(
+            traj,
+            str(out_dir / "xz_trajectories.pdf"),
+            title=f"{task_name}: x vs z trajectories",
+        )
+    )
+
+    for path in written:
+        print(f"[viz] wrote {path}")
+
+
+if __name__ == "__main__":
+    main()

src/repro_control/__init__.py

@@ -0,0 +1,5 @@
+"""Fail-closed control plane for the registered local reproduction."""
+
+from .constants import SCIENCE_SPEC_SHA256
+
+__all__ = ["SCIENCE_SPEC_SHA256"]

src/repro_control/aggregation.py

@@ -0,0 +1,69 @@
+"""Accepted-attempt registry and complete-only aggregation."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .artifacts import verify_read_back
+from .hashing import atomic_write_json, sha256_file
+
+
+class AggregationError(ValueError):
+    pass
+
+
+def accept_attempt(
+    registry_path: Path,
+    *,
+    logical_id: str,
+    attempt_id: str,
+    prefix: Path,
+) -> dict[str, Any]:
+    registry = (
+        json.loads(registry_path.read_text())
+        if registry_path.exists()
+        else {"format": 1, "accepted_attempts": []}
+    )
+    if set(registry) != {"format", "accepted_attempts"} or registry["format"] != 1:
+        raise AggregationError("invalid accepted-attempt registry")
+    existing = [
+        row for row in registry["accepted_attempts"] if row["logical_id"] == logical_id
+    ]
+    if existing:
+        raise AggregationError(f"logical identity already accepted: {logical_id}")
+    done = verify_read_back(prefix, logical_id=logical_id, attempt_id=attempt_id)
+    row = {
+        "logical_id": logical_id,
+        "attempt_id": attempt_id,
+        "prefix": prefix.as_posix(),
+        "done_sha256": sha256_file(prefix / "DONE.json"),
+        "object_root_sha256": done["object_root_sha256"],
+    }
+    registry["accepted_attempts"].append(row)
+    registry["accepted_attempts"].sort(key=lambda item: item["logical_id"])
+    atomic_write_json(registry_path, registry)
+    return row
+
+
+def load_complete_units(registry_path: Path, required_logical_ids: set[str]) -> list[dict[str, Any]]:
+    registry = json.loads(registry_path.read_text())
+    rows = registry["accepted_attempts"]
+    identities = [row["logical_id"] for row in rows]
+    if len(identities) != len(set(identities)):
+        raise AggregationError("duplicate accepted logical identities")
+    missing = required_logical_ids - set(identities)
+    extra = set(identities) - required_logical_ids
+    if missing or extra:
+        raise AggregationError(f"accepted identity mismatch: missing={sorted(missing)} extra={sorted(extra)}")
+    for row in rows:
+        prefix = Path(row["prefix"])
+        done = verify_read_back(
+            prefix, logical_id=row["logical_id"], attempt_id=row["attempt_id"]
+        )
+        if sha256_file(prefix / "DONE.json") != row["done_sha256"]:
+            raise AggregationError("accepted DONE receipt changed")
+        if done["object_root_sha256"] != row["object_root_sha256"]:
+            raise AggregationError("accepted object root changed")
+    return rows

src/repro_control/archives.py

@@ -0,0 +1,75 @@
+"""Deterministic input archives and traversal-safe extraction."""
+
+from __future__ import annotations
+
+import gzip
+import shutil
+import tarfile
+from pathlib import Path, PurePosixPath
+
+from .hashing import sha256_file
+
+
+class ArchiveError(ValueError):
+    pass
+
+
+def create_deterministic_tar_gz(source: Path, destination: Path) -> str:
+    if not source.is_dir():
+        raise ArchiveError(f"archive source is not a directory: {source}")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with (
+        destination.open("wb") as raw,
+        gzip.GzipFile(filename="", mode="wb", fileobj=raw, mtime=0) as compressed,
+        tarfile.open(fileobj=compressed, mode="w", format=tarfile.PAX_FORMAT) as archive,
+    ):
+        for path in sorted(source.rglob("*")):
+            relative = path.relative_to(source)
+            info = archive.gettarinfo(str(path), arcname=relative.as_posix())
+            info.uid = 0
+            info.gid = 0
+            info.uname = ""
+            info.gname = ""
+            info.mtime = 0
+            info.mode = 0o755 if path.is_dir() else 0o644
+            if path.is_file():
+                with path.open("rb") as handle:
+                    archive.addfile(info, handle)
+            elif path.is_dir():
+                archive.addfile(info)
+            else:
+                raise ArchiveError(f"unsupported archive entry: {path}")
+    return sha256_file(destination)
+
+
+def safe_extract_tar_gz(archive_path: Path, destination: Path) -> None:
+    if destination.exists() and any(destination.iterdir()):
+        raise ArchiveError(f"extraction destination is not empty: {destination}")
+    destination.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(archive_path, mode="r:gz") as archive:
+        members = archive.getmembers()
+        names = set()
+        for member in members:
+            relative = PurePosixPath(member.name)
+            if relative.is_absolute() or ".." in relative.parts or not relative.parts:
+                raise ArchiveError(f"unsafe archive member: {member.name!r}")
+            if member.name in names:
+                raise ArchiveError(f"duplicate archive member: {member.name!r}")
+            names.add(member.name)
+            if member.issym() or member.islnk() or member.isdev():
+                raise ArchiveError(f"links/devices are forbidden in input archives: {member.name}")
+        archive.extractall(destination, members=members, filter="data")
+
+
+def copy_tree_selected(source: Path, destination: Path, names: tuple[str, ...]) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    for name in names:
+        src = source / name
+        dst = destination / name
+        if not src.exists():
+            raise ArchiveError(f"selected source does not exist: {src}")
+        if src.is_dir():
+            shutil.copytree(src, dst)
+        else:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dst)

src/repro_control/artifacts.py

@@ -0,0 +1,85 @@
+"""Incremental object manifests, DONE-last completion, and independent read-back."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .hashing import atomic_write_json, canonical_root, file_entry, sha256_file
+
+OBJECT_MANIFEST = "OBJECT-MANIFEST.json"
+DONE_MARKER = "DONE.json"
+
+
+class ArtifactError(ValueError):
+    pass
+
+
+def build_object_manifest(prefix: Path, expected_outputs: list[str]) -> dict[str, Any]:
+    forbidden = {OBJECT_MANIFEST, DONE_MARKER}
+    outputs = [name for name in expected_outputs if name not in forbidden]
+    entries = []
+    for name in outputs:
+        path = prefix / name
+        if not path.is_file():
+            raise ArtifactError(f"missing expected output {name}")
+        entries.append(file_entry(path, relative_to=prefix))
+    manifest = {"format": 1, "entries": entries, "root_sha256": canonical_root(entries)}
+    atomic_write_json(prefix / OBJECT_MANIFEST, manifest)
+    return manifest
+
+
+def finalize_attempt(
+    prefix: Path,
+    *,
+    logical_id: str,
+    attempt_id: str,
+    expected_outputs: list[str],
+) -> dict[str, Any]:
+    if (prefix / DONE_MARKER).exists():
+        raise ArtifactError("DONE.json already exists")
+    manifest = build_object_manifest(prefix, expected_outputs)
+    done = {
+        "format": 1,
+        "logical_id": logical_id,
+        "attempt_id": attempt_id,
+        "object_manifest_sha256": sha256_file(prefix / OBJECT_MANIFEST),
+        "object_root_sha256": manifest["root_sha256"],
+        "complete": True,
+        "outcomes": {},
+    }
+    atomic_write_json(prefix / DONE_MARKER, done)
+    return done
+
+
+def verify_read_back(
+    prefix: Path, *, logical_id: str | None = None, attempt_id: str | None = None
+) -> dict[str, Any]:
+    done_path = prefix / DONE_MARKER
+    manifest_path = prefix / OBJECT_MANIFEST
+    if not done_path.is_file() or not manifest_path.is_file():
+        raise ArtifactError("attempt lacks completion markers")
+    done = json.loads(done_path.read_text())
+    manifest = json.loads(manifest_path.read_text())
+    if done.get("complete") is not True or done.get("outcomes") != {}:
+        raise ArtifactError("invalid local pre-outcome DONE marker")
+    if logical_id is not None and done.get("logical_id") != logical_id:
+        raise ArtifactError("logical_id mismatch")
+    if attempt_id is not None and done.get("attempt_id") != attempt_id:
+        raise ArtifactError("attempt_id mismatch")
+    if done.get("object_manifest_sha256") != sha256_file(manifest_path):
+        raise ArtifactError("object manifest hash mismatch")
+    actual = []
+    for row in manifest.get("entries", []):
+        path = prefix / row["path"]
+        if not path.is_file():
+            raise ArtifactError(f"missing object {row['path']}")
+        entry = file_entry(path, relative_to=prefix)
+        if entry != row:
+            raise ArtifactError(f"read-back mismatch {row['path']}")
+        actual.append(entry)
+    root = canonical_root(actual)
+    if root != manifest.get("root_sha256") or root != done.get("object_root_sha256"):
+        raise ArtifactError("object root mismatch")
+    return done

src/repro_control/c5_runtime.py

@@ -0,0 +1,52 @@
+"""C5 GPU admission probing and deterministic padded-tail runtime checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+BATCH_CANDIDATES = (1, 2, 4, 8, 16, 32, 64, 128)
+
+
+class C5RuntimeError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Probe:
+    batch_size: int
+    peak_bytes: int
+    post_compile_seconds: tuple[float, float, float]
+    weight_swap_compile_counts: tuple[int, int, int]
+
+
+def select_batch(probes: list[Probe], total_vram_bytes: int) -> Probe:
+    by_size = {probe.batch_size: probe for probe in probes}
+    if 1 not in by_size:
+        raise C5RuntimeError("batch-1 probe failure rejects the route")
+    valid = []
+    for size in BATCH_CANDIDATES:
+        probe = by_size.get(size)
+        if probe is None:
+            continue
+        if probe.peak_bytes <= 0 or probe.peak_bytes > 0.8 * total_vram_bytes:
+            continue
+        if len(probe.post_compile_seconds) != 3 or any(
+            value <= 0 for value in probe.post_compile_seconds
+        ):
+            raise C5RuntimeError("each probe needs three positive post-compile timings")
+        if probe.weight_swap_compile_counts != (1, 1, 1):
+            raise C5RuntimeError("all three weight swaps must reuse one compiled executable")
+        valid.append(probe)
+    if not valid:
+        raise C5RuntimeError("no batch size meets the 80% VRAM and parity contract")
+    return max(valid, key=lambda probe: probe.batch_size)
+
+
+def padded_tail(total_examples: int, batch_size: int) -> tuple[int, tuple[bool, ...]]:
+    if total_examples <= 0 or batch_size <= 0:
+        raise ValueError("total_examples and batch_size must be positive")
+    remainder = total_examples % batch_size
+    real = batch_size if remainder == 0 else remainder
+    return (total_examples + batch_size - 1) // batch_size, tuple(
+        index < real for index in range(batch_size)
+    )

src/repro_control/checkpoints.py

@@ -0,0 +1,93 @@
+"""Neutral checkpoint hashing, structural validation, and atomic round trips."""
+
+from __future__ import annotations
+
+import json
+import os
+import pickle
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .hashing import sha256_file
+
+
+class CheckpointError(ValueError):
+    pass
+
+
+def _tree_leaves(value: Any):
+    if isinstance(value, dict):
+        for key in sorted(value):
+            yield from _tree_leaves(value[key])
+    elif isinstance(value, (list, tuple)):
+        for item in value:
+            yield from _tree_leaves(item)
+    else:
+        yield value
+
+
+def parameter_count(tree: Any) -> int:
+    total = 0
+    for leaf in _tree_leaves(tree):
+        size = getattr(leaf, "size", None)
+        if size is None:
+            if isinstance(leaf, (int, float, bool, complex)):
+                size = 1
+            else:
+                raise CheckpointError(f"non-array parameter leaf {type(leaf).__name__}")
+        total += int(size)
+    return total
+
+
+def load_neutral_checkpoint(
+    checkpoint_path: Path,
+    config_path: Path,
+    import_row: dict[str, Any],
+) -> tuple[Any, dict[str, Any]]:
+    if checkpoint_path.stat().st_size != import_row["byte_size"]:
+        raise CheckpointError("checkpoint byte-size mismatch")
+    if sha256_file(checkpoint_path) != import_row["checkpoint_sha256"]:
+        raise CheckpointError("checkpoint hash mismatch")
+    if sha256_file(config_path) != import_row["sanitized_config_sha256"]:
+        raise CheckpointError("sanitized config hash mismatch")
+    config = json.loads(config_path.read_text())
+    with checkpoint_path.open("rb") as handle:
+        checkpoint = pickle.load(handle)
+        if handle.read(1):
+            raise CheckpointError("trailing checkpoint bytes")
+    if not isinstance(checkpoint, dict):
+        raise CheckpointError("checkpoint root must be a mapping")
+    params = checkpoint.get("params")
+    ema = checkpoint.get("ema_params")
+    if params is None or ema is None:
+        raise CheckpointError("checkpoint must contain params and EMA params")
+    if import_row["ema_status"]["present"] is not True:
+        raise CheckpointError("import row does not authorize EMA evaluation")
+    if parameter_count(params) != parameter_count(ema):
+        raise CheckpointError("parameter and EMA tree counts differ")
+    return checkpoint, config
+
+
+def save_checkpoint_atomic(path: Path, checkpoint: dict[str, Any]) -> str:
+    if "params" not in checkpoint or "ema_params" not in checkpoint:
+        raise CheckpointError("checkpoint must contain params and ema_params")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            pickle.dump(checkpoint, handle, protocol=5)
+            handle.flush()
+            os.fsync(handle.fileno())
+        with open(temporary, "rb") as handle:
+            reloaded = pickle.load(handle)
+        if parameter_count(reloaded["params"]) != parameter_count(checkpoint["params"]):
+            raise CheckpointError("checkpoint round-trip parameter mismatch")
+        os.replace(temporary, path)
+    except BaseException:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+        raise
+    return sha256_file(path)

src/repro_control/cnn.py

@@ -0,0 +1,109 @@
+"""Exact fixed MNIST CNN registered for Claim 3."""
+
+from __future__ import annotations
+
+from typing import Any
+
+PARAMETER_COUNT = 65_642
+
+
+def _jax():
+    import jax
+    import jax.numpy as jnp
+
+    return jax, jnp
+
+
+def init_params(key) -> dict[str, dict[str, Any]]:
+    jax, jnp = _jax()
+
+    def layer(subkey, shape):
+        fan_in = shape[0] * shape[1] * shape[2] if len(shape) == 4 else shape[0]
+        fan_out = shape[0] * shape[1] * shape[3] if len(shape) == 4 else shape[1]
+        limit = jnp.sqrt(jnp.asarray(6.0 / (fan_in + fan_out), dtype=jnp.float32))
+        return jax.random.uniform(subkey, shape, jnp.float32, -limit, limit)
+
+    keys = jax.random.split(key, 5)
+    params = {
+        "conv1": {"kernel": layer(keys[0], (3, 3, 1, 32)), "bias": jnp.zeros((32,), jnp.float32)},
+        "conv2": {"kernel": layer(keys[1], (3, 3, 32, 32)), "bias": jnp.zeros((32,), jnp.float32)},
+        "conv3": {"kernel": layer(keys[2], (3, 3, 32, 64)), "bias": jnp.zeros((64,), jnp.float32)},
+        "conv4": {"kernel": layer(keys[3], (3, 3, 64, 64)), "bias": jnp.zeros((64,), jnp.float32)},
+        "dense": {"kernel": layer(keys[4], (64, 10)), "bias": jnp.zeros((10,), jnp.float32)},
+    }
+    if count_parameters(params) != PARAMETER_COUNT:
+        raise AssertionError("fixed CNN parameter count mismatch")
+    return params
+
+
+def forward(params, images, *, return_shapes: bool = False):
+    jax, jnp = _jax()
+    x = jnp.asarray(images, dtype=jnp.float32)
+    if x.ndim != 4 or x.shape[-1] != 1 or x.shape[1] not in (28, 60) or x.shape[2] != x.shape[1]:
+        raise ValueError("images must be float32 [B,28,28,1] or [B,60,60,1]")
+    shapes = [tuple(x.shape)]
+
+    def conv(value, layer):
+        value = jax.lax.conv_general_dilated(
+            value,
+            params[layer]["kernel"],
+            window_strides=(1, 1),
+            padding="SAME",
+            dimension_numbers=("NHWC", "HWIO", "NHWC"),
+        )
+        return jax.nn.relu(value + params[layer]["bias"])
+
+    x = conv(x, "conv1")
+    x = conv(x, "conv2")
+    shapes.append(tuple(x.shape))
+    x = jax.lax.reduce_window(
+        x,
+        -jnp.inf,
+        jax.lax.max,
+        window_dimensions=(1, 2, 2, 1),
+        window_strides=(1, 2, 2, 1),
+        padding="VALID",
+    )
+    shapes.append(tuple(x.shape))
+    x = conv(x, "conv3")
+    x = conv(x, "conv4")
+    x = jnp.mean(x, axis=(1, 2))
+    logits = x @ params["dense"]["kernel"] + params["dense"]["bias"]
+    return (logits, shapes) if return_shapes else logits
+
+
+def count_parameters(params) -> int:
+    jax, _ = _jax()
+    return sum(int(leaf.size) for leaf in jax.tree_util.tree_leaves(params))
+
+
+def kernel_weight_decay_mask(params):
+    jax, _ = _jax()
+    flat, structure = jax.tree_util.tree_flatten_with_path(params)
+    leaves = [bool(path and getattr(path[-1], "key", None) == "kernel") for path, _ in flat]
+    return jax.tree_util.tree_unflatten(structure, leaves)
+
+
+def padded_masked_batches(images, labels, *, batch_size: int = 128):
+    """Yield fixed-size batches and real-example masks for exact loss normalization."""
+    _, jnp = _jax()
+    images, labels = jnp.asarray(images), jnp.asarray(labels)
+    if len(images) != len(labels):
+        raise ValueError("images and labels length mismatch")
+    for start in range(0, len(images), batch_size):
+        stop = min(start + batch_size, len(images))
+        real = stop - start
+        pad = batch_size - real
+        yield (
+            jnp.pad(images[start:stop], ((0, pad), (0, 0), (0, 0), (0, 0))),
+            jnp.pad(labels[start:stop], ((0, pad),)),
+            jnp.arange(batch_size) < real,
+        )
+
+
+def masked_sparse_cross_entropy(logits, labels, mask):
+    jax, jnp = _jax()
+    log_probs = jax.nn.log_softmax(logits)
+    losses = -jnp.take_along_axis(log_probs, labels[:, None], axis=-1)[:, 0]
+    weights = jnp.asarray(mask, jnp.float32)
+    return jnp.sum(losses * weights) / jnp.maximum(jnp.sum(weights), 1)

src/repro_control/cnn_training.py

@@ -0,0 +1,120 @@
+"""Fixed-final-epoch trainer for the registered CNN family."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .checkpoints import save_checkpoint_atomic
+from .cnn import forward, init_params, kernel_weight_decay_mask, masked_sparse_cross_entropy
+from .configs import verify_before_optimizer
+from .hashing import atomic_write_json
+
+
+def train_fixed_cnn(
+    data_dir: Path,
+    output_dir: Path,
+    *,
+    seed: int,
+    registered_config: dict,
+    registered_config_sha256: str,
+) -> None:
+    import jax
+    import jax.numpy as jnp
+    import numpy as np
+    import optax
+
+    from sheaf_admm.data import ImageDataset
+
+    verify_before_optimizer(
+        registered_config,
+        registered_config,
+        expected_sha256=registered_config_sha256,
+    )
+    if registered_config["training"]["seed"] != seed:
+        raise ValueError("CNN seed differs from the registered config")
+    if Path(registered_config["data"]["dir"]) != data_dir:
+        raise ValueError("CNN data path differs from the registered config")
+    dataset = ImageDataset(data_dir, "train")
+    if dataset.num_examples != 60_000:
+        raise ValueError("registered CNN requires the full 60,000-example train set")
+    images = np.asarray(dataset.images, dtype=np.float32)
+    labels = np.asarray(dataset.labels, dtype=np.int32)
+    if images.shape[1:] != (28, 28, 1) or np.min(images) < 0 or np.max(images) > 1:
+        raise ValueError("registered CNN input must be [60000,28,28,1] float32 in [0,1]")
+
+    key = jax.random.PRNGKey(seed)
+    params = init_params(key)
+    schedule = optax.join_schedules(
+        [optax.linear_schedule(0.0, 1e-3, 200), optax.constant_schedule(1e-3)],
+        [200],
+    )
+    optimizer = optax.chain(
+        optax.clip_by_global_norm(1.0),
+        optax.adamw(
+            schedule,
+            b1=0.9,
+            b2=0.999,
+            eps=1e-8,
+            weight_decay=1e-7,
+            mask=kernel_weight_decay_mask(params),
+        ),
+    )
+    optimizer_state = optimizer.init(params)
+    ema = jax.tree_util.tree_map(jnp.copy, params)
+
+    @jax.jit
+    def step(params, optimizer_state, ema, batch_images, batch_labels, real_mask):
+        loss, grads = jax.value_and_grad(
+            lambda p: masked_sparse_cross_entropy(
+                forward(p, batch_images), batch_labels, real_mask
+            )
+        )(params)
+        updates, optimizer_state = optimizer.update(grads, optimizer_state, params)
+        params = optax.apply_updates(params, updates)
+        ema = jax.tree_util.tree_map(lambda e, p: 0.999 * e + 0.001 * p, ema, params)
+        return params, optimizer_state, ema, loss
+
+    history = []
+    for epoch in range(20):
+        permutation = np.asarray(jax.random.permutation(jax.random.fold_in(key, epoch), 60_000))
+        epoch_losses = []
+        for start in range(0, 60_000, 128):
+            indices = permutation[start : start + 128]
+            real = len(indices)
+            if real < 128:
+                indices = np.pad(indices, (0, 128 - real), constant_values=0)
+            mask = np.arange(128) < real
+            params, optimizer_state, ema, loss = step(
+                params,
+                optimizer_state,
+                ema,
+                images[indices],
+                labels[indices],
+                mask,
+            )
+            epoch_losses.append(float(loss))
+        history.append({"epoch": epoch, "mean_train_loss": float(np.mean(epoch_losses))})
+        output_dir.mkdir(parents=True, exist_ok=True)
+        save_checkpoint_atomic(
+            output_dir / "checkpoint.partial.pkl",
+            {
+                "params": jax.device_get(params),
+                "ema_params": jax.device_get(ema),
+                "optimizer_state": jax.device_get(optimizer_state),
+                "seed": seed,
+                "next_epoch": epoch + 1,
+                "model": "mnist_cnn_repro",
+            },
+        )
+        atomic_write_json(output_dir / "history.partial.json", history)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    checkpoint = {
+        "params": jax.device_get(params),
+        "ema_params": jax.device_get(ema),
+        "optimizer_state": jax.device_get(optimizer_state),
+        "seed": seed,
+        "final_epoch": 19,
+        "model": "mnist_cnn_repro",
+    }
+    save_checkpoint_atomic(output_dir / "checkpoint.pkl", checkpoint)
+    atomic_write_json(output_dir / "history.json", history)

src/repro_control/configs.py

@@ -0,0 +1,194 @@
+"""Exact registered config expansion and pre-optimizer verification."""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+from typing import Any
+
+from .hashing import compact_json_bytes, sha256_bytes
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def _set_path(value: dict[str, Any], dotted: str, replacement: Any) -> None:
+    parts = dotted.split(".")
+    cursor = value
+    for part in parts[:-1]:
+        child = cursor.get(part)
+        if not isinstance(child, dict):
+            raise ConfigError(f"override path does not resolve: {dotted}")
+        cursor = child
+    if parts[-1] not in cursor:
+        raise ConfigError(f"override targets unknown key: {dotted}")
+    cursor[parts[-1]] = replacement
+
+
+def expand_exact(base: dict[str, Any], overrides: dict[str, Any]) -> dict[str, Any]:
+    result = copy.deepcopy(base)
+    for dotted in sorted(overrides):
+        _set_path(result, dotted, overrides[dotted])
+    return result
+
+
+def config_sha256(value: dict[str, Any]) -> str:
+    return sha256_bytes(compact_json_bytes(value))
+
+
+def verify_before_optimizer(
+    resolved: dict[str, Any],
+    expected: dict[str, Any],
+    *,
+    expected_sha256: str,
+) -> None:
+    if resolved != expected:
+        raise ConfigError("resolved config differs from the frozen expansion")
+    if config_sha256(resolved) != expected_sha256:
+        raise ConfigError("resolved config hash differs from the frozen expansion")
+    training = resolved.get("training", {})
+    data = resolved.get("data", {})
+    required = {
+        "batch_size": 128,
+        "warmup_steps": 200,
+        "grad_clip": 1.0,
+        "ema_decay": 0.999,
+    }
+    for name, expected_value in required.items():
+        if training.get(name) != expected_value:
+            raise ConfigError(f"training.{name} must equal {expected_value}")
+    if data.get("val_splits") != []:
+        raise ConfigError("training configuration must have data.val_splits=[]")
+    if resolved.get("dtype") != "float32":
+        raise ConfigError("scientific runs require float32")
+
+
+def load_json_config(path: Path) -> dict[str, Any]:
+    value = json.loads(path.read_text())
+    if not isinstance(value, dict):
+        raise ConfigError("config root must be an object")
+    return value
+
+
+def compose_hydra_config(
+    project_root: Path,
+    *,
+    experiment: str,
+    seed: int,
+    data_dir: str,
+    overrides: tuple[str, ...] = (),
+) -> dict[str, Any]:
+    """Compose the exact public Hydra application config without running training."""
+    from hydra import compose, initialize_config_dir
+    from omegaconf import OmegaConf
+
+    config_dir = (project_root / "configs").resolve()
+    hydra_overrides = [
+        f"+experiment={experiment}",
+        f"training.seed={seed}",
+        f"data.dir={data_dir}",
+        "data.val_splits=[]",
+        "wandb.mode=disabled",
+        *overrides,
+    ]
+    with initialize_config_dir(config_dir=str(config_dir), version_base=None):
+        cfg = compose(config_name="config", overrides=hydra_overrides)
+    value = OmegaConf.to_container(cfg, resolve=True)
+    if not isinstance(value, dict):
+        raise ConfigError("Hydra expansion did not produce an object")
+    return value
+
+
+def cnn_registered_config(*, seed: int, data_dir: str) -> dict[str, Any]:
+    """Exact non-Hydra config consumed by the fixed MNIST CNN trainer."""
+    return {
+        "task": "mnist",
+        "model_type": "mnist_cnn_repro",
+        "dtype": "float32",
+        "wandb": {"mode": "disabled"},
+        "training": {
+            "seed": seed,
+            "lr": 0.001,
+            "weight_decay": 0.0000001,
+            "epochs": 20,
+            "batch_size": 128,
+            "warmup_steps": 200,
+            "grad_clip": 1.0,
+            "ema_decay": 0.999,
+            "betas": [0.9, 0.999],
+            "epsilon": 0.00000001,
+            "schedule": "linear_to_task_lr_then_constant",
+            "epoch_permutation": "fold_in(PRNGKey(seed),epoch)",
+            "final_batch": "pad_to_128_mask_normalize",
+            "selection": "fixed_final_epoch",
+        },
+        "data": {
+            "dir": data_dir,
+            "train_split": "train",
+            "val_splits": [],
+            "loader": "image",
+            "examples": 60000,
+            "normalization": False,
+            "augmentation": False,
+            "input_range": [0, 1],
+        },
+        "model": {
+            "layout": "NHWC/HWIO/NHWC",
+            "parameter_count": 65642,
+            "pre_pool_sizes": [28, 60],
+            "post_pool_sizes": [14, 30],
+        },
+        "task_cfg": {},
+    }
+
+
+def registered_config_for(
+    project_root: Path,
+    logical_id: str,
+    *,
+    data_root: str = "/data/train",
+) -> dict[str, Any]:
+    """Expand one of the exactly fifteen registered scientific identities."""
+    try:
+        seed = int(logical_id.rsplit("-", 1)[1])
+    except (IndexError, ValueError) as exc:
+        raise ConfigError(f"logical identity has no registered seed: {logical_id}") from exc
+    if seed not in (42, 123, 456):
+        raise ConfigError(f"unregistered seed in logical identity: {logical_id}")
+
+    if logical_id.startswith("C1-SUD-MPNN225-"):
+        return compose_hydra_config(
+            project_root,
+            experiment="sudoku_mpnn",
+            seed=seed,
+            data_dir=f"{data_root}/sudoku_easy",
+            overrides=("model.d_v=225", "training.lr=1.7e-3", "training.epochs=10"),
+        )
+    if logical_id.startswith("C2-MAZE-MPNN84-"):
+        return compose_hydra_config(
+            project_root,
+            experiment="maze_mpnn",
+            seed=seed,
+            data_dir=f"{data_root}/maze_std3_19px_10k",
+        )
+    if logical_id.startswith("C3-MNIST-CNN-"):
+        return cnn_registered_config(seed=seed, data_dir=f"{data_root}/mnist")
+    if logical_id.startswith("C4-SUD-IDENTITY-"):
+        return compose_hydra_config(
+            project_root,
+            experiment="sudoku_sheaf",
+            seed=seed,
+            data_dir=f"{data_root}/sudoku_easy",
+            overrides=("model.rm_init=identity", "+model.rm_constant=true"),
+        )
+    if logical_id.startswith("C4-MAZE-QUADRATIC-"):
+        return compose_hydra_config(
+            project_root,
+            experiment="maze_sheaf",
+            seed=seed,
+            data_dir=f"{data_root}/maze_std3_19px_10k",
+            overrides=("model.objective_mode=quadratic",),
+        )
+    raise ConfigError(f"unregistered training logical identity: {logical_id}")

src/repro_control/constants.py

@@ -0,0 +1,12 @@
+"""Frozen public constants baked into every reproduction entrypoint."""
+
+SCIENCE_SPEC_SHA256 = "c0ded12138cb7c15a15966294ed9bdb87d3a66d2373a7d90050578dbb973c6fd"
+DEADLINE_UTC = "2026-08-03T11:59:00Z"
+NOT_APPLICABLE = "NOT_APPLICABLE"
+REGISTERED_SEEDS = (42, 123, 456)
+NORMAL_CAP_MICRO_USD = 75_000_000
+GPU_RETRY_RESERVE_MICRO_USD = 10_000_000
+MINIMUM_BALANCE_MICRO_USD = 10_000_000
+MAX_RETURNED_IDS = 29
+MAX_GPU_RETURNED_IDS = 26
+MAX_CPU_RETURNED_IDS = 3

src/repro_control/data.py

@@ -0,0 +1,271 @@
+"""Registered corruption masks, long-path data, and smoke fixture checks."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .hashing import atomic_write_json, compact_json_bytes, sha256_bytes
+
+MNIST_AGENT_COUNT = 81
+MNIST_DROP_COUNT = 24
+MNIST_DROPOUT_MASTER_SEED = 21005300
+C5_SIZES = (19, 23, 27, 31, 35, 39)
+
+
+def derived_seed(*parts: object) -> int:
+    material = "\0".join(str(part) for part in parts).encode()
+    return int.from_bytes(hashlib.sha256(material).digest()[:8], "big")
+
+
+def mnist_keep_mask(
+    dataset_revision: str,
+    example_id: int,
+    condition: str = "drop30",
+    master_seed: int = MNIST_DROPOUT_MASTER_SEED,
+) -> tuple[bool, ...]:
+    if condition != "drop30":
+        raise ValueError("registered dropout mask condition is drop30")
+    rng = random.Random(derived_seed(dataset_revision, example_id, condition, master_seed))
+    removed = frozenset(rng.sample(range(MNIST_AGENT_COUNT), MNIST_DROP_COUNT))
+    mask = tuple(index not in removed for index in range(MNIST_AGENT_COUNT))
+    if sum(mask) != MNIST_AGENT_COUNT - MNIST_DROP_COUNT:
+        raise AssertionError("dropout mask cardinality failure")
+    return mask
+
+
+def build_mnist_mask_bank(
+    dataset_revision: str,
+    example_ids: Iterable[int],
+    *,
+    master_seed: int = MNIST_DROPOUT_MASTER_SEED,
+) -> dict:
+    ids = list(example_ids)
+    if len(ids) != len(set(ids)):
+        raise ValueError("example IDs must be unique")
+    entries = [
+        {
+            "example_id": example_id,
+            "keep_mask": mnist_keep_mask(
+                dataset_revision,
+                example_id,
+                master_seed=master_seed,
+            ),
+        }
+        for example_id in ids
+    ]
+    serializable = [
+        {"example_id": row["example_id"], "keep_mask": [int(value) for value in row["keep_mask"]]}
+        for row in entries
+    ]
+    return {
+        "format": 1,
+        "dataset_revision": dataset_revision,
+        "condition": "drop30",
+        "master_seed": master_seed,
+        "entries": serializable,
+        "bank_sha256": sha256_bytes(compact_json_bytes(serializable)),
+    }
+
+
+def write_mnist_mask_bank(path: Path, bank: dict) -> None:
+    for row in bank["entries"]:
+        if len(row["keep_mask"]) != MNIST_AGENT_COUNT or sum(row["keep_mask"]) != 57:
+            raise ValueError("invalid registered mask bank")
+    atomic_write_json(path, bank)
+
+
+def apply_patch_dropout(images, keep_masks):
+    """Apply 9x9-agent 3x3 patch dropout; NumPy is imported only when invoked."""
+    import numpy as np
+
+    array = np.asarray(images)
+    masks = np.asarray(keep_masks, dtype=bool)
+    if array.ndim != 4 or array.shape[1:] != (28, 28, 1):
+        raise ValueError("images must have shape [B,28,28,1]")
+    if masks.shape != (array.shape[0], 81) or not np.all(masks.sum(axis=1) == 57):
+        raise ValueError("keep masks must be [B,81] with exactly 57 kept agents")
+    padded = np.pad(array, ((0, 0), (0, 2), (0, 2), (0, 0)))
+    result = padded.copy()
+    for agent in range(81):
+        row, col = divmod(agent, 9)
+        result[:, row * 3 : row * 3 + 3, col * 3 : col * 3 + 3, :] *= masks[
+            :, agent, None, None, None
+        ]
+    return result[:, :28, :28, :]
+
+
+def kept_edge_mask(edge_indices, keep_masks):
+    """Remove all incident edges for dropped agents."""
+    import numpy as np
+
+    edges = np.asarray(edge_indices)
+    masks = np.asarray(keep_masks, dtype=bool)
+    if edges.ndim != 2 or edges.shape[1] != 2:
+        raise ValueError("edge_indices must have shape [E,2]")
+    return masks[:, edges[:, 0]] & masks[:, edges[:, 1]]
+
+
+@dataclass(frozen=True)
+class C5Unit:
+    size: int
+    generator_seed: int
+    min_path_length: int
+    examples: int = 1000
+    iterations: int = 100
+
+
+def c5_units() -> tuple[C5Unit, ...]:
+    return tuple(
+        C5Unit(
+            size=size,
+            generator_seed=21005000 + size,
+            min_path_length=3 * (size - 1) // 2,
+        )
+        for size in C5_SIZES
+    )
+
+
+def canonical_maze_identity(inputs, labels) -> str:
+    """Hash canonical wall/start/goal/path bytes for overlap rejection."""
+    import numpy as np
+
+    inputs_array = np.asarray(inputs, dtype=np.uint8).reshape(-1)
+    labels_array = np.asarray(labels, dtype=np.uint8).reshape(-1)
+    return sha256_bytes(inputs_array.tobytes() + b"\0" + labels_array.tobytes())
+
+
+def generate_c5_size(
+    size: int,
+    *,
+    training_identities: frozenset[str],
+    examples: int = 1000,
+):
+    """Generate unique registered long-path examples using the released DFS builder."""
+    import numpy as np
+
+    from sheaf_admm.data.build_maze import (
+        _backtrack_maze,
+        _paint_grid,
+        _pick_positions,
+        _shortest_path,
+    )
+
+    if size not in C5_SIZES:
+        raise ValueError(f"unregistered C5 size {size}")
+    rng = np.random.default_rng(21005000 + size)
+    minimum = 3 * (size - 1) // 2
+    seen = set(training_identities)
+    inputs, labels = [], []
+    attempts = 0
+    while len(inputs) < examples:
+        attempts += 1
+        if attempts > examples * 10000:
+            raise RuntimeError("C5 generator exhausted deterministic replacement guard")
+        base = _backtrack_maze(size, size, rng)
+        start, goal = _pick_positions(base, rng)
+        path = _shortest_path(base, start, goal)
+        if len(path) - 1 < minimum:
+            continue
+        input_grid = _paint_grid(base, start, goal, path, with_path=False)
+        label_grid = _paint_grid(base, start, goal, path, with_path=True)
+        identity = canonical_maze_identity(input_grid, label_grid)
+        if identity in seen:
+            continue
+        seen.add(identity)
+        inputs.append(input_grid.reshape(-1).astype(np.uint8))
+        labels.append(label_grid.reshape(-1).astype(np.uint8))
+    arrays = {"inputs": np.stack(inputs), "labels": np.stack(labels)}
+    manifest = {
+        "format": 1,
+        "unit": asdict(
+            C5Unit(
+                size=size,
+                generator_seed=21005000 + size,
+                min_path_length=minimum,
+                examples=examples,
+            )
+        ),
+        "attempts": attempts,
+        "identity_root_sha256": sha256_bytes(
+            compact_json_bytes(
+                [canonical_maze_identity(x, y) for x, y in zip(inputs, labels, strict=True)]
+            )
+        ),
+    }
+    return arrays, manifest
+
+
+def deterministic_lpt(costs: dict[int, float]) -> dict[str, list[int]]:
+    if set(costs) != set(C5_SIZES) or any(value <= 0 for value in costs.values()):
+        raise ValueError("costs must cover all registered sizes with positive values")
+    shards: dict[str, list[int]] = {"A": [], "B": []}
+    totals = {"A": 0.0, "B": 0.0}
+    for size in sorted(C5_SIZES, key=lambda n: (-costs[n], n)):
+        shard = "A" if totals["A"] <= totals["B"] else "B"
+        shards[shard].append(size)
+        totals[shard] += costs[size]
+    return shards
+
+
+def validate_smoke_fixture_registry(registry_path: Path) -> None:
+    registry = json.loads(registry_path.read_text())
+    if registry["purpose"].lower().find("verdict metrics are forbidden") < 0:
+        raise ValueError("smoke fixture registry must forbid verdict metrics")
+    final_seeds = {21005300, *(21005000 + n for n in C5_SIZES)}
+    smoke_seeds = {91005101, 91005301, *(91005200 + n for n in C5_SIZES)}
+    if final_seeds & smoke_seeds:
+        raise ValueError("smoke and final generator seeds overlap")
+    for row in registry["entries"]:
+        if not row["path"].startswith("smoke-fixtures/"):
+            raise ValueError("unregistered smoke fixture path")
+
+
+def write_puzzle_split(
+    root: Path,
+    split: str,
+    inputs,
+    labels,
+    *,
+    height: int,
+    width: int,
+) -> None:
+    """Write one-example-per-puzzle arrays in the released PuzzleDataset format."""
+    import numpy as np
+
+    from sheaf_admm.data.common import PuzzleDatasetMetadata, save_npy
+
+    input_array = np.asarray(inputs, dtype=np.uint8)
+    label_array = np.asarray(labels, dtype=np.uint8)
+    if (
+        input_array.ndim != 2
+        or input_array.shape != label_array.shape
+        or input_array.shape[1] != height * width
+    ):
+        raise ValueError("puzzle arrays do not match the registered board dimensions")
+    count = len(input_array)
+    split_root = root / split
+    offsets = np.arange(count + 1, dtype=np.int32)
+    save_npy(split_root / "all__inputs.npy", input_array)
+    save_npy(split_root / "all__labels.npy", label_array)
+    save_npy(split_root / "all__puzzle_indices.npy", offsets)
+    save_npy(split_root / "all__group_indices.npy", offsets)
+    save_npy(split_root / "all__puzzle_identifiers.npy", np.zeros(count, dtype=np.int32))
+    PuzzleDatasetMetadata(
+        pad_id=0,
+        ignore_label_id=0,
+        blank_identifier_id=0,
+        vocab_size=6,
+        seq_len=height * width,
+        num_puzzle_identifiers=1,
+        total_groups=count,
+        mean_puzzle_examples=1.0,
+        total_puzzles=count,
+        sets=["all"],
+        height=height,
+        width=width,
+    ).write(split_root / "dataset.json")

src/repro_control/evaluation.py

@@ -0,0 +1,398 @@
+"""EMA-only evaluation backends for fused logical suites and C5 shards."""
+
+from __future__ import annotations
+
+import json
+import pickle
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from .cnn import forward as cnn_forward
+from .data import apply_patch_dropout
+from .hashing import atomic_write_json, compact_json_bytes, sha256_bytes, sha256_file
+
+
+class EvaluationError(ValueError):
+    pass
+
+
+def _load_pickle(path: Path) -> dict[str, Any]:
+    with path.open("rb") as handle:
+        value = pickle.load(handle)
+        if handle.read(1):
+            raise EvaluationError("checkpoint has trailing bytes")
+    if not isinstance(value, dict) or value.get("ema_params") is None:
+        raise EvaluationError("evaluation requires a checkpoint with EMA parameters")
+    return value
+
+
+def _puzzle_batches(dataset_dir: Path, split: str, batch_size: int):
+    import numpy as np
+
+    from sheaf_admm.data import PuzzleDataset
+
+    dataset = PuzzleDataset(dataset_dir, split)
+    for _set, batch in dataset.iter_test_batches(batch_size):
+        out = {"inputs": np.asarray(batch["inputs"]), "labels": np.asarray(batch["labels"])}
+        for name in ("height", "width"):
+            if name in batch:
+                out[name] = batch[name]
+        yield out
+
+
+def _fixed_puzzle_batches(
+    dataset_dir: Path,
+    split: str,
+    batch_size: int,
+) -> Iterator[tuple[dict[str, Any], int]]:
+    import numpy as np
+
+    from sheaf_admm.data import PuzzleDataset
+
+    dataset = PuzzleDataset(dataset_dir, split)
+    if set(dataset.sets) != {"all"}:
+        raise EvaluationError("registered C5 split requires exactly the all set")
+    puzzle_set = dataset.sets["all"]
+    for start in range(0, puzzle_set.num_examples, batch_size):
+        stop = min(start + batch_size, puzzle_set.num_examples)
+        real = stop - start
+        inputs = np.asarray(puzzle_set.inputs[start:stop])
+        labels = np.asarray(puzzle_set.labels[start:stop])
+        if real < batch_size:
+            inputs = np.pad(inputs, ((0, batch_size - real), (0, 0)))
+            labels = np.pad(labels, ((0, batch_size - real), (0, 0)))
+        yield (
+            {
+                "inputs": inputs,
+                "labels": labels,
+                "height": dataset.metadata.height,
+                "width": dataset.metadata.width,
+            },
+            real,
+        )
+
+
+def _load_mask_bank(path: Path, expected_sha256: str) -> dict[int, list[int]]:
+    value = json.loads(path.read_text())
+    if value.get("bank_sha256") != expected_sha256:
+        raise EvaluationError("MNIST mask bank hash differs from the unit manifest")
+    entries = value.get("entries")
+    if not isinstance(entries, list):
+        raise EvaluationError("invalid MNIST mask bank")
+    if sha256_bytes(compact_json_bytes(entries)) != expected_sha256:
+        raise EvaluationError("MNIST mask bank content hash mismatch")
+    bank = {int(row["example_id"]): row["keep_mask"] for row in entries}
+    if len(bank) != len(entries):
+        raise EvaluationError("duplicate MNIST mask example ID")
+    return bank
+
+
+def _image_batches(
+    dataset_dir: Path,
+    split: str,
+    batch_size: int,
+    *,
+    condition: str,
+    mask_bank_path: str = "",
+    mask_bank_sha256: str = "",
+) -> Iterator[dict[str, Any]]:
+    import numpy as np
+
+    from sheaf_admm.data import ImageDataset
+
+    dataset = ImageDataset(dataset_dir, split)
+    mask_bank = (
+        _load_mask_bank(Path(mask_bank_path), mask_bank_sha256)
+        if condition == "drop30"
+        else None
+    )
+    for start in range(0, dataset.num_examples, batch_size):
+        stop = min(start + batch_size, dataset.num_examples)
+        images = np.asarray(dataset.images[start:stop], dtype=np.float32)
+        labels = np.asarray(dataset.labels[start:stop])
+        if images.shape[1:] != (28, 28, 1):
+            raise EvaluationError("registered MNIST source split must be clean 28x28")
+        batch: dict[str, Any] = {"images": images, "labels": labels}
+        if condition == "pad16":
+            batch["images"] = np.pad(images, ((0, 0), (16, 16), (16, 16), (0, 0)))
+        elif condition == "drop30":
+            assert mask_bank is not None
+            masks = np.asarray([mask_bank[index] for index in range(start, stop)], dtype=bool)
+            batch["images"] = apply_patch_dropout(images, masks)
+            batch["keep_masks"] = masks
+        elif condition != "clean":
+            raise EvaluationError(f"unsupported MNIST condition {condition!r}")
+        yield batch
+
+
+def _upstream_backend(unit: dict[str, Any]):
+    import jax
+
+    from sheaf_admm.models import model_config_from_dict
+    from sheaf_admm.training import build_model, make_task
+    from sheaf_admm.training.loop import _forward
+
+    checkpoint_path = Path(unit["checkpoint_path"])
+    config_path = Path(unit["config_path"])
+    checkpoint = _load_pickle(checkpoint_path)
+    config = json.loads(config_path.read_text())
+    model_config = model_config_from_dict(config["model"])
+    model = build_model(model_config, config["model_type"])
+    task = make_task(config["task"], **config["task_cfg"])
+    params = checkpoint["ema_params"]
+    graph_readout = model_config.mpnn_graph_readout
+    model_type = config["model_type"]
+    k_eval = (
+        config["training"]["K_eval"]
+        if model_type == "sheaf"
+        else config["training"]["mpnn_eval_rounds"]
+    )
+
+    @jax.jit
+    def forward(current_params, fwd):
+        return _forward(
+            model.apply,
+            current_params,
+            fwd,
+            n_iter=k_eval,
+            loss_window=1,
+            model_type=model_type,
+            training=False,
+            rng=None,
+        )
+
+    return (
+        checkpoint_path,
+        config_path,
+        params,
+        task,
+        graph_readout,
+        model_type,
+        forward,
+    )
+
+
+def evaluate_upstream_unit(unit: dict[str, Any]) -> dict[str, Any]:
+    import jax
+
+    (
+        checkpoint_path,
+        config_path,
+        params,
+        task,
+        graph_readout,
+        model_type,
+        forward,
+    ) = _upstream_backend(unit)
+
+    dataset_dir = Path(unit["dataset_dir"])
+    config = json.loads(config_path.read_text())
+    if config["data"]["loader"] == "image":
+        batches = _image_batches(
+            dataset_dir,
+            unit["split"],
+            128,
+            condition=unit["condition"],
+            mask_bank_path=unit.get("mask_bank_path", ""),
+            mask_bank_sha256=unit.get("mask_bank_sha256", ""),
+        )
+    else:
+        batches = _puzzle_batches(dataset_dir, unit["split"], 128)
+    totals: dict[str, float] = {}
+    count = 0
+    for batch in batches:
+        fwd, targets, aux = task.prepare(batch)
+        logits = forward(params, fwd)
+        jax.block_until_ready(logits)
+        final = logits if model_type == "mpnn" else logits[-1]
+        metrics = (
+            task.evaluate_graph(final, targets, aux)
+            if model_type == "mpnn" and graph_readout == "graph"
+            else task.evaluate(final, targets, aux)
+        )
+        weight = len(batch["labels"])
+        for name, value in metrics.items():
+            totals[name] = totals.get(name, 0.0) + float(value) * weight
+        count += weight
+    if count == 0:
+        raise EvaluationError("evaluation unit contained no examples")
+    return {
+        "neutral_id": unit["neutral_id"],
+        "seed": unit["seed"],
+        "condition": unit["condition"],
+        "examples": count,
+        "metrics": {name: value / count for name, value in sorted(totals.items())},
+        "checkpoint_sha256": sha256_file(checkpoint_path),
+        "config_sha256": sha256_file(config_path),
+        "ema": True,
+    }
+
+
+def evaluate_cnn_unit(unit: dict[str, Any]) -> dict[str, Any]:
+    import jax
+    import numpy as np
+
+    checkpoint_path = Path(unit["checkpoint_path"])
+    config_path = Path(unit["config_path"])
+    checkpoint = _load_pickle(checkpoint_path)
+    params = checkpoint["ema_params"]
+    run = jax.jit(cnn_forward)
+    correct = count = 0
+    for batch in _image_batches(
+        Path(unit["dataset_dir"]),
+        unit["split"],
+        128,
+        condition=unit["condition"],
+        mask_bank_path=unit.get("mask_bank_path", ""),
+        mask_bank_sha256=unit.get("mask_bank_sha256", ""),
+    ):
+        logits = run(params, batch["images"])
+        predictions = np.asarray(jax.device_get(logits.argmax(axis=-1)))
+        labels = np.asarray(batch["labels"])
+        correct += int(np.sum(predictions == labels))
+        count += len(labels)
+    if count == 0:
+        raise EvaluationError("CNN evaluation unit contained no examples")
+    return {
+        "neutral_id": unit["neutral_id"],
+        "seed": unit["seed"],
+        "condition": unit["condition"],
+        "examples": count,
+        "metrics": {"acc": correct / count},
+        "checkpoint_sha256": sha256_file(checkpoint_path),
+        "config_sha256": sha256_file(config_path),
+        "ema": True,
+    }
+
+
+def evaluate_c5_size(units: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    import jax
+    import jax.numpy as jnp
+
+    from sheaf_admm.data import views
+    from sheaf_admm.models import model_config_from_dict
+    from sheaf_admm.training import build_model, make_task
+    from sheaf_admm.training.loop import _forward
+
+    if len(units) != 3 or {unit["seed"] for unit in units} != {42, 123, 456}:
+        raise EvaluationError("each C5 size requires exactly the three registered seeds")
+    first = units[0]
+    config = json.loads(Path(first["config_path"]).read_text())
+    model_config = model_config_from_dict(config["model"])
+    model = build_model(model_config, "sheaf")
+    task = make_task("maze", **config["task_cfg"])
+    batch_size = int(first["batch_size"])
+    if any(
+        int(unit["batch_size"]) != batch_size
+        or unit["dataset_dir"] != first["dataset_dir"]
+        or unit["split"] != first["split"]
+        for unit in units
+    ):
+        raise EvaluationError("C5 size units disagree on data or frozen batch size")
+
+    @jax.jit
+    def forward(params, fwd):
+        logits = _forward(
+            model.apply,
+            params,
+            fwd,
+            n_iter=100,
+            loss_window=1,
+            model_type="sheaf",
+            training=False,
+            rng=None,
+        )
+        return logits[-1]
+
+    batches = list(
+        _fixed_puzzle_batches(
+            Path(first["dataset_dir"]),
+            first["split"],
+            batch_size,
+        )
+    )
+    if sum(real for _, real in batches) != 1000:
+        raise EvaluationError("registered C5 unit must contain exactly 1000 real examples")
+    results = []
+    for unit in sorted(units, key=lambda row: row["seed"]):
+        checkpoint_path = Path(unit["checkpoint_path"])
+        config_path = Path(unit["config_path"])
+        params = _load_pickle(checkpoint_path)["ema_params"]
+        solved_count = cell_correct = cell_count = example_count = 0
+        for batch, real in batches:
+            fwd, targets, aux = task.prepare(batch)
+            logits = forward(params, fwd)
+            jax.block_until_ready(logits)
+            reconstructed = jnp.asarray(
+                views.reassemble_logits(
+                    logits,
+                    aux["centers"],
+                    aux["image_hw"],
+                    model_config.num_classes,
+                    mode="mean",
+                )
+            )
+            predictions = jnp.argmax(reconstructed, axis=-1)[:real]
+            labels = targets["labels_img"][:real]
+            solved = jnp.all(
+                (predictions == 5) == (labels == 5),
+                axis=(1, 2),
+            )
+            solved_count += int(jnp.sum(solved))
+            cell_correct += int(jnp.sum(predictions == labels))
+            cell_count += int(labels.size)
+            example_count += real
+        results.append(
+            {
+                "neutral_id": unit["neutral_id"],
+                "seed": unit["seed"],
+                "condition": "c5",
+                "size": unit["size"],
+                "examples": example_count,
+                "metrics": {
+                    "solved": solved_count / example_count,
+                    "cell_acc": cell_correct / cell_count,
+                },
+                "checkpoint_sha256": sha256_file(checkpoint_path),
+                "config_sha256": sha256_file(config_path),
+                "ema": True,
+                "batch_size": batch_size,
+                "padded_tail_excluded": True,
+            }
+        )
+    return results
+
+
+def evaluate_units(unit_manifest_path: Path, output_path: Path) -> None:
+    manifest = json.loads(unit_manifest_path.read_text())
+    if set(manifest) != {"format", "units"} or manifest["format"] != 1:
+        raise EvaluationError("invalid evaluator unit manifest")
+    identities = [unit["neutral_id"] for unit in manifest["units"]]
+    if len(identities) != len(set(identities)):
+        raise EvaluationError("duplicate evaluator unit identity")
+    results = []
+    c5_by_size: dict[int, list[dict[str, Any]]] = {}
+    for unit in manifest["units"]:
+        if unit["condition"] not in {"clean", "pad16", "drop30", "c5"}:
+            raise EvaluationError("unregistered evaluation condition")
+        if unit["condition"] == "c5":
+            c5_by_size.setdefault(int(unit["size"]), []).append(unit)
+        else:
+            result = (
+                evaluate_cnn_unit(unit)
+                if unit["model_kind"] == "mnist_cnn_repro"
+                else evaluate_upstream_unit(unit)
+            )
+            results.append(result)
+    for size in sorted(c5_by_size):
+        results.extend(evaluate_c5_size(c5_by_size[size]))
+    atomic_write_json(
+        output_path,
+        {
+            "format": 1,
+            "unit_manifest_sha256": sha256_file(unit_manifest_path),
+            "units": results,
+            "verdicts": {},
+        },
+    )

src/repro_control/hashing.py

@@ -0,0 +1,68 @@
+"""Canonical hashing and atomic local writes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Iterable
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def compact_json_bytes(value: Any) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+
+
+def canonical_root(entries: Iterable[dict[str, Any]]) -> str:
+    rows = sorted(entries, key=lambda row: row["path"])
+    return sha256_bytes(compact_json_bytes(rows))
+
+
+def file_entry(path: Path, *, relative_to: Path) -> dict[str, Any]:
+    return {
+        "path": path.relative_to(relative_to).as_posix(),
+        "bytes": path.stat().st_size,
+        "sha256": sha256_file(path),
+    }
+
+
+def tree_entries(root: Path, *, excluded_names: frozenset[str] = frozenset()) -> list[dict]:
+    return [
+        file_entry(path, relative_to=root)
+        for path in sorted(root.rglob("*"))
+        if path.is_file() and not any(part in excluded_names for part in path.relative_to(root).parts)
+    ]
+
+
+def atomic_write_bytes(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except BaseException:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def atomic_write_json(path: Path, value: Any) -> None:
+    atomic_write_bytes(path, json.dumps(value, indent=2, sort_keys=True).encode() + b"\n")

src/repro_control/heartbeat.py

@@ -0,0 +1,30 @@
+"""Line-buffered readiness and heartbeat markers for supervised HF Jobs."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+
+
+def marker(name: str, detail: str = "") -> None:
+    suffix = f" {detail}" if detail else ""
+    print(f"{name} {datetime.now(UTC).isoformat()}{suffix}", flush=True)
+
+
+@contextmanager
+def heartbeat(stage: str, *, interval_seconds: int = 60) -> Iterator[None]:
+    stop = threading.Event()
+
+    def emit() -> None:
+        while not stop.wait(interval_seconds):
+            marker("HEARTBEAT", stage)
+
+    worker = threading.Thread(target=emit, name=f"heartbeat-{stage}", daemon=True)
+    worker.start()
+    try:
+        yield
+    finally:
+        stop.set()
+        worker.join(timeout=1)

src/repro_control/hf_provider.py

@@ -0,0 +1,179 @@
+"""Hugging Face Jobs adapter for the durable direct-launch state machine."""
+
+from __future__ import annotations
+
+import math
+import re
+from datetime import UTC, datetime
+from typing import Any
+
+from huggingface_hub import HfApi, Volume
+from huggingface_hub.errors import HfHubHTTPError
+from requests import RequestException
+
+from .launcher import AmbiguousSubmission, LaunchError
+
+MARKER_TIME = re.compile(
+    r"\b(?P<marker>CPU_READY|GPU_READY|HEARTBEAT|DONE)\s+"
+    r"(?P<time>\d{4}-\d{2}-\d{2}T[^\s]+)"
+)
+
+
+def _iso(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, datetime):
+        return value.astimezone(UTC).isoformat()
+    return str(value)
+
+
+class HFJobsProvider:
+    def __init__(self, *, namespace: str = "Mindcraft", api: HfApi | None = None):
+        self.namespace = namespace
+        self.api = api or HfApi()
+
+    @staticmethod
+    def _volumes(rows: list[dict[str, Any]]) -> list[Volume]:
+        volumes = []
+        for row in rows:
+            volumes.append(
+                Volume(
+                    type="bucket",
+                    source=row["volume_source"],
+                    path=row["volume_path"] or None,
+                    mount_path=row["mount_path"],
+                    read_only=row["read_only"],
+                )
+            )
+        return volumes
+
+    @staticmethod
+    def _assert_no_credentials(request: dict[str, Any]) -> None:
+        if request.get("secrets"):
+            raise LaunchError("Jobs may not receive provider secrets under TRACE_MODE=none")
+        env = request.get("env") or {}
+        forbidden = ("TOKEN", "SECRET", "PASSWORD", "AUTHORIZATION", "API_KEY")
+        matches = [name for name in env if any(term in name.upper() for term in forbidden)]
+        if matches:
+            raise LaunchError(f"credential-like Job environment names are forbidden: {matches}")
+
+    def submit(self, request: dict[str, Any]) -> dict[str, Any]:
+        self._assert_no_credentials(request)
+        labels = {
+            "repro-attempt": request["label"],
+            "logical-id": request["logical_id"],
+            "job-class": request["job_class"],
+        }
+        try:
+            info = self.api.run_job(
+                image=request["image"],
+                command=request["command"],
+                env=request.get("env") or {},
+                secrets=None,
+                flavor=request["flavor"],
+                timeout=request["timeout_seconds"],
+                labels=labels,
+                volumes=self._volumes(request.get("mounts", [])),
+                namespace=self.namespace,
+            )
+        except HfHubHTTPError as exc:
+            status = getattr(exc.response, "status_code", None)
+            if status is not None and 400 <= status < 500 and status not in {408, 429}:
+                raise LaunchError(
+                    f"provider rejected Job before acceptance: HTTP {status}"
+                ) from exc
+            raise AmbiguousSubmission("provider response is ambiguous; reconcile by label") from exc
+        except (RequestException, TimeoutError, ConnectionError) as exc:
+            raise AmbiguousSubmission("provider response is ambiguous; reconcile by label") from exc
+        return self._normalize_identity(info)
+
+    def find_by_label(self, label: str) -> list[dict[str, Any]]:
+        return [
+            self._normalize_identity(info)
+            for info in self.api.list_jobs(namespace=self.namespace)
+            if (info.labels or {}).get("repro-attempt") == label
+        ]
+
+    def get(self, job_id: str) -> dict[str, Any]:
+        info = self.api.inspect_job(job_id=job_id, namespace=self.namespace)
+        logs = self._logs(job_id)
+        stage = getattr(info.status.stage, "value", str(info.status.stage))
+        states = {
+            "SCHEDULING": "STARTING",
+            "RUNNING": "RUNNING",
+            "COMPLETED": "COMPLETED",
+            "ERROR": "FAILED",
+            "CANCELED": "CANCELED",
+            "DELETED": "FAILED",
+        }
+        if stage not in states:
+            raise LaunchError(f"unrecognized Hugging Face Job stage {stage!r}")
+        ready_times = []
+        heartbeat_times = []
+        done_times = []
+        for line in logs:
+            for match in MARKER_TIME.finditer(line):
+                try:
+                    parsed = datetime.fromisoformat(match.group("time").replace("Z", "+00:00"))
+                except ValueError:
+                    continue
+                marker = match.group("marker")
+                if marker in {"CPU_READY", "GPU_READY"}:
+                    ready_times.append(parsed)
+                elif marker == "HEARTBEAT":
+                    heartbeat_times.append(parsed)
+                elif marker == "DONE":
+                    done_times.append(parsed)
+        duration = getattr(info, "durations", None)
+        running_seconds = getattr(duration, "running_secs", None)
+        normalized = {
+            "state": states[stage],
+            "provider_stage": stage,
+            "provider_message": info.status.message,
+            "starting_at": _iso(info.started_at),
+            "started_at": _iso(info.started_at),
+            "finished_at": _iso(info.finished_at),
+            "ready_marker": bool(ready_times),
+            "ready_at": _iso(min(ready_times)) if ready_times else "",
+            "heartbeat": bool(heartbeat_times),
+            "heartbeat_at": _iso(max(heartbeat_times)) if heartbeat_times else "",
+            "done_marker": bool(done_times),
+            "done_at": _iso(max(done_times)) if done_times else "",
+            "billable_duration_seconds": (
+                max(0, math.ceil(float(running_seconds)))
+                if running_seconds is not None
+                and states[stage] in {"COMPLETED", "FAILED", "CANCELED"}
+                else None
+            ),
+            "logs_tail": logs[-200:],
+        }
+        return normalized
+
+    def cancel(self, job_id: str) -> None:
+        self.api.cancel_job(job_id=job_id, namespace=self.namespace)
+
+    def _logs(self, job_id: str) -> list[str]:
+        try:
+            return list(
+                self.api.fetch_job_logs(
+                    job_id=job_id,
+                    namespace=self.namespace,
+                    follow=False,
+                    tail=1000,
+                )
+            )
+        except HfHubHTTPError as exc:
+            status = getattr(exc.response, "status_code", None)
+            if status in {404, 409}:
+                return []
+            raise
+
+    @staticmethod
+    def _normalize_identity(info: Any) -> dict[str, Any]:
+        job_id = str(info.id)
+        url = str(info.url or f"https://huggingface.co/jobs/{job_id}")
+        return {
+            "job_id": job_id,
+            "job_url": url,
+            "state": "SUBMITTED",
+        }

src/repro_control/interventions.py

@@ -0,0 +1,93 @@
+"""Bit-identity checks for the registered literal Sudoku intervention."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from typing import Any
+
+import jax
+import numpy as np
+
+
+class InterventionError(ValueError):
+    pass
+
+
+def without_restriction_map(tree: Any) -> Any:
+    """Return a structurally equivalent tree with every named ``rm`` subtree removed."""
+    if isinstance(tree, Mapping):
+        return {
+            key: without_restriction_map(value)
+            for key, value in tree.items()
+            if key not in {"rm", "restriction_maps", "R_indices"}
+        }
+    if isinstance(tree, list):
+        return [without_restriction_map(value) for value in tree]
+    if isinstance(tree, tuple):
+        return tuple(without_restriction_map(value) for value in tree)
+    return tree
+
+
+def stable_tree_digest(tree: Any) -> str:
+    """Digest semantic containers and array bytes without device/container metadata."""
+    digest = hashlib.sha256()
+
+    def visit(value: Any) -> None:
+        if isinstance(value, Mapping):
+            digest.update(b"M{")
+            for key in sorted(value, key=lambda item: str(item)):
+                encoded = str(key).encode()
+                digest.update(len(encoded).to_bytes(8, "big"))
+                digest.update(encoded)
+                visit(value[key])
+            digest.update(b"}")
+            return
+        if isinstance(value, (list, tuple)):
+            digest.update(b"S[")
+            digest.update(len(value).to_bytes(8, "big"))
+            for item in value:
+                visit(item)
+            digest.update(b"]")
+            return
+        array = np.asarray(jax.device_get(value))
+        digest.update(b"A")
+        digest.update(array.dtype.str.encode())
+        digest.update(repr(array.shape).encode())
+        digest.update(array.tobytes(order="C"))
+
+    visit(tree)
+    return digest.hexdigest()
+
+
+def contains_restriction_map(tree: Any) -> bool:
+    if isinstance(tree, Mapping):
+        return any(
+            key in {"rm", "restriction_maps", "R_indices"} or contains_restriction_map(value)
+            for key, value in tree.items()
+        )
+    if isinstance(tree, (list, tuple)):
+        return any(contains_restriction_map(value) for value in tree)
+    return False
+
+
+def assert_common_bit_identical(
+    learned_params: Any,
+    identity_params: Any,
+    learned_optimizer: Any,
+    identity_optimizer: Any,
+    learned_counters: Any,
+    identity_counters: Any,
+) -> None:
+    if contains_restriction_map(identity_params):
+        raise InterventionError("identity parameter tree contains a restriction-map leaf")
+    if contains_restriction_map(identity_optimizer):
+        raise InterventionError("identity optimizer tree contains a restriction-map leaf")
+    pairs = (
+        (without_restriction_map(learned_params), identity_params, "parameter"),
+        (without_restriction_map(learned_optimizer), identity_optimizer, "optimizer"),
+        (learned_counters, identity_counters, "counter"),
+    )
+    for learned, identity, name in pairs:
+        if stable_tree_digest(learned) != stable_tree_digest(identity):
+            raise InterventionError(f"common {name} leaves are not bit-identical")

src/repro_control/launcher.py

@@ -0,0 +1,432 @@
+"""Durable direct-launch state machine with submission disabled by default."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal, ROUND_CEILING
+from pathlib import Path
+from typing import Any, Protocol
+
+from .constants import (
+    DEADLINE_UTC,
+    GPU_RETRY_RESERVE_MICRO_USD,
+    MAX_CPU_RETURNED_IDS,
+    MAX_GPU_RETURNED_IDS,
+    MAX_RETURNED_IDS,
+    MINIMUM_BALANCE_MICRO_USD,
+    NORMAL_CAP_MICRO_USD,
+)
+from .hashing import atomic_write_json
+from .manifests import REQUIRED_FIELDS, validate_manifest
+
+ACTIVE = frozenset({"PENDING_SUBMISSION", "SUBMITTED", "STARTING", "RUNNING", "CANCELING"})
+TERMINAL = frozenset({"COMPLETED", "FAILED", "CANCELED"})
+
+
+class LaunchError(RuntimeError):
+    pass
+
+
+class AmbiguousSubmission(LaunchError):
+    pass
+
+
+class Provider(Protocol):
+    def submit(self, request: dict[str, Any]) -> dict[str, Any]: ...
+
+    def find_by_label(self, label: str) -> list[dict[str, Any]]: ...
+
+    def get(self, job_id: str) -> dict[str, Any]: ...
+
+    def cancel(self, job_id: str) -> None: ...
+
+
+def parse_utc(value: str) -> datetime:
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        raise ValueError("timestamp must include a timezone")
+    return parsed.astimezone(timezone.utc)
+
+
+def quantum_cost(rate_micro_usd_per_hour: int, seconds: int) -> int:
+    if rate_micro_usd_per_hour < 0 or seconds < 0:
+        raise ValueError("cost inputs must be nonnegative")
+    minutes = (seconds + 59) // 60
+    return (rate_micro_usd_per_hour * minutes + 59) // 60
+
+
+def rate_to_micro_usd(rate: str) -> int:
+    value = (Decimal(rate) * Decimal(1_000_000)).to_integral_value(rounding=ROUND_CEILING)
+    return int(value)
+
+
+def deterministic_attempt_id(
+    logical_id: str, ordinal: int, science_spec_sha256: str, science_freeze_sha256: str
+) -> str:
+    material = f"{logical_id}\0{ordinal}\0{science_spec_sha256}\0{science_freeze_sha256}"
+    return f"a{ordinal:02d}-{hashlib.sha256(material.encode()).hexdigest()[:20]}"
+
+
+def deterministic_label(logical_id: str, attempt_id: str) -> str:
+    return f"repro-{logical_id.lower()}-{attempt_id}"
+
+
+@dataclass(frozen=True)
+class BudgetSnapshot:
+    verified_balance_micro_usd: int
+    unsettled_estimate_micro_usd: int
+    incurred_micro_usd: int
+    active_remaining_micro_usd: int
+    mandatory_unsubmitted_micro_usd: int
+    non_job_cost_micro_usd: int = 0
+    gpu_retry_reserve_micro_usd: int = GPU_RETRY_RESERVE_MICRO_USD
+    cpu_retry_reserve_micro_usd: int = 0
+
+    def prospective_commitment(self, proposed_micro_usd: int) -> int:
+        return (
+            self.incurred_micro_usd
+            + self.active_remaining_micro_usd
+            + proposed_micro_usd
+            + self.mandatory_unsubmitted_micro_usd
+            + self.non_job_cost_micro_usd
+            + self.gpu_retry_reserve_micro_usd
+            + self.cpu_retry_reserve_micro_usd
+        )
+
+    def assert_feasible(self, proposed_micro_usd: int) -> None:
+        commitment = self.prospective_commitment(proposed_micro_usd)
+        if commitment > NORMAL_CAP_MICRO_USD:
+            raise LaunchError(f"normal spend cap exceeded: {commitment}>{NORMAL_CAP_MICRO_USD}")
+        available_after = (
+            self.verified_balance_micro_usd
+            - self.unsettled_estimate_micro_usd
+            - (commitment - self.incurred_micro_usd)
+        )
+        if available_after < MINIMUM_BALANCE_MICRO_USD:
+            raise LaunchError(
+                f"minimum balance gate failed: {available_after}<{MINIMUM_BALANCE_MICRO_USD}"
+            )
+
+
+@dataclass
+class LauncherState:
+    format: int = 1
+    attempts: list[dict[str, Any]] = field(default_factory=list)
+    reservations: list[dict[str, Any]] = field(default_factory=list)
+
+    @classmethod
+    def load(cls, path: Path) -> "LauncherState":
+        if not path.exists():
+            return cls()
+        value = json.loads(path.read_text())
+        if set(value) != {"format", "attempts", "reservations"} or value["format"] != 1:
+            raise LaunchError("invalid launcher state")
+        return cls(**value)
+
+    def save(self, path: Path) -> None:
+        atomic_write_json(
+            path,
+            {"format": self.format, "attempts": self.attempts, "reservations": self.reservations},
+        )
+
+    def returned_counts(self) -> tuple[int, int, int]:
+        returned = [row for row in self.attempts if row.get("job_id")]
+        gpu = sum(row.get("resource_class") == "GPU" for row in returned)
+        cpu = sum(row.get("resource_class") == "CPU" for row in returned)
+        return len(returned), gpu, cpu
+
+    def assert_identity_available(self, logical_id: str) -> None:
+        duplicate = [
+            row
+            for row in self.attempts
+            if row["logical_id"] == logical_id
+            and (row["state"] in ACTIVE or row["state"] == "COMPLETED")
+        ]
+        if duplicate:
+            raise LaunchError(f"duplicate active/complete logical identity {logical_id}")
+
+    def assert_id_capacity(self, resource_class: str) -> None:
+        total, gpu, cpu = self.returned_counts()
+        provisional = sum(row.get("provisional_id_slot", False) for row in self.attempts)
+        if total + provisional + 1 > MAX_RETURNED_IDS:
+            raise LaunchError("absolute returned-ID gate failed")
+        if resource_class == "GPU" and gpu + provisional + 1 > MAX_GPU_RETURNED_IDS:
+            raise LaunchError("GPU returned-ID gate failed")
+        if resource_class == "CPU" and cpu + provisional + 1 > MAX_CPU_RETURNED_IDS:
+            raise LaunchError("CPU returned-ID gate failed")
+
+
+class DirectLauncher:
+    """Provider-neutral launcher.
+
+    A real provider must be injected and ``enable_submit`` must be explicit.
+    The CLI never enables this in the local implementation turn.
+    """
+
+    def __init__(
+        self,
+        state_path: Path,
+        *,
+        provider: Provider | None = None,
+        enable_submit: bool = False,
+        deadline_utc: str = DEADLINE_UTC,
+        enforce_admission_sequence: bool = True,
+    ):
+        self.state_path = state_path
+        self.provider = provider
+        self.enable_submit = enable_submit
+        self.deadline = parse_utc(deadline_utc)
+        self.enforce_admission_sequence = enforce_admission_sequence
+
+    def assert_deadline(
+        self, now: datetime, guarded_critical_path_seconds: int, *, safety_hours: int = 12
+    ) -> None:
+        if now.tzinfo is None:
+            raise LaunchError("now must be timezone-aware")
+        finish = now.astimezone(timezone.utc) + timedelta(seconds=guarded_critical_path_seconds)
+        if finish > self.deadline - timedelta(hours=safety_hours):
+            raise LaunchError("guarded critical path misses the deadline safety margin")
+
+    def prepare(
+        self,
+        request: dict[str, Any],
+        *,
+        budget: BudgetSnapshot,
+        now: datetime,
+        guarded_critical_path_seconds: int,
+    ) -> dict[str, Any]:
+        state = LauncherState.load(self.state_path)
+        logical_id = request["logical_id"]
+        resource_class = request["resource_class"]
+        if self.enforce_admission_sequence:
+            canaries = [row for row in state.attempts if row["logical_id"] == "HF-CPU-CANARY"]
+            if not canaries and logical_id != "HF-CPU-CANARY":
+                raise LaunchError("the first attempted external mutation must be HF-CPU-CANARY")
+            if logical_id != "HF-CPU-CANARY" and not any(
+                row["state"] == "COMPLETED" for row in canaries
+            ):
+                raise LaunchError("CPU canary has not completed")
+        if request.get("is_retry"):
+            reason = request.get("retry_reason_class")
+            if reason != "INFRASTRUCTURE":
+                raise LaunchError("only classified infrastructure failures authorize retry")
+            prior_retries = sum(
+                row["resource_class"] == resource_class and row["request"].get("is_retry")
+                for row in state.attempts
+            )
+            ceiling = 3 if resource_class == "GPU" else 1
+            if prior_retries >= ceiling:
+                raise LaunchError(f"{resource_class} retry ceiling exhausted")
+        state.assert_identity_available(logical_id)
+        state.assert_id_capacity(resource_class)
+        self.assert_deadline(now, guarded_critical_path_seconds)
+        proposed = quantum_cost(
+            request["frozen_hourly_rate_micro_usd"], request["timeout_seconds"]
+        )
+        budget.assert_feasible(proposed)
+        ordinal = 1 + sum(row["logical_id"] == logical_id for row in state.attempts)
+        attempt_id = deterministic_attempt_id(
+            logical_id,
+            ordinal,
+            request["science_spec_sha256"],
+            request["science_freeze_sha256"],
+        )
+        if request.get("attempt_id") != attempt_id:
+            raise LaunchError(
+                f"request attempt_id mismatch: {request.get('attempt_id')!r}!={attempt_id!r}"
+            )
+        try:
+            manifest = {name: request[name] for name in REQUIRED_FIELDS}
+        except KeyError as exc:
+            raise LaunchError(f"request is missing manifest field {exc.args[0]!r}") from exc
+        try:
+            validate_manifest(
+                manifest,
+                freeze_sha256=(
+                    request["science_freeze_sha256"]
+                    if request["job_class"].startswith("SCIENTIFIC")
+                    else ""
+                ),
+            )
+        except ValueError as exc:
+            raise LaunchError(f"invalid Job manifest: {exc}") from exc
+        if request.get("hardware") != request.get("flavor"):
+            raise LaunchError("manifest hardware must equal provider flavor")
+        image = request.get("image")
+        if not isinstance(image, str) or not image.endswith(f"@{request['image_digest']}"):
+            raise LaunchError("provider image must end in the manifest image digest")
+        expected_resource_class = "CPU" if request["job_class"].startswith("CPU_") else "GPU"
+        if resource_class != expected_resource_class:
+            raise LaunchError(
+                f"{request['job_class']} requires resource_class={expected_resource_class}"
+            )
+        row = {
+            "logical_id": logical_id,
+            "attempt_id": attempt_id,
+            "label": deterministic_label(logical_id, attempt_id),
+            "resource_class": resource_class,
+            "state": "PENDING_SUBMISSION",
+            "job_id": "",
+            "job_url": "",
+            "provisional_id_slot": True,
+            "request": request,
+            "terminal_duration_seconds": None,
+            "estimated_cost_micro_usd": None,
+            "ready_at": "",
+            "last_heartbeat_at": "",
+        }
+        state.attempts.append(row)
+        state.reservations.append(
+            {
+                "attempt_id": attempt_id,
+                "reserved_timeout_cost_micro_usd": proposed,
+                "released": False,
+                "release_reason": "",
+            }
+        )
+        state.save(self.state_path)
+        return row
+
+    def submit_prepared(self, attempt_id: str) -> dict[str, Any]:
+        if not self.enable_submit:
+            raise LaunchError("submission disabled; inject a provider and explicitly enable it")
+        if self.provider is None:
+            raise LaunchError("no provider injected")
+        state = LauncherState.load(self.state_path)
+        row = _one(state, attempt_id)
+        if row["state"] != "PENDING_SUBMISSION":
+            raise LaunchError("attempt is not pending submission")
+        try:
+            result = self.provider.submit({**row["request"], "label": row["label"]})
+        except AmbiguousSubmission:
+            state.save(self.state_path)
+            raise
+        self._record_submit_result(state, row, result)
+        state.save(self.state_path)
+        return row
+
+    def reconcile_ambiguous(self, attempt_id: str) -> dict[str, Any]:
+        if self.provider is None:
+            raise LaunchError("no provider injected")
+        state = LauncherState.load(self.state_path)
+        row = _one(state, attempt_id)
+        if row["state"] != "PENDING_SUBMISSION":
+            raise LaunchError("only pending submissions can be reconciled")
+        matches = self.provider.find_by_label(row["label"])
+        if len(matches) > 1:
+            raise LaunchError("duplicate provider labels; owner review required")
+        if len(matches) == 1:
+            self._record_submit_result(state, row, matches[0])
+        else:
+            row["provisional_id_slot"] = False
+            row["state"] = "ABSENT_AFTER_RECONCILIATION"
+            _release_reservation(state, attempt_id, "provider_absence_proved")
+        state.save(self.state_path)
+        return row
+
+    @staticmethod
+    def _record_submit_result(
+        state: LauncherState, row: dict[str, Any], result: dict[str, Any]
+    ) -> None:
+        job_id, job_url = result.get("job_id"), result.get("job_url")
+        if not job_id or not job_url:
+            raise AmbiguousSubmission("provider response did not contain a complete identity")
+        if any(other.get("job_id") == job_id for other in state.attempts if other is not row):
+            raise LaunchError("provider job ID is already recorded")
+        row.update(
+            state="SUBMITTED",
+            job_id=job_id,
+            job_url=job_url,
+            provisional_id_slot=False,
+        )
+
+    def poll(self, attempt_id: str, *, now: datetime) -> dict[str, Any]:
+        if self.provider is None:
+            raise LaunchError("no provider injected")
+        state = LauncherState.load(self.state_path)
+        row = _one(state, attempt_id)
+        if not row["job_id"]:
+            raise LaunchError("attempt has no provider job ID")
+        remote = self.provider.get(row["job_id"])
+        remote_state = remote["state"]
+        if remote_state not in ACTIVE | TERMINAL:
+            raise LaunchError(f"unknown provider lifecycle state {remote_state!r}")
+        row["state"] = remote_state
+        if remote.get("ready_marker"):
+            row["ready_at"] = remote.get("ready_at") or now.astimezone(timezone.utc).isoformat()
+        if remote.get("heartbeat"):
+            row["last_heartbeat_at"] = remote.get("heartbeat_at") or now.astimezone(
+                timezone.utc
+            ).isoformat()
+        self._enforce_runtime_gates(row, remote, now)
+        if remote_state in TERMINAL:
+            duration = remote.get("billable_duration_seconds")
+            if not isinstance(duration, int) or duration < 0:
+                raise LaunchError("terminal attempt lacks final billable duration")
+            row["terminal_duration_seconds"] = duration
+            row["estimated_cost_micro_usd"] = quantum_cost(
+                row["request"]["frozen_hourly_rate_micro_usd"], duration
+            )
+            _release_reservation(state, attempt_id, "terminal_duration_recorded")
+        state.save(self.state_path)
+        return row
+
+    @staticmethod
+    def _enforce_runtime_gates(
+        row: dict[str, Any], remote: dict[str, Any], now: datetime
+    ) -> None:
+        billable_start = next(
+            (
+                remote.get(name)
+                for name in ("starting_at", "started_at", "first_running_at")
+                if remote.get(name)
+            ),
+            None,
+        )
+        if not billable_start or row["state"] in TERMINAL:
+            return
+        elapsed = (now.astimezone(timezone.utc) - parse_utc(billable_start)).total_seconds()
+        if not row["ready_at"] and elapsed > 180:
+            raise LaunchError("readiness deadline exceeded")
+        heartbeat_deadline = (
+            (
+                max(
+                    180,
+                    3 * row["request"]["largest_guarded_no_output_block_seconds"],
+                )
+                + 59
+            )
+            // 60
+        ) * 60
+        heartbeat_from = parse_utc(row["last_heartbeat_at"] or billable_start)
+        if (now.astimezone(timezone.utc) - heartbeat_from).total_seconds() > heartbeat_deadline:
+            raise LaunchError("heartbeat deadline exceeded")
+
+    def cancel(self, attempt_id: str) -> None:
+        if not self.enable_submit or self.provider is None:
+            raise LaunchError("cancellation disabled without an explicitly enabled provider")
+        state = LauncherState.load(self.state_path)
+        row = _one(state, attempt_id)
+        if row["state"] not in ACTIVE or not row["job_id"]:
+            raise LaunchError("attempt is not cancelable")
+        self.provider.cancel(row["job_id"])
+        row["state"] = "CANCELING"
+        state.save(self.state_path)
+
+
+def _one(state: LauncherState, attempt_id: str) -> dict[str, Any]:
+    matches = [row for row in state.attempts if row["attempt_id"] == attempt_id]
+    if len(matches) != 1:
+        raise LaunchError(f"attempt lookup returned {len(matches)} rows")
+    return matches[0]
+
+
+def _release_reservation(state: LauncherState, attempt_id: str, reason: str) -> None:
+    matches = [row for row in state.reservations if row["attempt_id"] == attempt_id]
+    if len(matches) != 1:
+        raise LaunchError("attempt reservation is missing or duplicated")
+    matches[0]["released"] = True
+    matches[0]["release_reason"] = reason

src/repro_control/manifests.py

@@ -0,0 +1,152 @@
+"""Strict static and lifecycle-aware Job manifest validation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Any
+
+from .constants import NOT_APPLICABLE, SCIENCE_SPEC_SHA256
+
+JOB_CLASSES = frozenset(
+    {"CPU_CANARY", "CPU_IMPORT", "GPU_SMOKE", "SCIENTIFIC_TRAIN", "SCIENTIFIC_EVAL"}
+)
+REQUIRED_FIELDS = frozenset(
+    {
+        "job_class",
+        "logical_id",
+        "attempt_id",
+        "image_digest",
+        "science_spec_sha256",
+        "science_freeze_sha256",
+        "hashes",
+        "task",
+        "seed",
+        "intervention",
+        "hardware",
+        "frozen_hourly_rate_micro_usd",
+        "timeout_seconds",
+        "largest_guarded_no_output_block_seconds",
+        "command",
+        "expected_outputs",
+        "mounts",
+    }
+)
+SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+ID_RE = re.compile(r"^[A-Z0-9][A-Z0-9-]{1,95}$")
+ATTEMPT_RE = re.compile(r"^[a-z0-9][a-z0-9-]{7,95}$")
+
+
+class ManifestError(ValueError):
+    pass
+
+
+def _exact_keys(value: dict[str, Any], expected: frozenset[str], where: str) -> None:
+    missing = expected - value.keys()
+    extra = value.keys() - expected
+    if missing or extra:
+        raise ManifestError(f"{where} keys: missing={sorted(missing)}, extra={sorted(extra)}")
+
+
+def _sha_or_empty(value: Any, name: str) -> None:
+    if value != "" and (not isinstance(value, str) or not SHA256_RE.fullmatch(value)):
+        raise ManifestError(f"{name} must be empty or lowercase SHA-256")
+
+
+def validate_mount(mount: dict[str, Any]) -> None:
+    _exact_keys(
+        mount,
+        frozenset({"volume_source", "volume_path", "mount_path", "read_only"}),
+        "mount",
+    )
+    for name in ("volume_source", "volume_path", "mount_path"):
+        if not isinstance(mount[name], str) or not mount[name]:
+            raise ManifestError(f"mount {name} must be a non-empty string")
+    path = PurePosixPath(mount["mount_path"])
+    if not path.is_absolute() or ".." in path.parts:
+        raise ManifestError("mount_path must be normalized and absolute")
+    if not isinstance(mount["read_only"], bool):
+        raise ManifestError("mount read_only must be boolean")
+
+
+def validate_manifest(value: dict[str, Any], *, freeze_sha256: str = "") -> None:
+    _exact_keys(value, REQUIRED_FIELDS, "manifest")
+    job_class = value["job_class"]
+    if job_class not in JOB_CLASSES:
+        raise ManifestError(f"unknown job_class {job_class!r}")
+    if not isinstance(value["logical_id"], str) or not ID_RE.fullmatch(value["logical_id"]):
+        raise ManifestError("logical_id must be a neutral uppercase identity")
+    if not isinstance(value["attempt_id"], str) or not ATTEMPT_RE.fullmatch(value["attempt_id"]):
+        raise ManifestError("attempt_id must be a deterministic lowercase identity")
+    if not isinstance(value["image_digest"], str) or not (
+        value["image_digest"].startswith("sha256:") and SHA256_RE.fullmatch(value["image_digest"][7:])
+    ):
+        raise ManifestError("image_digest must be sha256:<digest>")
+    expected_spec = NOT_APPLICABLE if job_class == "CPU_CANARY" else SCIENCE_SPEC_SHA256
+    if value["science_spec_sha256"] != expected_spec:
+        raise ManifestError(f"{job_class} science_spec_sha256 must be {expected_spec}")
+    if job_class in {"SCIENTIFIC_TRAIN", "SCIENTIFIC_EVAL"}:
+        if not freeze_sha256 or not SHA256_RE.fullmatch(freeze_sha256):
+            raise ManifestError("scientific manifest requires the expected freeze SHA-256")
+        if value["science_freeze_sha256"] != freeze_sha256:
+            raise ManifestError("scientific manifest freeze mismatch")
+    elif value["science_freeze_sha256"] != NOT_APPLICABLE:
+        raise ManifestError(f"{job_class} science_freeze_sha256 must be NOT_APPLICABLE")
+    if not isinstance(value["hashes"], dict):
+        raise ManifestError("hashes must be an object")
+    for name in ("source", "config", "data", "checkpoint"):
+        if name not in value["hashes"]:
+            raise ManifestError(f"hashes missing {name}")
+        _sha_or_empty(value["hashes"][name], f"hashes.{name}")
+    if value["seed"] not in (None, 42, 123, 456):
+        raise ManifestError("seed must be null or registered")
+    if not isinstance(value["frozen_hourly_rate_micro_usd"], int) or value[
+        "frozen_hourly_rate_micro_usd"
+    ] < 0:
+        raise ManifestError("rate must be a nonnegative integer")
+    for name in ("timeout_seconds", "largest_guarded_no_output_block_seconds"):
+        if not isinstance(value[name], int) or value[name] <= 0:
+            raise ManifestError(f"{name} must be a positive integer")
+    if not isinstance(value["command"], list) or not value["command"] or not all(
+        isinstance(item, str) and item for item in value["command"]
+    ):
+        raise ManifestError("command must be a non-empty argv list")
+    if not isinstance(value["expected_outputs"], list) or not value["expected_outputs"]:
+        raise ManifestError("expected_outputs must be a non-empty list")
+    if "DONE.json" not in value["expected_outputs"]:
+        raise ManifestError("expected_outputs must include DONE.json")
+    if not isinstance(value["mounts"], list):
+        raise ManifestError("mounts must be a list")
+    for mount in value["mounts"]:
+        validate_mount(mount)
+    if job_class in {"SCIENTIFIC_TRAIN", "SCIENTIFIC_EVAL"}:
+        controls = [m for m in value["mounts"] if m["mount_path"] == "/repro-control"]
+        if len(controls) != 1 or not controls[0]["read_only"]:
+            raise ManifestError("scientific jobs require one read-only /repro-control mount")
+
+
+def validate_prefix_capability(
+    requested_path: str, allowed_prefix: str, *, write: bool, read_only: bool
+) -> None:
+    requested = PurePosixPath("/" + requested_path.lstrip("/"))
+    allowed = PurePosixPath("/" + allowed_prefix.lstrip("/"))
+    if ".." in PurePosixPath(requested_path).parts:
+        raise ManifestError("parent traversal forbidden")
+    try:
+        requested.relative_to(allowed)
+    except ValueError as exc:
+        raise ManifestError("requested object lies outside the mounted prefix") from exc
+    if write and read_only:
+        raise ManifestError("write forbidden by read-only capability")
+
+
+@dataclass(frozen=True)
+class ReadinessContract:
+    ready_deadline_seconds: int = 180
+    heartbeat_interval_seconds: int = 60
+
+    @staticmethod
+    def heartbeat_deadline(largest_guarded_no_output_block_seconds: int) -> int:
+        raw = max(180, 3 * largest_guarded_no_output_block_seconds)
+        return ((raw + 59) // 60) * 60

src/repro_control/privacy.py

@@ -0,0 +1,95 @@
+"""Deterministic public-byte inventory and conservative privacy scanner."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from .hashing import atomic_write_json, canonical_root, file_entry
+
+SCANNER_VERSION = "repro-privacy-1"
+EXCLUDED_LOCAL_PARTS = frozenset({".git", ".venv", ".uv-cache", "__pycache__"})
+RULES = {
+    "credential_assignment": re.compile(
+        rb"(?i)(?:hf_token|huggingface_token|api[_-]?key|authorization)\\s*[:=]\\s*[\"']?[A-Za-z0-9_-]{12,}"
+    ),
+    "hf_token_shape": re.compile(rb"hf_[A-Za-z0-9]{20,}"),
+    "private_key": re.compile(rb"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),
+    "home_path": re.compile(rb"/(?:Users|home)/[A-Za-z0-9._-]+/"),
+    "private_phase_program": re.compile(
+        rb"(?i)(?:ph" rb"ase[\s_-]*1|sheaf-p" rb"11|p1\.[0-9])"
+    ),
+    "private_phase0_run_id": re.compile(
+        rb"\bE-(?:mnist|maze|sudoku)-s(?:42|123|456)(?:-[A-Za-z0-9_-]+)?\b"
+    ),
+}
+
+
+class PrivacyError(ValueError):
+    pass
+
+
+def scan_paths(
+    roots: Iterable[Path],
+    *,
+    relative_to: Path,
+    intended_remote_map: dict[str, str],
+    allow_checkpoint_references: frozenset[str] = frozenset(),
+) -> dict[str, Any]:
+    relative_to = relative_to.resolve()
+    paths: list[Path] = []
+    for root in roots:
+        root = root.resolve()
+        if root.is_file():
+            paths.append(root)
+        elif root.is_dir():
+            paths.extend(
+                path
+                for path in root.rglob("*")
+                if path.is_file()
+                and not (set(path.relative_to(relative_to).parts) & EXCLUDED_LOCAL_PARTS)
+            )
+    unique = sorted(set(paths))
+    entries, findings = [], []
+    for path in unique:
+        entry = file_entry(path, relative_to=relative_to)
+        entries.append(entry)
+        data = path.read_bytes()
+        display = entry["path"]
+        if display.endswith((".pkl", ".pickle")) and display not in allow_checkpoint_references:
+            findings.append(
+                {
+                    "path": display,
+                    "rule": "checkpoint_bytes",
+                    "offset": 0,
+                    "match_sha256": entry["sha256"],
+                }
+            )
+        for rule, pattern in RULES.items():
+            for match in pattern.finditer(data):
+                findings.append(
+                    {
+                        "path": display,
+                        "rule": rule,
+                        "offset": match.start(),
+                        "match_sha256": __import__("hashlib").sha256(match.group()).hexdigest(),
+                    }
+                )
+    return {
+        "format": 1,
+        "scanner_version": SCANNER_VERSION,
+        "rules": sorted(RULES),
+        "files": entries,
+        "root_sha256": canonical_root(entries),
+        "findings": findings,
+        "intended_remote_map": intended_remote_map,
+        "exit_code": 1 if findings else 0,
+    }
+
+
+def write_receipt(path: Path, receipt: dict[str, Any], *, require_clean: bool = True) -> None:
+    atomic_write_json(path, receipt)
+    if require_clean and receipt["exit_code"] != 0:
+        raise PrivacyError(f"privacy scanner found {len(receipt['findings'])} findings")

src/repro_control/reducers.py

@@ -0,0 +1,179 @@
+"""Exhaustive registered reducers; callers must supply accepted complete seeds."""
+
+from __future__ import annotations
+
+import math
+import statistics
+from dataclasses import dataclass
+from typing import Iterable
+
+T95_DF2 = 4.302652729911275
+T90_DF2 = 2.919985580355516
+
+
+class ReducerInputError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Summary:
+    seeds: tuple[float, float, float]
+    mean: float
+    sample_std: float
+    lower: float
+    upper: float
+    confidence: int
+
+
+def _three(values: Iterable[float], name: str) -> tuple[float, float, float]:
+    row = tuple(float(value) for value in values)
+    if len(row) != 3 or not all(math.isfinite(value) for value in row):
+        raise ReducerInputError(f"{name} must contain three finite accepted-seed values")
+    return row  # type: ignore[return-value]
+
+
+def summarize(values: Iterable[float], confidence: int = 95) -> Summary:
+    row = _three(values, "values")
+    critical = {95: T95_DF2, 90: T90_DF2}.get(confidence)
+    if critical is None:
+        raise ReducerInputError("confidence must be 90 or 95")
+    mean = statistics.fmean(row)
+    sample_std = statistics.stdev(row)
+    half = critical * sample_std / math.sqrt(3)
+    return Summary(row, mean, sample_std, mean - half, mean + half, confidence)
+
+
+def paired(left: Iterable[float], right: Iterable[float], confidence: int = 95) -> Summary:
+    left_row, right_row = _three(left, "left"), _three(right, "right")
+    return summarize((a - b for a, b in zip(left_row, right_row, strict=True)), confidence)
+
+
+def reduce_c1(
+    sheaf: Iterable[float],
+    mpnn: Iterable[float],
+    *,
+    sheaf_parameters: int,
+    mpnn_parameters: int,
+) -> dict:
+    s, m, gap = summarize(sheaf), summarize(mpnn), paired(sheaf, mpnn)
+    mismatch = abs(mpnn_parameters - sheaf_parameters) / sheaf_parameters
+    parameter = (
+        "PARAMETER_MATCH_REPRODUCED"
+        if mismatch <= 0.05
+        else "RELEASED_IMPLEMENTATION_NOT_PARAMETER_MATCHED"
+    )
+    if s.mean >= 85 and m.mean <= 20 and gap.lower > 60:
+        functional = "FUNCTIONAL_GAP_REPRODUCED"
+    elif s.mean < 85 or m.mean > 20 or gap.upper <= 60:
+        functional = "NOT_REPRODUCED_UNDER_PAPER_ROW_RECONSTRUCTION"
+    else:
+        functional = "INCONCLUSIVE"
+    overall = (
+        "FUNCTIONAL_GAP_REPRODUCED_BUT_RELEASE_NOT_PARAMETER_MATCHED"
+        if functional == "FUNCTIONAL_GAP_REPRODUCED"
+        and parameter == "RELEASED_IMPLEMENTATION_NOT_PARAMETER_MATCHED"
+        else functional
+    )
+    return {
+        "functional": functional,
+        "parameter": parameter,
+        "overall": overall,
+        "relative_count_mismatch": mismatch,
+        "summaries": {"sheaf": s, "mpnn": m, "paired_gap": gap},
+    }
+
+
+def reduce_c2(sheaf: Iterable[float], mpnn: Iterable[float]) -> dict:
+    s, m, gap = summarize(sheaf), summarize(mpnn), paired(sheaf, mpnn, 90)
+    if s.mean >= 95 and m.mean >= 95 and gap.lower >= -2 and gap.upper <= 2:
+        verdict = "STATE_EFFICIENCY_REPRODUCED"
+    elif s.mean < 90 or m.mean < 90 or gap.lower > 2 or gap.upper < -2:
+        verdict = "NOT_REPRODUCED"
+    else:
+        verdict = "INCONCLUSIVE"
+    return {
+        "verdict": verdict,
+        "per_vertex_latent_dimension_ratio": 8.4,
+        "memory_reduction_claimed": False,
+        "summaries": {"sheaf": s, "mpnn": m, "paired_gap_90": gap},
+    }
+
+
+def _adequate(values: tuple[float, float, float]) -> bool:
+    return statistics.fmean(values) >= 98.5 and min(values) >= 98.0
+
+
+def reduce_c3(
+    cnn_clean: Iterable[float],
+    sheaf_clean: Iterable[float],
+    cnn_pad16: Iterable[float],
+    sheaf_pad16: Iterable[float],
+    cnn_drop30: Iterable[float],
+    sheaf_drop30: Iterable[float],
+) -> dict:
+    cnn_clean_row = _three(cnn_clean, "cnn_clean")
+    sheaf_clean_row = _three(sheaf_clean, "sheaf_clean")
+    cnn_ok, sheaf_ok = _adequate(cnn_clean_row), _adequate(sheaf_clean_row)
+    if not cnn_ok or not sheaf_ok:
+        who = "BOTH" if not cnn_ok and not sheaf_ok else ("CNN" if not cnn_ok else "SHEAF")
+        verdict = f"INCONCLUSIVE_{who}_CLEAN_REFERENCE_INADEQUATE"
+        pad_gap = drop_gap = None
+    else:
+        pad_gap = paired(sheaf_pad16, cnn_pad16)
+        drop_gap = paired(sheaf_drop30, cnn_drop30)
+        if pad_gap.lower > 20 and drop_gap.lower > 10:
+            verdict = "ROBUSTNESS_GAPS_REPRODUCED"
+        elif pad_gap.upper <= 20 or drop_gap.upper <= 10:
+            verdict = "NOT_REPRODUCED_UNDER_TIER_B_RECONSTRUCTION"
+        else:
+            verdict = "INCONCLUSIVE"
+    return {
+        "verdict": f"{verdict}__DROPOUT_SEMANTICS_TARGET_SELECTED",
+        "clean_adequacy": {"cnn": cnn_ok, "sheaf": sheaf_ok},
+        "paired_gaps": {"pad16": pad_gap, "drop30": drop_gap},
+    }
+
+
+def reduce_c4_sudoku(learned: Iterable[float], identity: Iterable[float]) -> dict:
+    learned_summary, identity_summary = summarize(learned), summarize(identity)
+    gap = paired(learned, identity)
+    if learned_summary.mean >= 85 and identity_summary.mean <= 15 and gap.lower > 60:
+        verdict = "IDENTITY_ABLATION_REPRODUCED"
+    elif learned_summary.mean < 85 or identity_summary.mean > 15 or gap.upper <= 60:
+        verdict = "NOT_REPRODUCED"
+    else:
+        verdict = "INCONCLUSIVE"
+    return {"verdict": verdict, "learned": learned_summary, "identity": identity_summary, "gap": gap}
+
+
+def reduce_c4_maze(default: Iterable[float], quadratic: Iterable[float]) -> dict:
+    default_summary, quadratic_summary = summarize(default), summarize(quadratic)
+    gap = paired(default, quadratic)
+    if default_summary.mean >= 90 and quadratic_summary.mean >= 90 and gap.upper < 20:
+        verdict = "SUPPLIED_COLLAPSE_WORDING_FALSIFIED"
+    elif default_summary.mean >= 90 and quadratic_summary.mean <= 60 and gap.lower > 20:
+        verdict = "DIRECTION_SUPPORTED_UNDER_RECONSTRUCTION"
+    else:
+        verdict = "INCONCLUSIVE"
+    return {
+        "verdict": f"{verdict}__PROMPT_MISSTATES_PAPER_TABLE",
+        "default": default_summary,
+        "quadratic": quadratic_summary,
+        "gap": gap,
+    }
+
+
+def reduce_c5(by_size: dict[int, Iterable[float]]) -> dict:
+    expected = {19, 23, 27, 31, 35, 39}
+    if set(by_size) != expected:
+        raise ReducerInputError("C5 requires all six registered sizes")
+    summaries = {size: summarize(by_size[size]) for size in sorted(by_size)}
+    if all(summary.mean >= 95 for summary in summaries.values()):
+        verdict = "QUALITATIVE_2X_GENERALIZATION_SUPPORTED_UNDER_REGISTERED_RECONSTRUCTION"
+    else:
+        verdict = "NOT_REPRODUCED_UNDER_REGISTERED_LONG_PATH_RECONSTRUCTION"
+    return {
+        "verdict": verdict,
+        "exact_protocol": "INCONCLUSIVE_EXACT_DENSE_FIGURE6_CONFIG_UNRELEASED",
+        "summaries": summaries,
+    }

src/repro_control/runtime.py

@@ -0,0 +1,93 @@
+"""Entrypoint guards shared by import, smoke, train, and evaluation."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from .constants import SCIENCE_SPEC_SHA256
+from .manifests import validate_manifest
+
+
+class RuntimeContractError(RuntimeError):
+    pass
+
+
+def sha256_file(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def verify_science_spec(path: Path) -> dict:
+    if sha256_file(path) != SCIENCE_SPEC_SHA256:
+        raise RuntimeContractError("SCIENCE-SPEC.yaml hash mismatch")
+    value = json.loads(path.read_text())
+    if value.get("outcomes") != {}:
+        raise RuntimeContractError("science spec outcomes must remain empty")
+    return value
+
+
+def load_job_manifest(path: Path, *, freeze_sha256: str = "") -> dict:
+    value = json.loads(path.read_text())
+    validate_manifest(value, freeze_sha256=freeze_sha256)
+    return value
+
+
+def assert_smoke_isolated(manifest: dict) -> None:
+    if manifest["job_class"] != "GPU_SMOKE":
+        raise RuntimeContractError("smoke entrypoint requires GPU_SMOKE")
+    forbidden = ("final", "verdict", "test_hard", "test_ood", "evaluation")
+    for mount in manifest["mounts"]:
+        text = f"{mount['volume_path']} {mount['mount_path']}".lower()
+        if any(term in text for term in forbidden):
+            raise RuntimeContractError("smoke manifest exposes final/evaluation data")
+    for output in manifest["expected_outputs"]:
+        if "verdict" in output.lower():
+            raise RuntimeContractError("smoke entrypoint cannot emit verdict metrics")
+
+
+def assert_evaluation_isolated(manifest: dict) -> None:
+    if manifest["job_class"] != "SCIENTIFIC_EVAL":
+        raise RuntimeContractError("evaluation entrypoint requires SCIENTIFIC_EVAL")
+    for mount in manifest["mounts"]:
+        text = f"{mount['volume_path']} {mount['mount_path']}".lower()
+        if "train-data" in text or "/train" in text or text.endswith(" train"):
+            raise RuntimeContractError("evaluation manifest exposes registered training data")
+
+
+def require_control_freeze(
+    control_dir: Path, expected_freeze_sha256: str, expected_spec_sha256: str
+) -> dict:
+    freeze_path = control_dir / "SCIENCE-FREEZE.yaml"
+    if not freeze_path.is_file() or sha256_file(freeze_path) != expected_freeze_sha256:
+        raise RuntimeContractError("control freeze hash mismatch")
+    value = json.loads(freeze_path.read_text())
+    if value.get("science_spec_sha256") != expected_spec_sha256:
+        raise RuntimeContractError("freeze binds a different science spec")
+    return value
+
+
+def configure_scientific_runtime() -> None:
+    os.environ["JAX_DEFAULT_MATMUL_PRECISION"] = "highest"
+    os.environ.setdefault("TRACE_MODE", "none")
+
+
+def require_jax_platform(expected: str) -> str:
+    import jax
+
+    observed = jax.devices()[0].platform
+    if observed != expected:
+        raise RuntimeContractError(
+            f"scientific runtime requires JAX platform {expected!r}, observed {observed!r}"
+        )
+    return observed
+
+
+def common_parser(description: str) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument("--science-spec", type=Path, required=True)
+    parser.add_argument("--job-manifest", type=Path, required=True)
+    parser.add_argument("--dry-run", action="store_true", default=False)
+    return parser