#!/usr/bin/env python3 """Admission gate for profile-ordered page OCR projections.""" from __future__ import annotations import argparse import json from datetime import UTC, datetime from pathlib import Path from typing import Any from ocrtech.manifest import sha256_file REPORT_JSON = "page-reading-order-profile-application-admission.json" def _read_json(path: Path, label: str) -> dict[str, Any]: try: payload = json.loads(path.read_text(encoding="utf-8")) except FileNotFoundError as exc: raise ValueError(f"{label} is missing: {path}") from exc except json.JSONDecodeError as exc: raise ValueError(f"{label} is invalid JSON: {path}: {exc}") from exc if not isinstance(payload, dict): raise ValueError(f"{label} must contain a JSON object: {path}") return payload def _check_sha(path: Path, expected: Any, issues: list[str], *, label: str) -> str: if not path.is_file(): issues.append(f"{label} is missing: {path}") return "" actual = sha256_file(path) if isinstance(expected, str) and expected and expected != actual: issues.append(f"{label} SHA-256 mismatch: recorded={expected} actual={actual}") return actual def _optional_path(value: Any) -> Path | None: if not isinstance(value, str) or not value: return None return Path(value) def _profile_audit_paths(value: Any) -> list[Path]: if isinstance(value, (str, Path)): return [Path(value)] if isinstance(value, list): paths = [Path(item) for item in value] if paths: return paths raise ValueError("at least one --profile-audit is required") def _profile_usage_rows(profile_application: dict[str, Any]) -> list[dict[str, Any]]: rows = profile_application.get("profile_usage") if isinstance(rows, list) and rows: normalized: list[dict[str, Any]] = [] for index, row in enumerate(rows, start=1): if not isinstance(row, dict): raise ValueError(f"profile_usage row {index} must be an object") normalized.append(row) return normalized return [ { "profile": profile_application.get("profile") or "", "profile_sha256": profile_application.get("profile_sha256") or "", "profile_claim_safe": profile_application.get("profile_claim_safe"), "sample_ids": [], } ] def admit_application(args: argparse.Namespace) -> dict[str, Any]: profile_audit_paths = _profile_audit_paths(args.profile_audit) profile_application_path = Path(args.profile_application_report) effect_audit_path = Path(args.effect_audit) profile_map_audit_path = Path(args.profile_map_audit) if getattr(args, "profile_map_audit", None) else None out = Path(args.out) out.mkdir(parents=True, exist_ok=True) issues: list[str] = [] profile_audits = [_read_json(path, f"reading-order profile audit {index}") for index, path in enumerate(profile_audit_paths, start=1)] profile_application = _read_json(profile_application_path, "reading-order profile application report") effect_audit = _read_json(effect_audit_path, "candidate page-line effect audit") profile_map_audit = _read_json(profile_map_audit_path, "profile map audit") if profile_map_audit_path is not None else None profile_audit_reports: list[dict[str, Any]] = [] audit_by_profile_sha: dict[str, dict[str, Any]] = {} for path, audit in zip(profile_audit_paths, profile_audits, strict=True): audit_sha = _check_sha(path, None, issues, label="profile audit") profile_sha = str(audit.get("profile_sha256") or "") profile_audit_reports.append({"path": str(path), "sha256": audit_sha, "profile_sha256": profile_sha}) if not profile_sha: issues.append(f"profile audit missing profile_sha256: {path}") elif profile_sha in audit_by_profile_sha: issues.append(f"duplicate profile audit for profile SHA-256: {profile_sha}") else: audit_by_profile_sha[profile_sha] = audit if audit.get("audit_passed") is not True: issues.append(f"profile audit did not pass: {path}") if audit.get("operational_profile_safe") is not True: issues.append(f"profile audit does not mark operational_profile_safe=true: {path}") if audit.get("profile_claim_safe") is not True: issues.append(f"profile audit does not mark profile_claim_safe=true: {path}") profile_application_sha = _check_sha(profile_application_path, None, issues, label="profile application report") effect_audit_sha = _check_sha(effect_audit_path, None, issues, label="effect audit") profile_map_audit_sha = ( _check_sha(profile_map_audit_path, None, issues, label="profile map audit") if profile_map_audit_path is not None else "" ) application_profile_map_sha = str(profile_application.get("profile_map_sha256") or "") if application_profile_map_sha: if profile_map_audit is None: issues.append("profile application used a profile map but no --profile-map-audit was supplied") else: audit_map_sha = str(profile_map_audit.get("profile_map_sha256") or "") if not audit_map_sha: issues.append("profile map audit missing profile_map_sha256") elif audit_map_sha != application_profile_map_sha: issues.append(f"profile map SHA mismatch: audit={audit_map_sha} application={application_profile_map_sha}") if profile_map_audit.get("audit_passed") is not True: issues.append("profile map audit did not pass") if profile_map_audit.get("operational_profile_map_safe") is not True: issues.append("profile map audit does not mark operational_profile_map_safe=true") profile_usage = _profile_usage_rows(profile_application) for index, usage in enumerate(profile_usage, start=1): application_profile_sha = str(usage.get("profile_sha256") or "") if not application_profile_sha: issues.append(f"profile application usage row {index} missing profile_sha256") continue if application_profile_sha not in audit_by_profile_sha: issues.append(f"profile application usage row {index} has no matching profile audit: {application_profile_sha}") if usage.get("profile_claim_safe") is not True: issues.append(f"profile application usage row {index} was not run with a claim-safe profile") if int(profile_application.get("assignment_count") or 0) <= 0: issues.append("profile application report has no line assignments") if effect_audit.get("book_ocr_objective_safe") is not True: issues.append("page objective effect audit is not safe") effect_issues = effect_audit.get("issues") if isinstance(effect_issues, list) and effect_issues: issues.append(f"page objective effect audit contains issues: {len(effect_issues)}") elif not isinstance(effect_issues, list): issues.append("page objective effect audit missing issues list") candidate_score_dir = _optional_path(effect_audit.get("candidate_score_dir")) candidate_metrics_sha = "" if candidate_score_dir is not None: candidate_metrics_sha = _check_sha( candidate_score_dir / "metrics.json", effect_audit.get("candidate_metrics_sha256"), issues, label="candidate score metrics", ) report_path = out / REPORT_JSON all_operational_profile_safe = bool(profile_audits) and all( audit.get("operational_profile_safe") is True for audit in profile_audits ) report = { "tool": "tools/admit_page_reading_order_profile_application.py", "created_at_utc": datetime.now(UTC).isoformat(), "profile_audits": profile_audit_reports, "profile_application_report": str(profile_application_path), "profile_application_report_sha256": profile_application_sha, "profile_map_audit": str(profile_map_audit_path) if profile_map_audit_path is not None else "", "profile_map_audit_sha256": profile_map_audit_sha, "effect_audit": str(effect_audit_path), "effect_audit_sha256": effect_audit_sha, "profile_sha256": profile_audit_reports[0]["profile_sha256"] if len(profile_audit_reports) == 1 else "", "profile_usage": profile_usage, "candidate_score_dir": str(candidate_score_dir) if candidate_score_dir is not None else "", "candidate_metrics_sha256": candidate_metrics_sha, "assignment_count": profile_application.get("assignment_count"), "book_ocr_objective_safe": effect_audit.get("book_ocr_objective_safe"), "operational_profile_safe": all_operational_profile_safe, "admitted_operational": not issues, "issues": issues, "claim_boundary": ( "Profile-ordered page projection admission. It requires safe profile provenance " "and safe page objective effect; it does not certify claim-grade OCR without frozen held-out page coverage." ), } report["report_json"] = str(report_path) report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") return report def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--profile-audit", type=Path, action="append", required=True) parser.add_argument("--profile-map-audit", type=Path) parser.add_argument("--profile-application-report", type=Path, required=True) parser.add_argument("--effect-audit", type=Path, required=True) parser.add_argument("--out", type=Path, required=True) args = parser.parse_args() report = admit_application(args) print(report["report_json"]) print(f"admitted_operational={report['admitted_operational']} issues={len(report['issues'])}") return 0 if report["admitted_operational"] else 1 if __name__ == "__main__": raise SystemExit(main())