fix: harden pr264 projection repair contract

Author: PLeVasseur

.github/workflows/reviewer-bot-sweeper-repair.yml

@@ -19,7 +19,7 @@ on:
         type: string
       validation_nonce:
         description: Validation nonce used to correlate this repair run
-        required: false
+        required: true
         type: string
 
 permissions:

scripts/reviewer_bot_core/reviewer_response_policy.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import datetime, timezone
 
 from . import live_review_support, reviewer_review_helpers
@@ -173,11 +173,16 @@ def apply_reminder_cadence_overlay(response: ReviewerResponseDecision, cadence)
     if response.response_state != "awaiting_reviewer_response":
         return response
     reason = getattr(cadence, "exhaustion_reason", None) or "legacy_duplicate_reminders_exhausted"
+    scope = (
+        replace(response.scope, scope_basis="reminder_cadence_exhausted")
+        if response.scope is not None
+        else None
+    )
     return ReviewerResponseDecision(
         response_state="reviewer_reassignment_needed",
         reason=reason,
         suppression_reason=reason,
-        scope=response.scope,
+        scope=scope,
         current_head_sha=response.current_head_sha,
         anchor_timestamp=response.anchor_timestamp,
         reviewer_authority_outcome=response.reviewer_authority_outcome,

scripts/reviewer_bot_lib/app.py

@@ -558,6 +558,8 @@ def execute_run(bot: AppExecutionRuntime, context: EventContext) -> ExecutionRes
             if touched_items:
                 state = bot.state_store.load_state(fail_on_unavailable=True)
 
+        maintenance.emit_pending_issue314_state_health_repair_summary(bot)
+
         if touched_items:
             if not lock_acquired:
                 raise RuntimeError(

scripts/reviewer_bot_lib/issue314_state_health.py

@@ -19,6 +19,66 @@
     actual_status_labels_from_snapshot,
 )
 
+_REQUIRED_IDENTITY_FIELDS = (
+    "validation_nonce",
+    "evaluated_repo",
+    "head_sha",
+    "evaluated_ref",
+    "workflow_path",
+    "run_id",
+    "run_attempt",
+)
+_SUPPORTED_ACTION_WORKFLOWS = {
+    "preview-issue314-state-health": ".github/workflows/reviewer-bot-preview.yml",
+    "repair-issue314-state-health": ".github/workflows/reviewer-bot-sweeper-repair.yml",
+}
+_SUPPORTED_REPAIR_RESULTS = frozenset({"already_healthy", "changed", "blocked"})
+
+
+def _missing_identity_fields(values: dict[str, object]) -> tuple[str, ...]:
+    return tuple(
+        sorted(
+            name
+            for name in _REQUIRED_IDENTITY_FIELDS
+            if not isinstance(values.get(name), str) or not str(values.get(name)).strip()
+        )
+    )
+
+
+def _require_identity(values: dict[str, object], *, reason: str) -> None:
+    missing = _missing_identity_fields(values)
+    if missing:
+        raise RuntimeError(f"issue314_state_health_identity_blocked:{reason}:" + ",".join(missing))
+
+
+def _require_request_identity(request: "Issue314StateHealthRepairRequest") -> None:
+    expected_workflow = _SUPPORTED_ACTION_WORKFLOWS.get(request.repair_action)
+    if expected_workflow is None:
+        raise RuntimeError("issue314_state_health_request_blocked:unsupported_action")
+    _require_identity(request.__dict__, reason="missing")
+    if request.workflow_path != expected_workflow:
+        raise RuntimeError("issue314_state_health_request_blocked:workflow_path")
+
+
+def _require_repair_summary_contract(summary: "Issue314StateHealthRepairSummary") -> None:
+    _require_identity(summary.__dict__, reason="missing")
+    if summary.target_collection_mode != "global_issue314_state_health":
+        raise RuntimeError("issue314_state_health_repair_summary_blocked:target_collection_mode")
+    if summary.result not in _SUPPORTED_REPAIR_RESULTS:
+        raise RuntimeError("issue314_state_health_repair_summary_blocked:result")
+    if summary.reviewer_facing_reminder_posts_attempted != 0:
+        raise RuntimeError("issue314_state_health_repair_summary_blocked:reviewer_reminder_attempt")
+    if summary.manual_issue314_edit_status != "not_attempted":
+        raise RuntimeError("issue314_state_health_repair_summary_blocked:manual_issue314_edit")
+    if summary.rows_blocked and summary.result != "blocked":
+        raise RuntimeError("issue314_state_health_repair_summary_blocked:blocked_rows_success")
+    if set(summary.status_labels_changed) - set(summary.rows_repaired):
+        raise RuntimeError("issue314_state_health_repair_summary_blocked:final_label_only_status")
+    if summary.result == "already_healthy" and (
+        summary.rows_repaired or summary.rows_removed_closed or summary.status_labels_changed
+    ):
+        raise RuntimeError("issue314_state_health_repair_summary_blocked:changed_rows_marked_healthy")
+
 
 @dataclass(frozen=True)
 class Issue314StateHealthClassificationInput:
@@ -121,6 +181,7 @@ class Issue314StateHealthSummary:
     output_keys: tuple[str, ...]
 
     def to_output(self) -> dict[str, object]:
+        _require_identity(self.__dict__, reason="preview_output")
         payload: dict[str, object] = {
             "schema_version": self.schema_version,
             "preview_action": self.preview_action,
@@ -186,6 +247,7 @@ class Issue314StateHealthRepairSummary:
     result: str
 
     def to_output(self) -> dict[str, object]:
+        _require_repair_summary_contract(self)
         payload: dict[str, object] = {
             "schema_version": self.schema_version,
             "repair_action": self.repair_action,
@@ -285,6 +347,7 @@ def collect_issue314_state_health_input(
     request: Issue314StateHealthRepairRequest | None = None,
 ) -> Issue314StateHealthClassificationInput:
     request = request or _default_request(bot)
+    _require_request_identity(request)
     rows = _active_rows(state)
     snapshots: dict[int, dict[str, object]] = {}
     reviewer_responses: dict[int, ReviewerResponseDecision] = {}
@@ -293,8 +356,17 @@ def collect_issue314_state_health_input(
     for row in rows:
         issue_number = int(row["issue_number"])
         review_data = row["review_data"]
-        snapshot_result = bot.github.get_issue_or_pr_snapshot_result(issue_number)
-        snapshot = snapshot_result.payload if snapshot_result.ok and isinstance(snapshot_result.payload, dict) else None
+        try:
+            snapshot_result = bot.github.get_issue_or_pr_snapshot_result(issue_number)
+        except (AssertionError, AttributeError, RuntimeError):
+            snapshot_result = None
+        snapshot = (
+            snapshot_result.payload
+            if snapshot_result is not None
+            and snapshot_result.ok
+            and isinstance(snapshot_result.payload, dict)
+            else None
+        )
         if snapshot is not None:
             snapshots[issue_number] = snapshot
         scans[issue_number] = _comment_scan(bot, issue_number)
@@ -444,6 +516,7 @@ def _row_from_input(input: Issue314StateHealthClassificationInput, row: dict[str
 
 
 def classify_issue314_state_health(input: Issue314StateHealthClassificationInput) -> Issue314StateHealthSummary:
+    _require_identity(input.__dict__, reason="classification_input")
     inventory = tuple(_row_from_input(input, row) for row in input.active_review_rows)
     counts: dict[str, int] = {}
     for row in inventory:
@@ -520,6 +593,8 @@ def run_issue314_state_health_repair(
     state: dict,
     request: Issue314StateHealthRepairRequest,
 ) -> Issue314StateHealthRepairSummary:
+    _require_request_identity(request)
+    bot.assert_lock_held("run_issue314_state_health_repair")
     classification_input = collect_issue314_state_health_input(bot, state, request)
     summary = classify_issue314_state_health(classification_input)
     active_reviews = state.get("active_reviews") if isinstance(state, dict) else None

scripts/reviewer_bot_lib/maintenance.py

@@ -25,6 +25,7 @@
 
 ScheduleHandlerResult = maintenance_schedule.ScheduleHandlerResult
 SCHEDULE_LIKE_MANUAL_ACTIONS = frozenset({"check-overdue"})
+_PENDING_ISSUE314_REPAIR_SUMMARY_ATTR = "_reviewer_bot_pending_issue314_state_health_repair_summary"
 _now_iso = maintenance_privileged._now_iso
 _finalize_schedule_result = maintenance_schedule._finalize_schedule_result
 _record_maintenance_repair_marker = maintenance_schedule._record_maintenance_repair_marker
@@ -234,6 +235,14 @@ def _issue314_request(bot, request) -> issue314_state_health.Issue314StateHealth
     )
 
 
+def emit_pending_issue314_state_health_repair_summary(bot) -> None:
+    summary = getattr(bot, _PENDING_ISSUE314_REPAIR_SUMMARY_ATTR, None)
+    if summary is None:
+        return
+    issue314_state_health.emit_issue314_state_health_repair_summary(summary)
+    setattr(bot, _PENDING_ISSUE314_REPAIR_SUMMARY_ATTR, None)
+
+
 def derive_manual_dispatch_projection_policy(request) -> ManualDispatchProjectionPolicy:
     action = request.action or ""
     issue_number = request.issue_number if isinstance(request.issue_number, int) else None
@@ -296,49 +305,34 @@ def run_status_label_repair(bot, state: dict, request: StatusLabelRepairRequest)
     after: list[StatusLabelRepairItemResult] = []
     labels_added: set[str] = set()
     labels_removed: set[str] = set()
-    blocked = False
     for issue_number in targets:
-        try:
-            projection = reviews.project_status_label_projection_for_item(bot, issue_number, state)
-            delta = projection.delta
-            sync_result = reviews.apply_status_label_delta(bot, issue_number, delta)
-            item_result = "changed" if sync_result.changed else "already_aligned"
-            before.append(
-                StatusLabelRepairItemResult(
-                    issue_number=issue_number,
-                    before_status_labels=delta.actual_status_labels,
-                    desired_status_labels=delta.desired_status_labels,
-                    labels_added=delta.labels_to_add,
-                    labels_removed=delta.labels_to_remove,
-                    result=item_result,
-                )
-            )
-            after.append(
-                StatusLabelRepairItemResult(
-                    issue_number=issue_number,
-                    before_status_labels=delta.desired_status_labels,
-                    desired_status_labels=delta.desired_status_labels,
-                    labels_added=sync_result.labels_added,
-                    labels_removed=sync_result.labels_removed,
-                    result=item_result,
-                )
+        projection = reviews.project_status_label_projection_for_item(bot, issue_number, state)
+        delta = projection.delta
+        sync_result = reviews.apply_status_label_delta(bot, issue_number, delta)
+        item_result = "changed" if sync_result.changed else "already_aligned"
+        before.append(
+            StatusLabelRepairItemResult(
+                issue_number=issue_number,
+                before_status_labels=delta.actual_status_labels,
+                desired_status_labels=delta.desired_status_labels,
+                labels_added=delta.labels_to_add,
+                labels_removed=delta.labels_to_remove,
+                result=item_result,
             )
-            labels_added.update(sync_result.labels_added)
-            labels_removed.update(sync_result.labels_removed)
-        except RuntimeError:
-            blocked = True
-            before.append(
-                StatusLabelRepairItemResult(
-                    issue_number=issue_number,
-                    before_status_labels=(),
-                    desired_status_labels=(),
-                    labels_added=(),
-                    labels_removed=(),
-                    result="blocked",
-                )
+        )
+        after.append(
+            StatusLabelRepairItemResult(
+                issue_number=issue_number,
+                before_status_labels=delta.desired_status_labels,
+                desired_status_labels=delta.desired_status_labels,
+                labels_added=sync_result.labels_added,
+                labels_removed=sync_result.labels_removed,
+                result=item_result,
             )
-            after.append(before[-1])
-    result = "blocked" if blocked else "changed" if labels_added or labels_removed else "already_aligned"
+        )
+        labels_added.update(sync_result.labels_added)
+        labels_removed.update(sync_result.labels_removed)
+    result = "changed" if labels_added or labels_removed else "already_aligned"
     artifact = _repair_artifact_fields(request)
     payload = StatusLabelRepairSummary(
         schema_version=1,
@@ -499,7 +493,7 @@ def _handle_manual_dispatch_request(bot, state: dict, request) -> bool:
             state,
             _issue314_request(bot, request),
         )
-        issue314_state_health.emit_issue314_state_health_repair_summary(summary)
+        setattr(bot, _PENDING_ISSUE314_REPAIR_SUMMARY_ATTR, summary)
         return bool(summary.rows_removed_closed)
     if action == "execute-pending-privileged-command":
         source_event_key = request.privileged_source_event_key

tests/contract/reviewer_bot/test_workflow_files.py

@@ -446,6 +446,7 @@ def test_sweeper_repair_workflow_exposes_nonce_identity_and_repair_artifacts():
         "repair-issue314-state-health",
     ]
     assert inputs["validation_nonce"]["type"] == "string"
+    assert inputs["validation_nonce"]["required"] is True
     assert "VALIDATION_NONCE: ${{ github.event.inputs.validation_nonce }}" in text
     assert "EVALUATED_REPO: ${{ github.repository }}" in text
     assert "HEAD_SHA: ${{ github.sha }}" in text

tests/integration/reviewer_bot/test_app_preview_issue314_state_health.py

@@ -122,3 +122,58 @@ def test_execute_run_preview_issue314_state_health_is_read_only_and_inspects_act
     assert payload["artifact_name"] == "reviewer-bot-preview-output-999-attempt-4"
     assert payload["artifact_file"] == "preview-output.json"
     assert payload["output_keys"] == sorted(payload.keys())
+
+
+def test_execute_run_preview_issue314_state_health_blocks_unavailable_live_rows(
+    monkeypatch,
+    capsys,
+):
+    harness = AppHarness(monkeypatch)
+    harness.set_event(
+        EVENT_NAME="workflow_dispatch",
+        EVENT_ACTION="",
+        MANUAL_ACTION="preview-issue314-state-health",
+        ISSUE_NUMBER=314,
+        VALIDATION_NONCE="nonce-issue314-preview",
+        GITHUB_SHA="workflow-head",
+        GITHUB_REPOSITORY="rustfoundation/safety-critical-rust-coding-guidelines",
+        GITHUB_RUN_ID="1000",
+        GITHUB_RUN_ATTEMPT="1",
+        STATE_ISSUE_NUMBER=314,
+    )
+    state = make_state()
+    make_tracked_review_state(
+        state,
+        264,
+        reviewer="iglesias",
+        assigned_at="2026-02-10T17:20:07Z",
+        active_cycle_started_at="2026-02-10T17:20:07Z",
+    )
+    routes = RouteGitHubApi().add_request(
+        "GET",
+        "issues/264",
+        status_code=502,
+        payload={"message": "bad gateway"},
+    ).add_request(
+        "GET",
+        "issues/264/comments?per_page=100&page=1",
+        status_code=200,
+        payload=[],
+    )
+    harness.runtime.github.stub(routes)
+    harness.stub_load_state(lambda *, fail_on_unavailable=False: state)
+    harness.stub_lock(acquire=lambda: (_ for _ in ()).throw(AssertionError("preview should not acquire lock")))
+    harness.stub_save_state(lambda current: (_ for _ in ()).throw(AssertionError("preview should not save state")))
+    harness.stub_sync_status_labels(lambda current, issue_numbers: (_ for _ in ()).throw(AssertionError("preview should not sync labels")))
+
+    result = harness.run_execute()
+
+    assert result.exit_code == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["active_rows_inspected"] == [264]
+    assert payload["rows_blocked"] == [264]
+    assert payload["row_inventory"][0]["blockers"] == [
+        "live_snapshot_unavailable",
+        "reviewer_response_unavailable",
+        "status_projection_unavailable",
+    ]

tests/integration/reviewer_bot/test_app_preview_overdue.py

@@ -114,7 +114,7 @@ def test_execute_run_preview_check_overdue_uses_frozen_pr264_operational_project
     assert payload["reviewer_authority_outcome"] == "tracked_reviewer_confirmed"
     assert payload["suppression_reason"] == "legacy_duplicate_reminders_exhausted"
     assert payload["current_scope_key"] == "reviewer=iglesias|head=head-live|cycle=2026-02-10T17:20:07Z|anchor=2026-02-10T17:20:07Z"
-    assert payload["current_scope_basis"] == "active_cycle_started_at"
+    assert payload["current_scope_basis"] == "reminder_cadence_exhausted"
     assert payload["would_post_warning"] is False
     assert payload["would_post_transition"] is False
     assert payload["lock_attempted"] is False

tests/integration/reviewer_bot/test_app_preview_status_label_projection.py

@@ -107,7 +107,7 @@ def test_execute_run_preview_status_label_projection_is_read_only_pr264_contract
     assert payload["response_state"] == "reviewer_reassignment_needed"
     assert payload["reviewer_authority_outcome"] == "tracked_reviewer_confirmed"
     assert payload["suppression_reason"] == "legacy_duplicate_reminders_exhausted"
-    assert payload["current_scope_basis"] == "active_cycle_started_at"
+    assert payload["current_scope_basis"] == "reminder_cadence_exhausted"
     assert payload["actual_status_labels"] == ["status: awaiting reviewer response"]
     assert payload["desired_status_labels"] == ["status: reviewer reassignment needed"]
     assert payload["labels_to_add"] == ["status: reviewer reassignment needed"]