open-code-review-toolkit 0.4.2__tar.gz → 0.4.3__tar.gz

{open_code_review_toolkit-0.4.2 → open_code_review_toolkit-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-code-review-toolkit
-Version: 0.4.2
+Version: 0.4.3
 Summary: Unofficial GitLab CI integration layer for Open Code Review
 Project-URL: Homepage, https://github.com/xeonvs/open-code-review-toolkit
 Project-URL: Repository, https://github.com/xeonvs/open-code-review-toolkit
@@ -241,7 +241,7 @@ ocr --version
 ocr-ci --help
 ```
 
-The current compatibility target is OCR `1.8.3`. CI should pin the release and verify its published checksum before execution.
+The current compatibility target is OCR `1.8.6`. CI should pin the release and verify its published checksum before execution.
 The [versioned compatibility policy](docs/compatibility.md) records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases.
 Review output defaults to English. `OCR_REVIEW_LANGUAGE` accepts another explicit language name when a project needs localized review output; for example, `OCR_REVIEW_LANGUAGE=Russian`.
 

{open_code_review_toolkit-0.4.2 → open_code_review_toolkit-0.4.3}/README.md

@@ -15,7 +15,7 @@ ocr --version
 ocr-ci --help
 ```
 
-The current compatibility target is OCR `1.8.3`. CI should pin the release and verify its published checksum before execution.
+The current compatibility target is OCR `1.8.6`. CI should pin the release and verify its published checksum before execution.
 The [versioned compatibility policy](docs/compatibility.md) records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases.
 Review output defaults to English. `OCR_REVIEW_LANGUAGE` accepts another explicit language name when a project needs localized review output; for example, `OCR_REVIEW_LANGUAGE=Russian`.
 

{open_code_review_toolkit-0.4.2 → open_code_review_toolkit-0.4.3}/src/ocr_toolkit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.2'
-__version_tuple__ = version_tuple = (0, 4, 2)
+__version__ = version = '0.4.3'
+__version_tuple__ = version_tuple = (0, 4, 3)
 
 __commit_id__ = commit_id = None

{open_code_review_toolkit-0.4.2 → open_code_review_toolkit-0.4.3}/src/ocr_toolkit/posting/formatting.py

@@ -689,6 +689,7 @@ def format_reviewer_guide(
     omitted_count: int,
     *,
     outcome_status: str = "success",
+    coverage_summary: str = "",
 ) -> str:
     """Build a bounded reviewer guide from already published OCR findings."""
 
@@ -715,10 +716,12 @@ def format_reviewer_guide(
             f"- Estimated effort to review: {effort}/5",
         ]
     )
-    if outcome_status == "budget_exceeded":
+    if outcome_status in {"budget_exceeded", "partial"}:
         lines.append(
-            "- ⚠️ Review scope: OCR reached its token budget; treat all findings as a partial review."
+            "- ⚠️ Review scope: OCR reported partial coverage; treat all findings as a partial review."
         )
