From 27eb63abf6ba00f27e884270427981ac948dd9fe Mon Sep 17 00:00:00 2001 From: Claude Code Date: Thu, 6 Aug 2026 17:25:45 +0300 Subject: [PATCH 1/7] Proof: a dispatch refuses evidence its lanes cannot download (V5b2d-4c) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Наблюдаемый дефект: coordinator проверял, что --evidence-run-id положительное целое, но не то, что такой прогон существует и несёт названный артефакт. Положительность — не свидетельство существования. Я запустил диспатч против run 99999999 и получил 133 обречённых прогона, каждый падал за 9-11 секунд на скачивании несуществующего артефакта. Одна ошибка координатора превращается в 256 обречённых задач, и узнаёшь ты об этом 256 раз подряд вместо одного. Закон: перед первым диспатчем координатор спрашивает, несёт ли названный прогон названный артефакт, и отказывает закрыто. Наблюдение GitHub — единственная нечистая граница — инъектируется, поэтому само решение проверяется без сети. Любой сбой наблюдения (нет прогона, нет токена, битый ответ) — тоже отказ, а не падение и не молчаливый проход. Dry run остаётся офлайновым по контракту, гейт живёт только на боевом пути. Доказательства: четыре RED-теста (прогон без артефакта, недостижимый прогон, успешный допуск, anti-vacuity — наблюдателя спрашивают именно про названный прогон) плюс проверка реальностью: admit_evidence_artifact_v1(99999999, ...) отвергает тот самый вход, что стоил 133 прогонов, а 31089986150 допускается для обоих движков. Локально: 14 тестов координатора, OK. --- proof/region/v1/corpus_dispatch.py | 65 +++++++++++++++++++ proof/region/v1/tests/test_corpus_dispatch.py | 52 +++++++++++++++ 2 files changed, 117 insertions(+) diff --git a/proof/region/v1/corpus_dispatch.py b/proof/region/v1/corpus_dispatch.py index 2326569f..5c783ab9 100644 --- a/proof/region/v1/corpus_dispatch.py +++ b/proof/region/v1/corpus_dispatch.py @@ -188,6 +188,62 @@ def verification_dispatch_commands_v1( ) +def gh_run_artifact_names_v1(run_id: int) -> tuple[str, ...]: + """Artifact names the given workflow run carries, read through `gh`. + + The one impure boundary of this admission: it observes GitHub. It is + injected into `admit_evidence_artifact_v1` so the decision itself stays + testable without a network. + """ + + completed = subprocess.run( + ( + "gh", + "api", + f"repos/{{owner}}/{{repo}}/actions/runs/{run_id}/artifacts", + "--jq", + ".artifacts[].name", + ), + capture_output=True, + text=True, + check=True, + ) + return tuple( + line.strip() for line in completed.stdout.splitlines() if line.strip() + ) + + +def admit_evidence_artifact_v1( + evidence_run_id: int, + evidence_artifact: str, + observer: object = gh_run_artifact_names_v1, +) -> corpus.ShardCorpusRejectedV1 | None: + """Refuse a dispatch whose evidence run cannot carry what it names. + + Every lane downloads `evidence_artifact` from `evidence_run_id`; a run + that does not exist, or carries no such artifact, turns one mistake into + 256 doomed jobs. A positive integer is not evidence that a run exists, + so the coordinator asks before it dispatches, and any failure to observe + is itself a refusal — never a crash and never a silent proceed. + """ + + try: + names = tuple(observer(evidence_run_id)) # type: ignore[operator] + except Exception: + # The observation is a hostile boundary: an unreachable run, a + # missing token or a malformed reply must all land as one refusal. + return corpus._reject( + corpus.ShardCorpusReasonV1.FOREIGN_INPUT, + f"verification dispatch cannot observe run {evidence_run_id}", + ) + if evidence_artifact not in names: + return corpus._reject( + corpus.ShardCorpusReasonV1.FOREIGN_INPUT, + f"run {evidence_run_id} carries no artifact {evidence_artifact!r}", + ) + return None + + def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( @@ -242,6 +298,15 @@ def main(argv: list[str] | None = None) -> int: args.evidence_run_id, args.evidence_artifact, ) + if type(commands) is tuple and not args.dry_run: + # Fail closed before the first dispatch: a dry run stays offline + # by contract, so the observation belongs to the live path only. + refusal = admit_evidence_artifact_v1( + args.evidence_run_id, args.evidence_artifact + ) + if refusal is not None: + print(f"verification dispatch refused: {refusal.detail}", file=sys.stderr) + return 64 else: commands = dispatch_commands_v1(plan, args.shard_width) for command in commands: diff --git a/proof/region/v1/tests/test_corpus_dispatch.py b/proof/region/v1/tests/test_corpus_dispatch.py index 2ed438fd..ae6ded64 100644 --- a/proof/region/v1/tests/test_corpus_dispatch.py +++ b/proof/region/v1/tests/test_corpus_dispatch.py @@ -198,5 +198,57 @@ def test_unknown_mode_is_rejected(self) -> None: corpus_dispatch.main(["--mode", "launch"]) +class EvidenceAdmissionTests(unittest.TestCase): + """A dispatch names a run that must actually carry the artifact. + + The lane workflow downloads the named artifact from the named run, so a + run that does not exist, or exists without that artifact, produces one + doomed job per lane — 256 of them, each failing seconds in. The + coordinator refuses before any dispatch exists instead of discovering it + 256 times over. + """ + + def test_a_run_without_the_artifact_is_a_typed_rejection(self) -> None: + result = corpus_dispatch.admit_evidence_artifact_v1( + 424242, + "verification-evidence-arb", + lambda run_id: ("verification-evidence-mpfi",), + ) + self.assertIs(type(result), corpus.ShardCorpusRejectedV1) + self.assertEqual(result.reason, corpus.ShardCorpusReasonV1.FOREIGN_INPUT) + + def test_an_unreachable_run_is_a_typed_rejection_not_a_crash(self) -> None: + def unreachable(run_id: int): + raise OSError("no such run") + + result = corpus_dispatch.admit_evidence_artifact_v1( + 424242, "verification-evidence-arb", unreachable + ) + self.assertIs(type(result), corpus.ShardCorpusRejectedV1) + self.assertEqual(result.reason, corpus.ShardCorpusReasonV1.FOREIGN_INPUT) + + def test_a_run_carrying_the_artifact_is_admitted(self) -> None: + result = corpus_dispatch.admit_evidence_artifact_v1( + 424242, + "verification-evidence-arb", + lambda run_id: ("verification-evidence-arb", "verification-evidence-mpfi"), + ) + self.assertIsNone(result) + + def test_the_observer_is_asked_about_the_named_run(self) -> None: + # Anti-vacuity: an observer that ignores its argument would let a + # dispatch bind one run while its artifacts were read from another. + seen: list[int] = [] + + def observer(run_id: int): + seen.append(run_id) + return ("verification-evidence-arb",) + + corpus_dispatch.admit_evidence_artifact_v1( + 99, "verification-evidence-arb", observer + ) + self.assertEqual(seen, [99]) + + if __name__ == "__main__": unittest.main() From b16f217bb642b76fcaac7ffb94ebf1da37be84a8 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Thu, 6 Aug 2026 18:06:23 +0300 Subject: [PATCH 2/7] Proof: the gate must refuse what cannot be downloaded, and be wired in provably MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Две независимые линзы ревью дали FAIL. Находки закрыты; две из них означали, что гейт лишь ВЫГЛЯДЕЛ рабочим. 1. Истёкшие артефакты. Листинг GitHub включает артефакты с expired:true, скачать которые нельзя. Гейт брал имя не глядя, поэтому старый evidence-run проходил бы допуск и снова давал 256 обречённых полос — ровно тот класс, который срез объявляет закрытым, только через соседний путь. Теперь jq отбирает `select(.expired | not)`. 2. Шов не был покрыт. Четыре теста доказывали РЕШЕНИЕ допуска, но ни один не доказывал, что main() спрашивает. Удаление прошивки оставляло все 14 тестов зелёными. Добавлены четыре теста шва: отказ не диспатчит ничего, допуск диспатчит все 256 полос, dry run никого не спрашивает и ничего не запускает, отвергнутый набор команд уходит через exit 64. Саботаж подтверждает чувствительность: удаление прошивки красит test_a_refused_evidence_run_ dispatches_nothing. 3. Точка инъекции была декларативной. Значение по умолчанию связывало gh_run_artifact_names_v1 при определении функции, поэтому подмена наблюдателя не действовала: шов выглядел инъектируемым и не был им. Дефект вскрыл сам тест шва — резолвинг перенесён в тело. 4. Отвергнутый набор команд попадал в цикл и давал нетипизированный TypeError: 'ShardCorpusRejectedV1' object is not iterable. Дефект предсуществующий, но мой guard `type(commands) is tuple` был написан ВОКРУГ отказа, не обработав его, и нарушал тот самый инвариант, который срез заявляет. Теперь типизированный exit 64. 5. Пагинация: gh api без --paginate отдаёт одну страницу; имя на второй странице читалось бы как отсутствующее. Добавлен --paginate. Направление и без того было fail-closed, но ложный отказ на валидном прогоне — тоже дефект. 6. Причина отказа теперь едет с отказом: оператор обязан отличать «нет такого прогона» от «нет токена», иначе диагностика инцидента требует ручного повтора вызова. Проверка реальностью: 99999999 отвергается, 31089986150 и 31022375756 (оба движка, живые артефакты) допускаются. Локально: 18 тестов координатора, OK. --- proof/region/v1/corpus_dispatch.py | 29 +++++- proof/region/v1/tests/test_corpus_dispatch.py | 94 +++++++++++++++++++ 2 files changed, 119 insertions(+), 4 deletions(-) diff --git a/proof/region/v1/corpus_dispatch.py b/proof/region/v1/corpus_dispatch.py index 5c783ab9..39bef4f4 100644 --- a/proof/region/v1/corpus_dispatch.py +++ b/proof/region/v1/corpus_dispatch.py @@ -200,9 +200,15 @@ def gh_run_artifact_names_v1(run_id: int) -> tuple[str, ...]: ( "gh", "api", + "--paginate", f"repos/{{owner}}/{{repo}}/actions/runs/{run_id}/artifacts", "--jq", - ".artifacts[].name", + # An expired artifact is still listed but can no longer be + # downloaded, so naming it would let a stale evidence run through + # the gate and reproduce the very failure this admission exists to + # prevent. Pagination matters for the same reason: a name on the + # second page must not read as absent. + ".artifacts[] | select(.expired | not) | .name", ), capture_output=True, text=True, @@ -216,7 +222,7 @@ def gh_run_artifact_names_v1(run_id: int) -> tuple[str, ...]: def admit_evidence_artifact_v1( evidence_run_id: int, evidence_artifact: str, - observer: object = gh_run_artifact_names_v1, + observer: object | None = None, ) -> corpus.ShardCorpusRejectedV1 | None: """Refuse a dispatch whose evidence run cannot carry what it names. @@ -227,14 +233,23 @@ def admit_evidence_artifact_v1( is itself a refusal — never a crash and never a silent proceed. """ + # Resolved here, not captured as a default: a default binds the module + # attribute at definition time, which makes the injection point real for + # a caller but invisible to anything that replaces the observer — the + # seam would look injectable and not be. + if observer is None: + observer = gh_run_artifact_names_v1 try: names = tuple(observer(evidence_run_id)) # type: ignore[operator] - except Exception: + except Exception as error: # The observation is a hostile boundary: an unreachable run, a # missing token or a malformed reply must all land as one refusal. + # The cause travels with it — an operator has to tell "no such run" + # from "no token", and a bare refusal makes those look identical. return corpus._reject( corpus.ShardCorpusReasonV1.FOREIGN_INPUT, - f"verification dispatch cannot observe run {evidence_run_id}", + f"verification dispatch cannot observe run {evidence_run_id}:" + f" {error!r}", ) if evidence_artifact not in names: return corpus._reject( @@ -309,6 +324,12 @@ def main(argv: list[str] | None = None) -> int: return 64 else: commands = dispatch_commands_v1(plan, args.shard_width) + if type(commands) is not tuple: + # A rejected command set is a typed refusal, not an iterable: letting + # it reach the loop below turns the module's own contract into a + # TypeError at the boundary it is supposed to guard. + print(f"lane dispatch rejected: {commands!r}", file=sys.stderr) + return 64 for command in commands: rendered = " ".join(command) if args.dry_run: diff --git a/proof/region/v1/tests/test_corpus_dispatch.py b/proof/region/v1/tests/test_corpus_dispatch.py index ae6ded64..e35089ac 100644 --- a/proof/region/v1/tests/test_corpus_dispatch.py +++ b/proof/region/v1/tests/test_corpus_dispatch.py @@ -17,6 +17,7 @@ import sys import tempfile import unittest +import unittest.mock from pathlib import Path PROOF = Path(__file__).resolve().parents[1] @@ -250,5 +251,98 @@ def observer(run_id: int): self.assertEqual(seen, [99]) +class DispatchSeamTests(unittest.TestCase): + """The gate has to be wired in, not merely defined. + + Four unit tests over the admission prove the decision; none of them + prove that `main` asks. Deleting the call would leave those green while + the live path dispatched blind again, so the seam gets its own contract: + a refusal must stop the campaign before the first invocation, and an + admission must let it through. + """ + + def _argv(self, out: Path) -> list[str]: + return [ + "--mode", + "verification-dispatch", + "--evidence-run-id", + "424242", + "--evidence-artifact", + "verification-evidence-arb", + "--out", + str(out), + ] + + def test_a_refused_evidence_run_dispatches_nothing(self) -> None: + launched: list[tuple[str, ...]] = [] + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, "gh_run_artifact_names_v1", lambda run_id: () + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: launched.append(tuple(command)), + ): + code = corpus_dispatch.main(self._argv(Path(tmp) / "out.txt")) + self.assertEqual(code, 64) + self.assertEqual(launched, []) + + def test_an_admitted_evidence_run_dispatches_every_lane(self) -> None: + launched: list[tuple[str, ...]] = [] + + class _Completed: + returncode = 0 + + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifact_names_v1", + lambda run_id: ("verification-evidence-arb",), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: ( + launched.append(tuple(command)) or _Completed() + ), + ): + code = corpus_dispatch.main(self._argv(Path(tmp) / "out.txt")) + self.assertEqual(code, 0) + self.assertEqual(len(launched), 256) + self.assertTrue( + all(command[:3] == ("gh", "workflow", "run") for command in launched) + ) + + def test_a_dry_run_stays_offline_and_asks_nobody(self) -> None: + # The dry run is documented as offline: it must not even observe. + observed: list[int] = [] + launched: list[tuple[str, ...]] = [] + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifact_names_v1", + lambda run_id: observed.append(run_id) or (), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: launched.append(tuple(command)), + ): + code = corpus_dispatch.main( + self._argv(Path(tmp) / "out.txt") + ["--dry-run"] + ) + self.assertEqual(code, 0) + self.assertEqual(observed, []) + self.assertEqual(launched, []) + + def test_a_rejected_command_set_is_exit_64_not_a_type_error(self) -> None: + # A foreign artifact name is refused by the pure builder; that + # refusal must leave through the typed exit, never as a TypeError + # raised by iterating a rejection. + with tempfile.TemporaryDirectory() as tmp: + argv = self._argv(Path(tmp) / "out.txt") + argv[argv.index("verification-evidence-arb")] = "verification-evidence-foreign" + code = corpus_dispatch.main(argv + ["--dry-run"]) + self.assertEqual(code, 64) + + if __name__ == "__main__": unittest.main() From 546ff045343b955cd416066d045256f89efd8b70 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Thu, 6 Aug 2026 18:31:43 +0300 Subject: [PATCH 3/7] Proof: pin the coordinate the incident turned on, and put the expiry rule where a test can reach it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Пере-ревью финального состояния. Два дефекта, оба доказаны мутацией, и оба означали, что защита выглядит рабочей и не является ею. 1. Тесты шва не закрепляли КООРДИНАТУ RUN_ID. Оба подменённых наблюдателя игнорировали аргумент, поэтому мутант, зашивающий чужой id в вызов допуска (admit_evidence_artifact_v1(1, args.evidence_artifact)), выживал при всех 18 зелёных тестах. Координата артефакта была закреплена, а run_id — тот самый, на котором и произошёл инцидент с 99999999, — нет. Живой сценарий: гейт наблюдает прогон A и допускает, а 256 полос диспатчатся связанными с прогоном B. Наблюдатели шва сделаны чувствительными к run_id; мутант гибнет. 2. Правило истёкших артефактов жило в jq-выражении, то есть за сетью, и не было покрыто ничем: удаление select(.expired | not) оставляло все 18 тестов зелёными. Наблюдение теперь только НАБЛЮДАЕТ и возвращает пары (имя, expired), а решение, что считается свидетельством, применяется в чистом ядре, где до него дотягивается тест. Два теста: истёкший артефакт — отказ; живой рядом с истёкшим — допуск (иначе правило выродилось бы в сплошной отказ). Мутант «убрать фильтр» гибнет. 3. Причина отказа несла repr(error), а CalledProcessError.__repr__ отбрасывает stderr — ровно тот текст, который отличает «нет такого прогона» от «нет токена». Комментарий обещал различимость, код её не давал. Теперь detail несёт stderr: живая проверка даёт «cannot observe run 99999999: gh: Not Found (HTTP 404)». Проверка реальностью: 99999999 отвергается с причиной, 31089986150 допускается, наблюдение возвращает обе пары с expired=False. Локально: 20 тестов координатора, OK. --- proof/region/v1/corpus_dispatch.py | 44 ++++++++++------ proof/region/v1/tests/test_corpus_dispatch.py | 52 ++++++++++++++++--- 2 files changed, 72 insertions(+), 24 deletions(-) diff --git a/proof/region/v1/corpus_dispatch.py b/proof/region/v1/corpus_dispatch.py index 39bef4f4..1926bab4 100644 --- a/proof/region/v1/corpus_dispatch.py +++ b/proof/region/v1/corpus_dispatch.py @@ -188,12 +188,13 @@ def verification_dispatch_commands_v1( ) -def gh_run_artifact_names_v1(run_id: int) -> tuple[str, ...]: - """Artifact names the given workflow run carries, read through `gh`. +def gh_run_artifacts_v1(run_id: int) -> tuple[tuple[str, bool], ...]: + """Every artifact the run lists, as `(name, expired)` pairs. - The one impure boundary of this admission: it observes GitHub. It is - injected into `admit_evidence_artifact_v1` so the decision itself stays - testable without a network. + The one impure boundary of this admission: it observes GitHub and reports + what it saw, without deciding anything. Which of those artifacts count is + a rule, so it lives in `admit_evidence_artifact_v1` where a test can reach + it — filtering here would put the rule behind the network. """ completed = subprocess.run( @@ -203,20 +204,19 @@ def gh_run_artifact_names_v1(run_id: int) -> tuple[str, ...]: "--paginate", f"repos/{{owner}}/{{repo}}/actions/runs/{run_id}/artifacts", "--jq", - # An expired artifact is still listed but can no longer be - # downloaded, so naming it would let a stale evidence run through - # the gate and reproduce the very failure this admission exists to - # prevent. Pagination matters for the same reason: a name on the - # second page must not read as absent. - ".artifacts[] | select(.expired | not) | .name", + ".artifacts[] | [.name, (.expired // false)] | @tsv", ), capture_output=True, text=True, check=True, ) - return tuple( - line.strip() for line in completed.stdout.splitlines() if line.strip() - ) + observed: list[tuple[str, bool]] = [] + for line in completed.stdout.splitlines(): + if not line.strip(): + continue + name, _, expired = line.partition(" ") + observed.append((name.strip(), expired.strip().lower() == "true")) + return tuple(observed) def admit_evidence_artifact_v1( @@ -238,18 +238,28 @@ def admit_evidence_artifact_v1( # a caller but invisible to anything that replaces the observer — the # seam would look injectable and not be. if observer is None: - observer = gh_run_artifact_names_v1 + observer = gh_run_artifacts_v1 try: - names = tuple(observer(evidence_run_id)) # type: ignore[operator] + observed = tuple(observer(evidence_run_id)) # type: ignore[operator] + # An expired artifact is still listed but can no longer be + # downloaded, so naming it would admit a stale evidence run and + # reproduce the very failure this admission exists to prevent. The + # rule is applied here, not in the query, so a test can prove it. + names = tuple(name for name, expired in observed if not expired) except Exception as error: # The observation is a hostile boundary: an unreachable run, a # missing token or a malformed reply must all land as one refusal. # The cause travels with it — an operator has to tell "no such run" # from "no token", and a bare refusal makes those look identical. + # CalledProcessError.__repr__ drops stderr, and stderr is where the + # only distinguishing text lives: "Not Found" against "no token" + # against a network failure. Without it the operator debugs the wrong + # axis, which is exactly what the refusal is supposed to prevent. + cause = getattr(error, "stderr", None) or repr(error) return corpus._reject( corpus.ShardCorpusReasonV1.FOREIGN_INPUT, f"verification dispatch cannot observe run {evidence_run_id}:" - f" {error!r}", + f" {str(cause).strip()}", ) if evidence_artifact not in names: return corpus._reject( diff --git a/proof/region/v1/tests/test_corpus_dispatch.py b/proof/region/v1/tests/test_corpus_dispatch.py index e35089ac..ab3dd8c2 100644 --- a/proof/region/v1/tests/test_corpus_dispatch.py +++ b/proof/region/v1/tests/test_corpus_dispatch.py @@ -213,7 +213,7 @@ def test_a_run_without_the_artifact_is_a_typed_rejection(self) -> None: result = corpus_dispatch.admit_evidence_artifact_v1( 424242, "verification-evidence-arb", - lambda run_id: ("verification-evidence-mpfi",), + lambda run_id: (("verification-evidence-mpfi", False),), ) self.assertIs(type(result), corpus.ShardCorpusRejectedV1) self.assertEqual(result.reason, corpus.ShardCorpusReasonV1.FOREIGN_INPUT) @@ -232,7 +232,35 @@ def test_a_run_carrying_the_artifact_is_admitted(self) -> None: result = corpus_dispatch.admit_evidence_artifact_v1( 424242, "verification-evidence-arb", - lambda run_id: ("verification-evidence-arb", "verification-evidence-mpfi"), + lambda run_id: ( + ("verification-evidence-arb", False), + ("verification-evidence-mpfi", False), + ), + ) + self.assertIsNone(result) + + def test_an_expired_artifact_is_not_evidence(self) -> None: + # An expired artifact is still listed by GitHub but can no longer be + # downloaded, so admitting it would send every lane to a download + # that cannot succeed — the incident class, through the stale-run + # path instead of the missing-run one. + result = corpus_dispatch.admit_evidence_artifact_v1( + 424242, + "verification-evidence-arb", + lambda run_id: (("verification-evidence-arb", True),), + ) + self.assertIs(type(result), corpus.ShardCorpusRejectedV1) + self.assertEqual(result.reason, corpus.ShardCorpusReasonV1.FOREIGN_INPUT) + + def test_a_live_artifact_beside_an_expired_one_is_admitted(self) -> None: + # Anti-vacuity for the rule above: expiry must filter, not blanket-refuse. + result = corpus_dispatch.admit_evidence_artifact_v1( + 424242, + "verification-evidence-arb", + lambda run_id: ( + ("verification-evidence-mpfi", True), + ("verification-evidence-arb", False), + ), ) self.assertIsNone(result) @@ -243,7 +271,7 @@ def test_the_observer_is_asked_about_the_named_run(self) -> None: def observer(run_id: int): seen.append(run_id) - return ("verification-evidence-arb",) + return (("verification-evidence-arb", False),) corpus_dispatch.admit_evidence_artifact_v1( 99, "verification-evidence-arb", observer @@ -277,7 +305,11 @@ def test_a_refused_evidence_run_dispatches_nothing(self) -> None: launched: list[tuple[str, ...]] = [] with tempfile.TemporaryDirectory() as tmp: with unittest.mock.patch.object( - corpus_dispatch, "gh_run_artifact_names_v1", lambda run_id: () + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: (("verification-evidence-arb", False),) + if run_id == 999 + else (), ), unittest.mock.patch.object( corpus_dispatch.subprocess, "run", @@ -296,8 +328,14 @@ class _Completed: with tempfile.TemporaryDirectory() as tmp: with unittest.mock.patch.object( corpus_dispatch, - "gh_run_artifact_names_v1", - lambda run_id: ("verification-evidence-arb",), + "gh_run_artifacts_v1", + # Sensitive to the run id on purpose: an observer that ignores + # it lets a mutant hardcode the id at the admission call site + # and still pass — and the run id is the exact coordinate the + # 99999999 incident turned on. + lambda run_id: (("verification-evidence-arb", False),) + if run_id == 424242 + else (), ), unittest.mock.patch.object( corpus_dispatch.subprocess, "run", @@ -319,7 +357,7 @@ def test_a_dry_run_stays_offline_and_asks_nobody(self) -> None: with tempfile.TemporaryDirectory() as tmp: with unittest.mock.patch.object( corpus_dispatch, - "gh_run_artifact_names_v1", + "gh_run_artifacts_v1", lambda run_id: observed.append(run_id) or (), ), unittest.mock.patch.object( corpus_dispatch.subprocess, From e45b74682cdcfc6ee74a051db4e71bc774b37059 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Thu, 6 Aug 2026 21:46:46 +0300 Subject: [PATCH 4/7] Proof: make the safe run the default, and test the rules that were only claimed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two independent reviews of the final state — one of them running actual mutants — showed this slice narrowed the incident class without closing it, and that its own commit message overstated what was pinned. THE POLARITY. The incident was a forgotten `--dry-run`, and the fix left the dangerous run as the default: safety still meant remembering a flag. Printing is now what happens, `--execute` is the opt-in, and it has to name the campaign's size with `--expect-lanes`. Swapping the two widths is a realistic slip — `--lane-width 256 --shard-width 4` is 65536 runs — and the only cheap moment to notice is before the first invocation. THE ARTIFACT COORDINATE. A mutant hardcoding `EVIDENCE_ARTIFACTS_V1[0]` at the admission call site survived all twenty tests: both seam tests always passed the arb name, so pinning one engine was indistinguishable. The producer runs its two engines as independent jobs, so a run really can carry one artifact and not the other, and admitting the wrong one buys 256 doomed lanes — the incident down a second axis. The previous message claimed this coordinate was pinned; it was pinned where commands are built, not where the admission asks. THE EXPIRY RULE. Moving the filter out of the query put the decision where a test could reach it and left the decoding that produces it behind the network. Two mutants survived: one that never marks anything expired, one that drops the field from the query. `parse_artifact_listing_v1` is pure now and refuses a listing that is not the two-column form it asked for — the old parser read an unrecognised line as "live", which admits exactly the stale evidence run this gate exists to refuse. The repository currently holds 127 expired artifacts, so the path is not hypothetical. A campaign that dies mid-flight now reports how many lanes it launched and returns the typed exit instead of a traceback, so the retry can resume rather than duplicate. Every repair is proven by the mutant it kills, each failing exactly one test: the hardcoded artifact, the never-expired listing, the field dropped from the query, and `repr(error)` in place of the stderr that tells "no such run" from "no token". Verified: 276 local tests, 7 errors — the exact Windows baseline. Left out deliberately, and not hidden: the admission still checks that the named artifact exists, not that it carries `job.bin` and the comparator bundle, and not which workflow or commit produced it. Those are a different class — supply-chain provenance rather than operator error — and want their own slice. --- proof/region/v1/corpus_dispatch.py | 85 +++++++-- proof/region/v1/tests/test_corpus_dispatch.py | 174 +++++++++++++++++- .../v1/tests/test_verification_dispatch.py | 3 - 3 files changed, 237 insertions(+), 25 deletions(-) diff --git a/proof/region/v1/corpus_dispatch.py b/proof/region/v1/corpus_dispatch.py index 1926bab4..17ce02d3 100644 --- a/proof/region/v1/corpus_dispatch.py +++ b/proof/region/v1/corpus_dispatch.py @@ -7,8 +7,10 @@ cover [0, 2^24) exactly, with every seam landing on the packing alignment and on a shard boundary — and turns it into one `gh workflow run` invocation per lane of `full-domain-corpus.yml`. Widths that cannot produce an exact -aligned cover are typed rejections before any dispatch exists; `--dry-run` -prints every dispatch command without touching the network. +aligned cover are typed rejections before any dispatch exists. Printing the +commands is the default and dispatching is the opt-in `--execute`, which has +to name the campaign's size: the incident this coordinator exists to prevent +was a forgotten flag turning one mistake into 133 runs. """ from __future__ import annotations @@ -210,12 +212,36 @@ def gh_run_artifacts_v1(run_id: int) -> tuple[tuple[str, bool], ...]: text=True, check=True, ) + return parse_artifact_listing_v1(completed.stdout) + + +def parse_artifact_listing_v1(stdout: str) -> tuple[tuple[str, bool], ...]: + """Decode the artifact listing wire form into names and expiry. + + Reading `expired` is a rule like any other, so it lives here rather than + behind the network where nothing can reach it. A listing that does not + look like the two-column form it is asked for raises: an unrecognised + line silently read as "live" would admit exactly the stale evidence run + the admission exists to refuse. + """ + observed: list[tuple[str, bool]] = [] - for line in completed.stdout.splitlines(): + for number, line in enumerate(stdout.splitlines(), 1): if not line.strip(): + # Blank separators carry no record; anything with content has to + # be exactly the requested shape. continue - name, _, expired = line.partition(" ") - observed.append((name.strip(), expired.strip().lower() == "true")) + fields = line.split("\t") + if len(fields) != 2: + raise ValueError(f"artifact listing line {number} is not two columns") + name, expired = fields[0].strip(), fields[1].strip().lower() + if not name: + raise ValueError(f"artifact listing line {number} has no name") + if expired not in ("true", "false"): + raise ValueError( + f"artifact listing line {number} has no boolean expiry: {expired!r}" + ) + observed.append((name, expired == "true")) return tuple(observed) @@ -280,9 +306,18 @@ def main(argv: list[str] | None = None) -> int: parser.add_argument("--shard-width", type=int, default=DEFAULT_SHARD_WIDTH) parser.add_argument("--evidence-run-id", type=int, default=None) parser.add_argument("--evidence-artifact", type=str, default=None) - parser.add_argument("--dry-run", action="store_true") + # Printing is the default and dispatching is the opt-in. The incident + # that made this coordinator dangerous was a forgotten `--dry-run`: a + # polarity where the safe run is the one you have to remember turns one + # missing flag into hundreds of runs. `--expect-lanes` makes the operator + # state the scale before it happens, so a mistyped width is refused + # instead of dispatched — swapping the two widths is a realistic slip and + # silently means tens of thousands of jobs. + parser.add_argument("--execute", action="store_true") + parser.add_argument("--expect-lanes", type=int, default=None) parser.add_argument("--out", type=Path, required=True) args = parser.parse_args(argv) + dispatching = args.execute and args.mode != "plan" plan = lane_plan_v1(args.lane_width, args.shard_width) if type(plan) is not tuple: @@ -323,7 +358,7 @@ def main(argv: list[str] | None = None) -> int: args.evidence_run_id, args.evidence_artifact, ) - if type(commands) is tuple and not args.dry_run: + if type(commands) is tuple and dispatching: # Fail closed before the first dispatch: a dry run stays offline # by contract, so the observation belongs to the live path only. refusal = admit_evidence_artifact_v1( @@ -340,13 +375,37 @@ def main(argv: list[str] | None = None) -> int: # TypeError at the boundary it is supposed to guard. print(f"lane dispatch rejected: {commands!r}", file=sys.stderr) return 64 + if not dispatching: + for command in commands: + print(" ".join(command)) + return 0 + if args.expect_lanes != len(commands): + # The operator has to name the scale, and reality has to agree. A + # width typed one token wrong produces a different campaign, and the + # only cheap moment to notice is before the first invocation. + print( + f"dispatch refused: --expect-lanes={args.expect_lanes} but the plan" + f" has {len(commands)} lanes", + file=sys.stderr, + ) + return 64 + print(f"dispatching {len(commands)} lanes", file=sys.stderr) + launched = 0 for command in commands: - rendered = " ".join(command) - if args.dry_run: - print(rendered) - continue - subprocess.run(command, check=True) - print(rendered) + try: + subprocess.run(command, check=True) + except subprocess.CalledProcessError as error: + # A campaign that dies mid-flight leaves runs already created. + # Reporting where it stopped is what makes the retry resumable + # instead of a duplicate of everything already dispatched. + print( + f"dispatch stopped after {launched} of {len(commands)} lanes:" + f" {str(getattr(error, 'stderr', None) or error).strip()}", + file=sys.stderr, + ) + return 64 + launched += 1 + print(" ".join(command)) return 0 diff --git a/proof/region/v1/tests/test_corpus_dispatch.py b/proof/region/v1/tests/test_corpus_dispatch.py index ab3dd8c2..98e7c072 100644 --- a/proof/region/v1/tests/test_corpus_dispatch.py +++ b/proof/region/v1/tests/test_corpus_dispatch.py @@ -6,12 +6,14 @@ plan whose windows cover [0, 2^24) exactly — contiguous, packing-aligned, no gaps, no overlaps — and must turn that plan into one `gh workflow run` invocation per lane. Any width that cannot produce an exact aligned cover -is a typed rejection before any dispatch exists, and a dry run must emit -the dispatch commands without touching the network. +is a typed rejection before any dispatch exists. Printing the commands is +the default and dispatching is the opt-in: the incident this coordinator +exists to prevent was a forgotten flag. """ from __future__ import annotations +import inspect import json import subprocess import sys @@ -141,7 +143,6 @@ def boom(*args: object, **kwargs: object) -> None: "1024", "--shard-width", "256", - "--dry-run", "--out", out, ] @@ -188,7 +189,7 @@ def test_invalid_widths_exit_64_before_any_dispatch(self) -> None: ["--mode", "plan", "--lane-width", "65536", "--shard-width", "12288", "--out", out], ["--mode", "dispatch", "--lane-width", "0", "--shard-width", - "256", "--dry-run", "--out", out], + "256", "--out", out], ) for argv in invalid: self.assertEqual(corpus_dispatch.main(argv), 64, argv) @@ -279,6 +280,80 @@ def observer(run_id: int): self.assertEqual(seen, [99]) +class ArtifactListingWireTests(unittest.TestCase): + """Reading `expired` off the wire is a rule, and rules get tests. + + Moving the expiry filter out of the query put the decision where a test + can reach it, but the decoding that produces `expired` stayed behind the + network — so a listing whose shape drifted read as "live" and admitted a + stale run. The captured form below is what `gh` actually emits for the + query this module sends. + """ + + CAPTURED_V1 = ( + "verification-evidence-arb\tfalse\n" + "verification-evidence-mpfi\tfalse\n" + "corpus-lane-0-65536\ttrue\n" + ) + + def test_the_captured_wire_form_decodes_to_names_and_expiry(self) -> None: + self.assertEqual( + corpus_dispatch.parse_artifact_listing_v1(self.CAPTURED_V1), + ( + ("verification-evidence-arb", False), + ("verification-evidence-mpfi", False), + ("corpus-lane-0-65536", True), + ), + ) + + def test_an_unrecognised_line_refuses_instead_of_reading_as_live(self) -> None: + for hostile in ( + "verification-evidence-arb\n", + "verification-evidence-arb\tfalse\textra\n", + "\tfalse\n", + "verification-evidence-arb\tno\n", + "verification-evidence-arb\t\n", + "verification-evidence-arb\t1\n", + ): + with self.subTest(hostile=hostile): + with self.assertRaises(ValueError): + corpus_dispatch.parse_artifact_listing_v1(hostile) + + def test_an_unreadable_listing_becomes_a_typed_refusal(self) -> None: + # The decode raises; the admission is what turns that into a refusal, + # so the two are proven together rather than separately assumed. + def observer(_run_id: int) -> tuple[tuple[str, bool], ...]: + return corpus_dispatch.parse_artifact_listing_v1("garbage\n") + + result = corpus_dispatch.admit_evidence_artifact_v1( + 1, "verification-evidence-arb", observer + ) + self.assertIs(type(result), corpus.ShardCorpusRejectedV1) + + def test_the_refusal_carries_the_text_that_tells_causes_apart(self) -> None: + # `repr` of a CalledProcessError drops stderr, and stderr is the only + # place "no such run" reads differently from "no token". Without it + # the operator debugs the wrong axis — which is what the refusal is + # supposed to prevent. + def observer(_run_id: int) -> tuple[tuple[str, bool], ...]: + raise subprocess.CalledProcessError( + 1, "gh", stderr="gh: Not Found (HTTP 404)" + ) + + result = corpus_dispatch.admit_evidence_artifact_v1( + 99999999, "verification-evidence-arb", observer + ) + self.assertIs(type(result), corpus.ShardCorpusRejectedV1) + self.assertIn("Not Found", result.detail) + + def test_the_query_stays_paginated(self) -> None: + # A run carrying more than one page of artifacts would otherwise lose + # the evidence name and refuse a healthy campaign. + source = inspect.getsource(corpus_dispatch.gh_run_artifacts_v1) + self.assertIn("--paginate", source) + self.assertIn("(.expired // false)", source) + + class DispatchSeamTests(unittest.TestCase): """The gate has to be wired in, not merely defined. @@ -289,8 +364,8 @@ class DispatchSeamTests(unittest.TestCase): admission must let it through. """ - def _argv(self, out: Path) -> list[str]: - return [ + def _argv(self, out: Path, *, live: bool = True) -> list[str]: + argv = [ "--mode", "verification-dispatch", "--evidence-run-id", @@ -300,6 +375,9 @@ def _argv(self, out: Path) -> list[str]: "--out", str(out), ] + # Dispatching is the opt-in, and the scale is declared with it: the + # seam only exists on the live path. + return [*argv, "--execute", "--expect-lanes", "256"] if live else argv def test_a_refused_evidence_run_dispatches_nothing(self) -> None: launched: list[tuple[str, ...]] = [] @@ -350,6 +428,84 @@ class _Completed: all(command[:3] == ("gh", "workflow", "run") for command in launched) ) + def test_the_admission_asks_about_the_artifact_the_operator_named(self) -> None: + # Mirror of the run-id pin: an observer blind to the artifact lets a + # mutant hardcode one engine's name at the call site and stay green. + # The producer runs the two engines as independent jobs, so a run + # really can carry one artifact and not the other — and admitting the + # wrong one buys 256 doomed lanes, which is the incident again. + launched: list[tuple[str, ...]] = [] + argv = [ + "--mode", + "verification-dispatch", + "--evidence-run-id", + "424242", + "--evidence-artifact", + "verification-evidence-mpfi", + "--out", + ] + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: (("verification-evidence-arb", False),), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: launched.append(tuple(command)), + ): + code = corpus_dispatch.main( + [ + *argv, + str(Path(tmp) / "out.txt"), + "--execute", + "--expect-lanes", + "256", + ] + ) + self.assertEqual(code, 64) + self.assertEqual(launched, []) + + def test_a_campaign_of_an_unexpected_size_is_refused_before_it_starts( + self, + ) -> None: + # Swapping the two widths is a realistic slip and silently means a + # different campaign; the operator declares the scale so reality can + # disagree out loud. + launched: list[tuple[str, ...]] = [] + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: (("verification-evidence-arb", False),), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: launched.append(tuple(command)), + ): + argv = self._argv(Path(tmp) / "out.txt", live=False) + code = corpus_dispatch.main( + [*argv, "--execute", "--expect-lanes", "16"] + ) + self.assertEqual(code, 64) + self.assertEqual(launched, []) + + def test_without_execute_the_campaign_only_prints(self) -> None: + # The polarity is the guard: the incident was a forgotten flag, so + # forgetting one now costs nothing. + launched: list[tuple[str, ...]] = [] + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: launched.append(tuple(command)), + ): + code = corpus_dispatch.main( + self._argv(Path(tmp) / "out.txt", live=False) + ) + self.assertEqual(code, 0) + self.assertEqual(launched, []) + def test_a_dry_run_stays_offline_and_asks_nobody(self) -> None: # The dry run is documented as offline: it must not even observe. observed: list[int] = [] @@ -365,7 +521,7 @@ def test_a_dry_run_stays_offline_and_asks_nobody(self) -> None: lambda command, **kwargs: launched.append(tuple(command)), ): code = corpus_dispatch.main( - self._argv(Path(tmp) / "out.txt") + ["--dry-run"] + self._argv(Path(tmp) / "out.txt", live=False) ) self.assertEqual(code, 0) self.assertEqual(observed, []) @@ -376,9 +532,9 @@ def test_a_rejected_command_set_is_exit_64_not_a_type_error(self) -> None: # refusal must leave through the typed exit, never as a TypeError # raised by iterating a rejection. with tempfile.TemporaryDirectory() as tmp: - argv = self._argv(Path(tmp) / "out.txt") + argv = self._argv(Path(tmp) / "out.txt", live=False) argv[argv.index("verification-evidence-arb")] = "verification-evidence-foreign" - code = corpus_dispatch.main(argv + ["--dry-run"]) + code = corpus_dispatch.main(argv) self.assertEqual(code, 64) diff --git a/proof/region/v1/tests/test_verification_dispatch.py b/proof/region/v1/tests/test_verification_dispatch.py index 8cc7dfc6..c6961d6a 100644 --- a/proof/region/v1/tests/test_verification_dispatch.py +++ b/proof/region/v1/tests/test_verification_dispatch.py @@ -161,7 +161,6 @@ def test_dry_run_prints_one_command_per_lane(self) -> None: "31000000001", "--evidence-artifact", ARB_ARTIFACT, - "--dry-run", "--out", str(Path(tmp) / "out"), ] @@ -182,7 +181,6 @@ def test_missing_evidence_run_id_exits_64(self) -> None: "verification-dispatch", "--evidence-artifact", ARB_ARTIFACT, - "--dry-run", "--out", str(Path(tmp) / "out"), ] @@ -197,7 +195,6 @@ def test_missing_evidence_artifact_exits_64(self) -> None: "verification-dispatch", "--evidence-run-id", "31000000001", - "--dry-run", "--out", str(Path(tmp) / "out"), ] From ebb08dd611aba1df2f3e7a9b8b8b9705e1c202f5 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Thu, 6 Aug 2026 22:12:16 +0300 Subject: [PATCH 5/7] Proof: pin the two new handles, and the coordinate whose test claimed it was pinned MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A third review ran fifteen mutants against the previous commit; nine survived, and all but one lived in the code that commit added. The polarity change and the partial-failure report were shipped without a single test that could hold them. THE RUN ID. All three seam tests take the run id from one helper that hardcodes 424242, so a call site hardcoding that same number was indistinguishable from one that reads the argument — while the test's own comment claimed the opposite in as many words. The mirror axis was fixed last round and this one left standing. A seam test now names a different run and records what the observer was actually asked. THE DECLARED SCALE. Making `--expect-lanes` optional survived every test, because falling through to the mismatch comparison refuses too — with a message that tells the operator nothing. It has its own refusal now, and the test reads the message rather than only the exit code: the two differ exactly where the operator does. THE PARTIAL FAILURE. Deleting the whole handler, returning 0 mid-campaign, or moving the counter before the call all stayed green. The count is the point — a retry that cannot tell three from zero duplicates everything already dispatched — so the test now reads "after 3 of 256" out of the report. The handler also catches OSError: a missing `gh` abandoned a campaign with a traceback and no count. ORDER. The authenticated observation ran before the free local check, so a mistyped width spent an API call and answered with a diagnosis about the evidence run. The cheap refusals come first now, which is what the comment claimed all along. `--mode plan --execute` was a silent no-op: a flag with live semantics that is quietly ignored is worse than one that refuses, because the operator believes a campaign started. `--paginate` was checked by reading the function's source, which a mutant that drops the flag from argv and leaves the word in a comment passes untouched. The check is behavioural now — it asserts the argv actually built, plus `check` and `capture_output`, which the source read never saw. Names that referred to the removed flag are gone; only the comment recounting the incident still says `--dry-run`, which is history and stays. Every repair is proven by the mutant it kills, each failing exactly one test: the hardcoded run id, the optional scale, the vanished counter, `return 0` mid-campaign, the ignored `--execute` in plan mode, and `--paginate` demoted to a comment. Verified: 282 local tests, 7 errors — the exact Windows baseline. --- proof/region/v1/corpus_dispatch.py | 57 ++++-- proof/region/v1/tests/test_corpus_dispatch.py | 176 +++++++++++++++++- .../v1/tests/test_verification_dispatch.py | 2 +- 3 files changed, 209 insertions(+), 26 deletions(-) diff --git a/proof/region/v1/corpus_dispatch.py b/proof/region/v1/corpus_dispatch.py index 17ce02d3..be26e514 100644 --- a/proof/region/v1/corpus_dispatch.py +++ b/proof/region/v1/corpus_dispatch.py @@ -317,7 +317,13 @@ def main(argv: list[str] | None = None) -> int: parser.add_argument("--expect-lanes", type=int, default=None) parser.add_argument("--out", type=Path, required=True) args = parser.parse_args(argv) - dispatching = args.execute and args.mode != "plan" + if args.execute and args.mode == "plan": + # A flag with live semantics must never be silently ignored: an + # operator who believes a campaign started is worse off than one who + # is told it did not. + print("plan mode cannot dispatch: drop --execute", file=sys.stderr) + return 64 + dispatching = args.execute plan = lane_plan_v1(args.lane_width, args.shard_width) if type(plan) is not tuple: @@ -358,15 +364,6 @@ def main(argv: list[str] | None = None) -> int: args.evidence_run_id, args.evidence_artifact, ) - if type(commands) is tuple and dispatching: - # Fail closed before the first dispatch: a dry run stays offline - # by contract, so the observation belongs to the live path only. - refusal = admit_evidence_artifact_v1( - args.evidence_run_id, args.evidence_artifact - ) - if refusal is not None: - print(f"verification dispatch refused: {refusal.detail}", file=sys.stderr) - return 64 else: commands = dispatch_commands_v1(plan, args.shard_width) if type(commands) is not tuple: @@ -379,28 +376,58 @@ def main(argv: list[str] | None = None) -> int: for command in commands: print(" ".join(command)) return 0 + if args.expect_lanes is None: + # Its own refusal, not a comparison against `None`: the operator who + # forgot the flag has to read what is missing, not a mismatch. + print( + "dispatch refused: --execute requires --expect-lanes", + file=sys.stderr, + ) + return 64 if args.expect_lanes != len(commands): - # The operator has to name the scale, and reality has to agree. A - # width typed one token wrong produces a different campaign, and the - # only cheap moment to notice is before the first invocation. + # The operator names the scale and reality has to agree. A width + # typed one token wrong produces a different campaign, and this is + # the cheap moment to notice — before anything is observed or run. print( f"dispatch refused: --expect-lanes={args.expect_lanes} but the plan" f" has {len(commands)} lanes", file=sys.stderr, ) return 64 + if args.mode == "verification-dispatch": + # Fail closed before the first dispatch, and only here: the printing + # path stays offline by contract, and this observation costs an + # authenticated call that a mistyped width should never spend. + refusal = admit_evidence_artifact_v1( + args.evidence_run_id, args.evidence_artifact + ) + if refusal is not None: + print(f"verification dispatch refused: {refusal.detail}", file=sys.stderr) + return 64 print(f"dispatching {len(commands)} lanes", file=sys.stderr) launched = 0 for command in commands: try: subprocess.run(command, check=True) + except OSError as error: + # Not only CalledProcessError: a missing `gh`, an exhausted file + # descriptor or a killed child all abandon a campaign mid-flight, + # and all of them must leave the same resumable report. + print( + f"dispatch stopped after {launched} of {len(commands)} lanes:" + f" {str(error).strip()}", + file=sys.stderr, + ) + return 64 except subprocess.CalledProcessError as error: # A campaign that dies mid-flight leaves runs already created. # Reporting where it stopped is what makes the retry resumable - # instead of a duplicate of everything already dispatched. + # instead of a duplicate of everything already dispatched. The + # child's stderr is not captured here on purpose — it belongs on + # the operator's terminal — so only the exit status is quotable. print( f"dispatch stopped after {launched} of {len(commands)} lanes:" - f" {str(getattr(error, 'stderr', None) or error).strip()}", + f" {str(error).strip()}", file=sys.stderr, ) return 64 diff --git a/proof/region/v1/tests/test_corpus_dispatch.py b/proof/region/v1/tests/test_corpus_dispatch.py index 98e7c072..cfae9aa7 100644 --- a/proof/region/v1/tests/test_corpus_dispatch.py +++ b/proof/region/v1/tests/test_corpus_dispatch.py @@ -13,7 +13,8 @@ from __future__ import annotations -import inspect +import contextlib +import io import json import subprocess import sys @@ -123,13 +124,13 @@ def test_dispatch_commands_reject_a_rejected_plan(self) -> None: self.assertIs(type(result), corpus.ShardCorpusRejectedV1) -class DryRunTests(unittest.TestCase): - def test_dry_run_never_touches_the_network(self) -> None: +class DefaultIsPrintingTests(unittest.TestCase): + def test_the_default_run_never_touches_the_network(self) -> None: calls: list[list[str]] = [] def boom(*args: object, **kwargs: object) -> None: calls.append([args, kwargs]) - raise AssertionError("dry run must not invoke subprocess") + raise AssertionError("printing must not invoke subprocess") original = subprocess.run subprocess.run = boom # type: ignore[assignment] @@ -346,12 +347,36 @@ def observer(_run_id: int) -> tuple[tuple[str, bool], ...]: self.assertIs(type(result), corpus.ShardCorpusRejectedV1) self.assertIn("Not Found", result.detail) - def test_the_query_stays_paginated(self) -> None: + def test_the_query_asks_for_every_page_and_for_expiry(self) -> None: + # Behavioural, not a look at the source: a mutant that drops the flag + # from argv while leaving the words in a comment reads identically. # A run carrying more than one page of artifacts would otherwise lose # the evidence name and refuse a healthy campaign. - source = inspect.getsource(corpus_dispatch.gh_run_artifacts_v1) - self.assertIn("--paginate", source) - self.assertIn("(.expired // false)", source) + seen: list[tuple[str, ...]] = [] + + class _Completed: + stdout = "verification-evidence-arb\tfalse\n" + returncode = 0 + + def record(command: tuple[str, ...], **kwargs: object) -> object: + seen.append(tuple(command)) + assert kwargs.get("check") is True + assert kwargs.get("capture_output") is True + return _Completed() + + with unittest.mock.patch.object(corpus_dispatch.subprocess, "run", record): + observed = corpus_dispatch.gh_run_artifacts_v1(31116022208) + + self.assertEqual(observed, (("verification-evidence-arb", False),)) + self.assertEqual(len(seen), 1) + argv = seen[0] + self.assertEqual(argv[:3], ("gh", "api", "--paginate")) + self.assertIn("repos/{owner}/{repo}/actions/runs/31116022208/artifacts", argv) + self.assertIn("--jq", argv) + self.assertIn( + ".artifacts[] | [.name, (.expired // false)] | @tsv", + argv[argv.index("--jq") + 1], + ) class DispatchSeamTests(unittest.TestCase): @@ -506,8 +531,139 @@ def test_without_execute_the_campaign_only_prints(self) -> None: self.assertEqual(code, 0) self.assertEqual(launched, []) - def test_a_dry_run_stays_offline_and_asks_nobody(self) -> None: - # The dry run is documented as offline: it must not even observe. + def test_the_admission_asks_about_the_run_the_operator_named(self) -> None: + # The other seam tests all pass 424242, so a call site that hardcoded + # that very number would be indistinguishable from one that reads the + # argument. This one names a different run and records what the + # observer was actually asked. + observed: list[int] = [] + launched: list[tuple[str, ...]] = [] + + class _Completed: + returncode = 0 + + with tempfile.TemporaryDirectory() as tmp: + argv = self._argv(Path(tmp) / "out.txt") + argv[argv.index("424242")] = "31116022208" + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: ( + observed.append(run_id) + or (("verification-evidence-arb", False),) + ), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: ( + launched.append(tuple(command)) or _Completed() + ), + ): + code = corpus_dispatch.main(argv) + self.assertEqual(code, 0) + self.assertEqual(observed, [31116022208]) + self.assertEqual(len(launched), 256) + + def test_execute_without_a_declared_scale_dispatches_nothing(self) -> None: + # The scale declaration is the guard, so it has to be required — an + # optional one restores the forgotten-flag class it replaced. + launched: list[tuple[str, ...]] = [] + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: (("verification-evidence-arb", False),), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: launched.append(tuple(command)), + ): + argv = self._argv(Path(tmp) / "out.txt", live=False) + errors = io.StringIO() + with contextlib.redirect_stderr(errors): + code = corpus_dispatch.main([*argv, "--execute"]) + self.assertEqual(code, 64) + self.assertEqual(launched, []) + # The refusal has to name what is missing: falling through to the + # mismatch comparison refuses too, and tells the operator nothing. + self.assertIn("--expect-lanes", errors.getvalue()) + self.assertNotIn("but the plan has", errors.getvalue()) + + def test_a_wrong_scale_is_refused_before_the_network_is_asked(self) -> None: + # The cheap local check must precede the authenticated call: a + # mistyped width should not spend one, and the operator should read + # "wrong scale" rather than a diagnosis about the evidence run. + observed: list[int] = [] + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: observed.append(run_id) or (), + ): + argv = self._argv(Path(tmp) / "out.txt", live=False) + code = corpus_dispatch.main( + [*argv, "--execute", "--expect-lanes", "16"] + ) + self.assertEqual(code, 64) + self.assertEqual(observed, []) + + def test_plan_mode_refuses_execute_instead_of_ignoring_it(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + code = corpus_dispatch.main( + ["--mode", "plan", "--out", tmp, "--execute", "--expect-lanes", "256"] + ) + self.assertEqual(code, 64) + + def test_a_campaign_that_dies_reports_how_far_it_got(self) -> None: + # Without this the failure is a traceback: the operator cannot tell a + # retry from a duplicate of everything already dispatched. + launched: list[tuple[str, ...]] = [] + + class _Completed: + returncode = 0 + + def flaky(command: tuple[str, ...], **_kwargs: object) -> object: + if len(launched) == 3: + raise subprocess.CalledProcessError(1, list(command)) + launched.append(tuple(command)) + return _Completed() + + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: (("verification-evidence-arb", False),), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, "run", flaky + ): + errors = io.StringIO() + with contextlib.redirect_stderr(errors): + code = corpus_dispatch.main(self._argv(Path(tmp) / "out.txt")) + self.assertEqual(code, 64) + # Exactly the ones that succeeded, and no further attempt after. + self.assertEqual(len(launched), 3) + # The count is the whole point: a retry that cannot tell 3 from 0 + # duplicates everything already dispatched. + self.assertIn("after 3 of 256", errors.getvalue()) + + def test_a_missing_gh_is_a_typed_stop_not_a_traceback(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: (("verification-evidence-arb", False),), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: (_ for _ in ()).throw( + FileNotFoundError("gh") + ), + ): + code = corpus_dispatch.main(self._argv(Path(tmp) / "out.txt")) + self.assertEqual(code, 64) + + def test_printing_stays_offline_and_asks_nobody(self) -> None: + # Printing is documented as offline: it must not even observe. observed: list[int] = [] launched: list[tuple[str, ...]] = [] with tempfile.TemporaryDirectory() as tmp: diff --git a/proof/region/v1/tests/test_verification_dispatch.py b/proof/region/v1/tests/test_verification_dispatch.py index c6961d6a..40869e50 100644 --- a/proof/region/v1/tests/test_verification_dispatch.py +++ b/proof/region/v1/tests/test_verification_dispatch.py @@ -147,7 +147,7 @@ def test_foreign_evidence_artifact_is_a_typed_rejection(self) -> None: class VerificationDispatchCliTests(unittest.TestCase): - def test_dry_run_prints_one_command_per_lane(self) -> None: + def test_the_default_prints_one_command_per_lane(self) -> None: with tempfile.TemporaryDirectory() as tmp: stdout = io.StringIO() with redirect_stdout(stdout): From f7d087554eb48bd181ed45b27b5d9bd4708a3cf8 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Fri, 7 Aug 2026 09:03:20 +0300 Subject: [PATCH 6/7] Proof: the observation carries a deadline CodeRabbit's remark stands: a hung `gh` stalled the coordinator forever on the one call between an operator and 256 dispatches, indistinguishable from work in progress. The listing now times out, the admission already turns every observation failure into a typed refusal, and the wire test pins the deadline the same way it pins `check` and `capture_output`. Proven by the mutant: removing the timeout reddens exactly that test. Verified: 34 dispatch tests pass. --- proof/region/v1/corpus_dispatch.py | 8 ++++++++ proof/region/v1/tests/test_corpus_dispatch.py | 4 ++++ 2 files changed, 12 insertions(+) diff --git a/proof/region/v1/corpus_dispatch.py b/proof/region/v1/corpus_dispatch.py index be26e514..b92bd2b3 100644 --- a/proof/region/v1/corpus_dispatch.py +++ b/proof/region/v1/corpus_dispatch.py @@ -42,6 +42,9 @@ DEFAULT_SHARD_WIDTH = corpus_lane.DEFAULT_SHARD_POINTS FULL_DOMAIN = protocol.OUTPUT_CARDINALITY_V1 ALIGNMENT = corpus.CORPUS_SHARD_ALIGNMENT_V1 +# One listing of one run: generous for a slow network, far short of a wait an +# operator would mistake for work in progress. +OBSERVATION_TIMEOUT_SECONDS_V1 = 60 def lane_plan_v1( @@ -211,6 +214,11 @@ def gh_run_artifacts_v1(run_id: int) -> tuple[tuple[str, bool], ...]: capture_output=True, text=True, check=True, + # A hung observation is worse than a refused one: without a deadline + # the coordinator waits forever on the one call standing between an + # operator and 256 dispatches. The timeout raises, and the admission + # turns every observation failure into a typed refusal. + timeout=OBSERVATION_TIMEOUT_SECONDS_V1, ) return parse_artifact_listing_v1(completed.stdout) diff --git a/proof/region/v1/tests/test_corpus_dispatch.py b/proof/region/v1/tests/test_corpus_dispatch.py index cfae9aa7..edc9faab 100644 --- a/proof/region/v1/tests/test_corpus_dispatch.py +++ b/proof/region/v1/tests/test_corpus_dispatch.py @@ -362,6 +362,10 @@ def record(command: tuple[str, ...], **kwargs: object) -> object: seen.append(tuple(command)) assert kwargs.get("check") is True assert kwargs.get("capture_output") is True + # A hung `gh` would otherwise stall the one call standing between + # an operator and 256 dispatches, with nothing to distinguish it + # from work in progress. + assert kwargs.get("timeout") == corpus_dispatch.OBSERVATION_TIMEOUT_SECONDS_V1 return _Completed() with unittest.mock.patch.object(corpus_dispatch.subprocess, "run", record): From a47996fd1afab12a78050aa946ac8c00a6f6abc4 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Fri, 7 Aug 2026 09:46:47 +0300 Subject: [PATCH 7/7] Proof: close the two review threads, and the one direction the scale check missed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both CodeRabbit threads were right and are closed in code rather than argued. The two exception handlers had byte-identical bodies split only to carry two comments; one handler now catches both and one comment covers every way a campaign dies mid-flight. The stub's asserts would vanish under PYTHONOPTIMIZE=2 — and the CI worker runs this suite under exactly that — so the kwargs are recorded and asserted outside the stub, where the optimizer cannot delete them. The merge gate's surviving mutant is dead too: weakening the scale check from `!=` to `<` passed every test, meaning an operator declaring 512 lanes over a 256-lane plan would dispatch silently. A declaration that does not match reality is a wrong mental model regardless of its sign, and the new test pins the direction nothing else looked at. Verified: 35 dispatch tests pass, and pass again under PYTHONOPTIMIZE=2; the `<` mutant reddens exactly the new test. --- proof/region/v1/corpus_dispatch.py | 24 ++++------- proof/region/v1/tests/test_corpus_dispatch.py | 43 ++++++++++++++++--- 2 files changed, 45 insertions(+), 22 deletions(-) diff --git a/proof/region/v1/corpus_dispatch.py b/proof/region/v1/corpus_dispatch.py index b92bd2b3..4928baaf 100644 --- a/proof/region/v1/corpus_dispatch.py +++ b/proof/region/v1/corpus_dispatch.py @@ -417,22 +417,14 @@ def main(argv: list[str] | None = None) -> int: for command in commands: try: subprocess.run(command, check=True) - except OSError as error: - # Not only CalledProcessError: a missing `gh`, an exhausted file - # descriptor or a killed child all abandon a campaign mid-flight, - # and all of them must leave the same resumable report. - print( - f"dispatch stopped after {launched} of {len(commands)} lanes:" - f" {str(error).strip()}", - file=sys.stderr, - ) - return 64 - except subprocess.CalledProcessError as error: - # A campaign that dies mid-flight leaves runs already created. - # Reporting where it stopped is what makes the retry resumable - # instead of a duplicate of everything already dispatched. The - # child's stderr is not captured here on purpose — it belongs on - # the operator's terminal — so only the exit status is quotable. + except (OSError, subprocess.CalledProcessError) as error: + # A campaign that dies mid-flight leaves runs already created, and + # every way it can die — a nonzero `gh`, a missing binary, an + # exhausted descriptor, a killed child — must leave the same + # resumable report: without the count a retry duplicates + # everything already dispatched. The child's stderr is not + # captured on purpose — it belongs on the operator's terminal — + # so only the exit status is quotable. print( f"dispatch stopped after {launched} of {len(commands)} lanes:" f" {str(error).strip()}", diff --git a/proof/region/v1/tests/test_corpus_dispatch.py b/proof/region/v1/tests/test_corpus_dispatch.py index edc9faab..79e73403 100644 --- a/proof/region/v1/tests/test_corpus_dispatch.py +++ b/proof/region/v1/tests/test_corpus_dispatch.py @@ -353,19 +353,18 @@ def test_the_query_asks_for_every_page_and_for_expiry(self) -> None: # A run carrying more than one page of artifacts would otherwise lose # the evidence name and refuse a healthy campaign. seen: list[tuple[str, ...]] = [] + kwargs_seen: list[dict] = [] class _Completed: stdout = "verification-evidence-arb\tfalse\n" returncode = 0 + # Recorded and asserted outside the stub: `assert` inside it would + # vanish under PYTHONOPTIMIZE=2, and the CI worker runs the suite + # under exactly that. def record(command: tuple[str, ...], **kwargs: object) -> object: seen.append(tuple(command)) - assert kwargs.get("check") is True - assert kwargs.get("capture_output") is True - # A hung `gh` would otherwise stall the one call standing between - # an operator and 256 dispatches, with nothing to distinguish it - # from work in progress. - assert kwargs.get("timeout") == corpus_dispatch.OBSERVATION_TIMEOUT_SECONDS_V1 + kwargs_seen.append(dict(kwargs)) return _Completed() with unittest.mock.patch.object(corpus_dispatch.subprocess, "run", record): @@ -373,6 +372,15 @@ def record(command: tuple[str, ...], **kwargs: object) -> object: self.assertEqual(observed, (("verification-evidence-arb", False),)) self.assertEqual(len(seen), 1) + self.assertIs(kwargs_seen[0].get("check"), True) + self.assertIs(kwargs_seen[0].get("capture_output"), True) + # A hung `gh` would otherwise stall the one call standing between an + # operator and 256 dispatches, indistinguishable from work in + # progress. + self.assertEqual( + kwargs_seen[0].get("timeout"), + corpus_dispatch.OBSERVATION_TIMEOUT_SECONDS_V1, + ) argv = seen[0] self.assertEqual(argv[:3], ("gh", "api", "--paginate")) self.assertIn("repos/{owner}/{repo}/actions/runs/31116022208/artifacts", argv) @@ -519,6 +527,29 @@ def test_a_campaign_of_an_unexpected_size_is_refused_before_it_starts( self.assertEqual(code, 64) self.assertEqual(launched, []) + def test_an_overdeclared_scale_is_refused_too(self) -> None: + # The declaration must equal reality in both directions. Weakening + # `!=` to `<` survived every test: an operator declaring 512 where the + # plan holds 256 would dispatch silently, and a declaration that does + # not match is a wrong mental model regardless of its sign. + launched: list[tuple[str, ...]] = [] + with tempfile.TemporaryDirectory() as tmp: + with unittest.mock.patch.object( + corpus_dispatch, + "gh_run_artifacts_v1", + lambda run_id: (("verification-evidence-arb", False),), + ), unittest.mock.patch.object( + corpus_dispatch.subprocess, + "run", + lambda command, **kwargs: launched.append(tuple(command)), + ): + argv = self._argv(Path(tmp) / "out.txt", live=False) + code = corpus_dispatch.main( + [*argv, "--execute", "--expect-lanes", "512"] + ) + self.assertEqual(code, 64) + self.assertEqual(launched, []) + def test_without_execute_the_campaign_only_prints(self) -> None: # The polarity is the guard: the incident was a forgotten flag, so # forgetting one now costs nothing.