open-code-review-toolkit 0.7.0__tar.gz → 0.7.1__tar.gz

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-code-review-toolkit
-Version: 0.7.0
+Version: 0.7.1
 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
@@ -258,13 +258,13 @@ On a successful rerun, the toolkit replaces untouched OCR-only notes instead of
 
 Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
 
-After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v4's exact reviewed source SHA and merge-request author. This write is enabled by default; set `OCR_AUTO_APPROVE=false` when the bot must remain comment-only. Complete optional MR metadata and complete zero-record enrichment remain eligible, while degraded metadata, required context degradation, admitted mutable context, legacy receipts, any direct external MCP, author movement, or bot self-authorship prevents an approval write. GitLab approval rules and protected-branch policy remain authoritative. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.
+After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v5's exact reviewed source SHA and merge-request author. This write is enabled by default; set `OCR_AUTO_APPROVE=false` when the bot must remain comment-only. Complete optional MR metadata and complete zero-record enrichment remain eligible, while degraded metadata, required context degradation, admitted mutable context, legacy receipts, publication filtering, any direct external MCP, author movement, or bot self-authorship prevents an approval write. GitLab approval rules and protected-branch policy remain authoritative. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.
 
 Accepted tradeoffs can be recorded in `.opencodereview/accepted-decisions.md`; the evidence collector supplies only applicable target-ref decisions and never lets a source change self-authorize its review. Root and nested target `AGENTS.md`/`CLAUDE.md` guidance is similarly exposed through the existing evidence MCP with deterministic scope and precedence, while any guidance touched by the merge request is excluded. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) and [Target project guidance](docs/configuration.md#target-project-guidance) for formats and trust boundaries.
 
 ## Project architecture
 
-The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. Version 0.7.0 establishes protected-policy enriched reviews: they can acquire stable GitLab discussions and authorize external issue/document records through a provider-neutral stdio or HTTPS proxy before OCR. The same built-in MCP exposes only opaque committed `context_list`/`context_get` handles; it has no provider network or arbitrary identifier path. Direct external MCP remains a separate privileged, comment-only operator boundary.
+The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. Version 0.7.0 establishes protected-policy enriched reviews: they can acquire stable GitLab discussions and authorize external issue/document records through a provider-neutral stdio or HTTPS proxy before OCR. Version 0.7.1 adds closed receipt-v5 publication semantics, reconciled count-only evidence use, privacy-safe normalized token reporting, and deterministic Recommended focus ranking. The same built-in MCP exposes only opaque committed `context_list`/`context_get` handles; it has no provider network or arbitrary identifier path. Direct external MCP remains a separate privileged, comment-only operator boundary.
 
 - [Toolkit strategy](docs/engineering/toolkit_strategy.md) - durable product boundaries, architecture, invariants, and non-goals.
 - [Bounded review context](docs/review-context.md) - protected policy, adapter protocol, GitLab discussions, opaque handles, DLP, receipt, and cleanup contracts.

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/README.md

@@ -31,13 +31,13 @@ On a successful rerun, the toolkit replaces untouched OCR-only notes instead of
 
 Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
 
-After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v4's exact reviewed source SHA and merge-request author. This write is enabled by default; set `OCR_AUTO_APPROVE=false` when the bot must remain comment-only. Complete optional MR metadata and complete zero-record enrichment remain eligible, while degraded metadata, required context degradation, admitted mutable context, legacy receipts, any direct external MCP, author movement, or bot self-authorship prevents an approval write. GitLab approval rules and protected-branch policy remain authoritative. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.
+After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v5's exact reviewed source SHA and merge-request author. This write is enabled by default; set `OCR_AUTO_APPROVE=false` when the bot must remain comment-only. Complete optional MR metadata and complete zero-record enrichment remain eligible, while degraded metadata, required context degradation, admitted mutable context, legacy receipts, publication filtering, any direct external MCP, author movement, or bot self-authorship prevents an approval write. GitLab approval rules and protected-branch policy remain authoritative. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.
 
 Accepted tradeoffs can be recorded in `.opencodereview/accepted-decisions.md`; the evidence collector supplies only applicable target-ref decisions and never lets a source change self-authorize its review. Root and nested target `AGENTS.md`/`CLAUDE.md` guidance is similarly exposed through the existing evidence MCP with deterministic scope and precedence, while any guidance touched by the merge request is excluded. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) and [Target project guidance](docs/configuration.md#target-project-guidance) for formats and trust boundaries.
 
 ## Project architecture
 
-The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. Version 0.7.0 establishes protected-policy enriched reviews: they can acquire stable GitLab discussions and authorize external issue/document records through a provider-neutral stdio or HTTPS proxy before OCR. The same built-in MCP exposes only opaque committed `context_list`/`context_get` handles; it has no provider network or arbitrary identifier path. Direct external MCP remains a separate privileged, comment-only operator boundary.
+The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. Version 0.7.0 establishes protected-policy enriched reviews: they can acquire stable GitLab discussions and authorize external issue/document records through a provider-neutral stdio or HTTPS proxy before OCR. Version 0.7.1 adds closed receipt-v5 publication semantics, reconciled count-only evidence use, privacy-safe normalized token reporting, and deterministic Recommended focus ranking. The same built-in MCP exposes only opaque committed `context_list`/`context_get` handles; it has no provider network or arbitrary identifier path. Direct external MCP remains a separate privileged, comment-only operator boundary.
 
 - [Toolkit strategy](docs/engineering/toolkit_strategy.md) - durable product boundaries, architecture, invariants, and non-goals.
 - [Bounded review context](docs/review-context.md) - protected policy, adapter protocol, GitLab discussions, opaque handles, DLP, receipt, and cleanup contracts.

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/pyproject.toml

@@ -133,6 +133,11 @@ directory = "bugfix"
 name = "🐛 Bug Fixes"
 showcontent = true
 
+[[tool.towncrier.type]]
+directory = "maintenance"
+name = "🛠 Maintenance"
+showcontent = true
+
 [[tool.towncrier.type]]
 directory = "refactor"
 name = "🔧 Refactoring"

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/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.7.0'
-__version_tuple__ = version_tuple = (0, 7, 0)
+__version__ = version = '0.7.1'
+__version_tuple__ = version_tuple = (0, 7, 1)
 
 __commit_id__ = commit_id = None

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/src/ocr_toolkit/evidence/__main__.py

@@ -15,8 +15,10 @@ def main() -> int:
     parser.add_argument("--context-run-id", default="")
     parser.add_argument("--context-policy-digest", default="")
     arguments = parser.parse_args()
+    artifacts = repository_artifacts()
     return serve(
-        repository_artifacts().store,
+        artifacts.store,
+        action_receipt_path=artifacts.action_receipt,
         context_path=arguments.context_store,
         context_run_id=arguments.context_run_id,
         context_policy_digest=arguments.context_policy_digest,

open_code_review_toolkit-0.7.1/src/ocr_toolkit/evidence/actions.py

@@ -0,0 +1,124 @@
+"""Persist and validate count-only built-in evidence action attribution."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from collections.abc import Iterator
+from contextlib import contextmanager
+from fcntl import LOCK_EX, flock
+from pathlib import Path
+from typing import Any
+
+from ocr_toolkit.evidence.store.atomic import atomic_write
+
+ACTION_RECEIPT_SCHEMA = "ocr.evidence-action-receipt/v1"
+EVIDENCE_ACTIONS = ("summary", "list", "get")
+MAX_ACTION_CALLS = 1_000_000_000
+MAX_ACTION_RECEIPT_BYTES = 4_096
+
+
+def _locked_receipt_path(path: Path) -> Path:
+    """Return one sibling lock path that never enters the public receipt."""
+
+    return path.with_name(f".{path.name}.lock")
+
+
+@contextmanager
+def _serialized_receipt_update(path: Path) -> Iterator[None]:
+    """Serialize sibling receipt updates through one private regular lock file."""
+
+    lock_path = _locked_receipt_path(path)
+    flags = os.O_CREAT | os.O_RDWR
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = os.open(lock_path, flags, 0o600)
+    try:
+        metadata = os.fstat(descriptor)
+        if not stat.S_ISREG(metadata.st_mode) or metadata.st_nlink != 1:
+            raise OSError("evidence action receipt lock is unsafe")
+        os.fchmod(descriptor, 0o600)
+        flock(descriptor, LOCK_EX)
+        yield
+    finally:
+        os.close(descriptor)
+
+
+def _validated_counts(value: Any) -> dict[str, int] | None:
+    if not isinstance(value, dict) or set(value) != {"schema_version", "actions"}:
+        return None
+    actions = value.get("actions")
+    if value.get("schema_version") != ACTION_RECEIPT_SCHEMA or not isinstance(actions, dict):
+        return None
+    if set(actions) != set(EVIDENCE_ACTIONS):
+        return None
+    if any(
+        not isinstance(count, int) or isinstance(count, bool) or not 0 <= count <= MAX_ACTION_CALLS
+        for count in actions.values()
+    ):
+        return None
+    return {action: actions[action] for action in EVIDENCE_ACTIONS}
+
+
+def read_action_receipt(path: Path) -> dict[str, int] | None:
+    """Read one bounded receipt or return unavailable for any unsafe shape."""
+
+    flags = os.O_RDONLY
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    if hasattr(os, "O_NONBLOCK"):
+        flags |= os.O_NONBLOCK
+    descriptor = -1
+    try:
+        descriptor = os.open(path, flags)
+        metadata = os.fstat(descriptor)
+        if (
+            not stat.S_ISREG(metadata.st_mode)
+            or metadata.st_nlink != 1
+            or stat.S_IMODE(metadata.st_mode) & 0o077
+        ):
+            return None
+        raw = os.read(descriptor, MAX_ACTION_RECEIPT_BYTES + 1)
+    except OSError:
+        return None
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+    if len(raw) > MAX_ACTION_RECEIPT_BYTES:
+        return None
+    try:
+        value = json.loads(raw)
+    except (UnicodeDecodeError, json.JSONDecodeError, RecursionError):
+        return None
+    return _validated_counts(value)
+
+
+def record_action(path: Path, action: object) -> None:
+    """Atomically increment one completed action without retaining arguments."""
+
+    if action not in EVIDENCE_ACTIONS:
+        raise ValueError("evidence action is outside the closed receipt enum")
+    with _serialized_receipt_update(path):
+        counts = read_action_receipt(path)
+        try:
+            path.lstat()
+        except FileNotFoundError:
+            exists = False
+        else:
+            exists = True
+        if exists and counts is None:
+            raise ValueError("evidence action receipt is malformed")
+        if counts is None:
+            counts = dict.fromkeys(EVIDENCE_ACTIONS, 0)
+        if counts[action] >= MAX_ACTION_CALLS:
+            raise ValueError("evidence action receipt exceeds the count bound")
+        counts[action] += 1
+        payload = {
+            "schema_version": ACTION_RECEIPT_SCHEMA,
+            "actions": {name: counts[name] for name in EVIDENCE_ACTIONS},
+        }
+        atomic_write(
+            path,
+            lambda: json.dumps(payload, sort_keys=True, separators=(",", ":")) + "\n",
+        )

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/src/ocr_toolkit/evidence/artifacts.py

@@ -18,6 +18,8 @@ class EvidenceArtifacts:
     policy_rules: Path
     context_store: Path
     pre_execution_status: Path
+    action_receipt: Path
+    action_receipt_lock: Path
 
 
 def repository_artifacts(root: Path | None = None) -> EvidenceArtifacts:
@@ -32,6 +34,8 @@ def repository_artifacts(root: Path | None = None) -> EvidenceArtifacts:
         policy_rules=directory / "policy-rules.json",
         context_store=directory / "context.json",
         pre_execution_status=directory / "pre-execution-status.json",
+        action_receipt=directory / "evidence-actions.json",
+        action_receipt_lock=directory / ".evidence-actions.json.lock",
     )
 
 

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/src/ocr_toolkit/evidence/mcp.py

@@ -21,6 +21,7 @@ from ocr_toolkit.context.mcp import (
     tool_definitions,
 )
 from ocr_toolkit.context.store import ContextStore
+from ocr_toolkit.evidence.actions import record_action
 from ocr_toolkit.evidence.model import CoverageRecord, EvidenceDelta, EvidenceRecord
 from ocr_toolkit.evidence.policy.schema import is_legacy_policy_value
 from ocr_toolkit.evidence.store import EvidenceStore, EvidenceStoreError
@@ -399,7 +400,11 @@ def _error(request_id: object, code: int, message: str) -> dict[str, object]:
 
 
 def handle_request(
-    store: EvidenceStore, raw: object, context_store: ContextStore | None = None
+    store: EvidenceStore,
+    raw: object,
+    context_store: ContextStore | None = None,
+    *,
+    action_receipt_path: Path | None = None,
 ) -> dict[str, object] | None:
     """Handle one validated JSON-RPC request or notification."""
 
@@ -446,6 +451,13 @@ def handle_request(
                     request_id,
                     {"content": [{"type": "text", "text": str(exc)}], "isError": True},
                 )
+            if action_receipt_path is not None:
+                arguments = params.get("arguments", {})
+                action = arguments.get("action") if isinstance(arguments, dict) else None
+                try:
+                    record_action(action_receipt_path, action)
+                except (OSError, ValueError):
+                    pass
             return _success(request_id, result)
         if context_store is not None and isinstance(name, str) and name in {LIST_TOOL, GET_TOOL}:
             try:
@@ -482,6 +494,7 @@ def serve(
     stdin: TextIO = sys.stdin,
     stdout: TextIO = sys.stdout,
     *,
+    action_receipt_path: Path | None = None,
     context_path: Path | None = None,
     context_run_id: str = "",
     context_policy_digest: str = "",
@@ -516,7 +529,12 @@ def serve(
                 response = _error(None, -32700, "Parse error")
             else:
                 has_request_id = isinstance(request, dict) and "id" in request
-                response = handle_request(store, request, context_store)
+                response = handle_request(
+                    store,
+                    request,
+                    context_store,
+                    action_receipt_path=action_receipt_path,
+                )
         if response is None or not has_request_id:
             continue
         serialized = json.dumps(response, separators=(",", ":"), ensure_ascii=False)

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/src/ocr_toolkit/ocr_result.py

@@ -18,8 +18,8 @@ from ocr_toolkit.common.redaction import sanitize_ocr_value
 DEFAULT_MAX_RESULT_BYTES = 2_000_000
 MAX_RESULT_BYTES_HARD_LIMIT = 20_000_000
 TOOLKIT_RESULT_KEY = "_ocr_toolkit"
-TOOLKIT_RESULT_SCHEMA_VERSION = 4
-SUPPORTED_TOOLKIT_RESULT_SCHEMA_VERSIONS = frozenset({1, 2, 3, TOOLKIT_RESULT_SCHEMA_VERSION})
+TOOLKIT_RESULT_SCHEMA_VERSION = 5
+SUPPORTED_TOOLKIT_RESULT_SCHEMA_VERSIONS = frozenset({TOOLKIT_RESULT_SCHEMA_VERSION})
 # The receipt can name the 16 configured external servers plus the mandatory built-in.
 MAX_TOOLKIT_MCP_USAGE_SERVERS = 17
 MAX_TOOLKIT_MCP_TOOLS_PER_SERVER = 128

{open_code_review_toolkit-0.7.0 → open_code_review_toolkit-0.7.1}/src/ocr_toolkit/posting/approval.py

@@ -159,34 +159,42 @@ def _sha256(value: Any) -> bool:
 
 
 def publication_dlp_state(value: Any) -> str | None:
-    """Validate the exact v4 passed or filtered publication receipt."""
+    """Validate the exact v5 publication-policy receipt."""
 
-    if value == {"dlp": "passed"}:
+    if value == {"state": "passed"}:
         return "passed"
+    if not isinstance(value, dict):
+        return None
+    if value.get("state") == "private-sanitized":
+        if set(value) != {"state", "reason_counts", "sanitized_fields"}:
+            return None
+        reason_counts = value.get("reason_counts")
+        sanitized_fields = value.get("sanitized_fields")
+        if (
+            not _valid_dlp_reason_counts(reason_counts)
+            or not any(reason_counts.values())
+            or not isinstance(sanitized_fields, int)
+            or isinstance(sanitized_fields, bool)
+            or not 0 < sanitized_fields <= MAX_TOOLKIT_MCP_USAGE_COUNT
+        ):
+            return None
+        return "private-sanitized"
     if not isinstance(value, dict) or set(value) != {
-        "dlp",
+        "state",
         "reason_counts",
         "retained",
         "omitted",
         "original",
     }:
         return None
-    if value.get("dlp") != "filtered":
+    if value.get("state") != "publication-filtered":
         return None
     reason_counts = value.get("reason_counts")
     retained = value.get("retained")
     omitted = value.get("omitted")
     original = value.get("original")
     if (
-        not isinstance(reason_counts, dict)
-        or set(reason_counts)
-        != {"forbidden", "invalid_text", "laundering", "limit", "pii", "secret"}
-        or any(
-            not isinstance(count, int)
-            or isinstance(count, bool)
-            or not 0 <= count <= MAX_TOOLKIT_MCP_USAGE_COUNT
-            for count in reason_counts.values()
-        )
+        not _valid_dlp_reason_counts(reason_counts)
         or not any(reason_counts.values())
         or not isinstance(retained, dict)
         or set(retained) != {"comments", "warnings"}
@@ -210,7 +218,20 @@ def publication_dlp_state(value: Any) -> str | None:
         )
     ):
         return None
-    return "filtered"
+    return "publication-filtered"
+
+
+def _valid_dlp_reason_counts(value: Any) -> bool:
+    return bool(
+        isinstance(value, dict)
+        and set(value) == {"forbidden", "invalid_text", "laundering", "limit", "pii", "secret"}
+        and all(
+            isinstance(count, int)
+            and not isinstance(count, bool)
+            and 0 <= count <= MAX_TOOLKIT_MCP_USAGE_COUNT
+            for count in value.values()
+        )
+    )
 
 
 def automatic_approval_metadata_reason(toolkit_metadata: Any) -> str:
@@ -219,10 +240,7 @@ def automatic_approval_metadata_reason(toolkit_metadata: Any) -> str:
     invalid = "the review-time approval receipt is missing or invalid"
     if not isinstance(toolkit_metadata, dict):
         return invalid
-    schema_version = toolkit_metadata.get("schema_version")
-    if schema_version in {1, 2, 3}:
-        return "the review-time approval receipt predates current eligibility controls"
-    if schema_version != 4 or set(toolkit_metadata) != {
+    if toolkit_metadata.get("schema_version") != 5 or set(toolkit_metadata) != {
         "schema_version",
         "review",
         "context",
@@ -375,11 +393,17 @@ def automatic_approval_metadata_reason(toolkit_metadata: Any) -> str:
         return invalid
 
     evidence = toolkit_metadata.get("evidence")
-    if not isinstance(evidence, dict) or set(evidence) != {"mandatory", "used", "calls"}:
+    if not isinstance(evidence, dict) or set(evidence) != {
+        "mandatory",
+        "used",
+        "calls",
+        "actions",
+    }:
         return invalid
     mandatory = evidence.get("mandatory")
     used = evidence.get("used")
     evidence_calls = evidence.get("calls")
+    evidence_actions = evidence.get("actions")
     evidence_called = isinstance(evidence_calls, int) and evidence_calls > 0
     if (
         not isinstance(mandatory, bool)
@@ -390,6 +414,7 @@ def automatic_approval_metadata_reason(toolkit_metadata: Any) -> str:
         or used is not evidence_called
         or (mandatory and not used)
         or usage.get(builtin_server, 0) != evidence_calls + sum(context_usage.values())
+        or not _valid_evidence_actions(evidence_actions, evidence_calls)
     ):
         return invalid
     publication = toolkit_metadata.get("publication")
@@ -397,7 +422,7 @@ def automatic_approval_metadata_reason(toolkit_metadata: Any) -> str:
     publication_state = publication_dlp_state(publication)
     if publication_state is None or cleanup != {"result": "passed"}:
         return invalid
-    if publication_state == "filtered":
+    if publication_state == "publication-filtered":
         return "publication DLP filtered the complete review result"
     if context.get("state") == "degraded" or required_degraded:
         return "the selected review context was degraded"
@@ -406,3 +431,23 @@ def automatic_approval_metadata_reason(toolkit_metadata: Any) -> str:
     if external:
         return "external MCP was configured for a comment-only review"
     return ""
+
+
+def _valid_evidence_actions(value: Any, evidence_calls: Any) -> bool:
+    """Validate verified counts or an explicit unavailable attribution state."""
+
+    if value == {"state": "unavailable"}:
+        return True
+    if not isinstance(value, dict) or set(value) != {"state", "summary", "list", "get"}:
+        return False
+    counts = [value.get(action) for action in ("summary", "list", "get")]
+    return bool(
+        value.get("state") == "verified"
+        and all(
+            isinstance(count, int)
+            and not isinstance(count, bool)
+            and 0 <= count <= MAX_TOOLKIT_MCP_USAGE_COUNT
+            for count in counts
+        )
+        and sum(counts) == evidence_calls
+    )