+    if coverage_summary:
+        lines.append(f"- Review coverage: {coverage_summary}")
 
     if not security_comments and omitted_count:
         lines.append(
@@ -771,6 +774,7 @@ def summarize_result(
     mr_head_sha: str = "",
     outcome_status: str = "success",
     outcome_message: str = "",
+    coverage_summary: str = "",
     emoji: bool | None = None,
 ) -> str:
     """Build a compact summary note for the MR."""
@@ -782,6 +786,10 @@ def summarize_result(
         "completed_with_warnings": "⚠️",
         "completed_with_errors": "❌",
         "budget_exceeded": "⚠️",
+        "clean": "✅",
+        "warning": "⚠️",
+        "partial": "⚠️",
+        "failed": "❌",
     }
     marker = f"{status_markers.get(outcome_status, '❌')} " if use_emoji else ""
     safe_message = neutralize_quick_actions(
@@ -790,6 +798,8 @@ def summarize_result(
     if not safe_message:
         if outcome_status == "budget_exceeded":
             safe_message = "Review stopped after reaching its token budget; findings are partial."
+        elif outcome_status == "partial":
+            safe_message = "Review completed with partial coverage; findings are incomplete."
         else:
             safe_message = f"Found {total} issue(s)." if total else "No issues found."
     lines = [
@@ -808,6 +818,9 @@ def summarize_result(
     if mr_head_sha and mr_head_sha != reviewed_sha:
         lines.append(f"- MR head SHA: {_inline_code(mr_head_sha)}")
 
+    if coverage_summary and not reviewer_guide:
+        lines.append(f"- {coverage_summary}")
+
     severity_counts = format_metadata_counts(comments, "severity", OCR_FINDING_SEVERITY_ORDER)
     if severity_counts:
         lines.append(f"- severity tags: {severity_counts}")

{open_code_review_toolkit-0.4.2 → open_code_review_toolkit-0.4.3}/src/ocr_toolkit/posting/workflow.py

@@ -56,6 +56,7 @@ from ocr_toolkit.posting.snapshot import (
     publish_failure_exit,
     rollback_current_run_comments,
 )
+from ocr_toolkit.result_contract import OcrResultContractError, ReviewOutcome, parse_result_outcome
 
 # Kept as a module-level compatibility seam for tests and external monkey-patching.
 post_review_note = gitlab_api.post_review_note
@@ -386,31 +387,16 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
     tool_calls_summary = format_tool_calls_summary(result.get("tool_calls"))
     mcp_usage_summary = format_mcp_usage_summary(result.get(TOOLKIT_RESULT_KEY))
     token_usage_summary = format_token_usage_summary(result)
-    status = clean_text(result.get("status")) or "success"
-    allowed_statuses = {
-        "success",
-        "skipped",
-        "completed_with_warnings",
-        "completed_with_errors",
-        "budget_exceeded",
-    }
-    if status not in allowed_statuses:
-        return invalid_ocr_schema_exit(config, "field 'status' is unsupported")
+    try:
+        outcome = parse_result_outcome(result)
+    except OcrResultContractError as exc:
+        return invalid_ocr_schema_exit(config, str(exc))
     outcome_message = clean_text(result.get("message"))
 
     if not isinstance(comments_value, list):
         return invalid_ocr_schema_exit(config, "field 'comments' must be a list")
     if not isinstance(warnings_value, list):
         return invalid_ocr_schema_exit(config, "field 'warnings' must be a list")
-    summary_value = result.get("summary")
-    summary_budget_exceeded = (
-        isinstance(summary_value, dict) and summary_value.get("budget_exceeded") is True
-    )
-    if (status == "budget_exceeded") != summary_budget_exceeded:
-        return invalid_ocr_schema_exit(
-            config, "fields 'status' and 'summary.budget_exceeded' disagree"
-        )
-
     comments: list[dict[str, Any]] = []
     for index, comment in enumerate(comments_value):
         if not isinstance(comment, dict):
@@ -418,6 +404,17 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
         comments.append(comment)
 
     warnings = warnings_value
+    if outcome.kind == "failed":
+        return post_manifest_failure(
+            config,
+            outcome,
+            outcome_message,
+            warnings,
+            tool_calls_summary=tool_calls_summary,
+            mcp_usage_summary=mcp_usage_summary,
+            token_usage_summary=token_usage_summary,
+        )
+
     billing_warnings = llm_billing_failure_warnings(warnings)
     if billing_warnings:
         print(
@@ -464,7 +461,12 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
         comments = comments[:publish_limit]
 
     emoji = post_emoji()
-    reviewer_guide = format_reviewer_guide(comments, omitted_count, outcome_status=status)
+    reviewer_guide = format_reviewer_guide(
+        comments,
+        omitted_count,
+        outcome_status=outcome.kind,
+        coverage_summary=outcome.coverage_summary,
+    )
 
     if publishable_comment_count == 0:
         raw_message = clean_text(result.get("message"))
@@ -477,21 +479,20 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
             )
         message = neutralize_quick_actions(redact_sensitive(raw_message))
         marker = {
-            "success": "✅",
+            "clean": "✅",
+            "warning": "⚠️",
+            "partial": "⚠️",
             "skipped": "ℹ️",  # noqa: RUF001 - intentional information emoji
-            "completed_with_warnings": "⚠️",
-            "completed_with_errors": "❌",
-            "budget_exceeded": "⚠️",
-        }[status]
+        }[outcome.kind]
         fallback_message = (
             "No review comments generated. No issues found."
-            if status == "success"
+            if outcome.kind == "clean"
             else (
                 "No supported files changed."
-                if status == "skipped"
+                if outcome.kind == "skipped"
                 else (
                     "Review stopped after reaching its token budget; this is a partial result."
-                    if status == "budget_exceeded"
+                    if outcome.budget_exceeded
                     else "Review did not complete cleanly."
                 )
             )
@@ -515,6 +516,8 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
             body += f"\n{mcp_usage_summary}"
         if token_usage_summary:
             body += f"\n{token_usage_summary}"
+        if outcome.coverage_summary:
+            body += f"\n{outcome.coverage_summary}"
         if reviewer_guide:
             body += f"\n\n{reviewer_guide}"
         response = post_review_note_bounded(
@@ -528,8 +531,7 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
             return posting_failure_exit(config, previous_bot_comment_refs, draft_note_ids)
         if not finalize_posting(config, draft_note_ids):
             return publish_failure_exit(config, draft_note_ids)
-        delete_previous_bot_comments_if_collected(config, previous_bot_comment_refs)
-        resolve_requested_discussions(config, previous_bot_comment_refs)
+        finalize_previous_review_state(config, previous_bot_comment_refs, outcome)
         return 0
 
     refs = get_diff_refs(config)
@@ -665,8 +667,9 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
             fallback_reasons=fallback_reasons,
             reviewed_sha=reviewed_sha(),
             mr_head_sha=mr_head_sha(),
-            outcome_status=status,
+            outcome_status=outcome.kind,
             outcome_message=outcome_message,
+            coverage_summary=outcome.coverage_summary,
             emoji=emoji,
         ),
         draft_note_ids,
@@ -679,8 +682,7 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
     if not finalize_posting(config, draft_note_ids):
         return publish_failure_exit(config, draft_note_ids)
 
-    delete_previous_bot_comments_if_collected(config, previous_bot_comment_refs)
-    resolve_requested_discussions(config, previous_bot_comment_refs)
+    finalize_previous_review_state(config, previous_bot_comment_refs, outcome)
 
     print(
         f"Posted OCR comments: mode={post_mode()}, inline={inline_count}, "
@@ -690,6 +692,20 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
     return 0
 
 
+def finalize_previous_review_state(
+    config: GitLabConfig,
+    previous_refs: BotCommentRefs,
+    outcome: ReviewOutcome,
+) -> None:
+    """Replace prior notes only after a complete outcome; preserve them for partial coverage."""
+
+    if outcome.kind == "partial":
+        print("OCR coverage is partial; preserving previous review comments until a complete run.")
+    else:
+        delete_previous_bot_comments_if_collected(config, previous_refs)
+    resolve_requested_discussions(config, previous_refs)
+
+
 def resolve_requested_discussions(
     config: GitLabConfig, previous_refs: BotCommentRefs | None
 ) -> None:
@@ -737,6 +753,65 @@ def invalid_ocr_schema_exit(
     return 1 if strict_posting() else 0
 
 
+def post_manifest_failure(
+    config: GitLabConfig,
+    outcome: ReviewOutcome,
+    message: str,
+    warnings: Sequence[Any],
+    *,
+    tool_calls_summary: str = "",
+    mcp_usage_summary: str = "",
+    token_usage_summary: str = "",
+) -> int:
+    """Post a manifest-declared run failure while preserving prior review notes."""
+
+    draft_note_ids: list[int] = []
+    safe_message = compact_escaped_text(
+        neutralize_quick_actions(redact_sensitive(message)),
+        1_200,
+    )
+    body_parts = [
+        "OCR reported that the review run failed before it could produce a complete result.",
+        "",
+        "- Normal review comments were not published.",
+        "- Previous OCR review comments were preserved.",
+    ]
+    if safe_message:
+        body_parts.append(f"- Outcome: {safe_message}")
+    if outcome.coverage_summary:
+        body_parts.append(f"- {outcome.coverage_summary}")
+
+    warning_items: list[str] = []
+    for warning in warnings[:10]:
+        safe_warning = compact_escaped_text(
+            neutralize_quick_actions(redact_sensitive(ocr_warning_text(warning))),
+            1_200,
+        )
+        if safe_warning:
+            warning_items.append(f"- {safe_warning}")
+    if warning_items:
+        body_parts.extend(["", "**Warnings:**", *warning_items])
+    if tool_calls_summary:
+        body_parts.extend(["", tool_calls_summary])
+    if mcp_usage_summary:
+        body_parts.append(mcp_usage_summary)
+    if token_usage_summary:
+        body_parts.append(token_usage_summary)
+
+    response = post_review_note_bounded(
+        config,
+        "**Open Code Review failed result**",
+        "\n".join(body_parts),
+        draft_note_ids,
+    )
+    if response is None:
+        print("Failed to create OCR manifest-failure note.", file=sys.stderr)
+        return posting_failure_exit(config, None, draft_note_ids)
+    if not finalize_posting(config, draft_note_ids):
+        return publish_failure_exit(config, draft_note_ids)
+    return 1 if strict_posting() else 0
+
+
 def post_llm_provider_failure(
     config: GitLabConfig,
     warnings: Sequence[str],

{open_code_review_toolkit-0.4.2 → open_code_review_toolkit-0.4.3}/src/ocr_toolkit/preflight.py

@@ -24,7 +24,7 @@ DEFAULT_REQUEST_HEADERS = {
     "Accept": "application/json",
     "User-Agent": "open-code-review-ci-preflight/1.0",
 }
-EXPECTED_OCR_VERSION = "1.8.3"
+EXPECTED_OCR_VERSION = "1.8.6"
 
 
 class PreflightError(Exception):

open_code_review_toolkit-0.4.3/src/ocr_toolkit/result_contract.py

@@ -0,0 +1,271 @@
+"""Validate and normalize versioned Open Code Review result outcomes."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+OutcomeKind = Literal["clean", "warning", "partial", "failed", "skipped"]
+
+MANIFEST_SCHEMA = "ocr.run-manifest/v1"
+MAX_COVERAGE_RECORDS = 10_000
+MAX_ITEM_ID_CHARS = 256
+FAILURE_CLASSES = {
+    "provider",
+    "timeout",
+    "cancelled",
+    "configuration",
+    "input",
+    "budget",
+    "panic",
+    "unknown",
+}
+RUN_FAILURE_CLASSES = {
+    "input",
+    "configuration",
+    "timeout",
+    "cancelled",
+    "budget",
+    "internal",
+    "unknown",
+}
+LEGACY_OUTCOMES: dict[str, OutcomeKind] = {
+    "success": "clean",
+    "completed_with_warnings": "warning",
+    "completed_with_errors": "partial",
+    "budget_exceeded": "partial",
+    "skipped": "skipped",
+}
+MANIFEST_OUTCOMES: dict[str, OutcomeKind] = {
+    "complete": "clean",
+    "partial": "partial",
+    "failed": "failed",
+    "skipped": "skipped",
+}
+
+
+class OcrResultContractError(ValueError):
+    """An OCR result contradicts the supported legacy or manifest contract."""
+
+
+@dataclass(frozen=True, slots=True)
+class ReviewOutcome:
+    """Expose one validated OCR outcome without provider-specific branching."""
+
+    status: str
+    kind: OutcomeKind
+    budget_exceeded: bool
+    manifest_present: bool = False
+    selected_count: int = 0
+    completed_count: int = 0
+    reused_count: int = 0
+    failed_count: int = 0
+    waived_count: int = 0
+
+    @property
+    def requires_evidence_mcp(self) -> bool:
+        """Return whether the result represents review work that must use evidence."""
+
+        return self.kind in {"clean", "warning", "partial"}
+
+    @property
+    def coverage_summary(self) -> str:
+        """Return a path-free summary of versioned manifest coverage."""
+
+        if not self.manifest_present:
+            return ""
+        return (
+            f"Coverage: selected {self.selected_count}; completed {self.completed_count}; "
+            f"reused {self.reused_count}; failed {self.failed_count}; "
+            f"waived {self.waived_count}."
+        )
+
+
+def _budget_exceeded(result: Mapping[str, Any]) -> bool:
+    """Read the optional summary budget flag without accepting truthy substitutes."""
+
+    summary = result.get("summary")
+    if summary is None:
+        return False
+    if not isinstance(summary, Mapping):
+        raise OcrResultContractError("field 'summary' must be an object")
+    value = summary.get("budget_exceeded", False)
+    if not isinstance(value, bool):
+        raise OcrResultContractError("field 'summary.budget_exceeded' must be a boolean")
+    return value
+
+
+def _coverage_ids(value: Any, field: str) -> tuple[set[str], list[Mapping[str, Any]]]:
+    """Return bounded unique item identities from one coverage array."""
+
+    if not isinstance(value, list):
+        raise OcrResultContractError(f"field 'manifest.coverage.{field}' must be a list")
+    if len(value) > MAX_COVERAGE_RECORDS:
+        raise OcrResultContractError(
+            f"field 'manifest.coverage.{field}' exceeds {MAX_COVERAGE_RECORDS} records"
+        )
+    identities: set[str] = set()
+    records: list[Mapping[str, Any]] = []
+    for index, record in enumerate(value):
+        if not isinstance(record, Mapping):
+            raise OcrResultContractError(
+                f"field 'manifest.coverage.{field}[{index}]' must be an object"
+            )
+        item_id = record.get("item_id")
+        if (
+            not isinstance(item_id, str)
+            or not item_id
+            or len(item_id) > MAX_ITEM_ID_CHARS
+            or any(character.isspace() for character in item_id)
+        ):
+            raise OcrResultContractError(
+                f"field 'manifest.coverage.{field}[{index}].item_id' is invalid"
+            )
+        if item_id in identities:
+            raise OcrResultContractError(
+                f"field 'manifest.coverage.{field}' contains duplicate item_id values"
+            )
+        identities.add(item_id)
+        records.append(record)
+    return identities, records
+
+
+def _validate_failure_records(records: list[Mapping[str, Any]]) -> bool:
+    """Validate item failure classes and report whether budget caused one."""
+
+    budget_failure = False
+    for index, record in enumerate(records):
+        classification = record.get("classification")
+        if classification not in FAILURE_CLASSES:
+            raise OcrResultContractError(
+                f"field 'manifest.coverage.failed[{index}].classification' is unsupported"
+            )
+        budget_failure = budget_failure or classification == "budget"
+    return budget_failure
+
+
+def _validate_waived_records(records: list[Mapping[str, Any]]) -> None:
+    """Require an explicit bounded reason for every waived item."""
+
+    for index, record in enumerate(records):
+        reason = record.get("reason")
+        if not isinstance(reason, str) or not reason.strip() or len(reason) > 2_000:
+            raise OcrResultContractError(
+                f"field 'manifest.coverage.waived[{index}].reason' is invalid"
+            )
+
+
+def _manifest_outcome(
+    status: str, manifest: Mapping[str, Any], budget_exceeded: bool
+) -> ReviewOutcome:
+    """Validate the v1 coverage partition and derive its terminal outcome."""
+
+    if manifest.get("schema_version") != MANIFEST_SCHEMA:
+        raise OcrResultContractError("field 'manifest.schema_version' is unsupported")
+    if manifest.get("operation") != "review":
+        raise OcrResultContractError("field 'manifest.operation' must be 'review'")
+    terminal_state = manifest.get("terminal_state")
+    if terminal_state not in MANIFEST_OUTCOMES:
+        raise OcrResultContractError("field 'manifest.terminal_state' is unsupported")
+    if status != terminal_state:
+        raise OcrResultContractError("fields 'status' and 'manifest.terminal_state' disagree")
+
+    coverage = manifest.get("coverage")
+    if not isinstance(coverage, Mapping):
+        raise OcrResultContractError("field 'manifest.coverage' must be an object")
+
+    selected, _selected_records = _coverage_ids(coverage.get("selected"), "selected")
+    completed, _completed_records = _coverage_ids(coverage.get("completed"), "completed")
+    reused, _reused_records = _coverage_ids(coverage.get("reused"), "reused")
+    failed, failed_records = _coverage_ids(coverage.get("failed"), "failed")
+    waived, waived_records = _coverage_ids(coverage.get("waived"), "waived")
+
+    terminal_sets = (completed, reused, failed, waived)
+    terminal_union: set[str] = set()
+    for terminal_set in terminal_sets:
+        if terminal_union.intersection(terminal_set):
+            raise OcrResultContractError("manifest coverage terminal sets are not disjoint")
+        terminal_union.update(terminal_set)
+    if terminal_union != selected:
+        raise OcrResultContractError(
+            "manifest coverage selected items do not equal the terminal partition"
+        )
+
+    budget_failure = _validate_failure_records(failed_records)
+    _validate_waived_records(waived_records)
+
+    run_failure = manifest.get("run_failure")
+    if run_failure is not None:
+        if not isinstance(run_failure, Mapping):
+            raise OcrResultContractError("field 'manifest.run_failure' must be an object")
+        if run_failure.get("classification") not in RUN_FAILURE_CLASSES:
+            raise OcrResultContractError(
+                "field 'manifest.run_failure.classification' is unsupported"
+            )
+
+    derived_state = (
+        "failed"
+        if run_failure is not None
+        else "skipped"
+        if not selected
+        else "complete"
+        if not failed
+        else "failed"
+        if failed == selected
+        else "partial"
+    )
+    if terminal_state != derived_state:
+        raise OcrResultContractError(
+            "field 'manifest.terminal_state' disagrees with coverage and run_failure"
+        )
+    if budget_exceeded and not (
+        budget_failure
+        or (isinstance(run_failure, Mapping) and run_failure.get("classification") == "budget")
+    ):
+        raise OcrResultContractError(
+            "field 'summary.budget_exceeded' has no matching manifest budget failure"
+        )
+    if terminal_state in {"complete", "skipped"} and budget_exceeded:
+        raise OcrResultContractError(
+            "complete or skipped manifest cannot report summary.budget_exceeded"
+        )
+
+    return ReviewOutcome(
+        status=status,
+        kind=MANIFEST_OUTCOMES[status],
+        budget_exceeded=budget_exceeded,
+        manifest_present=True,
+        selected_count=len(selected),
+        completed_count=len(completed),
+        reused_count=len(reused),
+        failed_count=len(failed),
+        waived_count=len(waived),
+    )
+
+
+def parse_result_outcome(result: Mapping[str, Any]) -> ReviewOutcome:
+    """Validate one OCR result and normalize legacy and manifest outcomes."""
+
+    status_value = result.get("status", "success")
+    if not isinstance(status_value, str) or not status_value:
+        raise OcrResultContractError("field 'status' must be a non-empty string")
+    budget_exceeded = _budget_exceeded(result)
+    manifest = result.get("manifest")
+
+    if manifest is not None:
+        if not isinstance(manifest, Mapping):
+            raise OcrResultContractError("field 'manifest' must be an object")
+        return _manifest_outcome(status_value, manifest, budget_exceeded)
+
+    if status_value not in LEGACY_OUTCOMES:
+        if status_value in MANIFEST_OUTCOMES:
+            raise OcrResultContractError(f"status {status_value!r} requires a supported manifest")
+        raise OcrResultContractError("field 'status' is unsupported")
+    if (status_value == "budget_exceeded") != budget_exceeded:
+        raise OcrResultContractError("fields 'status' and 'summary.budget_exceeded' disagree")
+    return ReviewOutcome(
+        status=status_value,
+        kind=LEGACY_OUTCOMES[status_value],
+        budget_exceeded=budget_exceeded,
+    )

{open_code_review_toolkit-0.4.2 → open_code_review_toolkit-0.4.3}/src/ocr_toolkit/review_runner.py

@@ -32,6 +32,7 @@ from ocr_toolkit.ocr_result import (
     attach_toolkit_metadata,
 )
 from ocr_toolkit.providers.gitlab import invocation_identifiers
+from ocr_toolkit.result_contract import OcrResultContractError, parse_result_outcome
 
 STDERR_PROBE_BYTES = 64 * 1024
 DEFAULT_DIAGNOSTIC_CHARS = 4_000
@@ -83,28 +84,29 @@ def _mcp_usage_receipt(
 ) -> dict[str, object]:
     """Return bounded MCP usage tied to one validated review-time registry."""
 
-    status = payload.get("status")
-    if status not in {
-        "success",
-        "completed_with_warnings",
-        "completed_with_errors",
-        "budget_exceeded",
-    }:
-        if status == "skipped":
-            tool_calls = payload.get("tool_calls")
-            by_tool = tool_calls.get("by_tool") if isinstance(tool_calls, dict) else None
-            if (
-                payload.get("message") != "No supported files changed."
-                or payload.get("comments") != []
-                or not isinstance(tool_calls, dict)
-                or tool_calls.get("total") != 0
-                or by_tool != {}
-            ):
-                raise ReviewRunnerError(
-                    "OCR skipped result does not match the pinned no-supported-files contract"
-                )
-            return {"mcp_usage": {}}
-        raise ReviewRunnerError("OCR result has an unsupported status")
+    try:
+        outcome = parse_result_outcome(payload)
+    except OcrResultContractError as exc:
+        raise ReviewRunnerError(f"OCR result has an unsupported outcome contract: {exc}") from exc
+
+    if outcome.kind == "skipped":
+        tool_calls = payload.get("tool_calls")
+        by_tool = tool_calls.get("by_tool") if isinstance(tool_calls, dict) else None
+        legacy_message_invalid = (
+            not outcome.manifest_present and payload.get("message") != "No supported files changed."
+        )
+        if (
+            legacy_message_invalid
+            or payload.get("comments") != []
+            or not isinstance(tool_calls, dict)
+            or tool_calls.get("total") != 0
+            or by_tool != {}
+        ):
+            raise ReviewRunnerError(
+                "OCR skipped result does not match the pinned no-supported-files contract"
+            )
+        return {"mcp_usage": {}}
+
     tool_calls = payload.get("tool_calls")
     by_tool = tool_calls.get("by_tool") if isinstance(tool_calls, dict) else None
     owners = {
@@ -124,7 +126,7 @@ def _mcp_usage_receipt(
             ):
                 owner = owners[tool]
                 usage[owner] = usage.get(owner, 0) + count
-    if usage.get(mcp_config.BUILTIN_EVIDENCE_SERVER, 0) <= 0:
+    if outcome.requires_evidence_mcp and usage.get(mcp_config.BUILTIN_EVIDENCE_SERVER, 0) <= 0:
         raise ReviewRunnerError(f"OCR review did not call the mandatory {TOOL_NAME} tool")
     return {"mcp_usage": dict(sorted(usage.items()))}